From 185e0ac3901ede1956fd835669221bcc53f0c49e Mon Sep 17 00:00:00 2001 From: Mikkeli Date: Wed, 5 Aug 2026 23:16:25 +0900 Subject: [PATCH] Document the project, the hardware, and the camera that is not there yet MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README records the real starting state rather than an aspirational one: the camera module is NOT detected. rpicam-hello reports no cameras and dmesg has no sensor probe lines at all, while camera_auto_detect=1 is already set and the libcamera userland is fully installed. Silence in dmesg is the diagnostic — a sensor that is seen but misconfigured still probes — so this is cabling, not config, and the doc says so instead of sending anyone to edit dtoverlay lines. Also records the trap that /dev/video* nodes already exist on this Pi and belong to the codec and ISP blocks, so they are not evidence of a camera. AGENTS.md gives Codex the project-specific rules: it runs ON the target, so it should test rather than reason about whether something would run; it must not try to fix the camera in software; and claims about the stream need a command that ran, because a 200 with no frames looks exactly like a working one. --- AGENTS.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..15bcb86 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# Working in this repo + +Project instructions for Codex on `pi5`. The client-wide prompt lives in `~/.codex/AGENTS.md`; this +file is the project-specific part. + +## Where you are + +**You are running on the target hardware.** `pi5` is the Raspberry Pi 5 this software is *for*, so +you can test against the real camera, the real CPU and the real network — there is no emulation step +and no deploy step. Use that: prefer running the thing over reasoning about whether it would run. + +Call `platform_info` if you need to confirm which machine you are on. It is client-local and reports +this Pi, not `halogen`. + +## The camera is not detected yet + +`rpicam-hello --list-cameras` reports **"No cameras available!"**, and `dmesg` has no sensor probe +lines. See README.md for the diagnosis. + +⚠ **This is a hardware/cabling problem, and you cannot fix it from software.** Do not add +`dtoverlay=` lines, edit `/boot/firmware/config.txt`, or install packages to try to make it appear — +`camera_auto_detect=1` is already correct, and a silent `dmesg` means the sensor is not being reached +electrically. Report the state and ask the operator to reseat the cable. + +⚠ **Do not take `/dev/video*` as proof of a camera.** Those nodes are the Pi's codec and ISP blocks +and exist with nothing attached. + +Until a sensor appears, work that does not depend on live capture is still available: the web UI +shell, the streaming plumbing against a test pattern or a still image, project structure, tests. +**Say plainly when you are working against a placeholder** rather than a real frame. + +## Constraints + +- **Python 3 with `picamera2`** is the expected capture path once a sensor exists. It is not + installed yet; install it via `apt` (`python3-picamera2`), not `pip` — it binds to system + libcamera, and the pip build will not match. +- **Do not commit captured images or video.** Frames of a real room are not test fixtures. If a + fixture is genuinely needed, generate a synthetic one. +- This is a **4-core Pi 5**. Face recognition must run on downscaled frames and off the capture + thread; a per-frame full-resolution model will not hold a live stream. +- Prefer the **stdlib and system packages** over adding dependencies. Every dependency here is one + more thing that has to build on aarch64. + +## Verifying your work + +Claims about the camera or the stream must be backed by a command that ran: + +```bash +rpicam-hello --list-cameras # is a sensor present at all +dmesg | grep -iE 'imx|ov5647|cfe' # did it probe +curl -sI http://localhost:/ # is the server actually serving +``` + +⚠ **The absence of an error is not evidence something works.** A stream endpoint that returns 200 +with no frames, and a working one, look identical to `curl -o /dev/null`. Check what came back. + +## Git + +The remote is Gitea at `192.168.2.199:3005`, reachable from this Pi over SSH on port 2222. + +⚠ **`tea` (the Gitea CLI) is denied by policy** and is blocked by a `PreToolUse` hook. Ordinary +`git` is fine. **Do not push** unless the operator asks — commit locally and say what is ready. diff --git a/README.md b/README.md index daf7c21..2563df8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,71 @@ # pi5-camera-webui -Raspberry Pi 5 camera service: live MJPEG/WebRTC feed with a web UI, later face recognition. Codex-driven development on pi5. \ No newline at end of file +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.** So check the physical +connection before changing any config: + +1. The Pi 5 has **two CAM/DISP connectors, and they are interchangeable in shape** — a camera in a + DISP port looks correctly seated and will never appear. +2. Ribbon **orientation**: contacts face the correct side at both ends (the board end and the camera + end are not the same way round). +3. The connector latch is fully seated at both ends. +4. The Pi 5 uses the **narrower 22-pin** connector — a 15-pin camera cable needs an adapter. + +Power off before reseating. Re-check with: + +```bash +rpicam-hello --list-cameras # should list a sensor +dmesg | grep -iE 'imx|ov5647|cfe' +``` + +⚠ **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.