Home Assistant
The companion plugs into Home Assistant three ways, roughly from most to least integrated. They're not exclusive — pick whichever suit you (the table at the bottom summarises which does what).
Two further companion features are reachable from Home Assistant but aren't Home Assistant features at all — they're plain HTTP servers that work with or without it, and they have their own pages: the Vestaboard-compatible API and the MCP server.
Home Assistant now calls these Apps (formerly "Add-ons").
Runs the full Companion inside Home Assistant — in the sidebar, themed to match, configured from the Configuration tab (no environment variables, no command line).
Requires a Supervisor install — Home Assistant OS or Supervised. On Home Assistant Container/Core there is no App Store; run the companion's Docker image alongside HA and use the HACS integration below to connect them.
- Settings → Apps → App Store. (If you don't see "Apps", your install has no Supervisor — see the note above.)
- Top-right ⋮ menu → Repositories. Paste:
→ Add → Close. The store reloads with a SplitFlap section.
https://github.com/avandeputte/SplitFlapGatewayCompanion - It offers two entries — SplitFlap Gateway Companion (stable) and SplitFlap Gateway Companion (Beta). Pick stable unless you want prereleases. They're separate Apps, so you can run both, but point them at the same gateway only one at a time.
-
Install. It downloads a prebuilt multi-arch image (
amd64,aarch64,armv7) — there's no local build, so it's quick. - Open the Configuration tab and set
gateway_url— the gateway's address, e.g.http://192.168.1.42. Use the IP, notsplitflap-gw.local: the App runs in a container that often can't resolve mDNS. (→ Finding the gateway's IP). Save. - Back on the Info tab, switch on Start on boot, Watchdog and Show in sidebar, then press Start.
- Open Web UI — or just click SplitFlap in the sidebar.
The App won't start without gateway_url — if the log says FATAL: GATEWAY_URL is not set,
that option is empty.
Updates arrive like any other App: Home Assistant shows an Update banner, with the release notes in the store entry.
| Option | |
|---|---|
gateway_url |
Required. Your gateway, e.g. http://192.168.1.42. |
companion_public_url |
Override the address the companion registers with the gateway (only needed on odd networks). |
home_assistant |
Publish the MQTT device (§3). |
mqtt_password |
Password for the broker, if yours needs one. |
vestaboard / vestaboard_key
|
Turn on the Vestaboard-compatible API. |
mcp / mcp_token
|
Turn on the MCP server. |
dev_mode |
Adds simulation mode to the ⚙ menu (no hardware needed). |
log_level |
info by default; debug when something's wrong. |
Once it's running, the gateway's own UI is proxied into the App, so you provision, calibrate and configure the hardware without ever leaving Home Assistant.
A native integration — it adds a SplitFlap device with real entities, so the display works in dashboards, automations, scripts and voice assistants. It talks to the companion over plain HTTP: no MQTT broker required.
Requires HACS (if you don't have it, follow its install docs first).
-
Open HACS in the sidebar → top-right ⋮ → Custom repositories.
-
Repository:
https://github.com/avandeputte/SplitFlapGatewayCompanionType: Integration → Add → close the dialog. -
Search HACS for SplitFlap → open it → Download (accept the version it offers).
-
Restart Home Assistant — HACS only copies files; the integration loads on restart.
-
Settings → Devices & Services → + Add Integration → search SplitFlap.
-
It asks for the companion's URL — not the gateway's:
- Companion in Docker →
http://<docker-host>:8000 - Companion as the App above → the address on the App's Info page (its host's IP on
port
8000)
Submit, and a SplitFlap device appears with the entities below.
- Companion in Docker →
-
Several walls? If the companion drives multiple displays, the flow asks which one this entry is for — each display is its own device, so add the integration once per wall. (The
splitflap.messageservice sends to every configured wall.)
If the config flow can't connect, open that URL in a browser from the same machine HA runs on — that's the exact reachability the integration needs.
| Entity | Does |
|---|---|
| App (select) | Run an installed app, or Off to stop |
| Playlist (select) | Run a saved playlist, or Off
|
| Showing (sensor) | Which app is on the flaps right now — even mid-playlist |
| Message (sensor) | What the board reads, as text (lines attribute) |
| Board (image) | The wall as a live picture — see below |
| Clear / Stop / Home all (buttons) | — |
splitflap.message (service) |
Show text, with optional style and a timed auto-revert — sent to every configured wall |
The Board image entity renders the wall's current state as a picture, drawn in the companion's own visual language — split-flap tiles with the hinge line, the seven colour flaps as solid tiles, and every character the wall can show (the full Windows-1252 set with its accents, plus the fourteen pictograph flaps):
Drop it in a Picture card (image.<display>_board), glance at it on the
device page, or attach it to a notification — "here's what the wall says right
now." It is redrawn only when the board actually changes, so a ticking clock
doesn't make the frontend re-download every poll. With
multiple displays, each wall's entry renders its own board.
The integration's icon ships inside the integration itself (Home Assistant 2026.3+ serves it from the integration's
brand/folder — the central brands repository no longer takes custom integrations). On older HA versions the integration works fine but shows the generic placeholder icon.
Unlike a Vestaboard integration, this surfaces the apps and playlists as entities. The
message service with seconds set shows a message, then returns the board to whatever was
playing:
action:
- service: splitflap.message
data:
text: "Dinner's ready"
seconds: 30 # shows for 30s, then the playlist resumesWith Home Assistant enabled and a shared MQTT broker, the companion publishes a SplitFlap Companion MQTT device with App and Playlist selects and a Stop button. Use this if you already run MQTT and don't want the HACS integration. (The gateway also publishes its own MQTT device — see Gateway.)
If the companion drives several displays, it publishes one device per wall, named after it — SplitFlap Companion (Office wall).
The default display keeps the entity ids it has always had, unsuffixed. That is deliberate: hanging a second display must not rename the entities in automations you already wrote. The other walls get their display id appended, so nothing collides.
Set the default with Make default in the companion's Displays dialog — it is also the wall that every service call, Vestaboard post and MCP call drives when it doesn't name one.
The companion can answer the Vestaboard Local API, so
anything written for a Vestaboard drives your wall — including
ha-vestaboard, or a plain rest_command with
no integration at all. Useful mainly when you want to reuse automations that already
exist; for a fresh HA setup the HACS integration above is richer (it knows about apps and
playlists, which the Vestaboard API doesn't).
→ Vestaboard-compatible API — enabling it, the endpoints, the HA snippets.
Turn it on and the display becomes a set of MCP tools, so an LLM can read the board and drive it in plain language: "what's showing right now?", "put the standup time up for two minutes, then put back what was playing." It's a standalone HTTP server — Home Assistant isn't involved.
→ MCP Server — the tools it exposes, connecting Claude, worked examples.
| You want to… | Use |
|---|---|
| See and use the full companion UI in HA | The app |
| Automations, dashboards, voice — cleanest setup | HACS integration |
| Automations, and you already run MQTT | MQTT device |
| Reuse a Vestaboard automation or integration | Vestaboard API |
| Let an LLM/assistant drive the board | MCP server |
Next: Using splitflap-os → · or back to Quick Start