vizion-ctl
vizion-ctl Functionality Overview
vizion-ctl is a command-line utility for camera inspection, configuration, and maintenance through VizionSDK. It is useful when you need a scriptable way to check camera status, tune image controls, capture frames, manage profiles, update firmware, or run platform-specific utilities such as routes, IMU, intrinsics, and GMSL link margin checks.
This page is organized as a quick reference:
- Options lists command flags by task area.
- Intrinsics YAML file format shows the required output structure for
--get-intrin. - Control Parameters lists supported
get/setcamera controls with ranges and defaults. - Examples provides copy-ready command patterns for common operations.
warning
On Linux, commands that access I2C may require elevated privileges. See I2C permission troubleshooting.
Options
Most device-specific commands accept -d <num> / --device <num> to select a camera; if omitted, device 0 is used.
Help and device discovery
| Option | Purpose | Argument / Notes |
|---|---|---|
-h | Display available options. | - |
-v, --version | Show version information. | - |
-l, --list-devices | List connected camera devices. | - |
-d, --device | Select the target device. | <num>; default is 0. |
-i, --info | Display selected device information. | - |
-f, --list-formats | List supported capture formats. | - |
-hi, --header-info | Display ISP header information. | - |
Control and logging
| Option | Purpose | Argument / Notes |
|---|---|---|
-g, --get-ctrl | Retrieve one control value, or all control values. | <name> or --all. |
-s, --set-ctrl | Set a control value. | <ctrl=value>; for example, throughput=500. |
--debug | Enable debug logging. | Can be combined with other commands. |
--log-level | Set the VizionSDK log level. | trace, debug, info, warn, error, critical, or off. |
--log-path | Write logs to a file path. | Use a path with write permission for normal users. |
Capture and sensor files
| Option | Purpose | Argument / Notes |
|---|---|---|
-si, --save-image | Save camera image data. | Requires --path <filepath>. Optional: --skip <n>, --store <n>. |
-sc, --save-sensor | Save sensor config to a binary file. | <filepath>. |
-sd, --sensor-decode | Decode a sensor config binary to JSON. | Requires --bin <bin_file> and --json <json_file>. |
OSP and BSL profiles
| Option | Purpose | Argument / Notes |
|---|---|---|
-go, --get-osp | Get the current OSP profile flag. | - |
-so, --set-osp | Set the OSP profile flag. | 0 Disable, 1 Enabled, or 2 EnableAndSave. |
-ro, --reset-osp | Reset the OSP profile to default settings. | - |
--list-bsl-profile | List supported BSL profile keys from VxBSLMode.yaml. | Optional: --bsl-profile <name>. |
Firmware update and download
| Option | Purpose | Argument / Notes |
|---|---|---|
-fu, --firmware-update | Update device firmware. | <type=file>; type can be uvc or sensor. |
--target | Select the UVC firmware update target. | SPI by default; also supports RAM and I2C. |
-fd, --firmware-download | Download firmware interactively. | Requires --path <path>. |
Sensor firmware update supports direct mode, burned/recovery mode, and recondition traverse mode on Linux MIPI platforms.
Timestamp, framecount, and routing
| Option | Purpose | Argument / Notes |
|---|---|---|
--get-timestamp | Retrieve timestamp. | - |
--reset-timestamp | Reset timestamp. | Requires streaming. |
--get-framecount | Retrieve framecount. | - |
--reset-framecount | Reset framecount. | Requires streaming. |
--reset-route | Reset the active routes from the device. | Linux only. |
--setroute | Activate routes from a YAML file. | <yaml_file_path>; Linux only. |
IMU, intrinsics, and GMSL
| Option | Purpose | Argument / Notes |
|---|---|---|
--enable-imu | Enable an IMU mode. | self-test or ispu. |
--reboot-imu | Reboot an IMU mode. | self-test or ispu. |
--imu-acc | Get IMU accelerometer data. | Use with --self-test: normal, positive, or negative. |
--imu-gyr | Get IMU gyroscope data. | Use with --self-test: normal, positive, or negative. |
--imu-ispu | Get IMU ISPU data. | Requires IMU ispu mode. |
--get-intrin | Get intrinsics info and save it to YAML. | <filepath>. |
--gmsl-lm | Run the GMSL Link Margin Reverse and Forward algorithm. | <iteration>. |
IMU options are only available on VCM/TEVM cameras. Intrinsics options are only available on TEVS/TEVM cameras.
Intrinsics YAML file format
The YAML file used with the --get-intrin commands must follow the structure below:
cam0:
cam_overlaps: []
camera_model: pinhole
distortion_coeffs: [fx, fy, cx, cy]
distortion_model: radtan
intrinsics: [k1, k2, r1, r2]
resolution: [w, h]
rostopic: /usb_cam/image_raw
- w, h: Image width and height in pixels.
- fx, fy: Focal lengths along the horizontal (U) and vertical (V) axes.
- cx, cy: Principal point coordinates along the horizontal (U) and vertical (V) axes.
- k1, k2: Radial Distortion coefficients.
- r1, r2: Tangential Distortion coefficients.
info
The fields cam_overlaps, camera_model, distortion_model, and rostopic are fixed.
Control Parameters
Use -g <control> / --get-ctrl <control> to read a value, and -s <control=value> / --set-ctrl <control=value> to update a value.
Image tuning controls
| Control | Range | Step | Default | Notes |
|---|---|---|---|---|
brightness | -10 - 10 | 1 | 0 | Adjust image brightness. |
contrast | -50 - 50 | 1 | 0 | Adjust image contrast. |
saturation | 0 - 50 | 1 | 10 | Adjust color saturation. |
gamma | 4 - 79 | 1 | 22 | Adjust gamma correction. |
sharpness | -20 - 20 | 1 | 0 | Adjust edge sharpness. |
backlight | -150 - 150 | 1 | 10 | Adjust backlight compensation. |
noise | -20 - 20 | 1 | 0 | Adjust noise reduction. |
jpeg_quality | 0 - 255 | 1 | 233 | Adjust JPEG output quality. |
White balance controls
| Control | Range | Step | Default | Notes |
|---|---|---|---|---|
white_balance_mode | 0 - 1 | 1 | 1 | 0 Manual temperature, 1 Auto. |
white_balance_temperature | 2300 - 15000 | 1 | 5000 | Used when white balance is set to manual temperature mode. |
Exposure and flicker controls
| Control | Range | Step | Default | Notes |
|---|---|---|---|---|
exposure_mode | 0 - 2 | 1 | 1 | 0 Manual mode, 1 Auto mode, 2 Auto gain. |
exposure_time | 1 - 1000000 | 1 | 33333 | Manual exposure time. |
exposure_min_time | 1 - 1000000 | 1 | 16666 | Default follows the VxExposure.yaml min value. |
exposure_max_time | 1 - 1000000 | 1 | 66666 | Default follows the VxExposure.yaml max value. |
exposure_gain | 1 - 64 | 1 | 1 | Manual exposure gain. |
flick_mode | 0 - 3 | 1 | 0 | 0 Disable, 1 50Hz, 2 60Hz, 3 Auto. |
Orientation, effect, and lens controls
| Control | Range | Step | Default | Notes |
|---|---|---|---|---|
special_effect | 0 - 4 | 1 | 0 | 0 Normal, 1 Black white, 2 Grayscale, 3 Negative, 4 Sketch. |
flip_mode | 0 - 3 | 1 | 0 | 0 Normal, 1 H-Mirror, 2 V-Mirror, 3 Rotate-180. |
pan_target | 0 - 10 | 1 | 5 | Pan target position. |
tilt_target | 0 - 10 | 1 | 5 | Tilt target position. |
zoom_target | 10 - 80 | 1 | 10 | Zoom target position. |
Stream and trigger controls
| Control | Range | Step | Default | Notes |
|---|---|---|---|---|
throughput | 10.0 - 1000.0 | - | - | Stream throughput limit. |
max_fps | 1 - 120 | - | - | Maximum frame rate. |
trigger_mode | 0 - 3 | 1 | 0 | 0 Disable, 1 Sync, 2 Periodic, 3 Non Periodic. Supported on TEVS and VCS cameras. |
eHDR controls
| Control | Range | Step | Default | Notes |
|---|---|---|---|---|
ehdr_mode | 0 - 1 | 1 | 0 | 0 Enable, 1 Disable. Disable mode turns off the eHDR effect. |
ehdr_exposure_min_number | 1 - 4 | 1 | 1 | Minimum eHDR exposure count. |
ehdr_exposure_max_number | 1 - 4 | 1 | 4 | Maximum eHDR exposure count. |
ehdr_ratio_min | 1 - 128 | 1 | 12 | Minimum eHDR ratio. |
ehdr_ratio_max | 1 - 128 | 1 | 24 | Maximum eHDR ratio. |
eHDR features are only supported on AR0821, AR0822, and AR0246 sensors.
Examples
Use these examples as quick command patterns. Short flags are shown first, with long-flag equivalents included where they add clarity.
Basic device queries
# Show version information
vizion-ctl -v
vizion-ctl --version
# List connected devices and inspect device 0
vizion-ctl -l
vizion-ctl -d 0 -i
# List supported capture formats and read ISP header information
vizion-ctl -d 0 -f
vizion-ctl -d 0 -hi
Control values and logging
warning
When using --log-path, set the destination to a location with write permissions for normal users.
# Get all controls or one specific control
vizion-ctl -d 0 -g --all
vizion-ctl -d 0 --get-ctrl throughput
# Set a control value
vizion-ctl -d 0 -s throughput=500
# Enable debug logs, set log level, or write logs to a file
vizion-ctl -d 0 -g --all --debug
vizion-ctl -d 0 -g --all --log-level warn
vizion-ctl -d 0 -g --all --debug --log-path path_to_log_file
Capture, firmware, and sensor files
warning
Set output paths to locations with write permissions for normal users.
# Save one image, or discard 5 frames before saving 3 frames
vizion-ctl -d 0 -si --path image.raw
vizion-ctl -d 0 -si --path image.raw --skip 5 --store 3
# Update UVC firmware, update UVC firmware to RAM, or update sensor firmware
vizion-ctl -d 0 -fu uvc=firmware.img
vizion-ctl -d 0 -fu uvc=firmware.img --target RAM
vizion-ctl -d 0 -fu sensor=firmware.bin
# Download firmware, export sensor config, or decode sensor config
vizion-ctl -d 0 -fd --path path_to_fw
vizion-ctl -d 0 --save-sensor config.bin
vizion-ctl --sensor-decode --bin config.bin --json config.json
Linux MIPI sensor firmware modes:
# Direct mode, burned/recovery mode, and recondition traverse mode
vizion-ctl -fu sensor=firmware.bin --i2c-bus 2 --subdev /dev/v4l-subdev2
vizion-ctl -fu sensor=firmware.bin --i2c-bus 1 --slave-id 0x48 --bsl-profile edm-g-imx8mp
vizion-ctl -fu sensor=firmware.bin --recondition --bsl-profile orinnano
OSP and BSL profiles
# Get, set, or reset the OSP profile flag
vizion-ctl -d 0 -go
vizion-ctl -d 0 -so 1
vizion-ctl -d 0 -ro
# List all BSL profile keys or filter by profile name
vizion-ctl --list-bsl-profile
vizion-ctl --list-bsl-profile --bsl-profile orinnano
Timestamp, framecount, and routes
warning
Timestamp and framecount reset commands require the camera to be streaming. Route commands are supported only on Linux.
# Read or reset timestamp and framecount
vizion-ctl -d 0 --get-timestamp
vizion-ctl -d 0 --get-framecount
vizion-ctl -d 0 --reset-timestamp
vizion-ctl -d 0 --reset-framecount
# Clear active routes
vizion-ctl --reset-route
Activate the routes
vizion-ctl --setroute routes.yaml
IMU, intrinsics, and GMSL
warning
IMU commands are only available on VCM/TEVM cameras. Intrinsics commands are only available on TEVS/TEVM cameras. Set output paths to locations with write permissions for normal users.
# Enable or reboot IMU mode
vizion-ctl -d 0 --enable-imu ispu
vizion-ctl -d 0 --reboot-imu ispu
# Read IMU self-test accelerometer/gyroscope data or ISPU data
vizion-ctl -d 0 --imu-acc --self-test normal
vizion-ctl -d 0 --imu-gyr --self-test normal
vizion-ctl -d 0 --imu-ispu
# Export intrinsics data and run GMSL Link Margin
vizion-ctl -d 0 --get-intrin calibration.yaml
vizion-ctl -d 0 --gmsl-lm 1