Home Assistant

Home Assistant

The companion plugs into Home Assistant five ways, from most to least integrated. Most people use the app (for the UI) and either the HACS integration or the MQTT device (for automations). The Vestaboard API and MCP server are extras.

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

1. Settings → Apps → App Store → ⋮ → Repositories, add: https://github.com/avandeputte/SplitFlapGatewayCompanion
2. Install SplitFlap Gateway Companion, set gateway_url in its Configuration tab.
3. Start, then Open Web UI — it appears in the sidebar.

It ships on two channels — stable and Beta — as separate store entries; pick stable unless you want prereleases. The gateway's own configuration UI opens in the sidebar too, so you never leave Home Assistant to manage the hardware.

Options (Configuration tab): gateway_url (required), mqtt_password, companion_public_url, home_assistant, vestaboard + vestaboard_key, mcp + mcp_token, theme, dev_mode, log_level.

2. The HACS integration

A native integration — install via HACS, point it at the companion's URL, and it adds a SplitFlap device. No MQTT broker required.

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 Dev 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 Dev 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