Companion
The gateway can put any character on any flap — but deciding what to show is the Companion's job. It's a web app that runs a library of apps (weather, clocks, stocks, transit, sports, quotes, animations…), sequences them into playlists, runs them on schedules, reacts to events with triggers, lets you compose a message by hand, and mirrors the wall in a live view.
It runs on a separate machine from the gateway (a Raspberry Pi, a NAS, a home server, or as a Home Assistant app), and drives the display over the gateway's REST API. It's optional — you can drive the gateway by hand or with splitflap-os — but it's where the project comes alive.
The only thing you must configure is GATEWAY_URL — where your gateway is. The companion
reads the grid size and everything else from the gateway.
Home Assistant users: install it as an app — see Home Assistant; it's the easiest path and puts the UI in your sidebar.
Docker (anywhere else):
docker run -d --name splitflap-companion -p 8000:8000 \
-e GATEWAY_URL=http://192.168.1.50 -v companion-data:/data \
ghcr.io/avandeputte/splitflap-gateway-companion:latest
# then open http://<host>:8000The image is multi-arch (x86 + arm64), so the same tag runs on a Pi or a PC. There's also a one-line install script that sets up Docker and a compose project for you — see the repo README.
-
Apps — a tile grid of the whole splitflap-os app library. One tap
runs an app; a live "▶ running" marker shows what's on. An App Library lets you add or
remove apps, or upload your own as a
.zip. - Live view + Home all — the board mirrors exactly what's on the wall, updated in real time. ⌂ Home all returns every module home.
- Compose — a click-to-type grid with colour tiles and every transition style. Type a message, pick how it flips onto the board, push it.
- Playlists — sequence apps and messages with per-entry durations; save, run, loop. The same app can appear more than once with different settings (e.g. weather for two cities in two languages).
- Schedules — run an app or playlist, or turn the display off, in time-of-day windows per weekday, plus quiet hours.
- Triggers — apps that watch for something (the ISS passing overhead, a game, a weather change) and briefly interrupt the display, then let it resume.
- Global settings — Language, Location and Timezone at the top (they drive translations, date/number formats, currency and holidays for apps that adapt), then provider keys and defaults.
A global Language (US/UK/Australian English plus the major Western-European languages) changes translated words, date order, number format and 12h/24h clock for any app carrying a 🌐 badge. Currency and public holidays follow your Location (down to province/state), not the language — and both Language and Location are overridable per app and per playlist entry, so one playlist can show Paris in French and Tokyo in Japanese back to back.
Point the companion at your gateway and it registers: the gateway's own tabs (Modules, Calibration, Settings…) appear right in the companion's nav, and as a Home Assistant app they open inside the sidebar — so you configure the hardware without leaving the companion. See Gateway → the Companion tab.
The apps are the splitflap-os plugin format — a manifest.json plus an
app.py (live/functional) or data.json (static/channel). Upload a .zip from the App
Library, or write your own; the companion runs them unchanged. (A functional app runs Python
on the companion host, so only upload apps you trust.)
Next: Home Assistant →