Azure IoT Hub

The Azure IoT Hub library provides an API to connect to an Azure IoT Hub instance and interact with it. It connects to Azure IoT Hub using MQTT over TLS.

Optionally, the library supports Azure IoT Hub Device Provisioning Service (DPS). DPS can be enabled at compile time to make use of the device provisioning services for onboarding of devices to Azure IoT Hub. When the device provisioning is complete, the library automatically connects to the assigned Azure IoT Hub.

The library also has integrated support for a proprietary FOTA solution. For more information on Azure FOTA, see the documentation on Azure FOTA library and Azure IoT Hub sample.

The library uses Azure SDK for Embedded C for message processing and other operations. For more information on how Azure SDK for Embedded C is integrated in this library, see Azure SDK for Embedded C IoT client libraries.

Important

If the server sends a device-bound message when the device is unavailable for a period of time, for instance while in LTE Power Saving Mode, the server will most likely terminate the TCP connection. This will result in additional data traffic as the device has to reconnect to the server, which in turn requires a new TLS handshake and MQTT connection establishment.

Setup and configuration

To connect a device to Azure IoT Hub, complete the following steps:

  1. Setting up Azure IoT Hub

  2. Authenticate Azure CLI

  3. Create an IoT Hub

  4. Device Provisioning Service (optional)

  5. Generating certificates

  6. Register a device in Azure IoT Hub

  7. Provision root CA certificates

Setting up Azure IoT Hub

If you do not have an Azure account, you need to create one.

To get started with testing the Azure IoT Hub, make sure that the following prerequisites are met:

  • Install the Azure CLI.

  • To use the nrfcredstore tool, the dependencies in the nrf/scripts/requirements-extra.txt file must be installed.

Authenticate Azure CLI

Authenticate the Azure CLI tool to use your Azure account in the default browser with the following command:

az login

For other authentication options, see the Sign in with Azure CLI documentation.

Create an IoT Hub

  1. When creating an IoT Hub, you must create it in a resource group. You can create a resource group through Azure’s CLI using the following command:

    az group create --name <resource_name> --location westus

    If you want to use another region than westus, you can acquire a list of the available locations by running the following command:

    az account list-locations -o table

  2. To create an IoT Hub, use the following command, select the resource group you created, and create a unique name for your IoT Hub:

    az iot hub create --resource-group <resource_name> --name <hub_name> --sku F1 --partition-count 2

    Using F1 as an argument creates a free IoT Hub, which allows you to have only one instance. Hence, delete your existing free IoT Hub or change the SKU to S1.

For information on how to set up creating an Azure IoT Hub instance using the Azure portal, see Creating an Azure IoT Hub instance using the Azure portal.

Device Provisioning Service (optional)

Azure IoT Hub DPS is a helper service for IoT Hub that enables just-in-time provisioning to the right IoT hub without pre-registering each device manually.

The alternative is to register each device manually with the IoT Hub and hard-code the IoT Hub hostname in the device firmware.

When using DPS, make sure to select the DPS tabs in the following sections of this document.

To use DPS, you need to set up an Azure IoT Hub Device Provisioning Service (DPS) instance with the following commands:

  • To create the DPS instance:

    az iot dps create --name <dps_name> --resource-group <resource_name>

  • To link the IoT Hub to the DPS instance:

    az iot dps linked-hub create --dps-name <dps_name> --hub-name <hub_name> --resource-group <resource_name>

Generating certificates

The connection to the Azure IoT Hub with MQTT is secured using TLS. To create the device certificate, you need a Certificate Authority (CA) certificate and a private key that is used to sign all of your client certificates. The CA certificate is uploaded to Azure IoT Hub, so Azure can verify that the device certificate is signed by your CA. If you do not have a CA certificate, you can purchase one or make a self-signed test CA certificate for testing purposes.

To help generate test CA certificates and handle the device keys and certificates, you can use the nrf/scripts/cert_tool.py Python script. Either call the script relative from the current working directory or add it to the path.

Note

The cert_tool.py Python script has default values for all actions for the input and output file names. See the available arguments by running the --help argument to the script.

Generate test CA certificates

  • To generate the root CA certificate, use the following command:

    cert_tool.py root_ca

    This command generates a self-signed root CA certificate and private key and saves them to the files ca/root-ca-cert.pem and ca/root-ca-key.pem.

  • To generate the subordinate CA certificate, use the following command:

    cert_tool.py sub_ca

    This command generates a subordinate CA certificate (signed by the root CA) and private key and saves them to the files ca/sub-ca-cert.pem and ca/sub-ca-key.pem.

Proof of possession

To prove possession of the root CA key, you need to sign a verification code using the root CA certificate and upload the resulting certificate to Azure.

With individual enrollment, you need to upload and verify the root CA certificate with the IoT hub. When using DPS, you need to upload and verify the root CA certificate with the DPS instance.

To perform proof of possession of the root CA key, you can verify the root CA certificate using the following set of commands:

  • To upload root CA certificate:

    az iot hub certificate create --hub-name <hub_name> --name <cert_name> --path ca/root-ca-cert.pem

  • To ask Azure for a verification code (need two output values):

    az iot hub certificate generate-verification-code --hub-name <hub_name> --name <cert_name> --etag "<etag_from_prev_command>"

Note down the verification code and etag for later use.

  • To generate a new private key:

    cert_tool.py client_key

  • To Create a CSR with the verification code as common name:

    cert_tool.py csr --common-name <verification_code>

  • To Sign the CSR with the root CA:

    cert_tool.py sign_root

  • To Upload the verification certificate:

    az iot hub certificate verify --hub-name <hub_name> --name <cert_name> --etag "<etag_from_generate_verification_code>" --path certs/client-cert.pem

Generate and provision device certificates

The following are the ways to generate and register device certificates:

  • The device key and certificate are generated using the cert_tool.py script and provisioned to the device.

  • The device generates a key and a Certificate Signing Request (CSR). This method is more secure because the private key never leaves the device.

When the private key is generated inside the modem, it is never exposed to the outside world. This is more secure than generating a private key using a script. By default, the Common Name (CN) of the certificate is set to the device UUID, and the CN is read out by Azure to identify the device during the TLS handshake. This allows using the exact same firmware on many devices without hard-coding the device ID into the firmware because the device UUID can be read out at runtime. See the Azure IoT Hub sample for more information on how to read out the device UUID in the application.

Note

Generating a key pair on device requires an nRF91 Series device. If you are using an nRF9160 DK, modem version v1.3.x or later is required.

Important

Program the Cellular: AT Client sample to your device before following this guide.

Complete the following steps to generate a key pair and CSR on the modem, which is then signed using your CA and uploaded to Azure:

  1. Obtain a list of installed keys using the following command:

    nrfcredstore <serial port> list

    where <serial port> is the serial port of your device.

  2. Select a security tag that is not yet in use. This security tag must match the value set in the CONFIG_MQTT_HELPER_SEC_TAG Kconfig option.

  3. Generate a key pair and obtain a CSR using the following command:

    nrfcredstore <serial port> generate <sec tag> certs/client-csr.der

    where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.

  4. Convert the CSR from DER format to PEM format using the following command:

    openssl req -inform DER -in certs/client-csr.der -outform PEM -out certs/client-csr.pem

  5. Sign the CSR using the subordinate CA certificate using the following command:

    cert_tool.py sign

    Note

    This process might vary depending on the CA you are using. See the documentation for your CA for more information on how to sign a CSR.

  6. Take note of the CN, as it will be required later.

    In case you got the certificate from a CA, you can extract the CN using the following command:

    openssl x509 -in certs/client-cert.pem -noout -subject

  7. Combine the device certificate and the subordinate CA certificate chain into a single file using the following command:

    cat certs/client-cert.pem ca/sub-ca-cert.pem > certs/client-cert-chain.pem

    This is necessary for Azure to verify the certificate chain.

  8. Provision the certificate to the modem using the following command:

    nrfcredstore <serial port> write <sec tag> CLIENT_CERT certs/client-cert-chain.pem

    where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.

Register a device in Azure IoT Hub

Important

The device ID must match the CN of the certificate.

To register a new device in your IoT hub, use the following command:

az iot hub device-identity create -n <iothub_name> -d <device_id> --am x509_ca

Provision root CA certificates

The Azure IoT Hub library requires provisioning of the following certificates and a private key for a successful TLS connection:

  1. DigiCert Global Root G2 - The root CA certificate used to verify the server’s certificate chain while connecting.

  2. Baltimore CyberTrust Root Certificate - Azure’s legacy root CA certificate needed to verify the Azure server’s that have not migrated to DigiCert Global Root G2 yet.

  3. Device certificate - Generated by the procedures described in Generate and provision device certificates, used by Azure IoT Hub to authenticate the device.

  4. Private key of the device.

Important

Azure has started the process of migrating their DPS server certificates from Baltimore CyberTrust Root Certificate to DigiCert Global Root G2. Azure IoT Hub servers have finished this transition, and only DigiCert Global Root G2 is used now for those connections. Azure advises to have both Baltimore CyberTrust Root and DigiCert Global Root G2 certificates for all devices to avoid disruption of service during the transition. Refer to Azure IoT TLS: Critical changes for updated information and timeline. Due to this, it is recommended to provision the Baltimore CyberTrust Root Certificate to a secondary security tag set by the CONFIG_MQTT_HELPER_SECONDARY_SEC_TAG option. This ensures that the device can also connect after the transition.

To provision the certificates, use any of the following methods, depending on the DK you are using.

Important

Program the Cellular: AT Client sample to your device before following this guide and make sure you have nrfcredstore installed.

  1. Obtain a list of installed keys using the following command:

    nrfcredstore <serial port> list

    where <serial port> is the serial port of your device.

  2. Provision the server root CA certificates, which you downloaded previously, by running the following commands:

    nrfcredstore <serial port> write <sec tag> ROOT_CA_CERT DigiCertGlobalRootG2.crt.pem

    nrfcredstore <serial port> write <secondary sec tag> ROOT_CA_CERT BaltimoreCyberTrustRoot.crt.pem

The chosen security tag while provisioning the certificates must be the same as the security tag configured by the CONFIG_MQTT_HELPER_SEC_TAG option.

If more than one root server certificate is used, the second one can be provisioned to a different security tag and configured in the application using the CONFIG_MQTT_HELPER_SECONDARY_SEC_TAG Kconfig option. The modem checks both security tags if necessary when verifying the server’s certificate.

Configuring the library

You can configure the library to connect to Azure IoT Hub with or without using DPS. For both methods, you need to set the device ID, or registration ID, and the security tag used to store the certificates.

The following Kconfig options are common for both methods:

  1. Set the CONFIG_AZURE_IOT_HUB Kconfig option to y to enable the Azure IoT Hub library.

  2. Set the CONFIG_MQTT_HELPER_SEC_TAG Kconfig option to the security tag used while provisioning root CA certificates.

  3. Set the CONFIG_MQTT_HELPER_SECONDARY_SEC_TAG Kconfig option to the security tag of the extra root CA certificate until all Azure services have migrated to DigiCert Global Root G2.

To connect to Azure IoT Hub without using DPS, complete the following minimum required configuration:

  1. To retrieve your IoT Hub hostname, run the following command:

    az iot hub show --name <hub_name> --query "properties.hostName"

  2. Configure the CONFIG_AZURE_IOT_HUB_HOSTNAME Kconfig option to the returned address.

    You can also set the host name at runtime.

Device ID and Registration ID

The device ID is used to identify the device in the Azure IoT Hub. Registration ID is used to identify the device on the DPS server. The Azure IoT Hub sample uses the device ID as the registration ID when registering with the DPS server.

For testing on one device, you can manually configure the device ID with the CONFIG_AZURE_IOT_HUB_DEVICE_ID Kconfig option.

When running the same firmware on multiple devices, it is not practical to hard-code the registration ID. Instead, enable the use of a unique hardware identifier, such as the device UUID, as the registration ID. The hardware identifier of the device needs to match the CN in the certificate on the device.

Note

When using hardware identifiers in the Azure IoT Hub sample, set the CONFIG_AZURE_IOT_HUB_SAMPLE_DEVICE_ID_USE_HW_ID Kconfig option to y.

CONFIG_MODEM_JWT=y
CONFIG_HW_ID_LIBRARY_SOURCE_UUID=y

You can also set the device ID at runtime by populating the device_id member of the azure_iot_hub_config structure passed to the azure_iot_hub_connect() function when connecting. If the device_id.size buffer size is zero, the compile-time option CONFIG_AZURE_IOT_HUB_DEVICE_ID is used.

Application integration

This section describes how to initialize the library, use the DPS service, and connect to Azure IoT Hub.

Initializing the library

To initialize the library, call the azure_iot_hub_init() function. The initialization must be successful to make the other APIs in the library available for the application. An event handler is passed as the only argument to the azure_iot_hub_init() function. The library calls this function with data associated to the application, such as incoming data and other events. For an exhaustive list of event types and associated data, see azure_iot_hub_evt_type.

Using the Device Provisioning Service

You can use the Azure IoT Hub Device Provisioning Service to provision the device to an IoT Hub. When the registration process has completed successfully, the device receives its assigned hostname and device ID to use when connecting to Azure IoT Hub. The assigned host name and device ID are stored to the non-volatile memory on the device and are available also after a reset and power outage.

This code example shows how to configure and use DPS:

static void dps_handler(enum azure_iot_hub_dps_reg_status state)
{
   switch (state) {
   case AZURE_IOT_HUB_DPS_REG_STATUS_NOT_STARTED:
      LOG_INF("AZURE_IOT_HUB_DPS_REG_STATUS_NOT_STARTED");
      break;
   case AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNING:
      LOG_INF("AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNING");
      break;
   case AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNED:
      LOG_INF("AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNED");

      /* Act on assignment */
      k_sem_give(&dps_assigned_sem);
      break;
   case AZURE_IOT_HUB_DPS_REG_STATUS_FAILED:
      LOG_INF("ZURE_IOT_HUB_DPS_REG_STATUS_FAILED");

      /* Act on registration failure */
      k_sem_give(&dps_registration_failed_sem);
      break;
   default:
      LOG_WRN("Unhandled DPS registration status: %d", state);
      break;
   }
}

...

int err;
struct azure_iot_hub_buf assigned_hostname;
struct azure_iot_hub_buf assigned_device_id;
     struct azure_iot_hub_dps_config dps_cfg = {
             .handler = dps_handler,

   /* Can be left out to use CONFIG_AZURE_IOT_HUB_DPS_REG_ID instead. */
             .reg_id = {
                     .ptr = device_id_buf,
                     .size = device_id_len,
             },

   /* Can be left out to use CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE instead. */
   .id_scope = {
                     .ptr = id_scope_buf,
                     .size = id_scope_len,
             },
     };

     err = azure_iot_hub_dps_init(&dps_cfg);
/* Error handling */

err = azure_iot_hub_dps_start();
     if (err == 0) {
             LOG_INF("The DPS process has started");

   /* Wait for the registration process to complete. */
   err = k_sem_take(&dps_done_sem, K_SECONDS(SOME_TIMEOUT));
   /* Error handling */
     } else if (err == -EALREADY) {
             LOG_INF("Already assigned to an IoT hub, skipping DPS");
     } else {
   /* Error handling */
     }
     err = azure_iot_hub_dps_hostname_get(assigned_hostname);
/* Error handling */

     err = azure_iot_hub_dps_device_id_get(assigned_device_id);
/* Error handling */

/* Use the hostname and device ID to connect to IoT Hub. */

After the device has been successfully registered, the application can proceed to connect to the assigned IoT Hub using the obtained device ID.

When a device has been assigned to an IoT Hub and the information is stored to the non-volatile memory, the DPS APIs always return the stored information and do not trigger a new registration. To delete the stored assignment information, call the azure_iot_hub_dps_reset() function. Alternatively, you can call the functions azure_iot_hub_dps_hostname_delete() or azure_iot_hub_dps_device_id_delete() to delete specific information. After calling the azure_iot_hub_dps_reset() function, the library must be initialized again. After the initialization, a new registration with the DPS can be started by calling the azure_iot_hub_dps_start() function.

The DPS APIs are documented in the Azure IoT Hub DPS API section.

Connecting to Azure IoT Hub

After the initialization, calling the azure_iot_hub_connect() function connects the device to the configured IoT hub or DPS instance, depending on the configuration. The initial TLS handshake takes a few seconds to complete, depending on the network conditions and the TLS cipher suite used. During the TLS handshake, the azure_iot_hub_connect() function blocks. Consider this when deciding the context from which the API is called. Optionally, DPS registration can be run automatically as part of the call to the azure_iot_hub_connect() function.

Note

The azure_iot_hub_connect() function blocks when DPS registration is pending. Running DPS as part of the azure_iot_hub_connect() function also limits the DPS configuration options as follows:

Use the DPS APIs directly if you need more control over the DPS registration process.

When using the azure_iot_hub_connect() function, you can choose to provide the host name to the IoT Hub and device ID at runtime, or let the library use Kconfig options.

Here is an example for setting the host name and device ID at runtime:

struct azure_iot_hub_config cfg = {
   .hostname = {
      .ptr = hostname_buffer,
      .size = hostname_length,
   },
   .device_id = {
      .ptr = device_id_buffer,
      .size = device_id_length,
   },
   .use_dps = false,
};

err = azure_iot_hub_connect(&cfg);
/* Error handling */

You can pass NULL or a zeroed-out configuration to the azure_iot_hub_connect() function. The library uses the values for host name and device ID from the Kconfig options CONFIG_AZURE_IOT_HUB_HOSTNAME and CONFIG_AZURE_IOT_HUB_DEVICE_ID, respectively.

This code example uses a Kconfig value for the device ID (and by extension DPS registration ID) and runs DPS to acquire the assigned IoT Hub host name and assigned device ID.

struct azure_iot_hub_config cfg = {
   .use_dps = true,
};

err = azure_iot_hub_connect(&cfg);
/* Error handling */

After a successful connection, the library automatically subscribes to the following standard Azure IoT Hub MQTT topics (See Azure IoT Hub MQTT protocol support for details):

  • devices/<device ID>/messages/devicebound/# (cloud-to-device messages)

  • $iothub/twin/PATCH/properties/desired/# (desired properties update notifications)

  • $iothub/twin/res/# (operation responses)

  • $iothub/methods/POST/# (direct method requests)

Currently, the library does not support persistent MQTT sessions. Hence subscriptions are requested for each connection to the IoT hub.

For more information about the available APIs, see the Azure IoT Hub API section.

Configuration

To use the Azure IoT Hub library, you must enable the CONFIG_AZURE_IOT_HUB Kconfig option.

You can configure the following options when using this library:

MQTT helper library specific options:

DPS-specific configuration:

API documentation

Azure IoT Hub API

Header file: include/net/azure_iot_hub.h
Source files: subsys/net/lib/azure_iot_hub/src/azure_iot_hub.c
Azure IoT Hub library

Azure IoT Hub DPS API

Header file: include/net/azure_iot_hub_dps.h
Source files: subsys/net/lib/azure_iot_hub/src/azure_iot_hub_dps.c
Azure IoT Hub DPS library