Integration with ThingsBoard

This guide shows how to connect ThingsBoard to TBMQ using the ThingsBoard MQTT Integration, so that data published by MQTT clients to TBMQ becomes device telemetry in ThingsBoard.

The ThingsBoard MQTT Integration acts as an ordinary MQTT client: it connects to TBMQ, subscribes to a topic filter, and converts each received message into telemetry and attribute updates using an uplink data converter. This guide configures it as an APPLICATION client with a persistent session, so messages published while ThingsBoard is offline are queued by TBMQ and delivered on reconnect.

• A running ThingsBoard PE instance, or a ThingsBoard Cloud tenant with integrations enabled
• A running TBMQ instance reachable from ThingsBoard
• The mosquitto_pub MQTT client, to publish a test message

Four settings decide whether ThingsBoard receives every message or only the ones published while it happens to be connected. Three of them live on the ThingsBoard side, one on the TBMQ side:

Create the client credentials that ThingsBoard will use to connect.

These credentials use Basic authentication, which is the one authentication provider TBMQ enables out of the box. If it was turned off on your instance, re-enable it on the Authentication → Providers page before continuing.

1. In the TBMQ UI, go to Authentication → Credentials and click Add (+).
2. Enter a credential name and select Application as the client type.
3. Select Basic as the credentials type.
4. Enter a Username and Password (e.g., tb-pe / secret).
5. Click Add.

The Credentials table lists every client credential on the broker. Use the "plus" icon in the top right corner to add one. Client type "Application" is what routes this client to its own Kafka topic. Credentials type "Basic" enables username and password authentication. The Username and Password entered here are the ones ThingsBoard sends in its CONNECT packet. This guide uses "tb-pe" and "secret". The new credential appears in the table with client type APPLICATION.

The uplink converter parses each incoming MQTT message — payload plus metadata such as the topic it arrived on — into the device name, attributes, and telemetry that ThingsBoard stores.

In ThingsBoard, go to Integrations center → Data converters and add a converter. Name it TBMQ Uplink Converter, select type Uplink, and paste the decoder script below.

The script takes the device name from the fourth topic segment, so a message on tb/mqtt-integration-tutorial/sensors/SN-001/temperature is attributed to device SN-001.

/** 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;

/** 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 **/

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

function decodeToJson(payload) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

return result;

1. Go to Integrations center → Integrations and click + Add integration. Set Integration type to MQTT, name it MQTT Integration, and continue to the next step.
2. Select the TBMQ Uplink Converter you just created.
3. Leave the Downlink data converter field empty and click Skip — a downlink converter is only needed to send commands back to devices, which is covered in Downlink and RPC.
4. Specify the TBMQ Host and Port (1883 for the default TBMQ TCP listener). Select Basic credentials and enter the username and password created above. Add the topic filter tb/mqtt-integration-tutorial/sensors/+/temperature and set QoS to 1 or 2.
5. Open Advanced settings. Uncheck Clean session and set Client ID to tbpeintegration.
6. (Optional) Click Check connection to verify TBMQ is reachable. Click Add to create the integration.

Adding a new integration of type MQTT in the Integrations center. Selecting the uplink converter that will decode messages arriving from TBMQ. The downlink converter is optional and can be added later, so this step is skipped. Connection settings: the TBMQ host and port, Basic credentials, and the topic filter with QoS 1. QoS 0 here would bypass persistence entirely. Advanced settings. Clean session unchecked plus a fixed client ID are what make the session persistent and reusable across reconnects. Check connection confirms TBMQ accepted the credentials before the integration is saved.

Once the integration is created, open the Sessions page in the TBMQ UI. A session for client ID tbpeintegration should be listed with status Connected, client type APPLICATION, and marked as persistent.

Because the client is a persistent APPLICATION client, TBMQ has also created its dedicated Kafka topic. Open Kafka management → Topics and look for tbmq.msg.app.tbpeintegration, listed with its partitions, replicas, and size.

Publish a temperature reading as a device would. Replace the host and credentials with your own if you changed them:

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"

The -q 1 is deliberate: at QoS 0 the message would skip the persistent path, so it would be lost rather than queued if ThingsBoard happened to be disconnected.

In ThingsBoard, open the MQTT integration and go to its Events tab. An uplink event should show the message as received and converted.

Then go to Entities → Devices. The integration provisions a device named SN-001 on first message. Open it and switch to the Latest telemetry tab — the temperature key should hold 25.1.

To confirm the offline queueing actually works, disable the integration in ThingsBoard, publish a few more messages at QoS 1, then re-enable it. The messages queued in TBMQ are delivered as soon as the integration reconnects.

This guide covers uplink only. To send commands from ThingsBoard back to devices through TBMQ, add a downlink data converter to the integration: ThingsBoard encodes the Rule Engine message and publishes it to TBMQ, where the device is subscribed. The downlink topic comes from the integration’s Downlink topic pattern setting, which resolves metadata.topic from the converter output.

The encoder API and the RPC walkthroughs live in the ThingsBoard documentation:

• MQTT Integration — downlink setup and troubleshooting
• Downlink data converter — the full encoder function reference

• TBMQ client type — how DEVICE and APPLICATION clients are persisted and delivered
• Non-persistent and persistent sessions — what a persistent session retains
• MQTT over SSL — secure the connection between ThingsBoard and TBMQ
• TBMQ integrations — the reverse direction, where TBMQ itself pushes messages out to HTTP, Kafka, or another MQTT broker