Azure IoT Hub Integration

Azure IoT Hub Integration connects ThingsBoard to Azure IoT Hub over MQTT as one registered device. It receives the cloud-to-device messages addressed to that device, 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 hub as that device.

Use Azure IoT Hub Integration when:

• A backend application sends data to ThingsBoard as cloud-to-device messages through Azure IoT Hub.
• Messages for several ThingsBoard devices arrive through one device identity: the converter sets the target device for each message.
• An Azure-side consumer must receive ThingsBoard data from the hub’s built-in events endpoint.

1. Receive data. A backend application, the Azure portal, or the Azure CLI sends a cloud-to-device message to the integration’s device identity. The integration is subscribed to devices/{deviceId}/messages/devicebound/# and receives it.
2. Decode the payload. The uplink converter identifies the target device or asset from the payload and extracts 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 devices/{deviceId}/messages/events/ as a device-to-cloud message.

• Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• An Azure account with an active subscription and permission to create an IoT hub and register devices.
• Outbound TCP port 8883 open from the ThingsBoard server (or the remote integration host) to *.azure-devices.net.

Create the hub and the device identity in the Azure portal.

1. In the Azure portal, search for IoT Hub, open the IoT Hub service, and click + Create.
2. On the Basics tab, select or create a Resource group, enter a globally unique IoT hub name (for example, tb-iot-hub), choose a Region, and select a Tier. The Basic tier does not support cloud-to-device messages, so choose the Free or Standard tier.
3. Adjust the Networking and Management tabs if your environment requires it, then click Review + create and Create.
4. When the deployment finishes, click Go to resource.
5. Note the hub hostname {hub-name}.azure-devices.net, for example tb-iot-hub.azure-devices.net: the integration connects to it. The Overview page does not show it. It shows two other hostnames:
   • Service hostname {hub-name}.service.azure-devices.net — for back-end services. The integration connects as a device, so do not use it.
   • Device hostname {hub-name}.device.azure-devices.net — do not use it unless you upload DigiCert Global Root G3 (see Credentials): its server certificate does not chain to the root certificate that ThingsBoard uses by default, and the connection fails.

Search for IoT Hub, open the service, and click Create Select the resource group, enter the hub name, and choose the region and tier Check the summary and click Create When the deployment is complete, click Go to resource The Overview page of the hub. The integration uses tb-iot-hub.azure-devices.net, not the Service hostname or the Device hostname

For tiers and limits, see Create an IoT hub.

1. In the hub, go to Device management ⇾ Devices and click + Add Device.
2. Enter a Device ID, for example tb-bridge-01.
3. Keep Authentication type set to Symmetric key and Auto-generate keys selected.
4. Click Save. The device page opens.
5. Copy the Primary key.

Go to Device management ⇾ Devices and click Add Device Enter the Device ID, keep Symmetric key and Auto-generate keys, and click Save The device page opens. Copy the Primary key

To authenticate with X.509 certificates instead, see Create and manage device identities and Credentials.

You now have the values for the integration:

Create the uplink converter, assign it to a new Azure IoT Hub integration, and send a test message.

The uplink converter receives each message as a byte array plus its topic, resolves the target device, and returns its telemetry and attributes. Azure IoT Hub 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.

This guide uses the sample payload that ThingsBoard provides for Azure IoT Hub converters, with a recent timestamp:

{
  "deviceId": "8F4A2C6D",
  "deviceType": "Packing machine",
  "temperature": 25.5,
  "pressure": 1013.25,
  "vibration": {
    "x": 0.02,
    "y": 0.03,
    "z": 0.015
  },
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10
  },
  "timestamp": "2026-10-14T10:30:00Z",
  "status": "ALARM",
  "alarms": [
    {
      "type": "temperature",
      "severity": "high",
      "message": "Temperature exceeds threshold."
    },
    {
      "type": "vibration",
      "severity": "critical",
      "message": "Excessive vibration detected."
    }
  ],
  "metadata": {
    "version": 1,
    "batteryLevel": 100,
    "batteryStatus": "Charging",
    "manufacturer": "Example corporation"
  }
}

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select Azure IoT Hub.

4. Name — enter a name, for example Azure IoT Hub Uplink Converter.

5. Main decoding configuration — the editor opens with the default Azure IoT Hub template. Replace it with the decoder below. The decoder takes the device name from deviceId and the device profile from deviceType, and rejects a message without them, so no device is created with a wrong name or profile. It maps measurements and state to telemetry and static device properties to attributes. It also reads timestamp, location, and vibration when the payload carries them. The editor opens in TBEL. To use JavaScript, switch the TBEL / JS toggle: the editor then shows the generic JavaScript template, not an Azure IoT Hub one, so replace it with the JavaScript decoder below.

   • TBEL (Recommended)
   • JavaScript

   var data = decodeToJson(payload);
   
   // The device name and type come from the payload. Reject the message if one is missing or empty.
   var deviceName = data.deviceId != null ? data.deviceId.toString().trim() : "";
   if (deviceName.isEmpty()) {
       raiseError("Payload has no deviceId");
   }
   var deviceType = data.deviceType != null ? data.deviceType.toString().trim() : "";
   if (deviceType.isEmpty()) {
       raiseError("Payload has no deviceType");
   }
   
   // ISO 8601 timestamp; fall back to server time.
   var ts = data.timestamp != null ? new Date(data.timestamp).getTime() : Date.now();
   
   

   ▼Expand

   To adapt:

   • Device name in another field — replace data.deviceId, for example with data.serialNumber.
   • Optional fields — remove the location, vibration, status, or alarms mappings your devices never send.
   • Other telemetry — add keys to telemetry, for example humidity: data.humidity.
   • Other device properties — add them to attributes, for example model: data.model.
   • Update-only keys — for Azure IoT Hub, ThingsBoard pre-fills the Update only keys list in Advanced decoding parameters with manufacturer, receivedAlarms, status, batteryLevel, batteryStatus, and version. These keys are stored only when their value changes. Edit the list to match your keys.

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[].

For example, a message sent with the Azure CLI command from Send a Test Uplink arrives with this topic:

devices/tb-bridge-01/messages/devicebound/%24.mid=7c1b13d0-7baa-4cfb-a3c4-1bba7bcbc0b7&%24.to=%2Fdevices%2Ftb-bridge-01%2Fmessages%2Fdevicebound&%24.ce=utf-8&iothub-ack=none

The part after devicebound/ is the URL-encoded property bag: $.mid is the message ID, $.to the destination, $.ce the content encoding.

Built-in helpers:

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

Test the Decoder

Click Test decoder function below the editor. Replace the content of Payload with the sample payload. Click Test. The Output panel shows:

{
  "deviceName": "8F4A2C6D",
  "deviceType": "Packing machine",
  "attributes": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10,
    "version": 1,
    "manufacturer": "Example corporation"
  },
  "telemetry": {
    "ts": 1791973800000,
    "values": {
      "temperature": 25.5,
      "pressure": 1013.25,
      "status": "ALARM",
      "receivedAlarms": [
        {
          "type": "temperature",
          "severity": "high",
          "message": "Temperature exceeds threshold."
        },
        {
          "type": "vibration",
          "severity": "critical",
          "message": "Excessive vibration detected."
        }
      ],
      "vibrationX": 0.02,
      "vibrationY": 0.03,
      "vibrationZ": 0.015,
      "batteryLevel": 100,
      "batteryStatus": "Charging"
    }
  }
}

ts is the payload’s timestamp, 2026-10-14T10:30:00Z, in milliseconds.

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

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select Azure IoT Hub.
   • Name — keep the default 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 Azure IoT Hub 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 data to the hub.
5. Connection:
   • Hostname — enter the hub hostname, for example tb-iot-hub.azure-devices.net.
   • Device ID — enter tb-bridge-01.
   • Credentials — keep Shared Access Signature and paste the device’s primary key into SAS Key.
   • Topic filters — replace the default # with devices/tb-bridge-01/messages/devicebound/# and set QoS to 1 - At least once.
   • Advanced settings — set Max bytes in message to 131072. IoT Hub sends cloud-to-device messages up to 64 KB, and with the default 32368 a larger message (the limit includes the topic) is lost without an event.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

Advanced settings

The integration always connects over TLS on port 8883 with a clean session. IoT Hub delivers only the messages sent after the integration connects: messages sent while it is disabled, restarting, or offline are not delivered. The integration does not offer Check connection: check its status after you add it.

Without a CA certificate file, the integration verifies the hub with the DigiCert Global Root G2 certificate, which {hub-name}.azure-devices.net uses. A CA certificate file replaces it. With Shared Access Signature, the integration reads only the first certificate in the file, so upload a single root certificate: for example, DigiCert Global Root G3 to connect to the Device hostname {hub-name}.device.azure-devices.net. For X.509 device registration, see Authenticate identities with X.509 certificates.

Send a cloud-to-device message to the integration’s device identity, then confirm that ThingsBoard decoded it and created the device.

Send the sample payload without timestamp. The decoder then uses the current server time; with a fixed timestamp, the data would fall outside the recent time windows of your dashboards as time passes.

az iot device c2d-message send \
  --hub-name tb-iot-hub \
  --device-id tb-bridge-01 \
  --data '{"deviceId":"8F4A2C6D","deviceType":"Packing machine","temperature":25.5,"pressure":1013.25,"vibration":{"x":0.02,"y":0.03,"z":0.015},"location":{"latitude":37.7749,"longitude":-122.4194,"altitude":10},"status":"ALARM","alarms":[{"type":"temperature","severity":"high","message":"Temperature exceeds threshold."},{"type":"vibration","severity":"critical","message":"Excessive vibration detected."}],"metadata":{"version":1,"batteryLevel":100,"batteryStatus":"Charging","manufacturer":"Example corporation"}}'

• 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 payload.
• Converter events — open Azure IoT Hub 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 8F4A2C6D with the Packing machine profile. Open it and check the Latest telemetry tab for temperature, pressure, status, receivedAlarms, vibrationX–vibrationZ, batteryLevel, and batteryStatus, and the Attributes tab for latitude, longitude, altitude, version, and manufacturer.

ThingsBoard publishes downlinks to the hub when the Rule Engine routes a message to the integration — for example, after a shared attribute update. Downlinks are published with QoS 1 as device-to-cloud messages from the integration’s Device ID. They reach the hub’s built-in events endpoint, where an Azure-side consumer reads them.

The topic comes from the topic value in the downlink converter’s output metadata. The integration has no fixed downlink topic, so the encoder must set topic to devices/{deviceId}/messages/events/, with the integration’s Device ID. IoT Hub closes the connection when a device publishes to any other topic. The encoder does not receive the Device ID field, so this guide adds the Device ID to the integration’s Metadata as deviceId, and the encoder builds the topic from it. To identify the ThingsBoard device, put its name in the payload.

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

The encoder returns:

• contentType — JSON, TEXT, or BINARY.
• data — the payload to publish.
• metadata — topic, the topic to publish to.

The encoder reads:

• msg, msgType, metadata — the Rule Engine message, its type, and its metadata. For RPC commands, msg.method and msg.params are available.
• integrationMetadata — integrationName and the key–value pairs from the integration’s Metadata field. The encoder in this guide reads deviceId from it.

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 Azure IoT Hub integration type are preselected.
3. Enter a name, for example Azure IoT Hub Downlink Converter.
4. In Main encoding configuration, replace the default encoder with the one below. To use JavaScript, switch the TBEL / JS toggle and take the code from the JavaScript tab.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add.
7. In the integration, expand Advanced settings. In Metadata, click Add, enter deviceId as the key and the integration’s Device ID as the value, for example tb-bridge-01.
8. Click Apply changes.

Encoder used in this guide:

/** Encoder **/

// The rule chain adds the ThingsBoard device name to the metadata.
// Reject the message if it is missing or empty.
var deviceName = metadata.deviceName != null ? metadata.deviceName.trim() : "";
if (deviceName == "") {
  raiseError("Message metadata has no deviceName");
}

// The integration Metadata adds the Azure IoT Hub device ID.
// Reject the message if it is missing or empty.
var azureDeviceId = integrationMetadata.deviceId != null ? integrationMetadata.deviceId.trim() : "";
if (azureDeviceId == "") {
  raiseError("Integration metadata has no deviceId");
}

/** Encoder **/

// The rule chain adds the ThingsBoard device name to the metadata.
// Reject the message if it is missing or empty.
var deviceName = typeof metadata.deviceName === "string" ? metadata.deviceName.trim() : "";
if (!deviceName) {
  throw new Error("Message metadata has no deviceName");
}

// The integration Metadata adds the Azure IoT Hub device ID.
// Reject the message if it is missing or empty.
var azureDeviceId = typeof integrationMetadata.deviceId === "string" ? integrationMetadata.deviceId.trim() : "";
if (!azureDeviceId) {
  throw new Error("Integration metadata has no deviceId");
}

To check the encoder, click Test encoder function. Message type is already ATTRIBUTES_UPDATED. Set Message to {"temperatureUploadFrequency":60} and deviceName in Metadata to 8F4A2C6D, if they differ. Integration metadata has only integrationName until the converter records a downlink event, so click Add and enter deviceId with your Device ID, for example tb-bridge-01. Click Test. The Output shows:

{
  "contentType": "JSON",
  "data": "{\"deviceName\":\"8F4A2C6D\",\"ts\":1794478688069,\"method\":\"setSharedAttributes\",\"params\":{\"temperatureUploadFrequency\":60}}",
  "metadata": {
    "topic": "devices/tb-bridge-01/messages/events/"
  }
}

To adapt:

• Another envelope — build data in the structure your Azure-side consumer expects.
• Payload as is — use data: JSON.stringify(msg) and drop the branches.
• Message properties — append a URL-encoded property bag to the topic, for example 'devices/' + azureDeviceId + '/messages/events/source=thingsboard'. IoT Hub routing queries can filter on these properties.
• Other message types — add branches for other Rule Engine message types.

The encoder puts deviceName in the payload, so the rule chain first adds the device name 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
   • 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 Azure IoT Hub), select your Azure IoT Hub integration, and click Add.
7. Connect the originator fields node to the integration downlink node with the Success relation.
8. Click Apply changes.

IoT Hub does not keep a viewable history of device-to-cloud messages, so start monitoring before you trigger the downlink.

1. Start the event monitor:

   az iot hub monitor-events --hub-name tb-iot-hub --device-id tb-bridge-01

2. Go to Devices & assets ⇾ Devices, select 8F4A2C6D, 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.

• Monitor output — within a few seconds, the terminal prints the event:

  {
    "event": {
      "origin": "tb-bridge-01",
      "module": "",
      "interface": "",
      "component": "",
      "payload": "{\"deviceName\":\"8F4A2C6D\",\"ts\":1794478688069,\"method\":\"setSharedAttributes\",\"params\":{\"temperatureUploadFrequency\":60}}"
    }
  }

• Converter events — open the downlink converter’s Events tab. In shows the Rule Engine message, Out shows the encoded payload and the topic, and Metadata shows the integration name and deviceId.

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.
• Azure Event Hub Integration — read device-to-cloud telemetry from the hub’s built-in endpoint.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• Rule Engine — how messages are processed after decoding.