MQTT Integration

• Prerequisites
• Create converter and integration templates
• Modify Edge Root Rule Chain for downlinks
• Assign Integration to Edge
• Send uplink message
• Send downlink message to device
• Next steps

Edge MQTT Integration is implemented in a similar way, as MQTT Integration. The only difference is in the way, how integration is created and provisioned. Please make sure that you have knowledge of MQTT Integration before proceed.

MQTT Integration allows to connect to external MQTT brokers, subscribe to data streams from those brokers and convert any type of payload from your devices to ThingsBoard Edge message format. Its typical use is whenever your devices are already connected to external MQTT broker or any other IoT platform or connectivity provider with MQTT based back-end.

Please review the integration diagram to learn more.

ThingsBoard Edge MQTT Integration acts as an MQTT client. It subscribes to topics and converts the data into telemetry and attribute updates. In case of downlink message, MQTT integration converts it to the device-suitable format and pushes to external MQTT broker.

Pay attention: MQTT broker should be either co-located with ThingsBoard Edge instance or deployed in the cloud and have a valid DNS name or static IP address.

Prerequisites

In this tutorial, we will use:

• ThingsBoard Professional Edition instance — thingsboard.cloud;
• The instance of ThingsBoard PE Edge installed locally;
• MQTT broker, accessible by ThingsBoard Edge instance — broker.hivemq.com (port 1883);
• mosquitto_pub and mosquitto_sub MQTT clients to send and receive messages.

Let’s assume that we have a sensor which is sending current temperature readings. Our sensor device SN-001 publishes it’s temperature readings to ‘tb-edge/mqtt-integration-tutorial/sensors/SN-001/temperature’, and it is subscribed to ‘tb-edge/mqtt-integration-tutorial/sensors/SN-001/rx’ to receive RPC calls.

We will send a message with temperature readings in a simple format: {"value":25.1}

Create converter and integration templates

Converter and integration templates are created only on the ThingsBoard Professional Edition. So please use ThingsBoard Cloud or install your own platform instance to log in as Tenant administrator.

Follow the steps below to add the MQTT integration:

• Go to “Edge management” section -> “Integration templates” page and click “plus” button to add new integration. Select type ‘MQTT’. Name it “Edge MQTT integration”. Then, click “Next”;

While Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode can significantly increase the disk space used by the database since all the debug data is stored there. It is highly recommended turning the Debug mode off after debugging is complete.

• The next step is to create an Uplink data converter.

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. Attributes and telemetry are flat key-value objects. Nested objects are not supported.

For this example, use the code below.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);

var deviceName =  metadata.topic.split("/")[3];
// decode payload to JSON
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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);

var deviceName =  metadata.topic.split("/")[3];
// decode payload to JSON
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 **/

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
    // convert payload to string.
    var str = decodeToString(payload);

    // parse string to JSON
    var data = JSON.parse(str);
    return data;
}

return result;

• At the next step is to create a Downlink converter.

The downlink converter transforming outgoing RPC message and then the Integration sends it to external MQTT broker. You can customize a downlink according to your configuration. Let’s consider an example where we send an attribute update message.

For this example, use the code below.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/** 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;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/** 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;

Finally, we go to the “Connection” page.

• You can use placeholder ${{ATTRIBUTE_KEY}} to substitute integration field with attribute value from specific Edge entity. In this example, we will use the placeholder ${{brokerIp}} for ‘Host’ and 1883 for ‘Port’.
• Add a topic filter:

1
tb-edge/mqtt-integration-tutorial/sensors/+/temperature

• You can also select an MQTT QoS level. We use MQTT QoS level 0 (At most once) by default;

• Go to the ‘Advanced settings’. It is better to uncheck the ‘Clean session’ parameter. Many brokers do not support sticky sessions, so will silently close the connection if you try to connect with this option enabled;
• Let’s leave the ‘Downlink topic pattern’ by default, meaning that the integration will take the metadata.topic and use it as the downlink topic;
• Click “Add” button to create the integration.

Modify Edge Root Rule Chain for downlinks

We can send a downlink message to the device from Rule chain using the rule node. To be able to send downlink over integration we need to modify ‘Edge Root Rule chain’ on the ThingsBoard PE. We’ll need to add two rule nodes: ‘originator fields’ and ‘integration downlink’ nodes.

• Go to the "Edge management" section -> "Rule chain templates" page and click on the "Edge Root Rule Chain" to open it;
• Create an 'originator fields' node. Configure adding originator name and originator type to the message metadata - in the downlink converter name of the device will be used to set the proper downlink MQTT topic;
• Create an 'integration downlink' node. Specify your integration in its settings;
• Set the "Attributes Updated" and "Post attributes" links from the 'message type switch' node to the 'originator fields' node. And set 'Success' link from the 'originator fields' node to the 'integration downlink' node. When the attribute is created or changes are made to the attribute on the Edge, the downlink message will be sent to the integration. Apply changes.

Assign Integration to Edge

Once converter and integration templates are created, we can assign Integration template to Edge. Because we are using placeholder ${{brokerIp}} in the integration configuration, we need to add attribute ‘brokerIp’ to edge first. You need to provide IP address of the MQTT broker. We are using public URL ‘broker.hivemq.com’ in this tutorial, but this could be any internal IP address as well. Once attribute added, we are ready to assign integration and verify that it’s added.

• Go to the "Edge management" section -> "Instances" page, click on your edge instance to open "Edge details" window, and navigate to the "Attributes" tab. Click "plus" icon to add new server attribute to Edge;
• Named 'brokerIp' and set value as 'broker.hivemq.com'. After, click "Add" button;
• Added the server attribute ''brokerIp'' to the edge;
• Now, click "Manage edge integrations" icon of Edge entity;
• Click the "+" icon at the top right of the corner. Specify your integration and click "Assign" button to assign it to the Edge;
• Login to your ThingsBoard Edge instance and open "Integrations center" section -> "Integrations" page. You should see your integration. Click on it;
• In the "Integration details" window placeholder ${{brokerIp}} will be replaced with the value of the attribute.

Send uplink message

To send an uplink message, use the command provided below. It simulates a device sending temperature readings to the integration:

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

Now, go to the “Integrations center” -> “Integrations” and navigate to the “Events” tab in your MQTT integration on the ThingsBoard Edge. If you have done everything correctly, you will find an uplink message with the status ‘OK’. To see the message itself, click the three dots in the ‘Message’ column.

When you sent the message, a new device was created. The created device with data can be seen in the “Entities” section -> “Devices” page:

Also, received data can be viewed in the uplink converter. In the ‘In’ and ‘Out’ blocks of the “Events” tab:

Send downlink message to device

Now let’s check downlink functionality. Open the terminal window and execute the following command:

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

Please leave this terminal running in background - in this terminal window you should receive incoming messages sent later by integration.

Now, let’s add a ‘firmware’ shared attribute. Go to the “Devices” page, select your device, and navigate to the “Attributes” tab on the ThingsBoard Edge. Select the “Shared attributes” scope and click on the “plus” icon to create new attribute. Then set the attribute name, its value (for example, the key name is ‘firmware’, value: ‘v1.0’) and save the data.

An example of incoming messages from ThingsBoard Edge in the terminal:

To make sure that downlink message sent to integration you can check “Events” tab of the integration:

Received data and data that was sent can be viewed in the downlink converter. In the ‘In’ block of the “Events” tab, we see what data entered and in the ‘Out’ field, the message sent to the device is displayed:

Next steps

• Getting started guide - Provide quick overview of main ThingsBoard Edge features. Designed to be completed in 15-30 minutes:

• Installation guides - Learn how to setup ThingsBoard Edge on various available operating systems and connect to ThingsBoard CE server.

• Edge Rule Engine:

  • Rule Chain Templates - Learn how to use ThingsBoard Edge Rule Chain Templates.

  • Provision Rule Chains from cloud to edge - Learn how to provision edge rule chains from cloud to edge.

• Security:
  • gRPC over SSL/TLS - Learn how to configure gRPC over SSL/TLS for communication between edge and cloud.

• Features:

  • Edge Status - Learn about Edge Status page on ThingsBoard Edge.

  • Cloud Events - Learn about Cloud Events page on ThingsBoard Edge.

• Use cases:

  • Manage alarms and RPC requests on edge devices - This guide will show how to generate local alarms on the edge and send RPC requests to devices connected to edge:

  • Data filtering and traffic reduce - This guide will show how to send to cloud from edge only filterd amount of device data:

• Roadmap - ThingsBoard Edge roadmap.