Mikkeli
55b7a6f6d9
Written as a Pi 5 project because that is where the first camera went. That was never the destination — the camera is meant for an Orin Nano, and the Pi was convenient and available first. ⚠ This is not a wording change. The two boards do not share a camera stack: libcamera/picamera2 on the Pi, V4L2/GStreamer with Argus for CSI Bayer sensors on the Jetson. Code written directly against picamera2 does not run on the Orin at all. So capture goes behind an interface with a backend per platform, chosen at runtime from what the hardware reports, and everything above it depends only on "a source of frames". Recorded as the main design constraint rather than left to be discovered when the code moves. The same split decides where face recognition can live: TensorRT on GPU/DLA on the Orin, CPU-only on the Pi. The Pi proves the pipeline, never the performance, and AGENTS.md now requires a measurement to say which board it came from. Also generalises the camera-not-detected section to cover both boards, and keeps the cable notes that cost a module: the Pi 5's 22-pin FPC versus 15-pin Pi 4-era cables, and that Jetson carriers use their own pinout, so a cable fitting a Pi does not necessarily carry the same signals. Status corrected to "no camera connected anywhere" — the first module's cable is confirmed faulty and the module may be damaged; a second is being tried on an Orin.
79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
# Working in this repo
|
|
|
|
Project instructions for Codex. The client-wide prompt lives in `~/.codex/AGENTS.md`; this file is
|
|
the project-specific part.
|
|
|
|
## Know which board you are on
|
|
|
|
This project spans **two different single-board computers with incompatible camera stacks**, and
|
|
Codex is installed on both. Getting this wrong produces code that runs where you tested it and
|
|
nowhere else.
|
|
|
|
- **Jetson Orin Nano** — the *target*. L4T / JetPack, CUDA, TensorRT. V4L2 / GStreamer, with Argus
|
|
(`nvarguscamerasrc`) for CSI Bayer sensors.
|
|
- **Raspberry Pi 5** — the *test platform*. libcamera / `rpicam` / `picamera2`. CPU-only inference.
|
|
|
|
**Call `platform_info` before writing anything platform-specific.** It is client-local and reports
|
|
the machine you are actually on, not `halogen`. Do not infer the board from the fact that both are
|
|
aarch64 — that is the one thing they have in common.
|
|
|
|
⚠ **Code written directly against `picamera2` will not run on the Orin.** Put capture behind an
|
|
interface with a backend per platform, selected at runtime from what the hardware reports. Everything
|
|
above capture — streaming, UI, recognition — depends only on "a source of frames".
|
|
|
|
⚠ **The Pi proves the pipeline, never the performance.** Face recognition on the Orin goes through
|
|
TensorRT on GPU/DLA; on the Pi it is CPU-only and will not hold a live stream. Never present a Pi
|
|
timing as evidence the target is fast enough, and say which board a measurement came from.
|
|
|
|
## No camera is connected yet
|
|
|
|
No working camera has been attached to either board. The first module was not detected on the Pi 5 at
|
|
all — traced to a cable fault, with the module possibly damaged too. See README.md for the evidence
|
|
and the check commands.
|
|
|
|
⚠ **You cannot fix camera detection from software.** Do not add `dtoverlay=` lines, edit
|
|
`/boot/firmware/config.txt`, or install packages to make a sensor appear. On the Pi,
|
|
`camera_auto_detect=1` is already correct; a silent `dmesg` and a missing i2c bus mean the sensor is
|
|
not being reached electrically. Report the state and stop.
|
|
|
|
⚠ **`/dev/video*` is not evidence of a camera** — those nodes exist on both boards with nothing
|
|
attached.
|
|
|
|
Work that does not need live capture is still available: the capture interface and a synthetic or
|
|
still-image backend, the streaming plumbing, the web UI, project structure, tests. **Say plainly when
|
|
you are working against a placeholder** rather than a real frame.
|
|
|
|
## Constraints
|
|
|
|
- **Install capture libraries from system packages, not pip.** `python3-picamera2` on the Pi; the
|
|
Jetson camera stack ships with L4T. Both bind to system libraries and a pip build will not match.
|
|
- **Do not commit captured images or video.** Frames of a real room are not test fixtures. Generate a
|
|
synthetic fixture if one is genuinely needed.
|
|
- Keep dependencies few. Everything here has to build on aarch64, and on the Jetson it has to
|
|
coexist with a vendor-pinned CUDA and Python.
|
|
- Face recognition runs on **downscaled frames, off the capture thread**.
|
|
|
|
## Verifying your work
|
|
|
|
Claims about hardware, the stream, or performance need a command that ran:
|
|
|
|
```bash
|
|
# is a sensor present
|
|
rpicam-hello --list-cameras # Pi 5
|
|
v4l2-ctl --list-devices # Orin
|
|
|
|
# is the server actually serving frames
|
|
curl -sI http://localhost:<port>/
|
|
```
|
|
|
|
⚠ **The absence of an error is not evidence that something works.** A stream endpoint returning 200
|
|
with no frames and a working one are indistinguishable to `curl -o /dev/null` — check what actually
|
|
came back. The same applies to a capture backend that constructs cleanly and yields nothing.
|
|
|
|
## Git
|
|
|
|
The remote is Gitea at `192.168.2.199:3005`, reachable over SSH on port 2222.
|
|
|
|
⚠ **`tea` (the Gitea CLI) is denied by policy** and blocked by a `PreToolUse` hook. Ordinary `git` is
|
|
fine. **Do not push** unless the operator asks — commit locally and say what is ready.
|