BUSY Bar for Home Assistant

Turn a BUSY Bar into a tactile Home Assistant controller and two-screen pixel dashboard. Everything runs locally: Home Assistant talks directly to the bar's HTTP and WebSocket APIs through the official busylib Python client.

The interaction

The bar behaves like a tiny, physical Home Assistant app:

1. Move the top mode selector to Apps. Home Assistant opens automatically.
2. Turn the dial to browse your chosen accessories.
3. Press the large Start button to toggle the highlighted accessory right away, or press Select to open its combined control screen.
4. Turn the dial to choose Brightness, RGB color, or Color temperature.
5. Press Select, turn the dial to adjust the highlighted value, then press Select again to finish editing.
6. Press Start to toggle or activate the accessory from any screen. Press Back to exit; press Select to reopen the accessory overview.

Keep the physical selector on Apps while using Home Assistant. The BUSY firmware reserves the other selector positions for its built-in status and timer screens, which will otherwise reclaim the display. You can also press Select to reopen the dashboard after exiting it with Back.

Both BUSY displays update throughout the flow. The front RGB matrix shows four accessories at once, then combines a large device icon with its available controls and live value. The rear OLED shows the friendly name, state, position in the list, and contextual control hints. The display also follows changes made elsewhere in Home Assistant.

Accessory support

Home Assistant domain	Combined controls	Start button
light	Brightness, RGB presets, color temperature when supported	Toggle
fan	Percentage	Toggle
cover	Position	Open / close
media_player	Volume	Play / pause
number, input_number	Value	—
climate	Target temperature in 0.5° steps	On / off
switch, input_boolean	—	Toggle
lock	—	Lock / unlock
scene, script, button	—	Activate

The option picker is deliberately ordered: the order you choose accessories is the order shown when turning the dial.

Installation

HACS custom repository

1. In HACS, open Custom repositories.
2. Add https://github.com/kylewhirl/busybar-home-assistant as an Integration.
3. Install BUSY Bar, restart Home Assistant, then clear the browser cache.

Manual

Copy custom_components/busybar into your Home Assistant configuration's custom_components directory and restart Home Assistant.

Setup

1. On the BUSY Bar, enable its Wi-Fi HTTP API and set an access key.
2. In Home Assistant, go to Settings → Devices & services → Add integration.
3. Search for BUSY Bar.
4. Enter the bar's local IP address and HTTP API access key.
5. Open the integration's Configure dialog and select the accessories you want on the dial.

Use a DHCP reservation so the BUSY Bar keeps the same local IP. The access key is stored in the Home Assistant config entry and is never sent to this project or a cloud service.

Choose what appears on the bar

The BUSY Bar does not automatically include every entity in Home Assistant. You explicitly choose a short, useful list:

1. Open Settings → Devices & services in Home Assistant.
2. Find BUSY Bar and choose Configure.
3. In Accessories, add the entities you want to control.
4. Arrange them in the order you want to encounter while turning the dial.
5. Submit the form. The integration reloads and uploads only the device icons needed for that list.

The picker includes supported light, switch, fan, cover, media_player, climate, lock, scene, script, button, number, input_number, and input_boolean entities. Prefer room-level groups and the few individual devices you adjust often; a list of roughly 5–10 accessories is much nicer on a dial than every bulb in the house.

That same Configure dialog also controls the RGB accent color, the amount each dial detent changes a value, and the display priority used when other BUSY apps are active. Priority 100 is recommended on physical hardware so the built-in status screen does not immediately reclaim the display. To remove an accessory, reopen Configure, remove it from the Accessories field, and submit again.

Device icons

The bar uses each entity's real Home Assistant Material Design Icon instead of guessing a fixture from its name. A custom icon selected in the entity registry takes priority, followed by the entity's integration-provided icon and Home Assistant's normal domain or device-class default.

To give two lights different silhouettes, customize them in Home Assistant:

1. Open Settings → Devices & services → Entities.
2. Open the entity and choose its Settings cog.
3. Set Icon to an MDI icon such as mdi:desk-lamp, mdi:floor-lamp, or mdi:ceiling-light and save.
4. Reload the BUSY Bar integration, or reopen Configure and submit the existing accessory list, so the new image is uploaded to the bar.

If no custom icon is set, a light correctly uses Home Assistant's default mdi:lightbulb. Unsupported third-party icon sets fall back to a question-mark icon because their SVG artwork is not part of Home Assistant's MDI library.

Home Assistant entities

The integration creates:

• Connectivity, battery, firmware, navigation-state, and selected-accessory sensors.
• A Dashboard switch for opening or closing the Home Assistant UI remotely.
• Display brightness control.
• Previous, next, and refresh buttons for automations and dashboards.

It also emits a busybar_input event for every button, dial, and mode-switch input, so advanced automations can use the hardware directly.

Actions

action: busybar.show_message
data:
  text: Someone is at the front door
  color: "#FFB000"
  duration: 5

Also available:

• busybar.clear_display
• busybar.refresh_dashboard

If more than one bar is configured, pass config_entry_id to target one.

Design notes

• Polling is used only for slow diagnostics such as battery and firmware.
• Dial and button input is local push over the BUSY WebSocket stream.
• Home Assistant remains authoritative: selected entity state changes trigger a display redraw.
• Dashboard redraws update stable Canvas elements in place so BUSY keeps its system-layer input capture active and the app underneath never receives the same dial or button event.
• Display elements use the integration-owned home_assistant application namespace so exiting or unloading does not delete another app's assets.
• Entity MDI artwork is resolved from Home Assistant, rasterized in memory, and uploaded into the integration's own BUSY asset namespace. Selected lights use warm yellow while unselected accessories use muted blue, but their actual Home Assistant silhouettes are preserved.

Development

uv sync --dev
uv run ruff check .
uv run pytest

A standalone fake-device interaction flow lives in demos/busybar_ui. It mirrors the integration's multi-accessory overview and combined brightness/color/temperature screen, talks directly to BUSY Bar, and never uses the Home Assistant API.

For visual testing, run the community BUSY Bar emulator and point a development client at 127.0.0.1:8080. The emulator validates the real 72×16 front-display payload, uploaded icons, text scrolling, priorities, and clearing behavior. Input-stream behavior and the rear OLED are covered by unit tests and should be smoke-tested on hardware because the current emulator does not implement the BUSY protobuf status WebSocket or render the rear display.

The repository runs Ruff, tests, Hassfest, and HACS validation in GitHub Actions. This project is not affiliated with Home Assistant or Flipper Devices.

License

MIT