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 (direct USB-RS485), the Gateway alone, splitflap-os through the Gateway (over MQTT), 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 / B — splitflap-os, direct (no Gateway)

The classic setup: a Raspberry Pi as bus master over USB-RS485, splitflap-os providing the web UI, apps, compose and playlists. Entirely Gateway-free.

• A — with the original firmware: every module needs its own firmware build (the ID is compiled in).
• B — with the Universal Firmware: 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.

Either way (per the splitflap-os README): no scheduling/trigger system, no REST API.

C / D — Gateway alone (no content engine)

The ESP32 gateway as bus master: provision, calibrate, diagnose and drive the wall from its web UI, REST API and MQTT, with OTA updates and quiet hours. No apps, playlists or schedules — you send text yourself (browser, automation, anything speaking REST/MQTT).

• C — with the original firmware: display driving (text, characters, homing) works; everything that depends on Universal-Firmware commands doesn't — runtime provisioning, self-tests, custom flap sets — and calibration depends on what the firmware answers. Fine for an existing wall you don't want to reflash.
• D — with the Universal Firmware: the full hardware toolkit, including the provisioning UI and the calibration wizard.

E / F — splitflap-os through the Gateway (over MQTT)

A hybrid: the Gateway owns the bus, and splitflap-os provides the content, driving the display through the gateway's MQTT transport instead of a USB-RS485 adapter. You get splitflap-os's apps, compose and playlists plus the gateway's web UI, REST API, OTA and quiet hours — at the cost of running both a Pi and an ESP32.

• E — with the original firmware: the same firmware caveats as C.
• F — with the Universal Firmware: module provisioning and calibration now happen in the gateway's web UI — nicer than the terminal tool.

G — Universal Firmware + Gateway + Companion ★ recommended

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

(The Companion also runs against original-firmware modules — the content layer doesn't care — with the same hardware-tooling caveats as C.)

No mechanical build? In any gateway-based configuration (C–G), the Matrix Portal Gateway substitutes for the modules and the gateway with an LED matrix.

Feature grid

Feature	A Orig +sfOS	B Univ +sfOS	C Orig +GW	D Univ +GW	E Orig+GW +sfOS	F Univ+GW +sfOS	G ★ Univ+GW +Companion
Hardware you run	Pi	Pi	ESP32	ESP32	ESP32 + Pi	ESP32 + Pi	ESP32 + Docker/HA host
Flash every module with one binary	—	✅	—	✅	—	✅	✅
Assign module IDs at runtime	—	✅ ¹	—	✅ (web UI)	—	✅ (web UI)	✅ (web UI)
Calibration tooling	✅	✅	⚠️ ²	✅ (wizard)	⚠️ ²	✅ (wizard)	✅ (wizard)
Module self-tests (Hall / mechanical)	—	⚠️ ³	—	✅	—	✅	✅
Custom flap sets	—	⚠️ ³	—	✅	—	✅	✅
Live board preview in the browser	✅	✅	✅	✅	✅	✅	✅
Send text from the browser	✅	✅	✅	✅	✅	✅	✅
Compose — click-to-type grid, colour tiles	✅	✅	—	—	✅	✅	✅
Content apps (weather, stocks, …)	✅	✅	—	—	✅	✅	✅ ⁷
Upload your own apps from the browser (.zip)	— ⁴	— ⁴	—	—	— ⁴	— ⁴	✅
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)	✅ (gateway)	✅ (gateway + companion)
MQTT + Home Assistant device	✅	✅	✅	✅	✅ (both)	✅ (both)	✅ (both)
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 gateway updates OTA; the Pi (the splitflap-os host) updates like any Linux box (git pull / reinstall).
6. Gateway settings (WiFi, MQTT, grid, calibration backup) live on the ESP32 itself; splitflap-os's own content settings live on its Pi.
7. The companion ships a vendored snapshot of the splitflap-os app library and runs apps in the splitflap-os plugin format unchanged (plus your own uploads). The two projects' libraries are maintained separately and may diverge over time.

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.
• A/B → E/F: add the Gateway as bus master and switch splitflap-os's transport to the gateway's MQTT. Modules untouched.
• B/F → D/G: the Gateway replaces the Pi's USB-RS485 on the same rail. Your modules, IDs and calibration are untouched — they live in the modules' EEPROM.
• D → G: run the Companion (Docker or the HA app) and point it at the gateway. The gateway keeps working standalone if the companion is down.
• G without hardware: swap modules + gateway for the Matrix Portal Gateway; the companion can't tell.

---

Next: Quick Start · FAQ & Glossary