Skip to main content

Controlling your network via MQTT

Prerequisites​

In order to control your network via MQTT, you will need to have a Gateway configured in your network. For instructions on setting up a Gateway, see the Gateway Setup guide. The gateway will act as a MQTT client, enabling you to send and receive messages to and from your network via MQTT topics. Therefore you will also need to have a MQTT broker running in your network.

Setup​

In order to use the Gateway as an MQTT bridge, you will need to configure it. This includes configuring the Gateways MQTT client in order to connect to your MQTT broker. Additionally you will have to upload the network to the gateway for it to know your devices, groups and scenes.

info

The required gateway firmware version to enable MQTT configuration is >6.0.0. Gateways with older firmwares will not show the MQTT configuration option.

All configuration is done via the MQTT configuration page.

  • Go to the gateway device detail page
  • Open the context menu
  • Select "Configure MQTT"

Gateway MQTT configuration​

After adding the gateway to your network, you can configure it to connect to your MQTT broker.

Fill in the following fields:

  • MQTT-URL: The URL your MQTT broker is available at. This includes the protocol ("mqtt://" or if you have TLS enabled "mqtts://") and the IP address or hostname of your MQTT broker as well as the port number.
  • Root-Topic: The root topic under which the gateway will publish to and listen for messages. This will be prefilled to your current network name.
  • Client ID: A unique identifier for the gateways MQTT client, leave empty for a randomized one.
  • Username: The gateways MQTT client username.
  • Password: The gateways MQTT broker password.

Once you have entered all required fields, click the "Save" button to apply the configuration.

Certificate setup​

If you have enabled TLS on your MQTT broker, you will need to provide the certificate of your MQTT broker to the gateway. Enter a url starting with "mqtts://" into the MQTT-URL field. This will enable the options for you to upload a server certificate (required). Additionally you can optionally upload client certificates and keys.

Network upload​

In the MQTT settings page, select "Upload network" to upload the network to the gateway in order for it to be able to translate raw "Mesh Messages" into useful MQTT topics and associate them with the devices/groups in your network. After the network has been changed (e.g. new Groups added) this will have to be repeated to update the gateway's network representation.

Available Topics​

See MQTT API Documentation for a full documentation of the available topics and message formats.