# 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:

```sh
make
```

Or from `dev/cli/` directly:

```sh
make v4l2_ctrl_cli
```

The binary is placed in `dev/cli/`.

---

## Commands

### `list`

Enumerate all video devices present on the system.

```sh
./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.

```sh
./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).

```sh
./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.

```sh
# 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`](media_ctrl_cli.md) for pipeline topology and pad format configuration.