MQTT developer guide

Prepare your broker and panel

• Prepare a broker reachable from the panel

  Use a broker you manage, such as Mosquitto on your local network. Note the host, port, username and password. Give the panel permission to subscribe to command topics for its gateway and publish device state, results, availability and revision. For HA discovery, also allow it to publish the relevant homeassistant/switch/…/config topics.

• Check the gateway and connectivity edition

  Use a compatible LANBON edition with suitable firmware. In a Mesh installation, configure Open MQTT on the root panel. Connect an MQTT client to the same broker to subscribe to and verify messages.

Configure the panel

1. Enable Open Integration

   On the panel, open Settings → Open Integration and turn on the master switch. Enter the broker host. If you use a custom port, enter host:port as prompted. Enter your broker username and password.

2. Match the broker’s transport settings

   Match the TLS setting to the broker listener. Common defaults are 1883 for plain MQTT and 8883 for TLS. If the panel identifies LAN TLS as operating without certificate validation, that mode encrypts transport but does not verify the broker’s identity. Use a trusted local network and restrict access to the broker and panel.

3. Enable Open MQTT and confirm it is online

   Turn on the Open MQTT switch. Leave Discovery off for the first connection check. Subscribe to the filter below and confirm online on loip/<gateway_id>/availability. Find the gateway ID in this topic or read gateway_id from LOIP /info. With permissions scoped to a single gateway, subscribe directly to its availability topic.

   Copy

   loip/+/availability

Subscribe to state and send a command

1. Subscribe to component state and results

   Replace the gateway, device and component IDs with your own. Read the current state topics from the broker or get the IDs from the LOIP device snapshot. Keep the colon in the component ID. Subscribe to state, result and availability before sending a command. State is retained and results are not. The revision identifies the current snapshot.

   Copy

   loip/aabbccddeeff/availability
   loip/aabbccddeeff/revision
   loip/aabbccddeeff/d/aabbccddeeff/availability
   loip/aabbccddeeff/d/aabbccddeeff/c/switch:1/state
   loip/aabbccddeeff/d/aabbccddeeff/c/switch:1/result

2. Publish the command

   Publish to the command topic below with QoS 1 and Retain disabled. Use the full LOIP JSON payload. Match the IDs to the topic and use a fresh request_id for each new operation. For dimmers, fans, curtains and water heaters, choose commands and parameters from the capabilities reported by the device.

   Copy

   loip/aabbccddeeff/d/aabbccddeeff/c/switch:1/command

3. Confirm the device and state changed

   After sending the example, match the result by request_id. Watch the device operate and check that state.on becomes true on the state topic. Turn the switch off from the panel and check that the MQTT client receives the updated state. Check MQTT delivery and the device result separately.

   Copy

   {
     "request_id": "setup-001",
     "device_id": "aabbccddeeff",
     "component_id": "switch:1",
     "command": "set_on",
     "params": {
       "on": true
     }
   }

See command examples for other components

Use MQTT discovery in Home Assistant

• Discovery uses the existing broker

  The panel publishes switch discovery configuration to the same broker. Home Assistant reads the configured command and state topics and creates switches automatically. Other components can use their respective MQTT command and state topics.

Read the Home Assistant setup guide

Troubleshoot and disable

• No online message

  Check both switches, the broker listener address and port, TLS mode and account permissions. Check the broker’s connection log. If you have multiple gateways, narrow the subscription to the correct gateway_id.

• State arrives but commands fail

  Check the client’s publish permissions, the IDs in both topic and JSON, and the command and parameters. Check the result and current state before resending. Retained state can still be visible when a device is offline. Check both gateway and target availability before sending commands.

• Pause or resume

  Turn off Open MQTT to pause the broker connection. Turning off the master Open Integration switch also stops MQTT and keeps the saved MQTT switch, Discovery and broker settings. MQTT reconnects when the master switch is enabled again, provided MQTT is enabled and its settings are valid. A factory reset clears these settings and credentials.

Resources and downloads