Epic: #113 · Milestone: MC0 — Product & decisions
Why
Every Pi gate in this plan is "measured on real hardware from the Mac". .github/workflows/pi-hardware-test.yml pretends to do this but its scripts probe the host Linux (/dev/fb0, /sys/class/graphics) on a Raspberry Pi OS runner and never touch a HomeOS image. We need a real, repeatable rig first.
Bill of materials (one rig)
| Item | Purpose |
|---|---|
| Raspberry Pi 5 8 GB (a 4 GB unit as second device later) | target |
| Official 27 W USB-C PSU | required for USB/NVMe current |
| Raspberry Pi Debug Probe + 3-pin JST-SH cable | UART console on the dedicated debug connector (no GPIO wiring, works while the bootloader is running) |
| micro-HDMI → HDMI cable ×2 | TV + capture |
| USB UVC HDMI capture dongle (1080p60 class, with audio) | screenshot/audio capture for display and sound gates |
| Smart plug with a local API, or USB relay board | power-cycle from the host |
| microSD 32 GB A2 + USB reader (optional: SD mux) | boot media |
| USB 3 flash drive with the test-media corpus | local playback tests |
| Ethernet cable to the same switch as the Mac | TFTP netboot + NAS tests |
| CEC-capable TV or a USB-CEC adapter | remote tests |
| Optional: NVMe HAT + small NVMe; Bluetooth remote; IR receiver + remote | later milestones |
Tasks
- Buy/collect the BOM; document serial numbers and the Pi's EEPROM bootloader version.
- Wire and photograph the rig; document in
docs/testing/PI5_RIG.md. - Host setup on the Mac:
screen/picocomon the Debug Probe,tftpd(macOS built-in launchd service serving/private/tftpboot), capture viaffmpeg -f avfoundationor the OS-native capture API, power control script. - Put the Pi's EEPROM into network-first boot (
BOOT_ORDER=0xf12,TFTP_IP=<mac>) so an iteration is: build → copy to/private/tftpboot/→ power-cycle → read serial. No SD swapping. - Write
scripts/pi/helpers:pi-power.sh {on,off,cycle},pi-serial.sh(capture to file with timeout),pi-capture.sh(grab one HDMI frame as PNG, N seconds of audio as WAV),pi-deploy.sh(stage boot dir to TFTP root). - Smoke test the rig with the assembly-only UART banner from #57 (assembly is allowed for boot code) — this is the first thing that ever runs on the Pi.
Acceptance
scripts/pi/pi-cycle-and-capture.sh power-cycles the Pi, boots the staged image over TFTP, records serial output for 30 s, saves one HDMI frame, and exits 0 — run from the Mac with one command.