Skip to content

MQTT API

Developer documentation

This section is intended for developers only.

Overview

The MQTT API is compatible with the Home Assistant MQTT auto-discovery protocol.
In addition, extra MQTT topics are available for monitoring, service, and direct control.

For integrations with other MQTT clients, we strongly recommend following the
Home Assistant MQTT protocol conventions.

Topics

homeassistant/*

Home Assistant MQTT auto-discovery protocol.

  • Documentation: https://www.home-assistant.io/integrations/mqtt/
  • Enable auto-discovery using the advanced module option MHAE=1 (see LumaConfig manual)
  • More Home Assistant API information below Click here

lumaconnect/*

MQTT protocol used for connecting to LumaConnect.

lumacontrol/status

Comma-separated module status information.
All modules publish to this topic once per minute.

Example payload

ADDR=9,STAT=Normal,MOD=AutoMATE A1,SN=0.00.00.000,SW=0.9.3 (automate),
MAC=1c:9d:c2:f7:58:84,IP=192.168.178.38,UID=8612ffbb,
LL_ERR=0,TEMP=26°C,DT=Mon Dec 22 14:15:58 2025,UP=99d1238m,RAM=50196

Fields

Field Description
ADDR LumaLink bus address
MOD Module hardware
SN Serial number
SW Software version
MAC Ethernet MAC address
IP IPv4 address
LL_ERR LumaLink bus error counter
TEMP Module temperature (°C)
DT Date and time
UP Uptime (days and minutes)
RAM Free memory

lumacontrol/cmd

Send commands directly to one module or to all modules (broadcast).

General command format

command,module-address,channel,arg1,arg2
  • Use module-address = 0 and channel = 0 for broadcast commands

action — Output control

Toggle channel 1 on module 4:

action,4,1,3

Action arguments (arg1)

arg1 Action
1 Turn on (arg2 = optional value 0..100)
2 Turn off
3 Toggle (arg2 = optional value 0..100)
4 Turn on with auto-off delay (seconds)
6 Set value (0..100)

scene — Scene control

Activate the “all off” scene: 

scene,0,0,255

group_on / group_off — Group control

Activate group living:

group_on,0,0,living

Deactivate group living:

group_off,0,0,living

reboot — Restart modules

Restart all modules:

reboot,0,0,543210
  • 543210 = service key
  • module-address = 0 → broadcast reboot

Restart single module:

reboot,5,0,543210
  • 543210 = service key
  • module-address = 5 → restart module with LumaLink address 05

Home Assistant MQTT auto-discovery protocol

Mapping of channel function to HomeAssistant entity type

Channel Function HA entity type
In-Bin-Generic binary sensor
In-Bin-Switch N/A (*1)
In-Pulse-Count sensor
In-Utility-Elec-Energy sensor
In-0-10V sensor
Out-Bin-Generic switch
Out-Bin-Light light
Out-0-10V N/A
Out-Dimmer light
Out-Dimmer 0-10V light
Out-Dimmer CT light
Out-Dimmer RGB light
Out-Dimmer RGBW light
Out-Blinds cover
Out-Blinds H-bridge cover
Out-Bin-Virtual switch
Out-Bin-Logic AND switch
Out-Bin-Logic OR switch
Out-Bin-Logic XOR switch

(*1) A virtual output can be used to tie a pushbutton event to a virtual output action (so it can be used in Home Assistant).

light entity

  • Module MAC = ac1518983ee4
  • Channel = CH27
  • Module LumaLink address = 11

Config topic

homeassistant/light/ac1518983ee4/ch-27/config

Config payload

{
  "~": "homeassistant/light/ac1518983ee4/ch-27",
  "name": "RGB ledstrip",
  "uniq_id": "ac1518983ee4-ch-27",
  "cmd_t": "~/set",
  "stat_t": "~/state",
  "schema": "json",
  "brightness": true,
  "color_mode": true,
  "sup_clrm": [
    "hs"
  ],
  "device": {
    "ids": [
      "ac1518983ee4"
    ],
    "name": "Luma-11",
    "mf": "LumaControls",
    "mdl": "LUMA ONE (FW v0.1.5)",
    "cu": "http://192.168.178.23/"
  }
}
Config sent by module
color_mode and sup_clrm may be absent for unicolor lights.
brightness may be absent for non-dimmable lights.

State get topic

homeassistant/light/ac1518983ee4/ch-27/state

State get payload

{
  "state": "OFF",
  "brightness": 255,
  "color": {
    "h": 216,
    "s": 40
  }
}
State sent by module
Possible states: ON or OFF
color may be absent for unicolor lights.
h hsv hue value between 0 and 360.
s hsv saturation value between 0 and 100.
brightness value between 0 and 255, may be absent for non-dimmable lights.

State set topic

homeassistant/light/ac1518983ee4/ch-27/set

State set payload

{
  "state": "ON",
  "color": {
    "h": 9.123,
    "s": 67.059
  }
}
State received by module
Possible states: ON or OFF
color may be absent for unicolor lights.
h hsv hue value between 0 and 360.
s hsv saturation value between 0 and 100.

binary_sensor entity

  • Module MAC = ac1518983ee4
  • Channel = CH6
  • Module LumaLink address = 11

Config topic

homeassistant/binary_sensor/ac1518983ee4/ch-6/config

Config payload

{
  "~": "homeassistant/binary_sensor/ac1518983ee4/ch-6",
  "name": "Twilight",
  "uniq_id": "ac1518983ee4-ch-6",
  "stat_t": "~/state",
  "schema": "json",
  "device": {
    "ids": [
      "ac1518983ee4"
    ],
    "name": "Luma-11",
    "mf": "LumaControls",
    "mdl": "LUMA ONE (FW v0.1.5)",
    "cu": "http://192.168.178.23/"
  }
}
Config sent by module

State get topic

homeassistant/binary_sensor/ac1518983ee4/ch-6/state

State get payload

OFF
State sent by module
Possible states: ON or OFF

cover entity

  • Module MAC = ac1518983ee4
  • Channel = CH1
  • Module LumaLink address = 11

Config topic

homeassistant/cover/ac1518983ee4/ch-1/config

Config payload

{
  "~": "homeassistant/cover/ac1518983ee4/ch-1",
  "name": "Living cover",
  "uniq_id": "ac1518983ee4-ch-1",
  "cmd_t": "~/set",
  "pos_t": "~/state",
  "set_pos_t": "~/setpos",
  "schema": "json",
  "device": {
    "ids": [
      "ac1518983ee4"
    ],
    "name": "Luma-11",
    "mf": "LumaControls",
    "mdl": "LUMA ONE (FW v0.1.5)",
    "cu": "http://192.168.178.23/"
  }
}
Config sent by module

State get topic

homeassistant/cover/ac1518983ee4/ch-1/state

State get payload

50
State sent by module, value between 0 and 100 (100 = open).

State set topic

homeassistant/cover/ac1518983ee4/ch-1/setpos

State set payload

50
State received by module, value between 0 and 100 (100 = open).

State set action topic

homeassistant/cover/ac1518983ee4/ch-1/set

State set action payload

OPEN
Action received by module, possible actions: OPEN, CLOSE or STOP.

sensor entity

  • Module MAC = ac1518983ee4
  • Channel = CH114 (sensor on pushbutton interface)
  • Module LumaLink address = 11

Config topic

homeassistant/sensor/ac1518983ee4/ch-114/config

Config payload

{
  "~": "homeassistant/sensor/ac1518983ee4/ch-114",
  "name": "CH114-LMS Temp-2.7",
  "uniq_id": "ac1518983ee4-ch-114",
  "stat_t": "~/state",
  "unit_of_meas": "°C",
  "schema": "json",
  "device": {
    "ids": [
      "ac1518983ee4"
    ],
    "name": "Luma-11",
    "mf": "LumaControls",
    "mdl": "LUMA ONE (FW v0.1.5)",
    "cu": "http://192.168.178.23/"
  }
}
Config sent by module
unit_of_meas can be °C (temperature sensors) or % (0-10V inputs).
may be absent may be absent for other sensor types, state value = raw int32 LumaLink value.

State get topic

homeassistant/sensor/ac1518983ee4/ch-114/state

State get payload

21.7
State sent by module, value depends on unit_of_meas set in config.

switch entity

  • Module MAC = ac1518983ee4
  • Channel = CH1
  • Module LumaLink address = 11

Config topic

homeassistant/switch/ac1518983ee4/ch-1/config

Config payload

{
  "~": "homeassistant/switch/ac1518983ee4/ch-1",
  "name": "Socket relay",
  "uniq_id": "ac1518983ee4-ch-1",
  "cmd_t": "~/set",
  "stat_t": "~/state",
  "schema": "json",
  "device": {
    "ids": [
      "ac1518983ee4"
    ],
    "name": "Luma-11",
    "mf": "LumaControls",
    "mdl": "LUMA ONE (FW v0.1.5)",
    "cu": "http://192.168.178.23/"
  }
}
Config sent by module

State get topic

homeassistant/switch/ac1518983ee4/ch-1/state

State get payload

OFF
State sent by module
Possible states: ON or OFF

State set topic

homeassistant/switch/ac1518983ee4/ch-1/set

State set payload

ON
State received by module
Possible states: ON or OFF