From 44090c1d6ddecca27c152997a0ac2dff221bca6f Mon Sep 17 00:00:00 2001 From: mikael-lovqvists-claude-agent Date: Mon, 30 Mar 2026 00:45:27 +0000 Subject: [PATCH] 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 --- README.md | 24 ++--- docs/cli/config_cli.md | 80 +++++++++++++++++ docs/cli/controller_cli.md | 172 ++++++++++++++++++++++++++++++++++++ docs/cli/discovery_cli.md | 53 +++++++++++ docs/cli/protocol_cli.md | 64 ++++++++++++++ docs/cli/query_cli.md | 64 ++++++++++++++ docs/cli/reconciler_cli.md | 83 +++++++++++++++++ docs/cli/stream_recv_cli.md | 67 ++++++++++++++ docs/cli/stream_send_cli.md | 64 ++++++++++++++ docs/cli/test_image_cli.md | 70 +++++++++++++++ docs/cli/transport_cli.md | 69 +++++++++++++++ docs/cli/v4l2_view_cli.md | 69 +++++++++++++++ docs/cli/xorg_cli.md | 73 +++++++++++++++ 13 files changed, 940 insertions(+), 12 deletions(-) create mode 100644 docs/cli/config_cli.md create mode 100644 docs/cli/controller_cli.md create mode 100644 docs/cli/discovery_cli.md create mode 100644 docs/cli/protocol_cli.md create mode 100644 docs/cli/query_cli.md create mode 100644 docs/cli/reconciler_cli.md create mode 100644 docs/cli/stream_recv_cli.md create mode 100644 docs/cli/stream_send_cli.md create mode 100644 docs/cli/test_image_cli.md create mode 100644 docs/cli/transport_cli.md create mode 100644 docs/cli/v4l2_view_cli.md create mode 100644 docs/cli/xorg_cli.md diff --git a/README.md b/README.md index f450d97..2f91936 100644 --- a/README.md +++ b/README.md @@ -15,18 +15,18 @@ Designed to run on resource-constrained hardware (Raspberry Pi capturing raw MJP - [docs/cli/media_ctrl_cli.md](docs/cli/media_ctrl_cli.md) — media device and topology tool - [docs/cli/v4l2_ctrl_cli.md](docs/cli/v4l2_ctrl_cli.md) — V4L2 camera control tool -- `transport_cli` — send/receive framed messages, inspect transport frame headers -- `discovery_cli` — announce and discover peers over UDP multicast; print found/lost events -- `config_cli` — load an INI config file and print the resolved values after applying schema defaults -- `protocol_cli` — send and receive typed protocol messages; inspect frame payloads -- `query_cli` — wait for first discovered node, send ENUM_DEVICES, print results -- `test_image_cli` — generate test patterns and write PPM output for visual inspection -- `xorg_cli` — display a test pattern in the viewer window; exercises scale/anchor modes and text overlays -- `v4l2_view_cli` — live camera viewer; auto-selects highest-FPS format, displays FPS overlay -- `stream_send_cli` — capture MJPEG from V4L2, connect to a receiver over TCP, stream VIDEO_FRAME messages with per-stream stats -- `stream_recv_cli` — listen for incoming TCP stream, display received MJPEG frames with fps/Mbps overlay -- `reconciler_cli` — simulated state machine experiment; validate the reconciler with fake resources before wiring into the node -- `controller_cli` — interactive REPL; connects to nodes by peer index or host:port; enum-devices, enum-controls, get/set-control, start/stop-ingest, start/stop-display +- [docs/cli/transport_cli.md](docs/cli/transport_cli.md) — send/receive framed messages, inspect transport frame headers +- [docs/cli/discovery_cli.md](docs/cli/discovery_cli.md) — announce and discover peers over UDP multicast; print found/lost events +- [docs/cli/config_cli.md](docs/cli/config_cli.md) — load an INI config file and print the resolved values after applying schema defaults +- [docs/cli/protocol_cli.md](docs/cli/protocol_cli.md) — send and receive typed protocol messages; inspect frame payloads +- [docs/cli/query_cli.md](docs/cli/query_cli.md) — wait for first discovered node, send ENUM_DEVICES, print results +- [docs/cli/test_image_cli.md](docs/cli/test_image_cli.md) — generate test patterns and write PPM output for visual inspection +- [docs/cli/xorg_cli.md](docs/cli/xorg_cli.md) — display a test pattern in the viewer window; exercises scale/anchor modes and text overlays +- [docs/cli/v4l2_view_cli.md](docs/cli/v4l2_view_cli.md) — live camera viewer; auto-selects highest-FPS format, displays FPS overlay +- [docs/cli/stream_send_cli.md](docs/cli/stream_send_cli.md) — capture MJPEG from V4L2, connect to a receiver over TCP, stream VIDEO_FRAME messages with per-stream stats +- [docs/cli/stream_recv_cli.md](docs/cli/stream_recv_cli.md) — listen for incoming TCP stream, display received MJPEG frames with fps/Mbps overlay +- [docs/cli/reconciler_cli.md](docs/cli/reconciler_cli.md) — simulated state machine experiment; validate the reconciler with fake resources before wiring into the node +- [docs/cli/controller_cli.md](docs/cli/controller_cli.md) — interactive REPL; connects to nodes by peer index or host:port; enum-devices, enum-controls, get/set-control, start/stop-ingest, start/stop-display ## Structure diff --git a/docs/cli/config_cli.md b/docs/cli/config_cli.md new file mode 100644 index 0000000..b399647 --- /dev/null +++ b/docs/cli/config_cli.md @@ -0,0 +1,80 @@ +# config_cli + +A development tool for loading and inspecting INI configuration files against the node's schema. Useful for verifying that a config file parses correctly and seeing what values would be applied. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +### Load a config file + +```sh +./config_cli +``` + +Parses the file and prints all resolved values. Values absent from the file are filled with schema defaults. + +Example: + +```sh +./config_cli /etc/video-node/node.cfg +``` + +Example output: + +``` +[node] + name = camera:0 + site_id = 0 + tcp_port = 8000 + function = source + +[discovery] + interval_ms = 5000 + timeout_intervals = 3 + +[transport] + max_connections = 16 +``` + +### Print schema defaults + +```sh +./config_cli --defaults +``` + +Prints all keys with their default values and types, without reading any file. + +--- + +## Config Schema + +| Section | Key | Type | Default | +|---|---|---|---| +| `node` | `name` | string | `unnamed:0` | +| `node` | `site_id` | uint16 | `0` | +| `node` | `tcp_port` | uint16 | `0` (auto) | +| `node` | `function` | flags | `source` | +| `discovery` | `interval_ms` | uint32 | `5000` | +| `discovery` | `timeout_intervals` | uint32 | `3` | +| `transport` | `max_connections` | uint32 | `16` | + +`function` accepts a comma-separated list of role flags: `source`, `relay`, `sink`, `controller`. + +--- + +## Relationship to the Video Routing System + +`config_cli` exercises the `config` module used by the video node at startup. Both the node binary and `config_cli` share the same schema definition, so this tool is an accurate preview of how the node will interpret a config file. diff --git a/docs/cli/controller_cli.md b/docs/cli/controller_cli.md new file mode 100644 index 0000000..723653c --- /dev/null +++ b/docs/cli/controller_cli.md @@ -0,0 +1,172 @@ +# controller_cli + +An interactive REPL for controlling video nodes. Connects to a running node over TCP and lets you enumerate devices and controls, adjust camera parameters, start and stop ingest streams, and open and close display windows. Uses readline for line editing and history. + +> **Note:** `controller_cli` is a temporary development tool. The long-term replacement is a dedicated `controller` binary that maintains simultaneous connections to all discovered nodes rather than switching between them. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. Requires `libreadline`. + +--- + +## Usage + +```sh +./controller_cli [--host HOST] [--port PORT] +``` + +| Option | Default | Description | +|---|---|---| +| `--host HOST` | — | Connect to this host on startup | +| `--port PORT` | `8000` | TCP port to use with `--host` | + +Without `--host`, the tool starts in discovery mode and waits for nodes to appear. Connect to a discovered node from the REPL using the `connect` command. + +--- + +## REPL Commands + +### Discovery + +``` +peers +``` + +List all currently discovered nodes with their index, name, host, and port. + +``` +connect [idx | host:port] +``` + +Connect to a node. With no argument, connects to the first discovered peer. Examples: + +``` +connect # first discovered peer +connect 1 # peer at index 1 in the peers list +connect 192.168.1.42:8000 +``` + +--- + +### Device enumeration + +``` +enum-devices +``` + +List all devices on the connected node: media controller devices and their video nodes (with device index), standalone V4L2 devices, and active display windows. Each entry shows its flat device index `[N]` for use in control commands. + +``` +enum-controls +``` + +List all controls for a device. For V4L2 devices this returns camera parameters; for display windows it returns display controls. + +**Display device controls:** + +| ID | Name | Range | Description | +|---|---|---|---| +| `0x00D00001` | Scale | 0–3 | 0=stretch 1=fit 2=fill 3=1:1 | +| `0x00D00002` | Anchor | 0–1 | 0=center 1=topleft | +| `0x00D00003` | No-signal FPS | 1–60 | No-signal animation frame rate | + +--- + +### Control get/set + +``` +get-control +set-control +``` + +Examples: + +``` +get-control 0 0x00980900 # read Brightness on device 0 +set-control 0 0x00980900 200 # set Brightness to 200 +set-control 3 0x00D00001 1 # set Scale to 'fit' on display device 3 +``` + +--- + +### Ingest (source node) + +``` +start-ingest + [format] [width] [height] [fps_n] [fps_d] +``` + +Tell the connected node to open a V4L2 device and stream to `dest_host:dest_port`. Format, resolution, and frame rate default to auto-select (best MJPEG) when omitted. + +``` +stop-ingest +``` + +--- + +### Display (sink node) + +``` +start-display [win_x] [win_y] [win_w] [win_h] [no_signal_fps] +``` + +Tell the connected node to open a display window for `stream_id`. Position and size default to `0,0 1280×720`. No-signal FPS defaults to 15. + +``` +stop-display +``` + +--- + +### Other + +``` +help show command list +quit exit +exit exit +``` + +--- + +## Example session + +``` +$ ./controller_cli +listening for nodes... +[discovered 0] camera:0 192.168.1.42:8000 +> connect +connected to 192.168.1.42:8000 +> enum-devices +devices: + media /dev/media0 driver=unicam model=unicam ... (1 video node) + [0] video /dev/video0 entity=unicam-image ... [capture] +> start-ingest 1 /dev/video0 192.168.1.55 8001 +ok +> connect 1 +[discovered 1] display:0 192.168.1.55:8000 +connected to 192.168.1.55:8000 +> start-display 1 +ok +> enum-devices +devices: + [3] display stream=1 pos=0,0 size=1280x720 scale=stretch anchor=center +> set-control 3 0x00D00001 1 +ok +``` + +--- + +## Relationship to the Video Routing System + +`controller_cli` is the primary human interface for the video routing system during development. It exercises the full control channel: discovery, TCP transport, and every protocol command type. It is the reference implementation for how a controller interacts with nodes. + +See also: [`query_cli.md`](query_cli.md) for a simpler read-only query; [`stream_send_cli.md`](stream_send_cli.md) / [`stream_recv_cli.md`](stream_recv_cli.md) for testing streams without a full node. diff --git a/docs/cli/discovery_cli.md b/docs/cli/discovery_cli.md new file mode 100644 index 0000000..bb50e8e --- /dev/null +++ b/docs/cli/discovery_cli.md @@ -0,0 +1,53 @@ +# discovery_cli + +A development tool for testing the UDP multicast discovery layer. Announces a node on the local network and prints peers as they appear and disappear. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +```sh +discovery_cli [flags] +``` + +| Argument | Description | +|---|---| +| `name` | Node name in `namespace:instance` form, e.g. `v4l2:microscope` | +| `tcp_port` | The TCP port this node listens on for transport connections | +| `flags` | Comma-separated role list: `source`, `relay`, `sink`, `controller` (default: `source`) | + +Example — announce a source node and watch for peers: + +```sh +./discovery_cli camera:0 8000 source +``` + +Example output as peers are found and lost: + +``` +found: unnamed:0 192.168.1.42:8001 site=0 flags=source +found: display:0 192.168.1.55:8002 site=0 flags=sink +lost: unnamed:0 192.168.1.42:8001 +``` + +Run two instances on the same machine (different ports) to verify mutual discovery. + +--- + +## Relationship to the Video Routing System + +`discovery_cli` exercises the `discovery` module, which the video node uses to find peers on the LAN without configuration. The node starts a discovery listener on startup; controllers use discovered peer tables to locate nodes before connecting. + +See also: [`query_cli.md`](query_cli.md) for a combined discovery + protocol query. diff --git a/docs/cli/protocol_cli.md b/docs/cli/protocol_cli.md new file mode 100644 index 0000000..7a64c0c --- /dev/null +++ b/docs/cli/protocol_cli.md @@ -0,0 +1,64 @@ +# protocol_cli + +A development tool for testing the protocol layer in isolation. Runs a server that decodes and prints all incoming control messages, or a client that connects and sends a sample STREAM_OPEN request. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +### Server mode + +```sh +./protocol_cli --server [port] +``` + +Default port: `8000`. Listens for connections and prints a decoded description of every received frame. + +Example output on an incoming STREAM_OPEN: + +``` +CONTROL_REQUEST request_id=1 STREAM_OPEN stream_id=1 format=0x0001 pixel_format=0x0000 origin=0x0001 +``` + +Recognised message types and commands: + +| Type | Description | +|---|---| +| `VIDEO_FRAME` | stream_id + compressed payload | +| `STREAM_EVENT` | stream_id + event code (INTERRUPTED / RESUMED) | +| `CONTROL_REQUEST` | request_id + command (STREAM_OPEN, STREAM_CLOSE, ENUM_DEVICES, ENUM_CONTROLS, GET_CONTROL, SET_CONTROL, ENUM_MONITORS) | +| `CONTROL_RESPONSE` | request_id + status (OK, ERROR, UNKNOWN_CMD, INVALID_PARAMS, NOT_FOUND) | + +### Client mode + +```sh +./protocol_cli --client +``` + +Connects to the server and sends a single STREAM_OPEN request, then waits for the response. + +Example: + +```sh +./protocol_cli --client 127.0.0.1 8000 +``` + +--- + +## Relationship to the Video Routing System + +`protocol_cli` exercises the `protocol` module that all nodes use to encode and decode wire messages. Pairing the server with a running node lets you inspect raw control traffic; pairing the client with a running node lets you inject individual commands for debugging. + +See also: [`transport_cli.md`](transport_cli.md) for raw frame-level testing without protocol parsing. diff --git a/docs/cli/query_cli.md b/docs/cli/query_cli.md new file mode 100644 index 0000000..be08743 --- /dev/null +++ b/docs/cli/query_cli.md @@ -0,0 +1,64 @@ +# query_cli + +An integration smoke test that combines discovery and protocol. Waits for a video node to appear on the local network, then sends an ENUM_DEVICES query and prints the results. Optionally enumerates controls on a specific device. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +```sh +./query_cli [--timeout ms] [--controls device_index] +``` + +| Option | Default | Description | +|---|---|---| +| `--timeout ms` | `5000` | How long to wait for a node to appear (milliseconds) | +| `--controls idx` | — | After enumeration, also query controls for this device index | + +Example — query the first node found within 5 s: + +```sh +./query_cli +``` + +Example output: + +``` +discovered: camera:0 192.168.1.42:8000 +querying devices... + media /dev/media0 driver=unicam model=unicam bus=platform:fe801000.csi (1 video node) + [0] video /dev/video0 entity=unicam-image type=0x00010001 caps=[video-capture] [capture] + [1] standalone /dev/video1 card=USB Camera +``` + +Example with controls: + +```sh +./query_cli --controls 1 +``` + +``` + ctrl id=0x00980900 Brightness int min=0 max=255 step=1 default=128 current=127 + ctrl id=0x00980901 Contrast int min=0 max=255 step=1 default=128 current=128 + ... +``` + +--- + +## Relationship to the Video Routing System + +`query_cli` is an end-to-end integration test: it exercises discovery, transport, and protocol in one shot. It is the simplest way to verify that a node is reachable and responding correctly to control requests before using `controller_cli` for full interaction. + +See also: [`discovery_cli.md`](discovery_cli.md), [`controller_cli.md`](controller_cli.md). diff --git a/docs/cli/reconciler_cli.md b/docs/cli/reconciler_cli.md new file mode 100644 index 0000000..770e304 --- /dev/null +++ b/docs/cli/reconciler_cli.md @@ -0,0 +1,83 @@ +# reconciler_cli + +An interactive REPL for exploring the reconciler module. Sets up a simulated three-resource state machine (device, transport, stream) with declared dependencies and lets you drive reconciliation manually — useful for understanding reconciler behaviour before wiring it into the node. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +```sh +./reconciler_cli +``` + +Drops into an interactive prompt: + +``` +reconciler> _ +``` + +### Demo resources + +Three resources are pre-configured: + +| Resource | States | Notes | +|---|---|---| +| `device` | CLOSED → OPEN → STREAMING | Simulates a V4L2 device | +| `transport` | DISCONNECTED → CONNECTED | Depends on device=OPEN | +| `stream` | INACTIVE → ACTIVE | Depends on transport=CONNECTED and device=STREAMING | + +Dependencies are checked before each transition: the reconciler will not advance a resource until all its prerequisites are met. Blocked resources show the unmet dependency in the status output. + +### Commands + +``` +status print all resources with current/wanted state and transition status +want set the desired state (by number or case-insensitive name) +tick run one reconciler tick +run tick until stable (max 20 ticks) or a failure occurs +fail make the next action for this resource fail (simulates an error) +help show commands +quit / exit exit +``` + +### Example session + +``` +reconciler> want device STREAMING +reconciler> want transport CONNECTED +reconciler> want stream ACTIVE +reconciler> run +[device] CLOSED → OPEN ok +[device] OPEN → STREAMING ok +[transport] DISCONNECTED → CONNECTED ok +[stream] INACTIVE → ACTIVE ok +reconciler> status +device current=STREAMING wanted=STREAMING +transport current=CONNECTED wanted=CONNECTED +stream current=ACTIVE wanted=ACTIVE +reconciler> fail transport +reconciler> tick +[transport] CONNECTED → DISCONNECTED error (simulated) +reconciler> status +device current=STREAMING wanted=STREAMING +transport current=DISCONNECTED wanted=CONNECTED (will retry) +stream current=ACTIVE wanted=ACTIVE (blocked: transport != CONNECTED) +``` + +--- + +## Relationship to the Video Routing System + +The reconciler module manages device open/close and transport connect/disconnect in the video node. `reconciler_cli` lets you exercise the BFS pathfinding, dependency checking, and event-driven tick logic without any real hardware — the same code paths that run in the node on every incoming command or timer event. diff --git a/docs/cli/stream_recv_cli.md b/docs/cli/stream_recv_cli.md new file mode 100644 index 0000000..2dccd0c --- /dev/null +++ b/docs/cli/stream_recv_cli.md @@ -0,0 +1,67 @@ +# stream_recv_cli + +Listens for an incoming TCP stream of `VIDEO_FRAME` protocol messages and displays the frames in an X11 window with a per-stream fps/Mbps overlay. Pair with [`stream_send_cli`](stream_send_cli.md) to test end-to-end video transport without a full node. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +Requires GLFW, OpenGL, and libjpeg-turbo. + +--- + +## Usage + +```sh +./stream_recv_cli [--port PORT] [--stream-id N] + [--scale stretch|fit|fill|1:1] + [--anchor center|topleft] + [--x N] [--y N] +``` + +| Option | Default | Description | +|---|---|---| +| `--port PORT` | `7700` | TCP port to listen on | +| `--stream-id N` | `0` | Filter by stream ID; `0` accepts any stream | +| `--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. + +### Example + +```sh +./stream_recv_cli --port 7700 --scale fit +``` + +### Statistics overlay + +Updated every 0.5 seconds: + +``` +stream 1: 30.1 fps 18.3 Mbps +``` + +--- + +## Architecture note + +The tool is multi-threaded: transport receive runs on a background thread and deposits frames into a shared slot (mutex + condition variable); the main thread owns the GLFW/OpenGL context and pulls from that slot on each render cycle. This is the same pattern used by the node's display sink. + +--- + +## Relationship to the Video Routing System + +`stream_recv_cli` tests the sink end of the display pipeline: `VIDEO_FRAME` receive → MJPEG decode → xorg render. The node's display sink (started via `START_DISPLAY`) performs the same operation, driven by the control channel. + +See also: [`stream_send_cli.md`](stream_send_cli.md) for the send side; [`controller_cli.md`](controller_cli.md) to use the full node pipeline. diff --git a/docs/cli/stream_send_cli.md b/docs/cli/stream_send_cli.md new file mode 100644 index 0000000..b5c3798 --- /dev/null +++ b/docs/cli/stream_send_cli.md @@ -0,0 +1,64 @@ +# stream_send_cli + +Captures MJPEG from a V4L2 device and streams it to a receiver over TCP as `VIDEO_FRAME` protocol messages. Prints per-stream throughput statistics. Pair with [`stream_recv_cli`](stream_recv_cli.md) to test an end-to-end stream without running a full node. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +```sh +./stream_send_cli [--device PATH] [--host HOST] [--port PORT] [--stream-id N] +``` + +| Option | Default | Description | +|---|---|---| +| `--device PATH` | `/dev/video0` | V4L2 capture device | +| `--host HOST` | `127.0.0.1` | Receiver hostname or IP | +| `--port PORT` | `7700` | Receiver TCP port | +| `--stream-id N` | `1` | Stream ID embedded in each `VIDEO_FRAME` message | + +### Example + +```sh +# Terminal 1 — start a receiver +./stream_recv_cli --port 7700 + +# Terminal 2 — start the sender +./stream_send_cli --device /dev/video0 --host 127.0.0.1 --port 7700 --stream-id 1 +``` + +### Statistics output + +Printed to stderr every 0.5 seconds: + +``` +stream 1: 30.2 fps 18.4 Mbps +``` + +--- + +## Notes + +- The tool opens the device and selects the highest-FPS MJPEG mode automatically. +- Frames are sent as-is (raw MJPEG from the kernel) wrapped in `VIDEO_FRAME` messages — no re-encoding. +- The connection is outbound: `stream_send_cli` connects to the receiver, not the other way around. This mirrors the node's START_INGEST behaviour. + +--- + +## Relationship to the Video Routing System + +`stream_send_cli` tests the source end of the ingest pipeline: V4L2 capture → transport send → `VIDEO_FRAME` messages. The node's ingest module performs the same operation, but driven by `START_INGEST` commands over the control channel. + +See also: [`stream_recv_cli.md`](stream_recv_cli.md) for the receive side; [`v4l2_view_cli.md`](v4l2_view_cli.md) for local-only viewing. diff --git a/docs/cli/test_image_cli.md b/docs/cli/test_image_cli.md new file mode 100644 index 0000000..d9d29ef --- /dev/null +++ b/docs/cli/test_image_cli.md @@ -0,0 +1,70 @@ +# test_image_cli + +A development tool for generating test images and writing them to PPM files. Used to verify the `test_image` module's pattern generators and pixel format output without needing a camera or display. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +```sh +./test_image_cli [--pattern bars|ramp|grid] + [--width N] [--height N] + [--format yuv420|yuv422|bgra] + --out FILE.ppm +``` + +All options are optional except `--out`. + +| Option | Default | Description | +|---|---|---| +| `--pattern` | `bars` | Test pattern to generate | +| `--width N` | `1280` | Image width in pixels | +| `--height N` | `720` | Image height in pixels | +| `--format` | `yuv420` | Internal pixel format before PPM conversion | +| `--out FILE` | required | Output file path | + +### Patterns + +| Name | Description | +|---|---| +| `bars` | Colour bars (SMPTE-style) | +| `ramp` | Luminance ramp from black to white | +| `grid` | Crosshatch grid | + +### Formats + +| Name | Description | +|---|---| +| `yuv420` | Planar YUV 4:2:0 | +| `yuv422` | Packed YUV 4:2:2 | +| `bgra` | Packed BGRA 8-bit | + +The output is always written as a PPM (RGB) file regardless of format; the internal format affects how the pattern is generated and converted. + +### Example + +```sh +./test_image_cli --pattern bars --width 1920 --height 1080 --format yuv420 --out bars.ppm +``` + +Open with any image viewer that supports PPM (e.g. `feh`, `eog`, GIMP). + +--- + +## Relationship to the Video Routing System + +`test_image_cli` exercises the `test_image` module used by development tools to inject synthetic frames without a camera. The same module drives the xorg test pattern display in `xorg_cli`. + +See also: [`xorg_cli.md`](xorg_cli.md) for live window rendering. diff --git a/docs/cli/transport_cli.md b/docs/cli/transport_cli.md new file mode 100644 index 0000000..1ec5ef1 --- /dev/null +++ b/docs/cli/transport_cli.md @@ -0,0 +1,69 @@ +# transport_cli + +A development tool for exercising the transport layer. Starts a framed-TCP server (which echoes received frames) or a client that connects and sends a sequence of test frames. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +--- + +## Usage + +### Server mode + +Listen on a port and echo back every frame received: + +```sh +./transport_cli server [max_connections] +``` + +Example: + +```sh +./transport_cli server 8000 +``` + +Output (per received frame): + +``` +received frame: type=0x0001 len=8 +``` + +### Client mode + +Connect to a server and send three test frames: + +```sh +./transport_cli client +``` + +Example: + +```sh +./transport_cli client 127.0.0.1 8000 +``` + +Each frame carries a fixed payload with a counter: + +``` +frame 0: payload = deadbeef 00000000 +frame 1: payload = deadbeef 00000001 +frame 2: payload = deadbeef 00000002 +``` + +--- + +## Relationship to the Video Routing System + +`transport_cli` exercises the `transport` module, which provides the framed TCP stream used by all node-to-node communication. The frame header (message type + payload length) and single-write send are the building blocks for the protocol layer. + +See also: [`protocol_cli.md`](protocol_cli.md) for typed message-level testing. diff --git a/docs/cli/v4l2_view_cli.md b/docs/cli/v4l2_view_cli.md new file mode 100644 index 0000000..d911cae --- /dev/null +++ b/docs/cli/v4l2_view_cli.md @@ -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. diff --git a/docs/cli/xorg_cli.md b/docs/cli/xorg_cli.md new file mode 100644 index 0000000..a36488e --- /dev/null +++ b/docs/cli/xorg_cli.md @@ -0,0 +1,73 @@ +# xorg_cli + +A development tool for testing the xorg viewer sink. Opens an X11 window using GLFW/OpenGL, renders a test pattern at the chosen scale and anchor, and displays a text overlay showing the current date. The window stays open until the user presses Q, Escape, or closes it. + +--- + +## Build + +From the repository root: + +```sh +make cli +``` + +The binary is placed in `build/cli/`. + +Requires the GLFW, OpenGL, and libjpeg-turbo libraries. If compiled without `HAVE_GLFW`, the binary will print an error and exit. + +--- + +## Usage + +```sh +./xorg_cli [--pattern bars|ramp|grid] + [--width N] [--height N] + [--format yuv420|bgra] + [--scale stretch|fit|fill|1:1] + [--anchor center|topleft] + [--x N] [--y N] +``` + +| Option | Default | Description | +|---|---|---| +| `--pattern` | `bars` | Test pattern to render | +| `--width N` | `1280` | Window width in pixels | +| `--height N` | `720` | Window height in pixels | +| `--format` | `yuv420` | Frame pixel format | +| `--scale` | `stretch` | How the frame fills the window | +| `--anchor` | `center` | Frame alignment within the window | +| `--x N` | `0` | Window X position on screen | +| `--y N` | `0` | Window Y position on screen | + +### Scale modes + +| Mode | Description | +|---|---| +| `stretch` | Fill the window, ignoring aspect ratio | +| `fit` | Largest rect that fits, preserving aspect ratio (black bars) | +| `fill` | Smallest rect that covers, preserving aspect ratio (crops edges) | +| `1:1` | Native pixel size, no scaling | + +### Anchor modes + +Anchor applies when the frame does not fill the window (fit, fill, 1:1 modes): + +| Mode | Description | +|---|---| +| `center` | Centre the frame in the window | +| `topleft` | Align frame to the top-left corner | + +### Example + +```sh +./xorg_cli --pattern grid --scale fit --anchor center --width 1920 --height 1080 +``` + +--- + +## Relationship to the Video Routing System + +`xorg_cli` exercises the `xorg` module used by the video node for its display sink role. The same viewer, scale/anchor logic, and text overlay system are used by `stream_recv_cli` and the node's `START_DISPLAY` command. + +See also: [`v4l2_view_cli.md`](v4l2_view_cli.md) for live camera feed display; [`stream_recv_cli.md`](stream_recv_cli.md) for network stream display.