video-setup/docs/cli/v4l2_ctrl_cli.md

v4l2_ctrl_cli

A development tool for listing and adjusting V4L2 camera controls. It wraps the v4l2_ctrl module and provides a command-line interface for enumerating, reading, and writing camera parameters on /dev/video* devices.

This tool is the counterpart to v4l2-ctl from the v4l-utils package. It covers the same core functionality but is built on our own v4l2_ctrl translation unit.

---

Build

From the repository root:

make

Or from dev/cli/ directly:

make v4l2_ctrl_cli

The binary is placed in dev/cli/.

---

Commands

list

Enumerate all video devices present on the system.

./v4l2_ctrl_cli list

Example output:

Video devices:
  /dev/video0
  /dev/video1

---

controls <device>

List all controls available on a device, including their current values, valid ranges, and — for menu controls — all available menu options.

./v4l2_ctrl_cli controls /dev/video0

Example output (Pi camera):

Controls on /dev/video0:
  0x009e0903  Exposure Time (Absolute)    int        current=10000   default=10000   min=13       max=11766488  step=1
  0x009e0902  Analogue Gain               int        current=1000    default=1000    min=1000     max=16000     step=1
  0x00980913  Horizontal Flip             bool       current=0       default=0       min=0        max=1
  0x00980914  Vertical Flip               bool       current=0       default=0       min=0        max=1
  0x009e0905  Auto Exposure               menu       current=0       default=0       min=0        max=1
    [0] Manual Mode
    [1] Auto Mode
  0x0098091f  Auto White Balance          bool       current=1       default=1       min=0        max=1

Control types:

• int — integer value with min, max, and step
• bool — 0 or 1
• menu — discrete named options (shown with their labels)
• int-menu — discrete integer-valued options
• int64 — 64-bit integer
• bitmask — bit field

---

get <device> <id>

Read the current value of a single control by its numeric ID. The ID can be decimal or hexadecimal (with 0x prefix).

./v4l2_ctrl_cli get /dev/video0 0x009e0903

Example output:

0x009e0903 = 10000

Control IDs are shown in hex in the controls output.

---

set <device> <id>=<value>

Write a value to a control. The ID and value can both be decimal or hexadecimal.

# Set exposure time
./v4l2_ctrl_cli set /dev/video0 0x009e0903=5000

# Enable horizontal flip
./v4l2_ctrl_cli set /dev/video0 0x00980913=1

# Disable auto exposure (switch to manual)
./v4l2_ctrl_cli set /dev/video0 0x009e0905=0

The device will return an error if:

• The value is out of the control's min/max range
• The control is read-only
• The control does not exist on the device

---

Common Control IDs

These IDs are standardised in the V4L2 specification and are consistent across devices that support them:

ID	Name
0x00980900	Brightness
0x00980901	Contrast
0x00980902	Saturation
0x00980913	Horizontal Flip
0x00980914	Vertical Flip
0x009e0903	Exposure Time (Absolute)
0x009e0902	Analogue Gain
0x009e0905	Auto Exposure

Camera-specific controls (ISP parameters, codec settings, etc.) will have IDs outside the standard ranges and are best discovered via the controls command.

---

Relationship to the Video Routing System

v4l2_ctrl_cli exercises the v4l2_ctrl module, which is used in the video routing system for:

• Remote parameter tuning — a controlling node can adjust exposure, gain, white balance, and other parameters on a remote camera without SSH or local access
• Control enumeration — discovering the full set of parameters a camera supports, returned as structured data over the transport control channel

The Pi in the microscope setup runs a V4L2 control endpoint that accepts these operations via the transport protocol. v4l2_ctrl_cli lets you perform the same operations locally for development and calibration.

See also: media_ctrl_cli.md for pipeline topology and pad format configuration.