Azure IoT Hub Integration

Azure IoT Hub Integration connects ThingsBoard to Azure IoT Hub over MQTT, receiving device messages and converting them into ThingsBoard telemetry and attributes.

Before creating the integration in ThingsBoard, set up your Azure IoT Hub and register a device:

1. Create an IoT hub in the Azure portal.
2. Register a new device in the IoT hub. Note the device ID and SAS key — you will need them when configuring the integration.

The uplink converter transforms incoming Azure IoT Hub messages into the ThingsBoard data format. Azure IoT Hub uses a generic uplink converter. ThingsBoard provides a pre-built converter for Azure IoT Hub — import the JSON file and customize the decoder function to match your device payload structure.

Sample payload:

{
  "devName": "T1",
  "msg": {
    "temp": 42,
    "humidity": 77
  }
}

The devName field maps to the device name. The nested msg object provides temperature and humidity telemetry.

1. Download the uplink converter file:
   • TBEL (Recommended)
   • JavaScript
   azure_iot_hub_tbel_uplink_converter.json
2. Go to Integrations center ⇾ Data converters.
3. Click + Add data converter ⇾ Import converter.
4. Drag and drop the downloaded JSON file into the Import converter window and click Import.

The decoder function used in this tutorial:

var data = decodeToJson(payload);
var deviceName = data.devName;
var deviceType = 'thermostat';

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: {
        temperature: data.msg.temp,
        humidity: data.msg.humidity
    }
};

return result;

var data = decodeToJson(payload);
var deviceName = data.devName;
var deviceType = 'thermostat';

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: {
        temperature: data.msg.temp,
        humidity: data.msg.humidity
    }
};

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;

To adapt this converter to your device:

• Different device name — change data.devName to the field in your payload that carries the device identifier.
• Different payload structure — adjust the field paths (e.g. data.msg.temp) to match your payload layout.
• Additional telemetry — add more keys to the telemetry object (e.g. pressure: data.msg.pressure).
• Attributes — add an attributes key alongside telemetry to store static device properties.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to Azure IoT Hub.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the previously imported Azure IoT Hub Uplink Converter from the list.
   • Click Next.
4. Downlink data converter:
   • Leave empty and click Skip — the downlink converter can be added later if needed.
5. Connection settings:
   • Hostname — your Azure IoT Hub hostname (e.g. tbot.azure-devices.net).
   • Device ID — the device ID registered in Azure IoT Hub (e.g. T1).
   • Credentials — select Shared Access Signature and enter the device SAS key. See Credentials for X.509 certificate options.
   • Topic filter — MQTT topic to subscribe to (e.g. devices/T1/messages/devicebound/#). See Topic filter for details.
6. Click Add to save the integration.

Set Integration type to Azure IoT Hub, enter a name, and click Next Click Select existing, choose Azure IoT Hub Uplink Converter from the list, and click Next Skip the downlink converter for now — it can be added later Enter Hostname, Device ID, and SAS Key; set Topic filter to devices/T1/messages/devicebound/# and click Add

Two authentication types are supported:

Shared Access Signature:

• SAS Key — the device SAS key from Azure IoT Hub. See symmetric key authentication.
• CA certificate file — Azure IoT Hub uses the Baltimore CyberTrust Root certificate for TLS. Leave this field empty to use the built-in default; upload a custom bundle only if required by your environment.

PEM (X.509):

• CA certificate file — Baltimore CyberTrust Root certificate is used by default.
• Certificate file — your device certificate.
• Private key file — the private key for the certificate.
• Private key password — optional password for the private key.

For X.509 CA-signed authentication, see the Microsoft documentation and the CACertificates instructions.

Hostname

Your Azure IoT Hub hostname in the format {hub-name}.azure-devices.net. Find it in the Azure portal under IoT Hub ⇾ Overview.

Device ID

The device ID registered in Azure IoT Hub (e.g. T1). ThingsBoard authenticates to Azure IoT Hub as this device over MQTT on port 8883.

Credentials

Authentication type for the MQTT connection:

• Shared Access Signature — authenticate using a device SAS key (symmetric key)
• PEM — authenticate using X.509 certificates

Topic filter

The MQTT topic ThingsBoard subscribes to for incoming messages. The default format is devices/{deviceId}/messages/devicebound/#, which receives all cloud-to-device messages addressed to the registered device. The # wildcard matches any suffix, including lock tokens appended by Azure.

See IoT Hub MQTT support for details.

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that allow the integration to run as a separate process outside the ThingsBoard cluster — useful when the IoT Hub endpoint is only reachable from a restricted network.

Advanced settings

Use the Azure portal to send a message to device T1 and confirm that ThingsBoard receives and decodes it correctly.

1. In the Azure portal, open your IoT hub and navigate to IoT devices ⇾ T1.
2. Click Message to Device and enter the test payload in the Message Body field:

   {
     "devName": "T1",
     "msg": {
       "temp": 42,
       "humidity": 77
     }
   }

3. Click Send Message.

After sending, go to Entities ⇾ Devices in ThingsBoard. A device named T1 is automatically provisioned by the integration. Open it and check the Latest Telemetry tab — you should see temperature = 42 and humidity = 77.

• Integration Overview
• Uplink Converters
• Rule Engine
• ThingsBoard Expression Language (TBEL)