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 | The sidebar app, the HACS integration, the MQTT device. | Optional |
| Vestaboard API · MCP Server | Companion features, no HA required: answer the Vestaboard Local API, and expose the board as MCP tools an LLM can drive. | 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 separate content engine whose apps also run on the companion. 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
- Built-in Apps — every shipped app at a glance
- Companion without Home Assistant — Docker, the install script, the configuration reference
- Multiple Displays — drive several walls from one companion
- Home Assistant — the app, the HACS integration, the MQTT device
- Vestaboard-compatible API — reuse anything written for a Vestaboard
- MCP Server — let Claude read and drive the board
- Using splitflap-os — csader's engine as an alternative
- Writing Apps — build an app of your own
- Compatibility — the plugin ABI contract with splitflap-os
- Bus Protocol — the RS-485 wire-level reference
- Gateway API — the REST & MQTT reference, both gateways
- Languages & Localization — every language surface, and how to add one
- FAQ & Glossary — terms, gotchas, where things live
Release notes live with the code: the companion changelog, the gateway, the Matrix Portal gateway, and the module firmware.
Credits. The split-flap module hardware and the original bus protocol are by Adam G Makes (hardware repo). The companion's app library grew from csader/splitflap-os's plugin format, and apps written for that project still drop in. Everything here is CC BY-NC-SA 4.0 (non-commercial, share-alike, attribution).