.. _lib_azure_iot_hub: Azure IoT Hub ############# .. contents:: :local: :depth: 2 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 Azure FOTA. For more information on Azure FOTA, see the documentation on :ref:`lib_azure_fota` library and :ref:`azure_fota_sample` sample. .. 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. .. _prereq_connect_to_azure_iot_hub: Prerequisites for connecting to Azure IoT Hub ********************************************* In order to connect to Azure IoT Hub, an Azure account and an Azure IoT Hub instance must first be created and configured. See `Creating an Azure IoT Hub instance using the Azure portal`_ for more information. .. note:: If you do not use DPS to provision devices to your IoT Hub, make sure that you select ``X.509 CA Signed`` as the *Authentication type* while `Registering the device with Azure IoT Hub`_. The connection to Azure IoT Hub with MQTT is secured using TLS. For testing purposes, see `Creating Azure IoT Hub certificates`_ for the steps to create certificates and a private key for the leaf device, and to register the generated test root certificate to be used with an IoT hub. The Azure IoT Hub library requires the provisioning of the following certificates and a private key for a successful TLS connection: 1. `Baltimore CyberTrust Root certificate`_ - Server certificate, used to verify the server's certificate while connecting. #. Public device certificate - generated by the procedures described in `Creating Azure IoT Hub certificates`_ , used by Azure IoT Hub to authenticate the device. #. Private key of the device. .. note:: The location and name of the generated public device certificate and private key files vary depending on the method you use for the credential generation. For PowerShell scripts, the device certificate is called :file:`mydevice-public.pem` and the private key is :file:`mydevice-private.pem`. These files are located in the working directory with the other generated files. For bash scripts, the public device certificate is called :file:`new-device.cert.pem` and is located in a directory called :file:`certs` within the :file:`script` directory. The private key is called :file:`new-device.key.pem` and located in a directory called :file:`private` within the :file:`script` directory. The file and directory names may change if Azure changes their scripts. .. _azure_iot_hub_flash_certs: Provisioning of the certificates ================================ To provision the certificates and the private key to the nRF9160 modem, complete the following steps: 1. `Download nRF Connect for Desktop`_. #. Update the modem firmware on the onboard modem of the nRF9160-based device to the latest version by following the steps in :ref:`nrf9160_gs_updating_fw_modem`. #. Build and program the :ref:`at_client_sample` sample to the nRF9160-based device as explained in :ref:`gs_programming`. #. Launch the `LTE Link Monitor`_ application, which is part of `nRF Connect for Desktop`_. #. Click :guilabel:`Certificate manager` located at the top right corner. #. Copy the Baltimore CyberTrust Root certificate into the ``CA certificate`` entry. #. Copy and paste the device certificate and the key created using the scripts located in `Creating Azure IoT Hub certificates`_, into the respective entries (``Client certificate``, ``Private key``). #. Select a desired security tag (any positive integer, for example, ``42``) and click :guilabel:`Update certificates`. .. note:: The chosen security tag while provisioning the certificates must be same as the security tag configured by the :kconfig:option:`CONFIG_AZURE_IOT_HUB_SEC_TAG` option. Configuring the library ======================= You can configure the library to connect to Azure IoT Hub with or without using DPS. Configuration without using DPS +++++++++++++++++++++++++++++++ To connect to Azure IoT Hub without using DPS, complete the following minimum required configuration: 1. In the `Azure Portal`_, navigate to :guilabel:`IoT Hub` and select the desired IoT hub. #. In the overview page, locate and copy the ``Hostname`` and configure :kconfig:option:`CONFIG_AZURE_IOT_HUB_HOSTNAME` to this address. #. Set the option :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID` to the device ID. The device ID must match the device ID used while creating the certificates. #. Make sure that the device is already registered with your Azure IoT Hub, or follow the instructions in `Registering the device with Azure IoT Hub`_. #. Set :kconfig:option:`CONFIG_AZURE_IOT_HUB_SEC_TAG` to the security tag used in :ref:`azure_iot_hub_flash_certs`. .. _dps_config: Configuration using DPS +++++++++++++++++++++++ To connect to Azure IoT Hub using DPS, complete the following steps: 1. `Set up an Azure IoT Hub Device Provisioning Service (DPS) instance`_ and obtain the ID scope. #. `Add certificates to the DPS instance`_. #. Create an *enrollment group* as described in `Device enrollments with Azure Portal`_ and link it to your IoT hub. Select the certificate added in the previous step as the *Primary certificate​​​​​​​*. #. Enable :kconfig:option:`CONFIG_AZURE_IOT_HUB_DPS`. #. In the `Azure Portal`_, click :guilabel:`Device Provisioning Services` and select the DPS instance to use. #. In the overview page, locate and copy the ``ID Scope`` and configure :kconfig:option:`CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE` to this string. #. Set the :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID` option to device ID, unless :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP` is enabled. The device ID must match the device ID used while creating the certificates. #. Set :kconfig:option:`CONFIG_AZURE_IOT_HUB_SEC_TAG` to the security tag used while :ref:`azure_iot_hub_flash_certs`. Initializing the library ************************ The library is initialized by calling the :c:func:`azure_iot_hub_init` function. If the initialization fails, the application cannot use any APIs of the library. Optionally, you can enable :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP` and include a pointer to the :c:struct:`azure_iot_hub_config` structure containing the device ID in the :c:func:`azure_iot_hub_init` function call. Below is an example for setting the device ID at run time instead of compile time by configuring the :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID` option: .. code-block:: c struct azure_iot_hub_config cfg = { .device_id = "my-device", .device_id_len = sizeof("my-device") - 1, }; int err = azure_iot_hub_init(&cfg, event_handler); if (err) { printk("azure_iot_hub_init failed: %d\n", err); return err; } Connecting to Azure IoT Hub *************************** After the initialization, a :c:func:`azure_iot_hub_connect` function call connects the device to the configured IoT hub or DPS instance, depending on the configuration. The initial TLS handshake takes some time to complete, typically in the range of few seconds, depending on the network conditions and the TLS cipher suite used. During the TLS handshake, :c:func:`azure_iot_hub_connect` blocks, so care must be taken when deciding the context from which the API is called. 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//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. Configuration ************* Configure the following parameters when using this library: * :kconfig:option:`CONFIG_AZURE_IOT_HUB_HOSTNAME` - Sets the Azure IoT Hub host name. It must be configured, since DPS is not enabled by default. * :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID` - Specifies the device ID, which is used when connecting to Azure IoT Hub or when DPS is enabled. * :kconfig:option:`CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP` - Used to provide the device ID at run time. * :kconfig:option:`CONFIG_AZURE_IOT_HUB_DPS` - Enables Azure IoT Hub DPS. * :kconfig:option:`CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE` - Sets the Azure IoT Hub DPS ID scope that is used while provisioning the device. * :kconfig:option:`CONFIG_AZURE_IOT_HUB_NATIVE_TLS` - Configures the socket to be native for TLS instead of offloading TLS operations to the modem. API documentation ***************** | Header file: :file:`include/net/azure_iot_hub.h` | Source files: :file:`subsys/net/lib/azur_iot_hub/src/` .. doxygengroup:: azure_iot_hub :project: nrf :members: