Add common, media_ctrl and v4l2_ctrl modules with CLI drivers and docs
Modules (src/modules/): - common/error: App_Error struct with structured detail union, error codes, app_error_print(); designed for future upgrade to preprocessor-generated location codes - media_ctrl: media device enumeration, topology query (entities/pads/links), link enable/disable via Media Controller API (/dev/media*) - v4l2_ctrl: control enumeration (with menu item fetching), get/set via V4L2 ext controls API, device discovery (/dev/video*) All modules use -std=c11 -D_GNU_SOURCE, build artifacts go to build/ only. Kernel-version-dependent constants guarded with #ifdef + #warning. CLI drivers (dev/cli/): - media_ctrl_cli: list, info, topology, set-link subcommands - v4l2_ctrl_cli: list, controls, get, set subcommands Docs (docs/cli/): - media_ctrl_cli.md and v4l2_ctrl_cli.md with usage, examples, and context within the video routing system Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
147
docs/cli/v4l2_ctrl_cli.md
Normal file
147
docs/cli/v4l2_ctrl_cli.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user