camera-webui/README.md

# pi5-camera-webui

Camera service for a Raspberry Pi 5: a live video feed served over a small web UI, with face
recognition planned as a later stage.

Developed on the machine it runs on (`pi5`), with Codex as the coding client — see [AGENTS.md](AGENTS.md).

## Hardware

| | |
|---|---|
| Board | Raspberry Pi 5 Model B Rev 1.1 |
| OS | Debian 12 (bookworm), aarch64 |
| Camera | Pi camera module, connected to a CAM port |
| Host | `pi5`, `192.168.2.154` |

## ⚠ Current state: the camera is NOT detected

Nothing is built yet, and **the camera is not visible to the system**, so start here:

```console
$ rpicam-hello --list-cameras
No cameras available!
```

This is a *detection* problem, not a software one — the userland is already in place:

- `camera_auto_detect=1` is set in `/boot/firmware/config.txt` (the correct default; nothing to add)
- 12 `libcamera`/`rpicam` packages are installed
- **`dmesg` contains no camera probe lines at all** — no sensor (`imx*`, `ov5647`), no CFE

That last point is the diagnostic one. A camera that is seen but misconfigured still leaves probe
messages; **silence means the sensor is not being reached electrically.**

The imaging pipeline itself is fine, which narrows it further:

```console
$ lsmod | grep -iE 'pisp|cfe'
pisp_be                49152  0          # ISP backend loaded
$ ls /sys/bus/i2c/devices/
i2c-13  i2c-14                           # no camera i2c bus
```

`camera_auto_detect=1` probes the connectors at boot and loads a sensor overlay when it finds
something. **No sensor i2c bus was instantiated and no CFE bound**, so the firmware found nothing to
load an overlay for. Nothing in software will change that.

So check the physical connection, power off first:

1. The Pi 5 uses the **narrower 22-pin** FPC connector. Cameras from the Pi 4 era ship with a
   **15-pin** cable, which needs the 22-pin-to-15-pin adapter cable — this is the most common cause
   of a camera that is connected but invisible.
2. Ribbon **orientation**: contacts face the correct side at *each* end, and the two ends are not the
   same way round.
3. The connector latch is fully seated at both ends.
4. Try the **other connector** — the Pi 5 has two, `CAM/DISP 0` and `CAM/DISP 1`, and **both are
   dual-purpose**, so either accepts a camera. Swapping isolates a faulty port.

Re-check with:

```bash
rpicam-hello --list-cameras          # should list a sensor
dmesg | grep -iE 'imx|ov5647|cfe'    # should show a probe
ls /sys/bus/i2c/devices/             # a new bus should appear
```

⚠ **Do not treat `/dev/video*` as evidence the camera works.** Those nodes exist on this Pi already
and belong to the video codec and ISP blocks — they are present with no camera attached at all.

`picamera2` is **not** installed yet (`import picamera2` fails); it is the expected capture library
once a sensor is detected.

## Planned stages

1. **Capture** — confirm a sensor, grab a still, establish resolution/format.
2. **Live feed** — MJPEG stream first (simplest thing that works in a browser); WebRTC later if
   latency demands it.
3. **Web UI** — single page showing the live feed, plus basic controls.
4. **Face recognition** — detection first, recognition after; run it on a downscaled frame, not the
   full stream.

Each stage should be usable on its own before the next begins.

## Development

The model endpoint and MCP gateway live on `halogen` and are reachable from this Pi by name.
Codex is installed and configured here; see [AGENTS.md](AGENTS.md) for how it is expected to work in
this repo.