Epic: #113 · Milestone: MC9 — Ship
Why
The four Pi 5 docs (INSTALL_RPI5.md, RASPBERRY_PI_5.md, PI5_HARDWARE_MATRIX.md, QUICK_START_RPI5.md) describe target behaviour under a banner. The playbook is the measured procedure: every stage names the command, the expected serial/capture output, the pass criterion, and the issue that unblocks it. The initial content is the step-by-step in the epic #113; this issue keeps it current as gates land.
Tasks
- Stage 0 — Host setup (macOS):
brew install zig qemu, build the Home compiler (cd ~/Code/Home/lang && zig build -Doptimize=ReleaseSafe, version pinned inscripts/zig-version.txt),export HOME_REPO=~/Code/Home/lang, Debug Probe serial (screen /dev/tty.usbmodem* 115200), enable macOStftpd, capture dongle check. - Stage 1 — Rig smoke: assembly UART banner (
build.sh rpi5 --profile=smoke) → SD or TFTP → power → banner on serial. - Stage 2 — Home kernel on serial:
--profile=serial→ milestones → shell commands →boot-pi5-serialscript. - Stage 3 — Storage/network:
sdround-trip,lspci,usb,dhcp,ping. - Stage 4 — Display/audio:
fb-pi5-first-pixel, HVS test pattern,tone→ capture FFT. - Stage 5 — Media: reference clips from USB and NAS, gates, soak.
- Stage 6 — Product: flash the image, onboarding, CEC, phone remote, OTA round-trip, recovery.
- Troubleshooting table: no bootloader output (EEPROM/
uart_2ndstage), rainbow/blank screen, image not loaded (kernel=name, DTB missing), EL mismatch, no network (link LEDs, PHY), HDMI no signal (EDID, mode), audio silent (N/CTS), capture dongle quirks. - Realign the four docs: shrink to pointers at the playbook and status page; keep the ASPIRATION banner where measurement is missing.
Acceptance
A new contributor with the BOM reproduces Stage 1–2 from the doc alone; each later stage is updated in the PR that turns its gate green.
Size: S · Depends on: #48 · Blocks: —