# media_ctrl_cli

A development tool for exploring and configuring the Linux Media Controller pipeline. It wraps the `media_ctrl` module and provides a command-line interface to the Media Controller API (`/dev/media*`).

This tool is the counterpart to `media-ctl` from the `v4l-utils` package. It covers the same ground but is built on our own `media_ctrl` translation unit.

---

## Build

From the repository root:

```sh
make
```

Or from `dev/cli/` directly:

```sh
make media_ctrl_cli
```

The binary is placed in `dev/cli/`.

---

## Commands

### `list`

Enumerate all media devices present on the system.

```sh
./media_ctrl_cli list
```

Example output:

```
Media devices:
  /dev/media0
  /dev/media1
```

---

### `info <device>`

Show identification information for a media device.

```sh
./media_ctrl_cli info /dev/media0
```

Example output:

```
Device:          /dev/media0
Driver:          unicam
Model:           unicam
Serial:
Bus info:        platform:fe801000.csi
Media version:   5.15.0
Hardware rev:    0x00000000
Driver version:  5.15.0
```

---

### `topology <device>`

Show the full pipeline topology: all entities, their pads, and all links between them. This is the main tool for understanding how a camera pipeline is structured.

```sh
./media_ctrl_cli topology /dev/media0
```

Example output on a Raspberry Pi with an IMX477 camera:

```
Device: unicam (/dev/media0)

  Entity 1: imx477 4-001a
    type:  v4l2-subdev (0x00020001)
    flags: 0x00000000
    pads:  1   links: 1
      pad 0: source
      link: entity 1 pad 0  ->  entity 2 pad 0  [enabled]

  Entity 2: unicam-image
    type:  devnode (0x00010001)
    flags: 0x00000000
    pads:  1   links: 1
    device: 81:1
      pad 0: sink
      link: entity 1 pad 0  ->  entity 2 pad 0  [enabled]
```

Each entity shows:
- **type** — the kernel entity function code and its human-readable name
- **pads** — each pad with its direction (source or sink)
- **links** — connections to other entity pads, with enabled/disabled state and whether the link is immutable

---

### `set-link <device> <src_entity>:<src_pad> <sink_entity>:<sink_pad> <0|1>`

Enable or disable a link between two pads. Entity IDs and pad indices are the numeric values shown in the `topology` output.

```sh
# Enable a link
./media_ctrl_cli set-link /dev/media0 1:0 2:0 1

# Disable a link
./media_ctrl_cli set-link /dev/media0 1:0 2:0 0
```

Immutable links cannot be changed and will return an error.

---

## Relationship to the Video Routing System

`media_ctrl_cli` exercises the `media_ctrl` module, which is used in the video routing system for:

- **Remote device enumeration** — a connecting node can query the media topology of a remote host to discover available cameras before opening any streams
- **Pipeline configuration** — setting pad formats and enabling links is required before a V4L2 capture node can be used, particularly on platforms like the Raspberry Pi where the sensor and capture node are separate media entities

See also: [`v4l2_ctrl_cli.md`](v4l2_ctrl_cli.md) for runtime camera parameter control.