video-setup/docs/cli/controller_cli.md

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:

make cli

The binary is placed in build/cli/. Requires libreadline.

---

Usage

./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 <device_index>

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 <device_index> <control_id_hex>
set-control <device_index> <control_id_hex> <value>

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 <stream_id> <device_path> <dest_host> <dest_port>
             [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 <stream_id>

---

Display (sink node)

start-display <stream_id> [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 <stream_id>

---

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 for a simpler read-only query; stream_send_cli.md / stream_recv_cli.md for testing streams without a full node.