# Service Producer Display — Raspberry Pi appliance image

A complete flashable image for **Raspberry Pi 4 and Pi 5**, booting directly into the production Service Producer Display receiver. Built from the official **2026-10-06 Raspberry Pi OS Lite 64-bit / Debian 13 Trixie** image. Uses labwc/Wayland and Chromium, with no desktop shell, office applications, development toolchain, or first-boot package installation. This is a small practical build using supported Raspberry Pi drivers and a full browser; it is not a claim to be the smallest possible Linux distribution.

## Install

1. Open [Raspberry Pi Imager](https://www.raspberrypi.com/software/) on your Mac or PC. Choose your Pi model, then **Use custom** for the operating system and select `ServiceProducer-Display-Pi4-Pi5-2026-10-20.img.xz` (the uncompressed `.img` also works).
2. Select a **16 GB or larger microSD card**. Writing the image erases that card. **Skip Imager's OS customization**: this image has its own appliance user and network setup.
3. For Ethernet, connect the network cable. For Wi-Fi, either configure the boot-partition file described below or attach a keyboard and press **F2** after startup.
4. Put the card in the Pi. Connect a monitor to **HDMI 0** (the HDMI socket nearest USB-C power), then connect power. The first boot expands the filesystem to fill the card. Subsequent power-ups go directly to the display.
5. Use a keyboard/mouse once to confirm the device name and choose **Get pairing code**. On your producer device, open **Devices → Pair device**, choose **Display** access, and assign the Producer Desk and screen/layout. The Pi remembers its pairing across browser restarts and reboots.

Use one HDMI display per Pi. Start with 1080p; validate the desired 4K mode and text layout on your actual Pi/monitor. The image retains the Pi's standard automatic monitor detection. The Pi needs an appropriate power supply and internet access for pairing and live content.

## Network settings

Ethernet uses DHCP automatically. Wi-Fi supports the Pi's onboard radio, including hidden networks. On the connected display, **F2** opens NetworkManager's menu: choose **Activate a connection**, select Wi-Fi, and enter its password; **Quit** returns to the display. **Edit a connection** provides static IP and other settings. Arrow keys, Tab and Enter navigate the menu.

Alternatively, after flashing, reinsert the card into your computer and open the `bootfs` partition. Rename `service-producer.json.example` to **`service-producer.json`** and edit it as plain UTF-8 JSON. Set `wifi_ssid`, `wifi_password`, and the correct two-letter `wifi_country`. Set `wifi_hidden` to `true` only for a hidden network. Default country is **US** and timezone is **America/Chicago**. A blank Wi-Fi name leaves Ethernet as the initial connection. A Wi-Fi name with a blank password means an open network.

Optional fields:

| Field | Purpose |
| --- | --- |
| `hostname` | Lowercase letters, digits and hyphens. Blank generates a unique `sp-display-xxxxxx` name. |
| `display_name` | Suggested device name in the pairing screen; blank uses the hostname. |
| `timezone` | IANA timezone, for example `America/Chicago`. |
| `ssh_public_key` | Optional SSH public key for `spadmin`; leave blank to keep remote administration off. Never put a private key here. |

Settings are imported before networking starts, stored on the Linux partition, and the JSON is removed from the boot partition after success. A setup-complete text file confirms the import. If validation/import fails, the JSON stays in place with a setup-error text file; Ethernet and F2 remain available. The boot partition is readable on other computers, so keep a card containing a Wi-Fi password in your possession until import is complete. You can supply a new JSON file on a later boot to change settings. Omitting a Wi-Fi name does not delete an existing saved network.

The image includes the Pi 4/5 onboard Broadcom Wi-Fi firmware and normal Ethernet support. Large Atheros/MediaTek firmware bundles are omitted; adapters requiring those drivers need their firmware installed separately. Captive portals and enterprise Wi-Fi may require additional network configuration.

## Operation

- **Power on:** automatic full-screen startup; no OS login or package download.
- **Waiting for internet:** local connection screen retries automatically. Loaded Service Producer pages retain their existing reconnect/stale-state behavior.
- **Display identity:** the blue monitor icon and “Service Producer Display” label appear on the local startup/connection screen. The main producer keeps its green icon.
- **Browser exits:** the appliance launcher restarts it. Pairing storage remains on disk.
- **F2:** network settings.
- **Ctrl+Alt+R:** restart the browser without deleting pairing.
- **Ctrl+Alt+Backspace:** shut down cleanly; wait for shutdown before removing power.
- **Display sleep:** disabled. Logs and browser disk cache live in RAM to reduce card writes; persistent browser storage holds pairing.

Each flashed card starts **unpaired**, with a new machine identity and no shared SSH host keys. Never clone a card after pairing to deploy additional displays. Flash the supplied clean image for each device.

The receiver is `https://live.serviceproducer.app/services/live/receiver?app=display&slot=display-app`, using the production profile and the existing Display-only behavior. The app is delivered by that website; this image does not include an offline copy of the service platform or a LAN producer server. It does not output NDI or Blackmagic SDI.

## Administration and updates

Remote SSH is disabled by default. There is no default user password. To enable administration, supply your public key in `ssh_public_key`; connect as `spadmin` using that key. This administrator can use `sudo` without a password. The display user has no sudo access. SSH password authentication and root SSH login remain disabled.

Web app changes arrive from the production site. OS/browser updates are manual so a service is not interrupted by an unattended update. Between services, an administrator can run:

```sh
sudo apt update
sudo apt upgrade
sudo reboot
```

Automatic EEPROM updates are disabled; firmware maintenance remains an explicit administrator task. Chromium's sandbox and normal TLS validation are enabled. The root filesystem is writable with ext4 journaling, not a power-loss-proof read-only filesystem. A reliable card, clean shutdowns and stable power are still important.

## Build and verification

From Apple silicon macOS with Docker/Colima running, or native ARM64 Linux with Docker:

```sh
bash build-image.sh /absolute/path/to/output
```

Keep the parent `raspberry-pi/display-icon.png` beside the `image/` folder when
using the source archive; the build copies it into the appliance.

The script downloads a SHA-256-pinned official Lite image and installs packages from the configured signed Raspberry Pi/Debian repositories. It creates only container-local disk images; it does not flash a physical disk. The compressed image, raw image, checksums, package inventory and verification report are exported. Package versions can change on a future build; consult `packages.tsv` for the exact versions in an artifact. This is a repeatable build recipe, not a guarantee of byte-identical future builds.

Base image source: [Raspberry Pi download archive](https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2026-10-06/2026-10-06-raspios-trixie-arm64-lite.img.xz).
Base SHA-256: `483db18a48da399b5b7022ffae9a07bc6d99daab30e593aedac09b69ff422843`.

`test-config.py` checks input validation; `verify-root.py` checks the package database, executable architecture, boot files, service enablement and absence of cloned identities. `test-vm.sh` boots a **separate copy** under QEMU with a generic Debian ARM64 kernel and virtual GPU to test Linux userspace and the full-screen browser. That generic kernel and test service are not in the delivered image. A virtual test cannot validate Raspberry Pi firmware boot, HDMI/KMS acceleration, Wi-Fi radio reception, or abrupt-power-loss behavior.

Before using the image in a service, test physical Pi 4/5 boot, pairing and reboot retention, Wi-Fi/Ethernet reconnection, the assigned layouts, monitor resolution, and a prolonged run. Check the artifact's `verification.json` and accompanying build notes for completed tests.