Choosing a Configuration

Choosing a configuration

The stack is deliberately modular, and the pieces are swappable at two joints:

• The module firmware — Adam G Makes' original firmware (each module's bus ID is compiled in) or the Universal Firmware (one binary for every module, IDs assigned at runtime).
• What drives the bus and provides content — csader's splitflap-os on a Raspberry Pi, the Gateway alone, or the Gateway plus the Companion.

Every combination below is a working display. They differ in what you get around it — and Universal Firmware → Gateway → Companion is by far the most featureful path, which is why the Quick Start walks that one.

The configurations

A — Original firmware + splitflap-os

The classic setup: Adam's per-module firmware, a Raspberry Pi as bus master (USB-RS485), and splitflap-os providing the web UI, apps, compose and playlists. Entirely Gateway-free. The trade-offs: every module needs its own firmware build (the ID is compiled in), and there's no scheduling/trigger system and no REST API.

B — Universal Firmware + splitflap-os

Same as A, but the modules run the Universal Firmware — so you flash one binary to every module and assign IDs at runtime with the provision.py terminal tool on the Pi. splitflap-os is compatible with both firmwares, so nothing else changes. A good choice if you like splitflap-os but want to stop compiling per-module firmware.

C — Original firmware + Gateway (± Companion)

The Gateway can drive original-firmware modules for display — text, characters, homing. What you lose is everything that depends on Universal-Firmware commands: runtime provisioning (IDs are compiled in), the self-tests, and custom flap sets; calibration support depends on what the module firmware answers. Fine for an existing original-firmware wall you don't want to reflash, with the browser/REST/MQTT/OTA conveniences of the gateway.

D — Universal Firmware + Gateway (no Companion)

The full hardware experience with no extra host: provision, calibrate, diagnose and drive the wall from the gateway's web UI, REST API and MQTT, with OTA updates and quiet hours. No content engine though — no apps, playlists or schedules; you send text yourself (from the browser, an automation, or anything that can speak REST/MQTT).

E — Universal Firmware + Gateway + Companion ★ recommended

Everything in D, plus the whole content layer: the splitflap-os app library, playlists, schedules, triggers, localization, resume-after-restart — and the Home Assistant surfaces (sidebar app, HACS integration, Vestaboard-compatible API, MCP server for LLM control).

Also possible: splitflap-os can drive through the Gateway over MQTT instead of a USB-RS485 adapter (the gateway owns the bus; splitflap-os provides content). And in any gateway-based configuration, the Matrix Portal Gateway substitutes for the modules and gateway with an LED matrix.

Feature grid

Feature	A Orig + sfOS	B Univ + sfOS	C Orig + GW	D Univ + GW	E ★ Univ + GW + Companion
Bus controller hardware	Pi + USB-RS485	Pi + USB-RS485	ESP32	ESP32	ESP32 (+ any Docker/HA host)
Flash every module with one binary	—	✅	—	✅	✅
Assign module IDs at runtime	—	✅ ¹	—	✅ (web UI)	✅ (web UI)
Calibration tooling	✅	✅	⚠️ ²	✅ (wizard)	✅ (wizard)
Module self-tests (Hall / mechanical)	—	⚠️ ³	—	✅	✅
Custom flap sets	—	⚠️ ³	—	✅	✅
Live board preview in the browser	✅	✅	✅	✅	✅
Type a message from the browser	✅	✅	✅	✅	✅ (click-to-type grid)
Content apps (weather, stocks, …)	✅	✅	—	—	✅ (same app library)
Playlists	✅	✅	—	—	✅ (+ per-entry settings)
Run apps/playlists on a schedule	— ⁴	— ⁴	—	—	✅
Event triggers (ISS, games, weather)	— ⁴	— ⁴	—	—	✅
Localization (translated apps, locale formats)	—	—	—	—	✅
Quiet hours	—	—	✅	✅	✅
REST API	—	—	✅	✅	✅ (gateway + companion)
MQTT + Home Assistant device	✅	✅	✅	✅	✅ (gateway + companion devices)
HA sidebar app + HACS entities	—	—	—	—	✅
Vestaboard-compatible API	—	—	—	—	✅
MCP server (LLM control)	—	—	—	—	✅
OTA update of the bus controller	— ⁵	— ⁵	✅	✅	✅
Settings survive a host reinstall	—	—	✅ ⁶	✅ ⁶	✅ (mirrored to the gateway)
Resume what was playing after a restart	—	—	—	—	✅

Notes

1. Via the provision.py terminal tool on the Pi — splitflap-os's own UI doesn't provision; the tool ships with the Universal Firmware.
2. The gateway's calibration UI issues Universal-Firmware commands; how much works against the original firmware depends on which commands that firmware answers.
3. The firmware supports it (raw bus commands); there's no UI for it in splitflap-os — the gateway's Modules/Calibration tabs are the UI for these.
4. Per the splitflap-os README at the time of writing; check csader/splitflap-os for its current feature set.
5. The Pi updates like any Linux host (git pull / reinstall) — not OTA in the firmware sense.
6. Gateway settings (WiFi, MQTT, grid, calibration backup) live on the ESP32 itself.

Switching later

The joints are designed so you can move along the grid without redoing everything:

• A → B: reflash the modules with the Universal Firmware (once each), provision IDs. Keep splitflap-os exactly as it is.
• B → D/E: replace the Pi's USB-RS485 with the Gateway on the same rail. Your modules, IDs and calibration are untouched — they live in the modules' EEPROM.
• D → E: run the Companion (Docker or the HA app) and point it at the gateway. The gateway keeps working standalone if the companion is down.
• E without hardware: swap modules + gateway for the Matrix Portal Gateway; the companion can't tell.

---

Next: Quick Start · FAQ & Glossary