FAQ

FAQ & Glossary

Glossary

Term	What it means
Module	One split-flap character cell — an ATtiny1616 board with a reel, stepper and Hall sensor.
Reel / flaps	The printed flaps on a module. A default reel has 64 flaps, including 7 colour flaps.
Bus / RS-485	The shared serial pair all modules sit on, carried by the DIN conductor rail (with 12 V and ground) that modules contact via pogo pins. 9600 baud.
Gateway	The ESP32 that bridges your network to the bus and serves the web UI.
Provisioning	Assigning a bus ID to a freshly-flashed module (which starts with none).
Calibration	Teaching a module where home is and how far a full reel turn is.
Companion	The content app — apps, playlists, schedules, triggers, compose.
App / plugin	One content source (weather, clock, …), in the splitflap-os plugin format.
Channel vs functional app	Channel = static pages (data.json); functional = live data (app.py with fetch()).
Matrix Portal Gateway	The gateway on an LED matrix with virtual flaps — no mechanical build.

Frequently asked

Do I have to build the mechanical display? No. The Matrix Portal Gateway renders virtual flaps on an LED matrix and behaves exactly like a real gateway. It's the fastest way to try everything.

Do I need the Companion? No — the Gateway can show text on its own from its web UI. The companion is what adds apps, playlists, schedules and the Home Assistant surfaces. Most people want it.

Do I need Home Assistant? No. It's one of several optional ways to drive the companion. See Home Assistant.

Where do I set the grid size? On the gateway, in Settings → Display Layout. The companion reads it from there — set it once.

Why won't my new module respond to commands? A freshly-flashed module has no ID until you provision it — it advertises its serial number instead. Assign it an ID from the gateway's Provision tab.

My module's calibration/ID disappeared after I re-flashed it. You skipped the fuse step. Run pio run -t fuses once per chip — it sets the EESAVE fuse so EEPROM survives reflashes. Without it, every upload wipes the module.

The companion won't start. It needs GATEWAY_URL set to your gateway's address — it refuses to start without one. As a Home Assistant app, that's the gateway_url option.

Can I use my existing Vestaboard automations? Yes — turn on the companion's Vestaboard-compatible API and point them at the companion.

Where do settings and uploaded apps live? In the companion's data volume (/data). It can also mirror settings to the gateway so a fresh container inherits them.

The repositories

Repo	What
adamgmakes/SplitFlapDisplay	The hardware (Adam G Makes)
SplitFlapUniversalFirmware	Module firmware
SplitFlapGateway	The ESP32 gateway
MatrixPortalGateway	The LED-matrix gateway
SplitFlapGatewayCompanion	The content app (+ HA add-on & HACS integration)
csader/splitflap-os	The app library

---

← Home