Skip to content

Retro box — build runbook (operator-side)

Goal: retire the fm Pi 4 from Foyer audio duty (replaced by a Sonocotta HiFi-ESP32) and rebuild it as a Batocera handoff console (hostname retrobox) mirroring av's emulation library.

Order of operations

  1. Foyer replacement first — flash the third Sonocotta board: eh.fmm.house → "Foyer Speakers" (foyer-speakers-esp) → Install → USB. It self-registers with MA. Verify audio, THEN retire fm: ssh fm 'sudo systemctl disable --now sendspin-player sendspin-watchdog.timer' Remove fm's HA entities/areas afterward.
  2. Flash Batocera: RPi Imager → Other specific-purpose OS → Batocera (or image from batocera.org/download, rpi4 build) onto the SD card. Keep the fm SD card intact as fallback until the box proves out.
  3. First boot: HDMI + ethernet + power. Find its IP (AdGuard leases or the Batocera main menu → Network Settings).
  4. Provision: bash provision.sh <ip> — sets hostname retrobox, syncs the 11 GB library from av (GB/GBC/GBA/NES/SNES/N64/PSX/Genesis→megadrive), installs the docs site + custom.sh server, reboots.
  5. Controller: pair the spare pad (Batocera's autoconfig is good; the Stratus+ MAC-rotation quirk from av's notes applies to Bluetooth pairing — re-pair after battery pulls).
  6. Verify: one game per system; N64 spot-checks (pick Mario 64 — if that stutters something's wrong; obscure titles stuttering is normal).
  7. Handoff kit: the box, its supply, the printed card with the QR (docs-qr.png → http://retrobox.local:8080), a controller.

Notes

  • Batocera has no user accounts: ssh root/linux always (stock default kept per decision 2026-07-07).
  • ROM dir mapping av→Batocera: "Sega Genesis"→megadrive, rest 1:1 lowercase.
  • Saves/states live in /userdata/saves — tell the recipient they survive updates and power pulls.
  • GameCube ("gc" skeleton on av) has no library and doesn't run on Pi 4 — excluded.

Pre-handoff scrub

Batocera stores Wi-Fi credentials in PLAINTEXT (batocera.conf + connman cache). Before gifting, over ssh:

batocera-settings-set wifi.enabled 0
batocera-settings-set wifi.ssid ""
batocera-settings-set wifi.key ""
rm -rf /userdata/system/connman/wifi_*

Also consider removing the authorized ssh key if the recipient shouldn't be remotely reachable by us: rm /userdata/system/ssh/authorized_keys (check path; key was added via ssh-copy-id 2026-07-07).