In short
pi-build is a tool for creating preconfigured Raspberry Pi images. It starts from a Raspbian base image and uses a manifest describing a device role to produce an image ready to flash to an SD card. A Pi booted from that image can start doing its job without any manual setup on the device.
What varied
The images shared a core setup rather than one network configuration. The core
module installed a known SSH public key, so every device could be accessed the same
way once it was reachable. Where it was included, boot-report wrote startup diagnostics to the FAT
boot partition, so we could pull an SD card and read its logs without mounting the
Linux filesystem.
The network and software dependencies varied by role. The videosync system used a lite variant of Raspbian with mpv, while the arcade required a full graphical environment.
Payloads and modules
A payload described one deployable kind of image: the server, a Zero client, or the arcade. Its manifest listed the reusable modules that ran while the image was being built.
Once we had MQTT broker and telemetry modules, we could add telemetry to the other payloads by updating their manifests and rebuilding the images. After reflashing, they all reported to the broker.
server
core
Configures the baseline OS and installs the known SSH public key used to access every device.
tailscale
Joins the server to the tailnet at first boot for remote access.
mqtt-broker
Installs the Mosquitto broker used by the fleet.
mqtt-broker-tailnet
Advertises the broker as a service on the tailnet.
boot-report
Writes service, network, and journal diagnostics to the FAT boot partition after startup.
mqtt-telemetry
Publishes device health, status, and version information to the broker.
mqtt-dashboard
Serves the fleet status page from telemetry received by the broker.
aether-archiver
Records the MQTT event stream to JSONL for later inspection.
hostapd-ap
Creates the private wifi network used by the videosync clients.
flicd
Runs the BLE daemon for the show's physical buttons.
videosync-server
Installs the playback coordinator, operator interface, time source, and venue-wifi profile.
zero
core
Configures the baseline OS and installs the known SSH public key used to access every device.
boot-report
Writes service, network, and journal diagnostics to the FAT boot partition after startup.
mqtt-telemetry
Publishes device health, status, and version information to the broker.
cluster-client
Joins the private cluster network, synchronizes time, and assigns the client hostname.
videosync-client
Installs mpv, the playback client, its service, and the baked video files.
arcade
core
Configures the baseline OS and installs the known SSH public key used to access every device.
wifi
Adds the configured venue wifi profile.
desktop-kiosk
Sets up the graphical environment and automatic kiosk login.
mqtt-telemetry
Publishes device health, status, and version information to the broker.
arcade
Installs the game, Chromium launcher, overlay filesystem, and CRT display tuning.
Why I built it
I started with two kinds of Raspberry Pi image: the videosync server and client. The arcade required a third. A separate Pi in the phonebooth ran someone else's code and did not need to join this system until we later added telemetry.