63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
|
# 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:<port>/ # 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.
|