MQTT Integration

MQTT Integration connects ThingsBoard to an external MQTT broker as a client. It subscribes to the topics you configure, and an uplink data converter transforms each message into device or asset data, including telemetry and attributes. ThingsBoard can also publish downlink messages to the broker for devices to consume.

Use MQTT Integration when:

• Devices already publish to an existing broker (Mosquitto, HiveMQ, EMQX, and others) and you want their data in ThingsBoard without changing the firmware.
• The device name or type is encoded in the topic path rather than in the payload.
• Devices send a custom payload format that must be converted before ThingsBoard processes it.
• You need to send commands to devices through the same broker.

1. Receive data. A device publishes a message to the broker. The integration is subscribed to that topic and receives the message.
2. Decode the payload. The uplink converter uses the payload and topic to identify the device or asset and extract attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard can create an entity that does not exist yet.
4. Send downlink data (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and the integration publishes it to the broker on the downlink topic.

• Access to ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• The broker host, port, and credentials.
• The topics your devices publish to, and a sample payload.

Create the uplink converter, assign it to a new MQTT integration, and publish a test message.

The uplink converter receives each MQTT message as a byte array plus its topic, resolves the target device, and returns its telemetry and attributes. MQTT Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.
2. Converter type — keep Uplink.
3. Integration type — select MQTT.
4. Name — enter a name, for example MQTT Uplink Converter. To record converter events, click Failures next to the name, select All messages, and click Apply.
5. Main decoding configuration — the editor is pre-filled with the default MQTT decoder template. Use it as a starting point and, if needed, adapt it to your device. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.
   • TBEL (Recommended)
   • JavaScript

   // Decode an uplink message from a buffer
   // payload - array of bytes
   // metadata - key/value object
   
   /** Decoder **/
   
   // decode payload to JSON
   var data = decodeToJson(payload);
   
   // --- MQTT topic configuration ---
   
   // Supported MQTT topic formats:
   // tb/devices/{deviceType}/{deviceName}
   // tb/devices/{deviceType}/{deviceName}/telemetry
   // tb/sensors/{deviceType}/{deviceName}
   

   ▼Expand

6. Click Test decoder function and check the result (see Test the Decoder).
7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

With a wildcard topic filter, topic holds the actual topic of the message, not the filter. Split it with metadata['topic'].split('/') to read a device name or type from the path.

Built-in helpers:

For field renaming, nested values, and non-JSON payloads, see Common scripting patterns and the converter examples below.

Device Name and Type

The default decoder resolves the device in this order:

Supported topic formats:

• tb/devices/{deviceType}/{deviceName}, optionally followed by /telemetry
• tb/sensors/{deviceType}/{deviceName}, optionally followed by /telemetry

If neither the payload nor the topic provides the device name, the decoder fails with Device name is missing. Provide deviceName in the payload or use a supported MQTT topic format.

If your devices publish to other topics, change topicPrefixes at the start of the decoder, for example to ["factory/devices"]. Each prefix must have exactly two topic levels: the decoder reads {prefix}/{deviceType}/{deviceName}, optionally followed by /telemetry.

Test the Decoder

Click Test decoder function below the editor. The dialog opens with Payload content type set to JSON and this sample payload:

{
  "serialNumber": "SN-001",
  "temperature": 25.5,
  "humidity": 60,
  "battery": 95
}

Metadata is pre-filled with integrationName, includeGatewayInfo, and the topic that a real MQTT message carries:

Click Test. The payload has no deviceName or deviceType, so the decoder takes them from topic. The Output panel shows:

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "attributes": {
    "serialNumber": "SN-001"
  },
  "telemetry": {
    "ts": 1791873701196,
    "values": {
      "temperature": 25.5,
      "humidity": 60,
      "battery": 95
    }
  }
}

Check that deviceName is set and telemetry.values holds the expected keys. If the output is empty or shows an error, fix the decoder and test again.

To see how the template handles a topic in another format, change topic to sensors/Thermostat-01 and click Test again. The decoder fails with Device name is missing. Provide deviceName in the payload or use a supported MQTT topic format. Add "deviceName": "Thermostat-01" to the payload, and the test passes with the device type default.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select MQTT.
   • Name — keep the default MQTT integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose MQTT Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands to devices.
5. Connection:
   • Host and Port — enter the broker address. For a quick test, use the TBMQ demo broker: demo.tbmq.io, port 1883.
   • Credentials type — select the type your broker requires. For the demo broker, select Basic with demo / demo.
   • Topic filters — replace the default # with tb/devices/+/+/telemetry. This filter matches the topic format of the default decoder for every device type and name. With #, the integration also receives every other message on the broker, including its own downlinks on tb/devices/{deviceType}/{deviceName}/commands.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Check connection. When the broker is reachable, the wizard shows Connected. Click Add.

Broker connection

Advanced settings

To create a client certificate and key signed by your CA:

openssl req -newkey rsa:2048 -keyout client_key.pem -out client.csr \
  -nodes -subj "/CN=thingsboard-integration"

openssl x509 -req -in client.csr -CA ca.pem -CAkey ca_key.pem \
  -CAcreateserial -out client.pem -days 3650

Upload ca.pem as CA certificate file, client.pem as Certificate file, and client_key.pem as Private key file. The broker must have TLS enabled first; for TBMQ, see MQTT over SSL.

The integration subscribes to all topic filters when it connects.

Publish a message to the broker, then confirm that ThingsBoard decoded it and created the device.

Publish a test message with mosquitto_pub or any MQTT client. The payload has no deviceName, so the converter takes it from the topic (Thermostat-01).

For the TBMQ demo broker:

mosquitto_pub -h demo.tbmq.io -p 1883 \
  -u "demo" -P "demo" \
  -t "tb/devices/thermostat/Thermostat-01/telemetry" \
  -m '{"temperature":25.1}' -q 0

For your broker with Basic credentials:

mosquitto_pub -h YOUR_BROKER_HOST -p 1883 \
  -u "YOUR_USERNAME" -P "YOUR_PASSWORD" \
  -t "tb/devices/thermostat/Thermostat-01/telemetry" \
  -m '{"temperature":25.1}' -q 0

For a broker without authentication:

mosquitto_pub -h YOUR_BROKER_HOST -p 1883 \
  -t "tb/devices/thermostat/Thermostat-01/telemetry" \
  -m '{"temperature":25.1}' -q 0

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK. Click ⋅⋅⋅ in the Message column to see the topic and payload.
• Converter events — open MQTT Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the received payload, Out shows the decoded result, and Metadata shows the topic and integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created Thermostat-01 with the device profile thermostat. Open it and confirm temperature = 25.1 on the Latest telemetry tab.

ThingsBoard resends unacknowledged MQTT packets — PUBLISH (QoS 1 and 2), SUBSCRIBE, UNSUBSCRIBE, and PUBREL — with exponential backoff. The delay doubles after each attempt, and a jitter factor adds random variance so that clients do not retry in sync.

Example: 3 attempts, 5,000 ms initial delay, jitter factor 0.15 → retries at about 5,000 ms, 10,000 ms, and 20,000 ms (±15% each). After the last attempt, the packet is dropped.

ThingsBoard publishes downlinks to the broker when the Rule Engine routes a message to the integration — for example, after a shared attribute update. Downlinks are always published with QoS 1. The topic comes from the Downlink topic pattern: with the default ${topic}, it is the topic value in the downlink converter’s output metadata.

The downlink converter turns a Rule Engine message into an MQTT payload. For the full encoder reference, see Downlink data converter.

The encoder returns:

• contentType — JSON, TEXT, or BINARY.
• data — the payload to publish.
• metadata — values for the Downlink topic pattern placeholders, for example topic.

For RPC commands, msg.method and msg.params are available. msg.params is a string — use parseFloat(msg.params) or JSON.parse(msg.params) to get a number or an object.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and MQTT integration type are preselected.
3. Enter a name, for example MQTT Downlink Converter.
4. In Main encoding configuration, use the default encoder or write your own.
5. Click Test encoder function and check the result (see Test the Encoder).
6. To record downlink events, click Disabled next to the name, select All messages, and click Apply.
7. Click Add, then Apply changes.

The default encoder publishes the message as JSON to tb/devices/{deviceType}/{deviceName}/commands. If deviceName or deviceType is missing or contains /, +, or #, it raises an error and the downlink is not sent.

/** Encoder **/

// Publish the ThingsBoard message as JSON to the device commands topic:
// tb/devices/{deviceType}/{deviceName}/commands
// Requires deviceName and deviceType in the message metadata,
// e.g. added by the "Originator fields" rule node (name -> deviceName, type -> deviceType).
// metadata.topic is read by the integration when Downlink topic pattern is ${topic}.
var deviceName = metadata['deviceName'];
var deviceType = metadata['deviceType'];

// Reject values that are missing or contain MQTT topic separators/wildcards ('/', '+', '#'):
// such a topic would be invalid and the command would not be delivered.
if (!isValidTopicLevel(deviceName) || !isValidTopicLevel(deviceType)) {
  var errorMessage = "Invalid MQTT downlink topic: deviceName '" + deviceName + "' and deviceType '" + deviceType +
      "' must be present and must not contain '/', '+' or '#'.";
  raiseError(errorMessage);
}

var result = {
  contentType: "JSON",
  data: JSON.stringify(msg),
  metadata: {
    topic: 'tb/devices/' + deviceType + '/' + deviceName + '/commands'
  }
};

function isValidTopicLevel(value) {
  return value != null && value.toString().trim() != '' &&
      value.indexOf('/') < 0 && value.indexOf('+') < 0 && value.indexOf('#') < 0;
}

return result;

Test the Encoder

Click Test encoder function in the encoder toolbar. The dialog opens with Message type ATTRIBUTES_UPDATED, a sample message, and Metadata that includes deviceName and deviceType. To match this guide, set:

• Message — {"temperatureUploadFrequency": 60}
• deviceName — Thermostat-01
• deviceType — thermostat

Click Test. The Output panel shows:

{
  "contentType": "JSON",
  "data": "{\"temperatureUploadFrequency\":60}",
  "metadata": {
    "topic": "tb/devices/thermostat/Thermostat-01/commands"
  }
}

The encoder builds the topic from deviceName and deviceType, so the rule chain first adds these values to the message metadata.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Enrichment section, drag an originator fields node onto the canvas.
3. Enter a Name (for example, Retrieve device name) and map the source fields:
   • Name ⇾ deviceName
   • Profile name ⇾ deviceType
   • Add mapped originator fields to ⇾ Metadata
   • Click Add.
4. Connect the message type switch node to the originator fields node with the Attributes Updated relation.
5. From the Action section, drag an integration downlink node onto the canvas.
6. Enter a Name (for example, Downlink to MQTT integration), select your MQTT integration, and click Add.
7. Connect the originator fields node to the integration downlink node with the Success relation.
8. Click Apply changes.

Subscribe to the downlink topic, then update a shared attribute to trigger a downlink.

1. Subscribe to the downlink topic:

   mosquitto_sub -h demo.tbmq.io -p 1883 -t "tb/devices/thermostat/Thermostat-01/commands" -u "demo" -P "demo"

2. Go to Devices & assets ⇾ Devices, select your device, and open the Attributes tab.

3. Select Shared attributes and click +.

4. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add. ThingsBoard publishes the downlink.

• Subscriber output — the terminal prints the downlink payload:

  {"temperatureUploadFrequency":60}

• Converter events — open the downlink converter’s Events tab. In shows the Rule Engine message with deviceName and deviceType in its metadata. Out shows the encoded payload and the topic tb/devices/thermostat/Thermostat-01/commands in metadata.topic. Metadata shows the integration name.

Ready-made decoders for common payload shapes. Each example lists the input, the decoder, and the output.

Device Name and Type in the Payload

Use when every message carries deviceName and deviceType.

Input payload (any topic):

{
  "deviceName": "Thermometer",
  "deviceType": "thermostat",
  "model": "SN-001",
  "temperature": 33
}

Decoder:

/** Decoder **/

var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.deviceType;

var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       model: data.model,
       integrationName: metadata['integrationName'],
   },
   telemetry: {
       temperature: data.temperature
   }
};

/** Helper function 'decodeToJson' is already built-in **/

return result;

Field mapping:

Output:

{
  "deviceName": "Thermometer",
  "deviceType": "thermostat",
  "attributes": {
    "model": "SN-001",
    "integrationName": "MQTT integration"
  },
  "telemetry": {
    "temperature": 33
  }
}

To adapt:

• Device name in another field — replace data.deviceName with that field.
• One profile for all devices — replace data.deviceType with a string, for example 'thermostat'.
• Rename a field — write outputName: data.sourceField.
• More telemetry — extend the telemetry object.

Device Name from the Topic

Use when devices send readings only and put their identity in the topic path.

Topic structure: tb/mqtt-integration-tutorial/sensors/{deviceName}, for example tb/mqtt-integration-tutorial/sensors/Thermometer-01.

Input payload:

{
  "temperature": 25.1
}

Decoder:

/** Decoder **/

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

// Topic: tb/mqtt-integration-tutorial/sensors/{deviceName}
// Index:  0             1                2         3
var deviceName = metadata.topic.split("/")[3];
var deviceType = 'sensor'; // hardcoded device profile

// Result object with device attributes/telemetry data
var result = {
  deviceName: deviceName,
  deviceType: deviceType,
  attributes: {
    integrationName: metadata['integrationName'],
  },
  telemetry: {
    temperature: data.temperature,
  }
};

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

// Topic: tb/mqtt-integration-tutorial/sensors/{deviceName}
// Index:  0             1                2         3
var deviceName = metadata.topic.split("/")[3];
var deviceType = 'sensor'; // hardcoded device profile

// Result object with device attributes/telemetry data
var result = {
  deviceName: deviceName,
  deviceType: deviceType,
  attributes: {
    integrationName: metadata['integrationName'],
  },
  telemetry: {
    temperature: data.temperature,
  }
};

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

Field mapping:

Output for {"temperature": 25.1} on tb/mqtt-integration-tutorial/sensors/Thermometer-01:

{
  "deviceName": "Thermometer-01",
  "deviceType": "sensor",
  "attributes": {
    "integrationName": "MQTT integration"
  },
  "telemetry": {
    "temperature": 25.1
  }
}

To adapt:

• Another topic depth — change the index in split("/")[3].
• Device type from the topic — replace 'sensor' with another segment, for example metadata.topic.split("/")[2].
• Device name in the payload — replace the topic segment with a payload field, for example data.deviceId.
• Wildcard filter — with tb/mqtt-integration-tutorial/sensors/+, metadata.topic holds the real topic, so the same split works.

Nested JSON Flattened with toFlatMap

Use when the payload is nested and every remaining field should become telemetry. toFlatMap produces dot-separated keys (sensors.co2) and skips the keys in excludeKeys.

Input payload:

{
  "deviceName": "air-monitor-X",
  "deviceType": "air-quality",
  "meta": { "source": "cloud" },
  "sensors": {
    "co2": 412,
    "pm25": 8.2,
    "voc": 0.3
  },
  "location": {
    "lat": 50.45,
    "lon": 30.52
  },
  "ts": 1700000000000
}

Decoder:

/** Decoder **/

var data = decodeToJson(payload);

// Fields to exclude from telemetry — used as device identity, attributes, or timestamp
var excludeKeys = ['deviceName', 'deviceType', 'ts', 'meta', 'location'];

// Flatten all remaining fields into telemetry (nested objects become dot-separated keys)
var telemetry = {};
telemetry.putAll(toFlatMap(data, excludeKeys, true));

// Use the device timestamp (ms) if present, otherwise the current time
var ts = data.ts != null ? data.ts : Date.now();

var result = {
    deviceName: data.deviceName,
    deviceType: data.deviceType,
    attributes: {
        latitude:        data.location.lat,
        longitude:       data.location.lon,
        source:          data.meta.source,
        integrationName: metadata['integrationName']
    },
    telemetry: {
        ts:     ts,
        values: telemetry
    }
};

/** Helper functions 'decodeToString', 'decodeToJson' and 'toFlatMap' are already built-in **/

return result;

Field mapping:

Output:

{
  "deviceName": "air-monitor-X",
  "deviceType": "air-quality",
  "attributes": {
    "latitude": 50.45,
    "longitude": 30.52,
    "source": "cloud",
    "integrationName": "MQTT integration"
  },
  "telemetry": {
    "ts": 1700000000000,
    "values": {
      "sensors.co2": 412,
      "sensors.pm25": 8.2,
      "sensors.voc": 0.3
    }
  }
}

To adapt:

• Other top-level fields to skip — add them to excludeKeys.
• Rename a flattened key — extract the field explicitly and add its parent to excludeKeys so it is not duplicated.
• No timestamp — use ts: Date.now().
• Timestamp in seconds — use ts: data.ts * 1000.

Delimited Text Payload

Use when the device sends text instead of JSON. decodeToString converts the bytes to a string, and split separates the fields.

Input payload:

sensor-001;23.5;60;87

Decoder:

/** Decoder **/

// Decode bytes to a UTF-8 string and split by delimiter
var raw   = decodeToString(payload);
var parts = raw.trim().split(';');

// parts[0] = device name
// parts[1] = temperature
// parts[2] = humidity
// parts[3] = battery

var result = {
    deviceName: parts[0],
    deviceType: 'csv-sensor',
    attributes: {
        integrationName: metadata['integrationName'],
        topic: metadata['topic']
    },
    telemetry: {
        ts: Date.now(),
        values: {
            temperature: parseFloat(parts[1]),
            humidity:    parseFloat(parts[2]),
            battery:     parseInt(parts[3])
        }
    }
};

/** Helper function 'decodeToString' is already built-in **/

return result;

Field mapping:

Output:

{
  "deviceName": "sensor-001",
  "deviceType": "csv-sensor",
  "attributes": {
    "integrationName": "MQTT integration",
    "topic": "tb/sensors/csv/sensor-001"
  },
  "telemetry": {
    "ts": 1780299924174,
    "values": {
      "temperature": 23.5,
      "humidity": 60.0,
      "battery": 87
    }
  }
}

To adapt:

• Another delimiter — replace ';', for example with ',' or '|'.
• Device name from the topic — replace parts[0] with metadata['topic'].split('/').pop().
• Timestamp in the string — parse it into ts and convert seconds to milliseconds.
• Fewer or more fields — edit the values object and the index comments.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — run the integration next to a broker in a private network.
• TBEL — built-in functions and syntax for converter scripts.
• Rule Engine — how messages are processed after decoding.
• MQTT one-way RPC — send a command to a device over MQTT without a response.
• MQTT two-way RPC — send a command to a device over MQTT and receive its response.