Link Search Menu Expand Document
ModalAI DOCS
Store

Configuring VOXL Cameras

When setting up a custom VOXL board for the first time or when changing camera configurations, you will need to configure VOXL’s software to make it aware of the physical camera configuration. This is done with the voxl-configure-cameras tool, which ships with the voxl-camera-server package:

voxl2:~$ voxl-configure-cameras

Run without arguments it prompts you interactively. The full usage is:

voxl-configure-cameras <config-id>   - set up a specific camera config
voxl-configure-cameras custom        - use /data/modalai/custom_camera_config.txt
voxl-configure-cameras disable       - configure but leave the service disabled
voxl-configure-cameras --dry-run     - print the resulting camera + driver list, change nothing
voxl-configure-cameras help          - show help text

Camera config IDs are per-platform

The list of valid config IDs depends on which board you are on — there is no single global list. Run print-camera-configs on target to see the live list for your hardware:

  • VOXL 2 / VOXL 2 Mini (M0054/M0104/M0205): the platform config is read from /sys/module/voxl_platform_mod/parameters/config, which selects one of three config sets — the legacy breakout-board set (M0074/M0135 era), the M0173/M0181 coax front-end set, and the VOXL 2 Mini (M0188/M0195) set.
  • M0197: its own dedicated config set.

Each numbered config corresponds to a known combination of sensors on known connectors (for example, on Starling the config provides hires + TOF + tracking). The camera configs reference describes the common combinations and their connector wiring.

What the script does

  • Generates /etc/modalai/voxl-camera-server.conf with per-sensor defaults for the chosen configuration
  • Applies frame-sync settings (fsync_en / fsync_gpio) where the config calls for them
  • Removes all camera driver files (com.qti.sensormodule*) from /usr/lib/camera/ and copies in only the ones the configuration needs
  • Enables the voxl-camera-server systemd service

Power cycle the board after running the script. It changes low-level camera drivers, and the new configuration is not fully applied until a full power cycle.

You can further customize the configuration (image resolutions, encoder settings, etc.) by editing the config file directly — see voxl-camera-server for the config file reference.

Custom camera configurations

If your combination of cameras isn’t one of the numbered configs, use the custom config workflow instead of hand-editing voxl-camera-server.conf:

cp /usr/share/modalai/voxl-camera-server/custom_camera_config.txt /data/modalai/
vi /data/modalai/custom_camera_config.txt
voxl-configure-cameras custom --dry-run    # preview the camera + driver list
voxl-configure-cameras custom

The file declares, per camera connector, which sensor is attached and how it should be presented: J6_LOWER_SENSOR, J6_LOWER_NAME, J6_LOWER_ROTATE, combo-mode fields for stereo pairs (left-right, right-left, independent, single) with a second name for the pair, and frame-sync fields (FSYNC_GPIO, FSYNC_EN). The script assigns camera IDs and installs the right drivers for you — no manual renumbering needed.

A vehicle can be permanently marked as using a custom camera config by setting the camera field of its SKU to CC.

Connect A New Camera

For most cases, the custom camera config workflow above handles new cameras automatically. The manual steps below explain what happens under the hood, for unusual setups.

When a new camera is physically connected to VOXL2, it is not automatically detected by software. Please follow the steps below to enable a new camera that is added to an existing camera configuration

  • identify the type of camera (such as IMX412, ov7251, AR0144, etc)
  • based on where the new camera is actually connected, figure out the camera’s hardware slot ID
    • For VOXL2 without M0173: link, see HW Sensor ID (0…5)
      • VOXL2 J6L : slot 0, J6U : slot 1, J7L : slot 2, J7U : slot 3, J8L : slot 4, J8U : slot 5
    • For VOXL2 + M0173: link link2:
      • M0173 J1 : slot 0 (Front Tracking)
      • M0173 J4 : slot 1 (Hires)
      • M0173 J5 : slot 2 (Rear Tracking)
      • M0173 J3 : slot 3 (TOF sensor)
      • M0173 J2 : slot 6 (Down Tracking)
      • VOXL2 J8L : slot 4 (can be used with M0076 or M0135, etc)
      • VOXL2 J8U : slot 5 (can be used with M0076 or M0135, etc, but needs a kernel change due to a reset mapping change)
  • copy the appropriate sensormodule from /usr/share/modalai/chi-cdk/ to /usr/lib/camera
  • check if camera is detected, see link
    • you should see your new camera detected in the correct slot
    • sensor i2c ID (WHOAMI register value) for all cameras is provided here
  • also note the new camera IDs (not slot IDs). The camera IDs are sequentially assigned as the cameras are probed, so connecting the new camera can cause the camera IDs to shift
    • update the camera IDs for previously existing cameras (in /etc/modalai/voxl-camera-server.conf)
  • add a new camera entry to /etc/modalai/voxl-camera-server.conf
    • if an additional camera is of the same type as another camera in the configuration, simply copy the whole entry and update the camera name and camera id and any settings you might want to change
    • if the new camera is of a different type, you should at least try to start off with a similar configuration and update camera name, id, type
      • if your new camera is present in another standard configuration, you can run voxl-configure-cameras and temporarily configure the system for that configuration, then check voxl-camera-server.conf for the corresponding entry for your camera. After copying that entry, you can restore your original configuration and copy the new sensormodule again
      • keep in mind that running voxl-configure-cameras will change which sensormodule files (camera drivers) are present in /usr/lib/camera and will re-write voxl-camera-server.conf (save changes before running it)

Useful Definitions

  • Camera ID: Software ID, which is assigned to each camera as the camera is detected during probing state. Camera IDs start from zero and are consecutive.
  • Slot ID : Hardware ID that uniquely maps a camera to the hardware port on VOXL2. Slot ID of a camera remains the same regardless of what other cameras are connected.
  • Sensor ID : typically means the value of WHOAMI register, which is used to detect the camera via I2C (CCI) during camera probing stage as camera server starts up.