Local Home Assistant control for Brilliant smart-home touchscreen panels — no cloud, no HomeKit pairing, no flaky BLE.
For Brilliant NextGen in-wall panels (brilliant.tech) — not the Australian "Brilliant Smart" plug/bulb brand. See Credits.
A small agent runs on each Brilliant panel and bridges it to your MQTT broker. Home Assistant discovers everything automatically — no YAML:
- Control your lights and switches. Every load wired to a panel, plus the house-wide Brilliant mesh dimmers and plug-ins, as ordinary HA lights and switches with dimming.
- See what your house is doing. Live per-circuit power for every load, motion from mesh dimmers and panel faceplates, room occupancy, device temperatures, and fault alerts.
- Manage the panels themselves. Screen, brightness, volumes, mic mute, night mode, child lock, screensaver, firmware auto-update — all from HA.
- Use Brilliant scenes from HA (in pilot). Each panel's existing Brilliant scenes and modes appear over MQTT: run them from HA with confirmed execution, and trigger HA automations when someone runs one on the panel.
- Talk to your house (optional). Any panel can become a local wake-word voice satellite for HA Assist, using its built-in mic and speaker.
- Drive Home Assistant lights from the wall (operator setup). Point the panel's built-in Hue integration at a local diyHue bridge backed by Home Assistant, and a wall slider controls any HA-managed bulb (Tuya, WiZ, …) natively — fully local, no SmartThings, no cloud. See the diyHue bridge guide.
Everything stays local: the agent taps the panel's own internal message bus — the same one Brilliant's HomeKit bridge uses — and runs alongside Alexa and HomeKit without breaking them. It survives panel firmware updates.
| Area | What you get |
|---|---|
| Lighting & switches | Panel loads and BLE-mesh loads as HA lights/switches, with brightness |
| Energy | Live wattage per circuit — including always-on gangs you can't see anywhere else |
| Motion & presence | Motion from every mesh dimmer/switch and panel faceplate, plus panel-in-use occupancy |
| Panel settings | 25+ entities per panel: screen, audio, privacy, governance switches |
| Brilliant scenes & modes (in pilot) | Per-panel scene/mode catalogs, HA services with confirmed execution, HA events on native scene runs — see the scene bridge guide |
| Voice satellite | Local wake word → your own HA Assist pipeline (opt-in per panel) |
| HA lights via Hue (operator setup) | The panel's native Hue client drives HA-managed bulbs through a local diyHue bridge — wall slider → any HA light, no cloud. A Hue CA recovery component keeps it alive across firmware OTAs. See diyHue bridge |
| Reliability | Auto-reconnect, watchdogs, and retained MQTT state — entities survive HA restarts, panel reboots, and firmware updates. A bus-health watchdog self-recovers a panel whose Brilliant bus stays wedged. |
Compared to pairing the panels through HomeKit Controller (the usual
workaround): no dropped pairings or setup_retry, far more entities (power,
motion, panel internals), and one clean set of mesh entities instead of
per-panel duplicates.
- One or more Brilliant Smart Home Control panels with Root SSH Login enabled (a supported toggle in the panel's settings)
- An MQTT broker that Home Assistant is connected to. The official Home
Assistant Mosquitto add-on (
core_mosquitto) is the recommended shortcut; an existing local, remote, or hosted broker is equally supported. - Home Assistant with HACS (for the recommended install path)
Recommended: install the companion integration via HACS — add it once, validate the shared broker, then add panels to the resulting fleet. It installs the agent on each panel over SSH, keeps it updated from HA, and auto-repairs after firmware updates.
| Option | Best for | Guide |
|---|---|---|
| HACS integration (recommended) | Most users | docs/ha-integration.md |
| Manual deploy | No Home Assistant, or shell/Ansible preference | deploy/README.md |
Full guide, including broker setup: INSTALL.md.
Sensible defaults out of the box; everything tunable lives in one place:
- docs/CONFIGURATION.md — every entity, env var, and MQTT topic
- docs/voice.md — voice satellite setup
- docs/README.md — full documentation index
- Brilliant Smart Home Control panels — 1-, 2-, 3-, and 4-switch in-wall models and the plug-in Smart Home Control
- Loads wired to panels — dimmers, switches, and always-on circuits
- Brilliant BLE-mesh accessories — Smart Dimmer Switches and Smart Plugs house-wide, published once by an elected panel (with automatic failover)
- Panel sensors — faceplate motion (PIR), ambient light, touch, mic/speaker
Motion-activated dining lights, using a mesh dimmer's built-in motion sensor (entity names follow your own panel and load names):
automation:
- alias: "Dining room: lights on motion"
triggers:
- trigger: state
entity_id: binary_sensor.brilliant_ble_mesh_dining_room_lights_motion
to: "on"
actions:
- action: light.turn_on
target:
entity_id: light.brilliant_ble_mesh_dining_room_lightsAlert when a circuit's power looks wrong (space heater left on):
automation:
- alias: "Office heater left on"
triggers:
- trigger: numeric_state
entity_id: sensor.brilliant_office_heater_power
above: 500
for: "01:00:00"
actions:
- action: notify.mobile_app
data:
message: "The office heater has been on for an hour."Common problems — entities missing, sensors lagging, motion not firing, broker/ACL issues — are covered in docs/TROUBLESHOOTING.md.
git clone https://github.com/joyfulhouse/brilliant-mqtt.git
cd brilliant-mqtt
uv sync
uv run ruff check
uv run mypy --strict src tests scripts/brilliant-panel/bundle_manifest.py
uv run pytestPython 3.10 (panel-locked), uv, ruff, mypy --strict, pytest; all bus/broker I/O sits behind Protocol seams so the unit suite runs on any machine. See docs/DEVELOPMENT.md and docs/ARCHITECTURE.md. Implementation agents: read CLAUDE.md first.
- Join the JoyfulHouse Discord for support and discussion across all JoyfulHouse Home Assistant integrations and libraries.
- Issues: https://github.com/joyfulhouse/brilliant-mqtt/issues
If this project is useful to you, please consider supporting its development:
This project is licensed under the MIT License — see LICENSE for details.
- Built for Brilliant Smart Home Control panels by Brilliant NextGen, Inc. (brilliant.tech, San Mateo, CA). This project is not affiliated with or endorsed by Brilliant NextGen, and is not related to the Australian "Brilliant Smart" lighting brand.
- The agent uses the same on-panel message-bus APIs Brilliant's own HomeKit bridge uses — nothing is modified or jailbroken; Root SSH is an official panel feature.
Built with Omnigent — the open-source AI agent framework and meta-harness.