Integration with ThingsBoard

ThingsBoard PE Feature

Only Professional Edition supports Platform Integrations feature.
Use ThingsBoard Cloud or install your own platform instance.

• Prerequisites
• TBMQ setup
• ThingsBoard setup
  • Uplink Converter
  • MQTT Integration Setup
  • Send Uplink message
• Next steps

TBMQ is an industry-ready MQTT broker developed and distributed under the ThingsBoard umbrella that facilitates MQTT client connectivity, message publishing, and distribution among subscribers.

In this guide, we integrate the TBMQ with the ThingsBoard using MQTT integration. We utilize TBMQ client credentials with the type APPLICATION to connect ThingsBoard integration as an APPLICATION client. APPLICATION clients specialize in subscribing to topics with high message rates. The messages will be persisted when the client is offline and will be delivered once it goes online, ensuring the availability of crucial data. Read more about the APPLICATION client here.

ThingsBoard MQTT Integration acts as an MQTT client. It subscribes to topics and converts the received data into telemetry and attribute updates. In case of a downlink message, MQTT integration converts it to the device-suitable format and pushes it to TBMQ. Pay attention: TBMQ should be either co-located with the ThingsBoard instance or deployed in the cloud and have a valid DNS name or static IP address. ThingsBoard instance that is running in the cloud can’t connect to the TBMQ deployed in the local area network with no internet connection.

Prerequisites

In this tutorial, we will use:

• The instance of ThingsBoard Professional Edition installed locally;
• TBMQ installed locally and accessible by ThingsBoard PE instance;
• mosquitto_pub MQTT client to send messages.

TBMQ setup

First, we need to create TBMQ client credentials to use them for connecting ThingsBoard integration to TBMQ.

To do this, login to your TBMQ user interface and follow the next steps.

• Navigate to "Credentials" tab, click on the "plus" icon in the top right corner of the table;
• Input client credentials name, select client type. Enable "Basic" authentication type.
• Input "Username" and "Password" with chosen values. For example, use `tb-pe` value for Username and `secret` for Password fields. Click "Add" to save credentials.
• New client credential is created.

Please note:
The “SECURITY_MQTT_BASIC_ENABLED” environment variable must be set to “true”.

Now you can proceed to the next step - configuration of ThingsBoard integration.

ThingsBoard setup

In this example, we will use the MQTT integration to connect the ThingsBoard to TBMQ. Before setting up an MQTT integration, you need to create uplink converter.

Uplink Converter

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume.

To create uplink converter, go to the “Integrations center” section -> “Data converters” page and click on the “plus” icon. Name it “TBMQ Uplink Converter” and select type “Uplink”. Paste the decoder script below into the decoder functions section. Click “Add”.

In our example, use the following script for the decoder function section:

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;

MQTT Integration Setup

Now create an integration.

• Go to the "Integrations center" section -> "Integrations" page and click "plus" icon to add a new integration. Name it "MQTT Integration", select type "MQTT";
• Add the recently created uplink converter;
• Leave the "Downlink data converter" field empty. Click "Skip";
• Specify host and port of TBMQ instance. Select "Basic" credentials type and specify TBMQ client credentials. Add a topic filter: "tb/mqtt-integration-tutorial/sensors/+/temperature" and select an MQTT QoS level higher than 0;
• Now go to the advanced settings. Uncheck the "Clean session" parameter and specify client ID as `tbpeintegration`;
• [Optional] Click on Check connection button to check connection to TBMQ. Click Add button to create the integration.

Now go to the “Sessions” page in the TBMQ UI. Upon successful establishment of the connection between ThingsBoard and TBMQ, we will see a new session and its status - “Connected”.

And on the “Topics” page of the “Kafka Management” menu section you will see a name of Kafka topic (which corresponds to the client ID specified in the MQTT integration), number of partitions, replication factor and size of the topic.

Send Uplink message

Now let’s simulate the device sending a temperature reading to TBMQ.

Open the terminal and execute the following command to send a message with temperature readings in a simple format: {"value":25.1} to the topic “tb/mqtt-integration-tutorial/sensors/SN-001/temperature”:

1
mosquitto_pub -h $THINGSBOARD_MQTT_BROKER_HOST_NAME -p 1883 -q 1 -t "tb/mqtt-integration-tutorial/sensors/SN-001/temperature" -m '{"value":25.1}' -u "username" -P "password"

Replace the $THINGSBOARD_MQTT_BROKER_HOST_NAME with the correct public IP address or DNS name of the broker, username and password values according to the specified ones in the provisioned credentials.

Use the following command for our example:

1
mosquitto_pub -h localhost -p 1883 -q 1 -t "tb/mqtt-integration-tutorial/sensors/SN-001/temperature" -m '{"value":25.1}' -u "tb-pe" -P "secret"

After you sent uplink message, go to your integration in ThingsBoard UI and navigate to the “Events” tab. There you’ll see the message consumed by the “MQTT Integration”.

Go to the “Entities” section -> “Devices” page. You should find a SN-001 device provisioned by the integration. Click on the device, go to “Latest Telemetry” tab to see “temperature” key and its value (25.1) there.

Next steps

• Getting started guide - This guide provide quick overview of TBMQ.

• Installation guides - Learn how to set up TBMQ on various available operating systems.

• Security guide - Learn how to enable authentication and authorization of MQTT clients.

• Configuration guide - Learn about TBMQ configuration files and parameters.

• MQTT client type guide - Learn about TBMQ client types.