SplitFlap OS

A web-based control interface for modular split-flap displays. Manage apps, compose messages, and calibrate hardware from any device.

Built on Adam G Makes' Split-Flap Display hardware platform.

Features

• 40+ apps — weather, stocks, sports scores, crypto, word clock, trivia, news headlines, quotes, and more
• App Library — browse and install apps by category (time, entertainment, news, lifestyle, education, finance, sports)
• Compose — click-to-type grid editor with color tile support
• Playlists — sequence apps and composed messages with per-entry timing and transitions
• Live preview — animated flap simulation in the browser
• Calibration tools — hardware inspector, auto fine-tune, teach mode
• Universal Firmware provisioning — automatically discover, identify, assign, diagnose, and de-provision modules from the calibration page
• MQTT — Home Assistant integration with auto-discovery
• Configurable serial port — auto-detect available ports or enter a custom path; supports env var, settings UI, and Docker deployments
• SplitFlap Gateway (MQTT) — alternatively drive the display remotely through an ESP32 gateway over MQTT instead of a local serial port; configure broker, port, topic prefix, and optional credentials in the settings UI
• WiFi hotspot fallback — Pi creates its own network when no WiFi is found, so you can always access the UI
• Offline resilience — internet-dependent apps degrade gracefully, offline apps keep running
• Plugin architecture — community apps via manifest + fetch pattern
• Mobile-friendly — hamburger menu, sticky bottom tabs, responsive layout

Quick Start

On your Split-Flap Display's Raspberry Pi:

Raspberry Pi OS Lite users: git may not be pre-installed. Run this first:

sudo apt-get update && sudo apt-get install -y git

git clone https://github.com/csader/splitflap-os.git
cd splitflap-os
sudo bash setup/install.sh

The installer sets up auto-start, WiFi hotspot fallback, and all dependencies. Access the UI at http://<your-pi-ip>.

If no WiFi is available, the Pi creates a hotspot:

• SSID: SplitflapOS
• Password: splitflap
• UI: http://192.168.4.1

Configure WiFi from Settings > WiFi / Network in the UI.

Updating

cd ~/splitflap-os
git pull origin main
sudo bash setup/install.sh

Hardware

This project is the web UI only. For the firmware and physical display hardware (3D printed parts, PCBs, BOM), see the original project by Adam G Makes:

https://github.com/adamgmakes/SplitFlapDisplay

SplitFlap Gateway (MQTT)

Instead of a local serial connection, SplitFlap OS can drive the display through a SplitFlap Gateway (an ESP32 running SplitFlapGateway_2.ino) over MQTT. This is useful when the display and the server aren't physically wired together.

Switch modes under Settings > Hardware Connection > Connection Type. When "SplitFlap Gateway (MQTT)" is selected, enter the broker address, port, topic prefix, and optional username/password, then click Connect Gateway.

SplitFlap OS only interacts with two topics, so the impact on the rest of the system is minimal:

Topic	Direction	Payload
<prefix>/send	OS → gateway	Raw RS485 frame (e.g. m05-A\n), forwarded verbatim to the bus
<prefix>/rx	gateway → OS	JSON {"command":"<frame>", ...} for each frame received from a module

The gateway transport presents the same interface as a serial port internally, so calibration, EEPROM sync, and all display writes work identically in either mode.

These settings can also be supplied via environment variables (useful for Docker/headless deployments), which take precedence over the settings file:

SPLITFLAP_CONNECTION_TYPE=gateway     # 'serial' (default) or 'gateway'
SPLITFLAP_GATEWAY_BROKER=192.168.1.50
SPLITFLAP_GATEWAY_PORT=1883
SPLITFLAP_GATEWAY_PREFIX=splitflap
SPLITFLAP_GATEWAY_USER=               # optional
SPLITFLAP_GATEWAY_PASSWORD=           # optional

Note: this MQTT connection (display transport) is independent of the existing MQTT / Home Assistant integration (state publishing & control), which continues to use its own broker settings.

Universal Firmware

Universal Firmware is an optional alternative to the original per-module firmware. It lets every module run the same firmware image instead of compiling a different build for each module ID. IDs are assigned later over RS-485, making it much easier to add, replace, or rearrange modules.

You can find and download the universal version of the firmware from avandeputte/SplitFlapUniversalFirmware. When it is used, Splitflap OS can discover new modules, identify them by moving the reel, assign IDs, and run supported diagnostics from the Calibration page. The original module firmware remains supported.

Learn more: firmware and protocol documentation | provision.py example | architecture notes

Repo Structure

server/          — Flask web app (backend + frontend)
apps/            — Plugin library (all installable apps)
setup/           — Raspberry Pi setup scripts and systemd services

Creating an App

Each app is a directory in apps/ with:

• manifest.json for metadata and settings schema
• app.py with a fetch(settings, format_lines, get_rows, get_cols) function

fetch() returns a list of page strings. Each page shows for loop_delay seconds, and results are cached by refresh_interval.

For full app-development documentation, settings schema, and examples, see APPS_README.md.

Attribution

• Splitflap OS is based on the Split-Flap Display by Adam G Makes, licensed under CC BY-NC-SA 4.0.

• Thanks to @avandeputte for SplitFlapUniversalFirmware, its documented RS-485 provisioning protocol and provision.py reference, and SplitFlapGateway, whose web UI helped inform this independent provisioning interface.

License

Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)

You are free to share and adapt this project for non-commercial purposes, as long as you give appropriate credit and distribute derivatives under the same license.