docs: write CLI docs for all 12 previously undocumented tools

Add docs/cli/ entries for:
  transport_cli, discovery_cli, config_cli, protocol_cli, query_cli,
  test_image_cli, xorg_cli, v4l2_view_cli, stream_send_cli,
  stream_recv_cli, reconciler_cli, controller_cli

Each doc covers: description, build instructions, full usage with all
options and defaults, example output, and a relationship note pointing
to related tools. controller_cli includes the display control IDs table
and notes its temporary status.

README.md: convert all CLI tool entries to links.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-30 00:45:27 +00:00
parent 8c4cd69443
commit 44090c1d6d
13 changed files with 940 additions and 12 deletions

69
docs/cli/v4l2_view_cli.md Normal file
View File

@@ -0,0 +1,69 @@
# v4l2_view_cli
A live camera viewer. Opens a V4L2 capture device, selects the best available format, and displays the video stream in an X11 window with a real-time FPS and format overlay. Bypasses the node system entirely — useful for verifying a camera works before wiring it into a node.
---
## Build
From the repository root:
```sh
make cli
```
The binary is placed in `build/cli/`.
Requires GLFW, OpenGL, libjpeg-turbo, and a V4L2-capable kernel.
---
## Usage
```sh
./v4l2_view_cli [--device PATH]
[--width N --height N]
[--format mjpeg|yuyv]
[--scale stretch|fit|fill|1:1]
[--anchor center|topleft]
[--x N] [--y N]
```
| Option | Default | Description |
|---|---|---|
| `--device PATH` | `/dev/video0` | V4L2 device to open |
| `--width N` | auto | Capture width; if omitted, selects highest-FPS mode |
| `--height N` | auto | Capture height |
| `--format` | auto | Prefer `mjpeg` or `yuyv`; auto selects best available |
| `--scale` | `fit` | Frame scaling in window |
| `--anchor` | `center` | Frame alignment in window |
| `--x N` | `0` | Window X position |
| `--y N` | `0` | Window Y position |
Press **Q** or **Escape** to close the window.
### Auto format selection
Without `--width`/`--height`, the tool selects the format with the highest frame rate, and within that the largest resolution. This is the same logic the node's ingest module uses.
### Overlay
Every 0.5 seconds the overlay updates with:
```
MJPEG 1280x720 @ 30.0 fps
```
### Example
```sh
./v4l2_view_cli --device /dev/video0 --scale fit
```
---
## Relationship to the Video Routing System
`v4l2_view_cli` is a standalone sanity-check tool. It exercises the same V4L2 format enumeration, mmap capture, MJPEG decode, and xorg rendering path that the node's ingest + display pipeline uses — but without any transport or protocol overhead.
See also: [`stream_send_cli.md`](stream_send_cli.md) to capture and send over the network; [`xorg_cli.md`](xorg_cli.md) for static test patterns.