MQTT Integration

MQTT Integration connects ThingsBoard Edge to an external MQTT broker as an MQTT client. It subscribes to topics, converts incoming payloads into telemetry and attribute updates, and can send downlink messages back to devices via the same broker.

• A ThingsBoard Professional Edition (Cloud) account or a self-hosted ThingsBoard PE server — used to create integration templates.
• A locally installed ThingsBoard PE Edge instance.
• An accessible MQTT broker. This guide uses broker.hivemq.com on port 1883.
• mosquitto_pub and mosquitto_sub MQTT clients installed locally.
• A sensor device SN-001 that:
  • publishes temperature readings to tb-edge/mqtt-integration-tutorial/sensors/SN-001/temperature as {"value":25.1}
  • subscribes to tb-edge/mqtt-integration-tutorial/sensors/SN-001/rx to receive RPC commands.

Integration and converter templates are created on the Cloud (ThingsBoard PE server) and assigned to Edge instances.

1. In the Cloud, go to Edge management > Integration templates and click +. Select MQTT as the type, name it Edge MQTT Integration, then click Next.

2. Create the Uplink converter. The uplink converter decodes the raw MQTT payload into ThingsBoard telemetry and attributes. The device name is extracted from the MQTT topic (segment index 3).

   • TBEL (recommended)
   • JavaScript

   /** Decoder **/
   
   // decode payload to string
   var payloadStr = decodeToString(payload);
   var data = JSON.parse(payloadStr);
   
   var deviceName = metadata.topic.split("/")[3];
   var deviceType = 'sensor';
   
   // Result object with device attributes/telemetry data
   var result = {
       deviceName: deviceName,
       deviceType: deviceType,
       attributes: {
           integrationName: metadata['integrationName'],
       },
       telemetry: {
           temperature: data.value,
       }
   };
   
   /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
   
   return result;

   Select Create new, paste the script into the Decoder function field, and click Next.

3. Create the Downlink converter. The downlink converter encodes outbound messages (e.g. attribute updates) into the MQTT payload and sets the target topic using the device name from metadata.

   • TBEL (recommended)
   • JavaScript

   /** Encoder **/
   
   // Result object with encoded downlink payload
   var result = {
       // downlink data content type: JSON, TEXT or BINARY (base64 format)
       contentType: "JSON",
   
       // downlink data
       data: JSON.stringify(msg),
   
       // Optional metadata object presented in key/value format
       metadata: {
           topic: 'tb-edge/mqtt-integration-tutorial/sensors/' + metadata['originatorName'] + '/rx'
       }
   };
   
   return result;

   Select Create new, paste the script into the Encoder function field, and click Next.

4. On the Connection page, configure the broker connection:

   • Set Host to ${{brokerIp}} — this placeholder will be replaced by the brokerIp attribute value on each Edge instance.
   • Set Port to 1883.
   • Add a topic filter: tb-edge/mqtt-integration-tutorial/sensors/+/temperature
   • Set the QoS level as needed (default is 0 — at most once).

5. Open Advanced settings:

   • Uncheck Clean session — many brokers silently close connections when this option is enabled.
   • Leave Downlink topic pattern at the default so the integration uses metadata.topic as the downlink topic.

   Click Add to save the integration template.

To send downlink messages from the Rule Engine to the MQTT integration, add two rule nodes to the Edge Root Rule Chain: originator fields and integration downlink.

Before assigning the integration template, add the brokerIp attribute to the Edge instance. This provides the value for the ${{brokerIp}} placeholder used in the integration configuration.

1. Send a test uplink message using mosquitto_pub. This simulates a device publishing a temperature reading:

   mosquitto_pub -h broker.hivemq.com -p 1883 \
     -t "tb-edge/mqtt-integration-tutorial/sensors/SN-001/temperature" \
     -m '{"value":25.2}'

2. On the Edge, go to Integration center > Integrations and open the Events tab on your MQTT integration. A message with status OK should appear. Click the three dots in the Message column to inspect the payload.

3. A new device is created automatically. Go to Entities > Devices on the Edge to see it.

4. To inspect how the Uplink Converter processed the message, go to Integration center > Data converters, open the uplink converter, and select the Events tab.

1. In a terminal, subscribe to the device’s RX topic. Keep this window open — incoming downlink messages will appear here.

   mosquitto_sub -h broker.hivemq.com -p 1883 \
     -t "tb-edge/mqtt-integration-tutorial/sensors/+/rx"

2. On the Edge, go to Entities > Devices, select device SN-001, and open the Attributes tab. Under Shared attributes, click + and add a new attribute — for example, key firmware, value v1.0. Save.

3. The subscriber terminal should receive the downlink message.

4. Verify the downlink was sent by opening the integration’s Events tab.

5. Inspect the downlink in the Downlink Converter. Go to Integration center > Data converters, open the downlink converter, and select the Events tab.