Azure Event Hub Integration

Azure Event Hub Integration connects ThingsBoard to the built-in Event Hub-compatible endpoint of Azure IoT Hub. ThingsBoard subscribes as a consumer group, reads device-to-cloud messages, and converts them into devices and telemetry via an uplink converter. For downlink, ThingsBoard sends cloud-to-device messages back to Azure IoT Hub devices using the Azure IoT Hub API.

1. Sign in to the Azure portal and click Create a resource.
2. Search for IoT Hub, select it from the list, and click Create.
3. On the Basics tab, click Create new to create a new resource group. Enter a resource group name and an IoT hub name.
4. Click Review + create, review the configuration, then click Create.
5. Wait for the deployment to complete, then click Go to resource.

Click "Create a resource" on the Azure portal home page Type "IoT Hub" in the search box and select IoT Hub from the results Click Create on the IoT Hub marketplace page Set the resource group and IoT hub name, then click Review + create Review the configuration and click Create Wait for the deployment to complete Click "Go to resource" when the deployment finishes

1. In your IoT Hub resource, open IoT devices from the left menu.
2. Click + New.
3. Enter a Device ID (e.g. TB-D-01), leave Auto-generate keys checked, and click Save.

Open IoT devices from the left menu Click + New to register a device Enter the Device ID (e.g. TB-D-01), leave Auto-generate keys checked, and click Save Device TB-D-01 appears in the list with Enabled status

The uplink converter transforms incoming Azure Event Hub messages into the ThingsBoard format. Azure Event Hub uses a generic uplink converter.

Sample payload sent from the device:

{
  "devName": "TB-D-01",
  "msg": {
    "temp": 42,
    "humidity": 77
  }
}

The decoder reads devName to set the device name and extracts temp and humidity from the nested msg object as telemetry.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Set Converter type to Uplink and enter a name.
4. Paste the decoder function below and click Add.

The decoder function used in this tutorial:

var data = decodeToJson(payload);
var deviceName = data.devName;
var deviceType = 'azure-event-hub-device';

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

return result;

var data = decodeToJson(payload);
var deviceName = data.devName;
var deviceType = 'azure-event-hub-device';

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: {
        temp: 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 field — replace data.devName with whichever field carries the device identifier in your payload.
• Different telemetry fields — replace temp and humidity with your actual sensor fields; add or remove entries as needed.
• Flat payload — if your payload is not nested (no msg object), access fields directly: data.temperature, data.battery, etc.
• Additional attributes — add an attributes: {} block next to telemetry to store non-time-series data such as firmware version or hardware revision.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to Azure Event Hub and enter a name.
   • Click Next.
3. Uplink data converter:
   • Select existing — choose the previously created Azure Event Hub Uplink Converter from the list.
   • Click Next.
4. Downlink data converter:
   • Click Skip — the downlink converter can be added later.
5. Connection settings — fill in the following fields (see subsections below for where to find each value):
   • Connection string — the Event Hub-compatible endpoint from your IoT Hub.
   • Storage connection string — the connection string from your Azure Storage account. Used for checkpointing.
   • Container name — the name of the Azure Blob Storage container used to store checkpoints.
   • Optionally enable Persistent checkpoints to resume from the last processed event after a restart.
6. Click Check connection to verify, then click Add.

Set Integration type to Azure Event Hub, enter a name, and click Next Select an existing uplink converter or click Create new — the default decoder is pre-filled; click Next Skip the downlink converter for now — it can be added later Enter the Connection String, Storage connection string, and Container name; click Check connection, then Add

1. In your IoT Hub resource, go to Built-in endpoints.
2. Under Event Hub-compatible endpoint, copy the full connection string and paste it into the Connection String field in ThingsBoard.

Open Built-in endpoints in your IoT Hub (Settings section of the left menu) Copy the full Event Hub-compatible endpoint connection string

ThingsBoard uses Azure Blob Storage to store consumer checkpoints — offsets that record which Event Hub messages have already been processed. This prevents duplicate processing when the integration restarts.

Container name

1. In the Azure portal, navigate to Storage accounts and open your storage account.
2. Go to Data storage ⇾ Containers and note the container name you want to use for checkpoints.

Navigate to Storage accounts from the Azure portal home page and open your storage account Open Containers under Data storage and note the container name (e.g. eventhubcontainer)

Connection string

Go to Security + networking ⇾ Access keys and copy the Connection string for key1.

Use the Rule Engine to send a test message to Azure IoT Hub. Azure routes it to the built-in Event Hub endpoint, and ThingsBoard reads it back through the integration.

1. Open Rule Chains and open the Root Rule Chain in edit mode.
2. Add a Generator node. Configure it with a name, set the Originator to Single entity ⇾ Integration ⇾ Azure Event Hub integration, and paste the generate function below.

var msg = {
    devName: "TB-D-01",
    msg: {
        temp: 42,
        humidity: 77
    }
};
var metadata = { data: 40 };
var msgType = "POST_TELEMETRY_REQUEST";

return { msg: msg, metadata: metadata, msgType: msgType };

3. Add an Azure IoT Hub action node with the following settings:

   • Topic — devices/TB-D-01/messages/events/
   • Hostname — your IoT Hub hostname (e.g. thingsboard-integration.azure-devices.net)
   • Device ID — TB-D-01
   • Credentials — Shared Access Signature; SAS Key — the Primary key
4. Connect the Generator node to the Azure IoT Hub node using the Success relation.
5. Click Apply changes to save the rule chain.

Add an Azure IoT Hub node: enter a name, set Topic to devices/TB-D-01/messages/events/, set Hostname and Device ID, and paste the Primary key as SAS Key; click Add Connect the Generator node to the Azure IoT Hub node: drag from its right circle to the left circle of the Azure IoT Hub node, set the relation to Success, and click Apply changes

1. In your IoT Hub resource, open IoT devices and click on device TB-D-01.
2. Copy the Primary key value — use it as the SAS Key in the next step.

Open IoT devices in your IoT Hub — click on device TB-D-01 to open its details Copy the Primary key — use it as the SAS Key in the Azure IoT Hub rule node

Go to Integrations center ⇾ Integrations, open the Azure Event Hub integration, and check the Events tab — Uplink events with status OK confirm that data is flowing from Azure to ThingsBoard.

Go to Entities ⇾ Devices — a device named TB-D-01 is automatically created by the integration. Open it and check the Latest telemetry tab — you should see temp = 42 and humidity = 77.

To send commands from ThingsBoard to Azure IoT Hub devices, three things must be in place: a downlink converter attached to the integration with the Event Hub-compatible name configured, and a Rule Chain node that forwards attribute changes to the integration.

The downlink converter encodes ThingsBoard messages into the format required by the Azure IoT Hub cloud-to-device messaging API. For the full encoder reference, see Downlink data converter.

Expected output structure:

{
  "contentType": "JSON",
  "data": "{\"down-att\": \"scm:55\"}",
  "metadata": {
    "deviceId": "TB-D-01"
  }
}

The result object must follow this format:

• contentType — how data is encoded: TEXT, JSON, or BINARY
• data — the serialized payload sent to the device
• metadata.deviceId — the Azure IoT Hub Device ID of the target device

The encoder function used in this tutorial:

var result = {
    contentType: "JSON",
    data: JSON.stringify(msg),
    metadata: {
        deviceId: metadata.deviceName
    }
};
return result;

var result = {
    contentType: "JSON",
    data: JSON.stringify(msg),
    metadata: {
        deviceId: metadata.deviceName
    }
};
return result;

The encoder serializes the full ThingsBoard message (msg) as JSON. metadata.deviceName is automatically populated from the device context when the downlink is triggered from the device’s rule chain, and maps to the Azure IoT Hub Device ID.

To adapt this converter to your device:

• Specific fields only — replace JSON.stringify(msg) with a selective object to send only the relevant command fields.
• Fixed device target — replace metadata.deviceName with a hardcoded Device ID if the downlink always targets the same device.
• Binary payload — set contentType to BINARY and encode data accordingly.

1. Go to Integrations center ⇾ Integrations and open the Azure Event Hub integration.
2. Click Toggle edit mode.
3. In the Downlink data converter field, type a name and click Create new converter.
4. Paste the encoder function from the section above in the editor and click Add.
5. Scroll down to Advanced settings and enter the Event Hub-compatible name in the IoT Hub Name field.
6. Click Apply changes to update the integration.

Open the Azure Event Hub integration — the Downlink data converter field is empty; click the pencil icon to enter editing mode Type a name for the downlink converter and click Create new converter Paste the encoder function in the TBEL editor and click Add In Advanced settings, enter the Event Hub-compatible name in the IoT Hub name field and click Apply changes

1. Open the Azure portal. In your IoT Hub resource, go to Built-in endpoints.
2. Copy the Event Hub-compatible name — you will need it in the integration’s Advanced settings.

1. Open Rule Chains ⇾ Root Rule Chain and click the edit icon.
2. Drag the Integration Downlink action node onto the canvas. Enter a name, select the Azure Event Hub integration, and click Add.
3. Connect the Message Type Switch node to the Integration Downlink node using the Post attributes and Attributes Updated relations. These relations fire whenever a shared attribute is created or changed, triggering the downlink.
4. Click Apply changes to save the rule chain.

Open the Root Rule Chain in edit mode — find Integration Downlink in the node panel and drag it onto the canvas Enter a name, select the Azure Event Hub integration, and click Add Connect the Integration Downlink node via Post attributes and Attributes Updated relations, then click Apply changes

1. Go to Entities ⇾ Devices, open device TB-D-01, and click the Attributes tab.
2. Switch to Shared attributes and click + to add a new attribute.
3. Enter the key (e.g. powerState) and value (e.g. on), then click Add.

Adding the attribute fires the Attributes Updated relation in the rule chain, which routes the message to the Integration Downlink node and sends a cloud-to-device message to Azure IoT Hub device TB-D-01.

Go to Integrations center ⇾ Integrations, open the Azure Event Hub integration, and check the Events tab for Downlink events with status OK. The message payload contains deviceId and the attribute key-value pair sent to the device.

To confirm delivery on the Azure side, open your IoT Hub in the Azure portal, navigate to IoT devices, select device TB-D-01, and verify that the Cloud to Device Message Count has increased to 1.

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