From 1066f793e2660209a3295153c17a7671c4814a09 Mon Sep 17 00:00:00 2001 From: mikael-lovqvists-claude-agent Date: Sun, 29 Mar 2026 21:55:43 +0000 Subject: [PATCH] docs: sync docs with code; fix Makefile modules target Makefile: - Add reconciler and ingest to the `modules` target; they were only built as side-effects of `make node`, making `make modules` incomplete planning.md: - Add 4 missing CLI drivers: discovery_cli, config_cli, protocol_cli, query_cli (all existed in code and dev/cli/Makefile but were absent) - Add header-only utilities table: stream_stats.h, v4l2_fmt.h README.md: - Add transport_cli, discovery_cli, config_cli, protocol_cli, query_cli to CLI tools list conventions.md: - Add ERR_NOT_FOUND to Error_Code enum example - Replace placeholder Invalid_Error_Detail with actual fields (config_line, message) that have been in use since config module - Add missing error macros: APP_INVALID_ERROR, APP_INVALID_ERROR_MSG, APP_NOT_FOUND_ERROR - Update directory structure: node/ description (was "later"), add web/ and tools/ entries Co-Authored-By: Claude Sonnet 4.6 --- Makefile | 2 ++ README.md | 7 ++++++- conventions.md | 33 +++++++++++++++++++-------------- planning.md | 13 +++++++++++++ 4 files changed, 40 insertions(+), 15 deletions(-) diff --git a/Makefile b/Makefile index 7d35dea..a6517f0 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,8 @@ modules: $(MAKE) -C src/modules/protocol $(MAKE) -C src/modules/test_image $(MAKE) -C src/modules/xorg + $(MAKE) -C src/modules/reconciler + $(MAKE) -C src/modules/ingest cli: modules $(MAKE) -C dev/cli diff --git a/README.md b/README.md index 48af721..f450d97 100644 --- a/README.md +++ b/README.md @@ -15,13 +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 a running node; supports enum-devices, enum-controls, get/set-control, start/stop-ingest, start/stop-display +- `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 ## Structure diff --git a/conventions.md b/conventions.md index 5e9e437..0970981 100644 --- a/conventions.md +++ b/conventions.md @@ -77,9 +77,10 @@ Errors are returned as `struct App_Error` values. Functions that can fail return /* modules/common/error.h */ typedef enum Error_Code { - ERR_NONE = 0, - ERR_SYSCALL = 1, /* errno is meaningful */ - ERR_INVALID = 2, + ERR_NONE = 0, + ERR_SYSCALL = 1, /* errno is meaningful */ + ERR_INVALID = 2, + ERR_NOT_FOUND = 3, } Error_Code; struct Syscall_Error_Detail { @@ -87,7 +88,8 @@ struct Syscall_Error_Detail { }; struct Invalid_Error_Detail { - /* fields added as concrete cases arise */ + int config_line; /* source line number, or 0 if not applicable */ + const char *message; /* static string describing what was wrong */ }; struct App_Error { @@ -110,16 +112,17 @@ struct App_Error { #define APP_IS_OK(e) \ ((e).code == ERR_NONE) -#define APP_ERROR(error_code, detail_field, ...) \ - ((struct App_Error){ \ - .code = (error_code), \ - .file = __FILE__, \ - .line = __LINE__, \ - .detail = { .detail_field = { __VA_ARGS__ } } \ - }) - #define APP_SYSCALL_ERROR() \ - APP_ERROR(ERR_SYSCALL, syscall, .err_no = errno) + /* sets ERR_SYSCALL + captures errno */ + +#define APP_INVALID_ERROR() \ + /* sets ERR_INVALID, no message */ + +#define APP_INVALID_ERROR_MSG(cfg_line, msg) \ + /* sets ERR_INVALID with config_line and message */ + +#define APP_NOT_FOUND_ERROR() \ + /* sets ERR_NOT_FOUND */ ``` ### Presentation @@ -140,11 +143,13 @@ video-setup/ modules/ - translation units; each has a .c and a Makefile common/ - shared types (error, base definitions); no external dependencies / - node/ - video node entry point and integration (later) + node/ - video node binary (source + display sink roles) include/ - public headers (.h files) dev/ - development aids; not part of the final deliverable cli/ - exploratory CLI drivers, one per module + web/ - development web UI (Node.js/Express) experiments/ - freeform experiments + tools/ - build-time code generators (e.g. gen_font_atlas) tests/ - automated tests (later) Makefile - top-level build ``` diff --git a/planning.md b/planning.md index 11321de..49642e7 100644 --- a/planning.md +++ b/planning.md @@ -84,6 +84,10 @@ Each module gets a corresponding CLI driver that exercises its API and serves as | `media_ctrl_cli` | `media_ctrl` | List media devices, show topology, configure pad formats | | `v4l2_ctrl_cli` | `v4l2_ctrl` | List controls, get/set values — lightweight `v4l2-ctl` equivalent | | `transport_cli` | `transport` | Send/receive framed messages, inspect headers | +| `discovery_cli` | `discovery` | Announce and discover peers over UDP multicast; print found/lost events | +| `config_cli` | `config` | Load an INI config file and print the resolved values after applying schema defaults | +| `protocol_cli` | `protocol` | Send and receive typed protocol messages; inspect frame payloads | +| `query_cli` | `discovery` + `protocol` | Wait for first discovered node, send ENUM_DEVICES, print results — integration smoke test | | `test_image_cli` | `test_image` | Generate test patterns, write PPM for visual inspection | | `xorg_cli` | `xorg` | Display test pattern in viewer window; exercises scale/anchor modes and text overlays | | `v4l2_view_cli` | V4L2 + `xorg` | Live camera viewer — auto-selects highest-FPS format, FPS/format overlay; bypasses node system | @@ -92,6 +96,15 @@ Each module gets a corresponding CLI driver that exercises its API and serves as | `reconciler_cli` | `reconciler` | Simulated state machine experiment — define resources with fake transitions, drive reconciler via CLI commands; validates the generic reconciler before wiring into the node | | `controller_cli` | `transport` + `protocol` + `discovery` | Interactive controller REPL — connects to nodes by peer index or host:port; supports enum-devices, enum-controls, get/set-control, start-ingest, stop-ingest, start-display, stop-display; readline + discovery integration; **temporary dev tool** — will be superseded by a dedicated `controller` binary that holds simultaneous connections to all peers | +### Header-only utilities (`include/`) + +Not modules (no `.c` or Makefile) but public interfaces used across CLI tools and the node: + +| Header | Used by | Notes | +|---|---|---| +| `stream_stats.h` | `stream_send_cli`, `stream_recv_cli` | Per-stream rolling fps/Mbps stats; single-header, no dependencies | +| `v4l2_fmt.h` | `ingest`, `v4l2_view_cli` | V4L2 format enumeration — (pixfmt, size, fps) combinations, best-format selection | + ### Web UI (`dev/web/`) A Node.js/Express development web UI that connects to running video nodes as a binary protocol peer. Exposes V4L2 control inspection and adjustment, media topology view, and stream state through a browser interface. Supports live peer discovery via SSE — discovered nodes appear automatically in the UI.