Home Assistant

Home Assistant

The companion plugs into Home Assistant five ways, roughly from most to least integrated. They're not exclusive — pick whichever suit you (the table at the bottom summarises which does what).

1. The app (add-on)

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.

Install it

1. Settings → Apps → App Store. (If you don't see "Apps", your install has no Supervisor — see the note above.)
2. Top-right ⋮ menu → Repositories. Paste:

   https://github.com/avandeputte/SplitFlapGatewayCompanion
   

   → Add → Close. The store reloads with a SplitFlap section.
3. 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.
4. Install. It downloads a prebuilt multi-arch image (amd64, aarch64, armv7) — there's no local build, so it's quick.
5. Open the Configuration tab and set gateway_url — the gateway's address, e.g. http://192.168.1.42. Use the IP, not splitflap-gw.local: the App runs in a container that often can't resolve mDNS. (→ Finding the gateway's IP). Save.
6. Back on the Info tab, switch on Start on boot, Watchdog and Show in sidebar, then press Start.
7. 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.

Options (Configuration tab)

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.

2. The HACS integration

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.

Install it

Requires HACS (if you don't have it, follow its install docs first).

1. Open HACS in the sidebar → top-right ⋮ → Custom repositories.

2. Repository: https://github.com/avandeputte/SplitFlapGatewayCompanion Type: Integration → Add → close the dialog.

3. Search HACS for SplitFlap → open it → Download (accept the version it offers).

4. Restart Home Assistant — HACS only copies files; the integration loads on restart.

5. Settings → Devices & Services → + Add Integration → search SplitFlap.

6. 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.

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)
Clear / Stop / Home all (buttons)	—
splitflap.message (service)	Show text, with optional style and a timed auto-revert

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 resumes

3. The MQTT device

With 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.)

4. The Vestaboard-compatible API

A Vestaboard is a commercial split-flap with a widely-used Local API. Turn this on and the companion answers that API, so anything written for a Vestaboard drives your wall — including the popular ha-vestaboard integration. A plain rest_command works with no extra software:

rest_command:
  splitflap_message:
    url: "http://companion-host:8000/local-api/message"
    method: POST
    headers:
      X-Vestaboard-Local-Api-Key: !secret splitflap_api_key
    content_type: "application/json"
    payload: '{"text": "{{ message }}"}'

Enable it with vestaboard: true (add-on) or COMPANION_VESTABOARD=1; the key is shown in the companion's ⚙ menu.

5. The MCP server

Turn this on and the display becomes a set of MCP tools, so an LLM client — Claude, an agent, an IDE — can drive the wall in words: "put the standup time on the board," "what's showing right now?," "show Paris weather for 30 seconds." Point a client at http://<host>:8000/mcp with a bearer token (shown in the ⚙ menu). Tools cover reading the board, showing messages (with timed revert), running and configuring apps, and running playlists.

---

Which should I use?

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