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.
• One hub connection must deliver data for many ThingsBoard devices: 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 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 to *.azure-devices.net.

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

1. In the Azure portal, click + Create a resource, search for IoT Hub, 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), and choose a Region.
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. On the Overview page, copy the Hostname, for example tb-iot-hub.azure-devices.net.

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.
5. Open the device and copy its 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 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; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   var data = decodeToJson(payload);
   
   var deviceName = data.deviceId != null ? data.deviceId : "Device A";
   var deviceType = data.deviceType != null ? data.deviceType : "default";
   
   // ISO 8601 timestamp; fall back to server time.
   var ts = data.timestamp != null ? new Date(data.timestamp).getTime() : Date.now();
   
   // Static device properties become attributes.
   var attributes = {};
   if (data.location != null) {
       attributes.latitude = data.location.latitude;
       attributes.longitude = data.location.longitude;
       attributes.altitude = data.location.altitude;
   }
   

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

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/#.
   • 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. It does not offer Check connection: check the integration status after you add it.

Without a CA certificate file, the integration verifies the hub with the DigiCert Global Root G2 certificate, which Azure IoT Hub uses. Upload your own CA bundle only if your environment requires it. 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. 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.

For RPC commands, msg.method and msg.params are available.

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. Replace tb-bridge-01 with your Device ID.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add, then Apply changes.

Encoder used in this guide (TBEL and JavaScript):

/** Encoder **/

// Prepare the downlink payload.
var data = {
  deviceName: metadata.deviceName,
  ts: Date.now()
};

// Map Rule Engine messages to commands.
if (msgType == 'RPC_CALL_FROM_SERVER_TO_DEVICE') {
  // RPC request.
  data.method = msg.method;
  data.params = msg.params;
  data.requestId = metadata.requestId;
} else if (msgType == 'ATTRIBUTES_UPDATED' || msgType == 'POST_ATTRIBUTES_REQUEST') {

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, then click Test. The Output shows:

{
  "contentType": "JSON",
  "data": "{\"deviceName\":\"8F4A2C6D\",\"ts\":1755422164000,\"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/tb-bridge-01/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\":1755422164000,\"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 Metadata shows the topic.

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.