Using splitflap os

Using splitflap-os

The apps that make the display interesting — weather, clocks, stocks, transit, quotes, animations — come from csader/splitflap-os, an open-source split-flap "OS" and app library. This page explains the relationship and your options.

How the projects relate

• splitflap-os (by csader) is the original project: a controller plus a plugin library of apps, designed for its own setup.
• The Companion reuses that app library through a behavior-identical plugin runtime, so any splitflap-os app runs unchanged against this project's Gateway. A conformance test asserts the runtime honours the plugin contract.

In other words: the companion is a bridge that lets csader's apps drive Adam G Makes' hardware through the ESP32 gateway. You get the splitflap-os app ecosystem without splitflap-os needing to know anything about this gateway.

The compatibility contract is documented in the companion repo's COMPATIBILITY.md, and there's a full app-authoring guide in WRITING_APPS.md.

Your options

Use the companion (recommended). You already have the whole splitflap-os app library, plus playlists, schedules, triggers, compose, a live view, localization and the Home Assistant surfaces. Nothing extra to set up — see Companion.

Run splitflap-os itself. If you'd rather use csader's original project — for its own tooling, or to develop apps against it — head to github.com/csader/splitflap-os. It targets its own environment; this wiki covers the gateway + companion path, not the splitflap-os controller.

Write your own apps. Because the runtimes share a plugin format, an app you write works in both. A plugin is a manifest.json plus:

• an app.py with a fetch() function (a functional app — live data), or
• a data.json (a channel app — static pages).

Upload a .zip from the companion's App Library, and it loads immediately. The full ABI — fetch() arguments, settings fields, the injected i18n / get_weather / get_location helpers, triggers and animations — is in WRITING_APPS.md.

Credit

The app library and plugin format are csader's work; see csader/splitflap-os and this project's ATTRIBUTION.md. Everything here is CC BY-NC-SA 4.0, a derivative of splitflap-os.

---

Next: Quick Start →