# 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 <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`](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.