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
• MQTT — Home Assistant integration with auto-discovery
• 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

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

Based on the Split-Flap Display by Adam G Makes, licensed under CC BY-NC-SA 4.0.

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.