How-to

Port Slowboard to new hardware

Run Slowboard on an e-paper panel or computer that isn't supported yet: describe the hardware in one file, test it, and send it upstream so others can build one too.

If you have an e-paper panel or a small computer that isn’t on the supported list, you can make Slowboard run on it. You describe the hardware in a profile, a short TOML file that tells slowd the panel’s size, colours, refresh timings, keys and wiring. Then you work through a bring-up checklist on the real hardware, which proves the panel, keys and recovery paths behave. Once both are done, a pull request adds your hardware to the supported list, so anyone with the same parts can build one.

You don’t need this page to build a Slowboard 1085: its profile and bring-up are done, and Set up a Slowboard 1085 covers assembly and first boot.

Before you start

Hardware is supported when it has a profile and a passed bring-up. Before writing either, you need to know, for the hardware in front of you:

• The panel backend. Which driver in sb-hw talks to the panel. A new panel also needs a new backend in sb-hw; a board that reuses a known panel does not.
• The surface. Width, height, bits per pixel and the ink set, and how many controller ICs drive the panel and which columns each one covers.
• The refresh modes. Which waveforms the panel has and how long each one takes, measured on the hardware; whether partial windows work, and whether a row-limited box confines the flash.
• The keys. How many, how they are wired (GPIO lines and polarity), or none.
• The bus. The SPI device and clock, the GPIO chip, and the control lines: reset, panel power, busy, data/command and a chip select per controller.
• Wi-Fi setup. Whether the board needs slownet to join a network.

The bring-up checklist below measures most of these. Record the results with the date, OS image and kernel.

Write the profile

Write a TOML file in crates/sb-hw/profiles/ with the display size and inks, the controller ranges and window mode, the refresh modes and timings, the key lines, the bus pins, and whether the board needs Wi-Fi setup. Profiles lists every field and shows the Slowboard 1085 profile as a worked example.

Select the new profile in /etc/slowd/slowd.toml (profile = "…") on the board.

Run the bring-up checklist

Bring-up proves the panel, keys and recovery paths on real hardware. Work through every list; a board passes when every box is ticked.

Board and OS

• The OS boots from the intended storage and joins Wi-Fi. (On the Lyra: erase the onboard SPI NAND so the SD card boots, and unblock the Bluetooth rfkill so wlan0 appears.)
• nproc, free -m and MemAvailable recorded.
• Nothing else owns the panel’s GPIO lines or SPI pins (gpioinfo, /sys/kernel/debug/gpio).
• SPI device present (ls /dev/spidev*) and pins muxed to SPI.

Panel

• Wiring check with no refresh: the controller answers reset and BUSY behaves.
• First light: a test pattern, the right way round, colours right on every controller.
• Full refresh time measured with each waveform; these become [refresh] modes.
• Partial refresh: a window on each controller alone and one spanning both, with nothing leaking outside the window.
• A row-limited box (a strip) flashes only the box, or not; this decides windows.
• slowd selftest passes; refreshes through slowd match the measured times within 5 %.

Keys

• Every key line read, tap and hold, with the configured debounce and polarity.

Robustness

• A refresh of the same area within the cooldown waits, then runs.
• The lifetime refresh counter in slowd status shows no gap across the run.
• systemctl restart slowd during a refresh completes the refresh.
• kill -9 during a refresh: panel-safe runs, the panel sleeps, and a full refresh follows on start.
• Core loop stopped (kill -STOP): systemd restarts slowd after 30 s.
• slowd RSS idle and during a refresh.

Offline

• Hub stopped: presses still work and answers queue, then arrive once after the restart.
• Reboot with the internet unplugged: the deck comes back from the pinned set and the keys arm.

Submit the board

1. Open a board proposal. An issue on GitHub with the panel, the SoC, RAM, and how the keys (if any) are wired.
2. Write its profile. A TOML file in crates/sb-hw/profiles/ with the fields in Profiles: display size and inks, controller ranges and window mode, refresh modes and timings, key lines, bus pins, and whether it needs Wi-Fi setup. A new panel also needs a backend in sb-hw.
3. Run the bring-up on the hardware and fill in the checklist. Set up a Slowboard 1085 shows the end-user path a supported board should reach: flash the card, join Wi-Fi through slownet, add slowapps.
4. Open a pull request with the profile, the bring-up results and a photo of it running. CI checks the profile against the protocol.
5. Once it is merged, the board joins the supported list on Supported screens and profiles.