Skip to content

Quick Start

Jump to bottom
Alex Van de Putte edited this page Jul 12, 2026 · 9 revisions

Quick Start

The whole journey, from parts to a message on the wall — with every optional step marked, so you can see the shortest path to your setup.

The flow

Two ways to begin

A — Real split-flap wall B — LED matrix (no mechanical build)
You build/source Adam G Makes' modules one Adafruit MatrixPortal + a HUB75 panel
Steps 1–4 below all of them skip to step 4
The result clacking mechanical flaps virtual flaps on an LED matrix

Path B is the fastest way to see the entire stack working. Everything from step 5 on is identical for both.

Step 1 — Build the modules (Path A only)

Build or source the split-flap modules from Adam G Makes' SplitFlapDisplay repo — the PCB, printed parts, BOM and assembly. The modules clip onto a DIN rail; pogo pins on each module contact a conductor rail carrying 12 V, ground and the two RS-485 bus signals, so mounting a module is all the wiring there is. See Hardware.

Step 2 — Flash each module (Path A only)

Flash the Universal Firmware to every module (same binary for all) with a SerialUPDI programmer. Remember pio run -t fuses once per chip so the EEPROM survives. → Module Firmware → Flash

Step 3 — Provision & calibrate (Path A only)

Easiest from the gateway's web UI once step 4 is done: assign each module a bus ID (Provision tab) and calibrate it (Calibration wizard). → Module Firmware

Step 4 — Set up the Gateway (everyone)

  • Path A: flash the ESP32 gateway, join it to WiFi, set your grid size.
  • Path B: flash the Matrix Portal Gateway instead — same steps, no modules to provision.

Then open http://splitflap-gw.local, and use the Display tab to send text — you should see the wall move. → Gateway

✅ Checkpoint: you can show text from the gateway's web UI. The hardware works. If you only wanted a manually-driven display, you're done.

Step 5 — Run the Companion (optional, recommended)

Bring the display to life with apps, playlists and schedules. Point the companion at your gateway (GATEWAY_URL) and open its UI. → Companion

docker run -d --name splitflap-companion -p 8000:8000 \
  -e GATEWAY_URL=http://splitflap-gw.local -v companion-data:/data \
  ghcr.io/avandeputte/splitflap-gateway-companion:latest

Run a clock or weather app, build a playlist, set a schedule. The gateway now shows a Companion tab, and the companion shows the gateway's tabs.

Prefer csader's original engine? See Using splitflap-os.

Step 6 — Home Assistant (optional)

Install the companion as a Home Assistant app (sidebar UI) and add the HACS integration for entities and automations — App/Playlist selects, a Showing sensor, and a splitflap.message service with timed auto-revert. There's also an MQTT device, a Vestaboard-compatible API, and an MCP server for LLM control. → Home Assistant

action:
  - service: splitflap.message
    data:
      text: "Welcome home"
      seconds: 20

The shortest paths

  • "I just want to see it work" → Path B (Matrix Portal) → step 4 → step 5. No soldering.
  • "Real flaps, driven by hand" → steps 1–4. Skip the companion.
  • "Real flaps, full experience" → steps 1–6.
  • "I use Home Assistant" → get the gateway working (step 4), then install the companion as an app (step 6) — it's the easiest way to run it.

Reference: FAQ & Glossary

SplitFlap wiki

Start

Build it

Drive it

Extend it

Reference

Hardware © Adam G Makes

Clone this wiki locally