The Azure IoT Hub Connector connects SIA Connect to Microsoft Azure IoT Hub. It can send telemetry and reported properties, receive cloud-to-device messages, and synchronize device-twin properties.

This guide explains how to configure a direct connection or use Device Provisioning Service (DPS), create and use Azure IoT items, and resolve common connection, provisioning, and message-delivery errors.

Before you begin

Make sure that:

• The Azure IoT Hub Connector is installed and enabled.
• SIA Connect has internet access and can resolve the Azure hostnames used by your IoT Hub or DPS.
• An Azure IoT Hub device identity or DPS enrollment has been created.
• You have the connection string, symmetric key, or X.509 certificate and private key required by the selected authentication method.
• The selected IoT Hub tier supports the features you intend to use. Device twins are not available with the Basic tier.

Choose a connection method

Upload X.509 files

Complete this section only when using X.509 authentication.

1. In the Edge Portal, open Configuration > Connectors.
2. Open the installed Azure IoT Hub Connector.
3. Upload the device certificate and matching private key under the Connector files.
4. Protect the private key and make sure the certificate is valid for the Azure device enrollment.

The uploaded filenames become available in the Certificate and Key lists when you configure the instance.

Create an Azure IoT Hub instance

1. In the Edge Portal, open Workspace > Instances.
2. Select Add instance.
3. Select the Azure IoT Hub Connector.
4. Enter a descriptive instance name.
5. Complete the address and Connector-specific parameters for your connection method.
6. Save the instance.

The Connector creates the connection when the enabled instance starts. If DPS is selected, the Connector registers the device before connecting to the assigned IoT Hub.

Configure the instance parameters

Configure a direct connection

Use a symmetric key

1. Set Provisioning to None.
2. Set Authentication type to Symmetric key (SAS).
3. Enter the device connection string in Address.
4. Select the required protocol.
5. Save the instance.

The connection string normally has this structure:

HostName=<hub-name>.azure-devices.net;DeviceId=<device-id>;SharedAccessKey=<device-key>

Use a device connection string, not an IoT Hub service connection string.

Use an X.509 certificate

1. Set Provisioning to None.
2. Set Authentication type to x509 Certificate.
3. Enter the X.509 device connection string in Address.
4. Select the uploaded Certificate and Key.
5. Save the instance.

The connection string normally has this structure:

HostName=<hub-name>.azure-devices.net;DeviceId=<device-id>;x509=true

Configure DPS provisioning

1. Select IoT Central, Individual, or Group under Provisioning.
2. Enter the Registration URI. Keep global.azure-devices-provisioning.net unless your Azure configuration specifies another endpoint.
3. Enter the ID Scope.
4. Enter the enrollment registration ID under Device ID.
5. Select the authentication type:
   • For SAS authentication, enter the device key in Address. For a Group enrollment, enter the group key. The Connector derives the device key from the group key and Device ID.
   • For X.509 authentication, select the uploaded certificate and private key.
6. Select a protocol and save the instance.

A successful registration assigns the device to an IoT Hub. If registration fails, the Connector waits before retrying to avoid repeated connection attempts.

Use the automatically created message items

For a normal Azure IoT connection, the Connector creates two enabled items automatically:

These items are not created when the instance is configured to set up the Shadow API with provisioned data.

Send telemetry

1. Create a mapping whose destination is the Device-to-cloud item.
2. Send the required payload through the mapping.
3. If Azure message properties are required, edit the item and enter them in Properties as a JSON object.
4. Choose whether the Connector should wait for Azure to confirm delivery.

Example application properties:

{"facility":"bottle_plant","floor":"1"}

Every property value is sent as text in the Azure message properties.

Use device-twin properties

When Device twin is set to Yes, the Connector retrieves the complete device twin and listens for later property updates. IoT Central provisioning enables this behavior automatically.

For each applicable desired or reported property, the Connector creates a read-and-write item named <property name> property. The item receives desired values from Azure. Writing to the item sends a reported-property update back to Azure.

If a property value is not already valid JSON, the Connector formats it according to the type received from Azure. It preserves numeric, Boolean, null, and string values. A null desired property causes the corresponding item to be removed after the Connector reports null back to Azure.

Send a reported property manually

You can also configure an item with Message type set to Property. Enter the Azure property name in the item's Properties field, then map a value to the item.

You may send a complete JSON object directly. If the value is not valid JSON, the Connector wraps it using the configured property name and the type previously received from Azure. The Connector waits up to approximately 20 seconds for the reported-state callback.

Set up the Shadow API from DPS

Use this option when the Shadow API is installed and you want the Azure provisioning result to configure its MQTT connection.

1. Configure a DPS connection.
2. Set Shadow API to Setup Shadow API with Provisioned data.
3. Select the certificate and private key when required by the enrollment.
4. Save the instance.

After successful provisioning, the Connector configures the Shadow API with the assigned IoT Hub hostname, device ID, TLS 1.2, port 8883, the device-bound subscription topic, and the device-to-cloud event topic. It then requests a Shadow API service restart.

Verify the configuration

1. Confirm that the instance is enabled and does not show a current error.
2. Map a known test value to the Device-to-cloud item.
3. Confirm that the telemetry arrives for the correct device in Azure.
4. Send a cloud-to-device test message and confirm that it appears on the Cloud-to-device item.
5. If device twins are enabled, change a desired property in Azure and confirm that the corresponding property item is created or updated.

Troubleshoot the Connector

Failure creating IotHub device. Hint: Check your connection string.

The direct connection string could not be used to create the Azure client. Confirm that it is a device connection string, contains the correct IoT Hub hostname and device ID, and uses either SharedAccessKey or x509=true as required.

Registration failed

DPS did not complete the registration. Confirm the Registration URI, ID Scope, Device ID, enrollment type, and credentials. For a Group enrollment, enter the group key and make sure the Device ID is permitted by the enrollment. For X.509, confirm that the selected certificate is registered or chained to the configured enrollment and matches the selected private key.

SaS token expired

The SAS token is no longer valid. Check that the device key is current and that the SIA Connect system time is correct. If DPS is used, verify the enrollment key and registration details.

Device disabled in IoT Hub or invalid connection string

Enable the device identity in Azure and verify the connection string. Confirm that the string belongs to the device, not to a service policy.

Bad credential

The supplied key, certificate, or private key was rejected. Re-enter the symmetric key or select the correct certificate and matching private key. Confirm that the authentication method matches the Azure device or DPS enrollment.

No network connection or Communication error

Confirm that SIA Connect has internet access, DNS resolution works, and outbound traffic for the selected MQTT or AMQP transport is permitted. If the normal transport is blocked, try the corresponding WebSocket option when permitted by your network policy.

Retry expired

The Azure SDK stopped its current retry sequence. Correct the network or credential problem, then disable and enable the instance to start a new connection attempt if required.

Connection failed

The Connector includes the Azure SDK connection reason after this message. Use that reason together with the Connector and system logs to identify whether the failure concerns authentication, network access, or service availability.

Message timeout. Check connection string.

Azure did not confirm a telemetry message before the delivery callback timed out. Verify the connection string, network connection, and device status. Consider using No callback only if the application does not require per-message delivery confirmation.

Confirmation error or Tunnel destroyed

The SDK could not confirm delivery or the connection was destroyed while the message was pending. Check the instance connection state and network stability, then retry the test message.

Telemetry arrives without application properties

Make sure the item's Properties value is a valid JSON object. Invalid JSON is ignored. Use simple key-value pairs and confirm that the property field is configured on the item that sends the telemetry.

Device-twin items are not created

Set Device twin to Yes, confirm that the IoT Hub tier supports device twins, and check that the instance is connected. The Connector creates property items only after it receives applicable desired or reported properties.

Unable to setup ShadowAPI, make sure ShadowAPI is installed

Install and configure the Shadow API before enabling the provisioning option. Confirm that the current SIA Connect software exposes the Shadow API settings, then repeat the DPS provisioning attempt.

Related articles

• Install and manage Connectors
• Manage and configure Connector files and certificates
• Set up the Shadow API
• Change network settings in the Edge Portal
• Use the Ping tool