Home
Build a mechanical split-flap display — the kind you hear clacking in old train stations and airports — and drive it with rich, live content: clocks, weather, stocks, transit, sports, quotes, animations, or a message you type. This wiki is the single place that ties the whole project together, from a bare circuit board to a message on the wall, and into Home Assistant.
The project is a small stack. Each layer does one job and hands off to the next; you only build the layers you need.
| Layer | What it is | Required? |
|---|---|---|
| Hardware | The physical split-flap modules — Adam G Makes' design (ATtiny1616, stepper, Hall sensor, RS-485). | Required (unless you use the Matrix Portal below) |
| Module firmware | The Universal Firmware each module runs. Flash once; identity is assigned later. | Required for real modules |
| Flaps & character sets | What's printed on your reels — the flap count and character set are configurable per module. | Optional (defaults work) |
| Gateway | An ESP32 that bridges your network to the module bus, with a web UI to provision, calibrate and drive the wall. | Required |
| Companion | The content app: apps, playlists, schedules, triggers, compose, a live view. | Optional but recommended |
| Home Assistant | Add-on, HACS integration, MQTT device, Vestaboard API, MCP server. | Optional |
Two branches keep the whole thing flexible:
- No mechanical build? The Matrix Portal Gateway is the same gateway running on an LED matrix with virtual flaps. It replaces the modules and the gateway; the companion can't tell the difference. Great for trying the full stack, or as an LED-matrix display in its own right.
- Don't want the companion? You can drive the gateway with csader's splitflap-os instead — a compatible app library, a different content engine. Every viable mix is compared in Choosing a Configuration.
→ Quick Start: from parts to a message on the wall — the recommended end-to-end path, with every optional step clearly marked.
- Quick Start — the whole flow, start to finish
- Choosing a Configuration — every viable mix of firmware × driver, with a feature grid
- Hardware — Adam G Makes' split-flap modules; what to build or buy
- Module Firmware — flash, provision, calibrate a module
- Flaps & Character Sets — flap count, custom reels, localization
- Gateway — flash the ESP32, join WiFi, tour the web UI
- Matrix Portal Gateway — the no-hardware alternative
- Companion — the content app: install and use it
- Home Assistant — five ways to use it from HA
- Using splitflap-os — csader's engine as an alternative
- FAQ & Glossary — terms, gotchas, where things live
Credits. The split-flap module hardware and the original bus protocol are by Adam G Makes (hardware repo). The companion's app library is csader/splitflap-os. Everything here is CC BY-NC-SA 4.0 (non-commercial, share-alike, attribution).