Skip to content

Integrating Luma One with Home Assistant

This guide explains how to securely connect Luma One (XL) modules to Home Assistant using MQTT Auto Discovery. Once configured, Luma One modules automatically appear in Home Assistant.

Architecture Overview

flowchart LR
  LO([Luma One Module])
  MQTT[(Mosquitto Broker)]
  HA([Home Assistant])

  LO <-- MQTT --> MQTT
  MQTT <--> HA

Broker location

This tutorial assumes the MQTT broker (Mosquitto) runs as an add-on inside Home Assistant.

Prerequisites

  • Luma One (XL) modules connected to the local network
  • Home Assistant device running on the same network

Step 1 — Configure modules

a. Enable Home Assistant Support

  1. Connect to your module with LumaConfig
  2. Navigate to: Dashboard Module → Configuration → Module Configuration → Other
  3. Select sync to other devices on save to automatically enable Home Assistant support for all modules on the LumaLink bus (instead of the connected module only).
  4. Add the following module option (Module Home Assistant Enable): MHEA=1
  5. Press Save

HA Enable

b. Configure MQTT connection

  1. Navigate to Dashboard Module → Configuration → Module Configuration → MQTT
  2. Select sync to other devices on save to automatically set the same MQTT config for all modules on the LumaLink bus (instead of the connected module only).
  3. Select MQTT TCP mode
  4. Set MQTT broker URL, use homeassistant.local or the IPv4 address of your Home Assistant device.
  5. Set your Home Assistant username
  6. Set your Home Assistant password
  7. Press Save and restart the module(s)

MQTT Config

Tip

Using homeassistant.local as URL can cause problems in some cases (multiple Home Assistant devices, mDNS network issues etc.). So use a fixed IPv4 address for your Home Assistant device if you experience problems.

Step 2 — Install and configure Mosquitto broker add-on (Home Assistant)

  1. Navigate to Home Assistant Dashboard → Settings → Add-ons → Add-on store → Mosquitto broker
  2. Install add-on
  3. Enable Start on boot and Watchdog settings
  4. Restart add-on afterwards

MQTT Config

Step 3 — Verify setup

  1. Navigate to Home Assistant Dashboard → Settings → Devices & services → Services
  2. If all went well, your Luma devices should now be present in this list. The device name suffix corresponds to the set LumaLink bus address.
    HA device list
  3. Opening (clicking on) a device shows an overview of the automatically added entities for this device.
    HA device entities
  4. Now you can manually control entities, add them to dashboards, integrate them in automations etc. Please refer to the Home Assistant documentation.

Troubleshooting

❌ Modules not appearing in Home Assistant devices list

  • MQTT autodiscovery typically takes 1-2 minutes to be fully in sync
  • Ensure MHEA=1 option is enabled for all modules
  • Restart Mosquitto broker add-on
  • Restart Luma modules + Home Assistant device
  • Verify all devices are on the same local network
  • Ensure your MQTT credentials are correct
  • Check MQTT connection state in modules with LumaConfig: Dashboard Module → Information → MQTT → State
  • Check Mosquitto broker add-on logs: Add-on → Logs
  • Check Home Assistant logs: Settings → System → Logs
  • Use a fixed IPv4 address for Home Assistant instead of homeassistant.local