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 attributes, and can publish downlink messages to devices through the same broker.

• A ThingsBoard server with tenant administrator access. The templates are created there.
• A ThingsBoard Edge instance connected to the server.
• An MQTT broker that the Edge can reach by DNS name or static IP address. This guide uses broker.hivemq.com on port 1883.
• The mosquitto_pub and mosquitto_sub clients installed locally.

The example sensor SN-001 publishes temperature readings to tb-edge/mqtt-integration-tutorial/sensors/SN-001/temperature as {"value":25.1} and subscribes to tb-edge/mqtt-integration-tutorial/sensors/SN-001/rx for commands.

Converter templates are created on the server. The uplink converter decodes the MQTT payload into telemetry and attributes and takes the device name from the topic (segment index 3). The downlink converter encodes messages from the rule engine and sets the target topic from the device name in the message metadata.

1. On the server, go to Edge management > Templates and open the Converter tab. Click Add data converter and select Create new converter.

2. Set Converter type to Uplink, select MQTT as the Integration type, and enter the name MQTT uplink converter.

3. In Main decoding configuration, select TBEL or JS, paste the matching script, and click Add.

   • 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
   

   ▼Expand

1. On the Converter tab, click Add data converter and select Create new converter.

2. Set Converter type to Downlink, select MQTT as the Integration type, and enter the name MQTT downlink converter.

3. In Main encoding configuration, select TBEL or JS, paste the matching script, and click Add.

   • 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),
   
   

   ▼Expand

1. On the server, go to Edge management > Templates, open the Integration tab, and click Add integration.

2. On the Basic settings step, select MQTT as the Integration type. Keep the name MQTT integration or enter your own. Click Next.

3. On the Uplink data converter step, select Select existing, choose MQTT uplink converter, and click Next.

4. On the Downlink data converter step, select Select existing, choose MQTT downlink converter, and click Next.

5. On the Connection step, configure the broker connection:

   Field	Value
   Host	${{brokerIp}}. The placeholder is replaced by the brokerIp server attribute of each Edge.
   Port	1883
   Credentials type	Anonymous
   Topic filters	Replace the default # with tb-edge/mqtt-integration-tutorial/sensors/+/temperature. Keep QoS at 0 - At most once.

6. Expand Advanced settings, turn off Clean session, and keep Downlink topic pattern at its default ${topic}. The integration then publishes downlinks to the topic set by the downlink converter in metadata.topic. Click Add.

The ${{brokerIp}} placeholder lets you assign one template to several Edges that use different brokers. See Configuration placeholders.

Add the brokerIp attribute first. Without it, the assignment dialog warns Edge has missing attribute(s) and the Edge receives the literal placeholder.

1. On the server, go to Edge management > Edges and click the Edge. On the Attributes tab, with the Server attributes scope selected, click +. Enter brokerIp as the key and broker.hivemq.com as the value. Click Add.

2. On the Details tab, click Manage integrations, then Assign to edge (+). Select MQTT integration and click Assign.

3. Log in to the Edge and go to Integrations > Integrations. Open the integration. Host shows broker.hivemq.com instead of the placeholder.

1. Publish a test message with mosquitto_pub. This simulates the sensor sending 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 Integrations > Integrations, open the MQTT integration, and select the Events tab. An Uplink event with status OK appears. Click the three dots in the Message column to see the topic and payload.

3. The device SN-001 is created automatically. On the Edge, go to Devices & assets > Devices, open it, and select the Latest telemetry tab. The temperature key shows 25.2.

4. To see how the converter processed the message, go to Integrations > Data converters, open MQTT uplink converter, and select the Events tab. The In column shows the raw payload, the Out column the decoded telemetry.

To send messages from the rule engine to the integration, add two nodes to the root rule chain of the Edge: originator fields, which puts the device name into the message metadata, and integration downlink, which passes the message to the integration. The downlink converter uses originatorName from the metadata to build the topic.

1. On the Edge, go to Data processing > Rule chains and open Edge Root Rule Chain.

2. In the node search field, type originator fields and drag the originator fields node onto the canvas. Name it add name & type. Keep the default Originator fields mapping (Name to originatorName, Profile name to originatorType) and keep Add mapped originator fields to at Metadata. Click Add.

3. Search for integration downlink and drag the integration downlink node onto the canvas. Name it push to integration, select MQTT integration in the Integration field, and click Add.

4. Connect the nodes:

   • message type switch to originator fields with the Attributes Updated and Post attributes labels.
   • originator fields to integration downlink with the Success label.

5. Click the checkmark icon (Apply changes) to save the rule chain.

1. In a terminal, subscribe to the command topic of the device and keep the window open:

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

2. On the Edge, go to Devices & assets > Devices, open SN-001, and select the Attributes tab. Select the Shared attributes scope, click +, enter the key firmware and the value v1.0, and click Add.

3. The subscriber terminal receives the downlink message:

   {"firmware":"v1.0"}

4. On the Edge, open the Events tab of the integration. A Downlink event with status OK appears. Its message contains the target topic tb-edge/mqtt-integration-tutorial/sensors/SN-001/rx and the payload.

5. To see the encoded message, go to Integrations > Data converters, open MQTT downlink converter, and select the Events tab. The In column shows the message from the rule engine, including originatorName in the metadata. The Out column shows the message sent to the device.