Azure IoT Hub

The Azure IoT Hub sample demonstrates the communication of an Internet-connected device with an Azure IoT Hub instance. This sample uses the Azure IoT Hub library to communicate with the IoT hub and the Azure FOTA library to provide firmware over-the-air (FOTA) functionality. The sample connects either to an LTE network using an nRF91 Series device, or to Wi-Fi® using an nRF71 Series or nRF70 Series device combined with a compatible host platform.

Cellular connectivity is supported on the nRF91 Series SiPs, while Wi-Fi connectivity is supported on the nRF71 Series SoCs and on the nRF53 or nRF54 Series SoCs hosting the nRF70 Series Wi-Fi companion ICs.

The sample uses the connection manager that provides a common connectivity API for LTE and Wi-Fi stacks.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target	Shields
nRF9161 DK	PCA10153	nrf9161dk	`nrf9161dk/nrf9161/ns`
nRF9160 DK	PCA10090	nrf9160dk	`nrf9160dk/nrf9160/ns`
nRF9151 DK	PCA10171	nrf9151dk	`nrf9151dk/nrf9151/ns`
nRF7120 DK	PCA10217	nrf7120dk	`nrf7120dk/nrf7120/cpuapp/ns`
nRF7002 DK	PCA10143	nrf7002dk	`nrf7002dk/nrf5340/cpuapp/ns`
nRF54LM20 DK	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20b/cpuapp/ns` `nrf54lm20dk/nrf54lm20a/cpuapp/ns`	`"nrf7002eb2"`
Native Simulator		native_sim	`native_sim`

Additionally, the sample supports emulation using the native simulator.

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Overview 

The sample supports the direct connection of an IoT device that is already registered to an Azure IoT Hub instance. Alternatively, it supports the provisioning of the device using Azure IoT Hub Device Provisioning Service (DPS) to an IoT hub. See the documentation on Azure IoT Hub library for more information.

The sample periodically publishes telemetry messages (events) to the connected Azure IoT Hub instance. By default, telemetry messages are sent every 20 seconds. To configure the default interval, set the device twin property desired.telemetryInterval. The sample reads the value of this property as seconds. Here is an example of a telemetry message:

{
  "temperature": 25.2,
  "timestamp": 151325
}

In a telemetry message, temperature is a value between 25.0 and 25.9, and timestamp is the uptime of the device in milliseconds.

The sample handles the Azure IoT Hub direct method with the name led. If the device receives a direct method invocation with the name led and payload 1 or 0, LED 1 on the device is turned on or off, depending on the payload.

Firmware update 

The sample subscribes to incoming Azure IOT Hub device twin messages that contain the firmware update information. By default, the sample requests the device twin document when the device connects to the IoT hub. Thus, the sample parses any existing firmware information in the desired property. See Azure FOTA for more details on the content of the firmware information in the device twin.

Note

This sample requires a file server instance that hosts the new firmware image. The Azure FOTA library does not require a specific host, but it has been tested using Azure Blob Storage.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

Azure IoT Hub setup 

For the sample to work as intended, you must set up and configure an Azure IoT Hub instance. See Setup and configuration for information on creating an Azure IoT Hub instance and Configuration options for additional information on the configuration options that are available. For a successful TLS connection to the Azure IoT Hub instance, you must provision credentials on the device. If you want to test FOTA, ensure that you also provision the required credentials for the file server. Also ensure that you set the CONFIG_AZURE_FOTA_SEC_TAG Kconfig option accordingly. See Setup and configuration for information on provisioning the credentials.

Note

On nRF91 Series devices, you can provision the credentials only when the modem is not connected to the network.

Configuration options 

The following sample-specific Kconfig options are used in this sample (located in samples/net/azure_iot_hub/Kconfig):

CONFIG_AZURE_IOT_HUB_SAMPLE_DEVICE_ID_USE_HW_ID

(bool) Use HW ID as device ID

Use the devices’s hardware ID as device ID when connecting to Azure IOT Hub

Check and configure the following library options that are used by the sample:

CONFIG_AZURE_IOT_HUB_DEVICE_ID - Sets the Azure IoT Hub device ID. Alternatively, you can provide the device ID at runtime.
CONFIG_AZURE_IOT_HUB_HOSTNAME - Sets the Azure IoT Hub host name. If you use the Device Provisioning Service (DPS), the sample assumes that the host name is unknown and ignores the configuration. You can also omit the configuration and provide the host name at run time.

If DPS is used, check and configure the following library options:

CONFIG_AZURE_IOT_HUB_DPS - Enables Azure IoT Hub DPS.
CONFIG_AZURE_IOT_HUB_DPS_REG_ID - Sets the Azure IoT Hub DPS registration ID. You can provide it at runtime. By default, the sample uses the device ID as the registration ID and sets it at runtime.
CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE - Sets the DPS ID scope of the Azure IoT Hub. You can provide it at runtime.

For FOTA, check and configure the following library options:

CONFIG_AZURE_FOTA_APP_VERSION - Defines the application version string. Indicates the current firmware version on the development kit.
CONFIG_AZURE_FOTA_APP_VERSION_AUTO - Automatically generates the application version. If you enable this option, the sample ignores CONFIG_AZURE_FOTA_APP_VERSION.
CONFIG_AZURE_FOTA_TLS - Enables HTTPS for downloads. By default, TLS is enabled. You must configure the transport protocol at compile time.
CONFIG_AZURE_FOTA_SEC_TAG - Sets the security tag for TLS credentials when using HTTPS as the transport layer. See Setup and configuration for more details.

Note

The sample sets the CONFIG_MQTT_KEEPALIVE Kconfig option to the maximum value that Azure IoT Hub allows, which is 1767 seconds (29.45 minutes). This value limits the IP traffic between the device and the Azure IoT Hub message broker, to support a low-power sample. In certain LTE networks, the NAT timeout can be considerably lower than 1767 seconds. To prevent unexpected disconnections, set the option CONFIG_MQTT_KEEPALIVE to the lowest timeout limit (maximum allowed MQTT keepalive and NAT timeout).

Configuring Wi-Fi access point credentials 

This sample uses the Wi-Fi credentials library to manage Wi-Fi credentials. Before the sample can connect to a Wi-Fi network, you must configure at least one credential set.

Once you have flashed your device with this sample, connect to your device’s UART interface and add credentials using the following command:

wifi cred add -s NetworkSSID -k SecurityMode -p NetworkPassword

Where NetworkSSID is replaced with the SSID of the Wi-Fi access point you want your device to connect to, and NetworkPassword is its password. SecurityMode is replaced by the number as listed here:

0: None
1: WPA2-PSK
2: WPA2-PSK-256
3: SAE-HNP
4: SAE-H2E
5: SAE-AUTO
6: WAPI (not supported on Nordic Semiconductor Wi-Fi devices)
7: EAP-TLS
8: WEP
9: WPA-PSK
10: WPA-Auto-Personal
11: DPP (not supported on Nordic Semiconductor Wi-Fi devices)

If you are not sure which security mode to use, enable the CONFIG_NET_L2_WIFI_SHELL Kconfig option and use the wifi scan command to display a list of all accessible networks along with their corresponding security modes. Then either reboot the device or use the wifi cred auto_connect command to manually trigger a connection attempt.

From now on, these credentials will be automatically used when the configured network is reachable.

When building as firmware image for a non-secure board target, the Wi-Fi credentials backend will be set to PSA using TF-M.

See the Wi-Fi: Shell sample document for more details on the wifi cred command.

Wi-Fi static credential options

If you want to configure the credentials statically, set the CONFIG_WIFI_CREDENTIALS_STATIC Kconfig option to y.

Important

Do not use static credentials in production environments.

Other options for statically configuring your Wi-Fi credentials:

CONFIG_WIFI_CREDENTIALS_STATIC - This option enables static Wi-Fi configuration.
CONFIG_WIFI_CREDENTIALS_STATIC_SSID - Wi-Fi SSID.
CONFIG_WIFI_CREDENTIALS_STATIC_PASSWORD - Wi-Fi password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_OPEN - Wi-Fi network uses no password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK - Wi-Fi network uses a password and PSK security (default).
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK_SHA256 - Wi-Fi network uses a password and PSK-256 security.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_SAE - Wi-Fi network uses a password and SAE security.

Sending traces over UART on an nRF91 Series DK 

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Configuration files 

The sample provides predefined configuration files for the following development kits:

prj.conf - General configuration file for all devices.
boards/nrf9151dk_nrf9151_ns.conf - Configuration file for the nRF9151 DK.
boards/nrf9161dk_nrf9161_ns.conf - Configuration file for the nRF9161 DK.
boards/nrf9160dk_nrf9160_ns.conf - Configuration file for the nRF9160 DK.
boards/native_sim.conf - Configuration file for the native simulator emulation.
boards/nrf7120dk_nrf7120_cpuapp_ns.conf - Configuration file for the nRF7120 DK.
boards/nrf7002dk_nrf5340_cpuapp_ns.conf - Configuration file for the nRF7002 DK.
boards/nrf54lm20dk_nrf54lm20a_cpuapp_ns.conf - Configuration file for the nRF54LM20 DK (nRF54LM20A SoC).
boards/nrf54lm20dk_nrf54lm20b_cpuapp_ns.conf - Configuration file for the nRF54LM20 DK (nRF54LM20B SoC).
wifi.conf - Wi-Fi networking configuration, common to the nRF71 Series and nRF70 Series devices. Must be added explicitly for Wi-Fi builds.
wifi-fota.conf - FOTA configuration for Wi-Fi builds.
dps.conf - Enables provisioning of the device using DPS.

Board files under the boards/ folder are merged automatically for the selected target. The wifi.conf and other extra configuration files are not board-specific and must be passed with azure_iot_hub_EXTRA_CONF_FILE.

To add a specific extra configuration file to the build, add the -- -Dazure_iot_hub_EXTRA_CONF_FILE=<extra_conf_file> flag to your west build command.

Wi-Fi

Networking, TLS, and FOTA are not part of the default configuration when you build for Wi-Fi. Add them with the wifi.conf and wifi-fota.conf files. For example, to build for the nRF7002 DK:

west build -p -b nrf7002dk/nrf5340/cpuapp/ns -- -Dazure_iot_hub_EXTRA_CONF_FILE="wifi.conf;wifi-fota.conf"

To build for the nRF54LM20 DK with the nRF7002 EB2 shield, also add the shield:

west build -p -b nrf54lm20dk/nrf54lm20a/cpuapp/ns -- -Dazure_iot_hub_SHIELD="nrf7002eb2" -Dazure_iot_hub_EXTRA_CONF_FILE="wifi.conf;wifi-fota.conf"

Device Provisioning Service

To use DPS, add the dps.conf file to the build. For example, to build with DPS for the nRF9161 DK:

west build -p -b nrf9161dk/nrf9161/ns -- -Dazure_iot_hub_EXTRA_CONF_FILE=dps.conf

To use DPS on a Wi-Fi build, add it to the other files:

west build -p -b nrf7002dk/nrf5340/cpuapp/ns -- -Dazure_iot_hub_EXTRA_CONF_FILE="wifi.conf;wifi-fota.conf;dps.conf"

Building and running 

This sample can be found under samples/net/azure_iot_hub in the nRF Connect SDK folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing 

Microsoft has created Azure IoT Explorer to interact and test devices connected to an Azure IoT Hub instance. Optionally, follow the instructions at Azure IoT Explorer to install and configure the tool and use it as described in the following instructions.

After programming the sample to your development kit, complete the following steps to test it:

Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.
Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Power on or reset the kit.
Observe the log output and verify that it is similar to the Sample output.
Use the Azure IoT Explorer, or log in to the Azure Portal.
Select the connected IoT hub and then your device.
Change the device twin’s desired property telemetryInterval to a new value, for instance 60, and save the updated device twin. If it does not exist, you can add the desired property.
Observe that the device receives the updated telemetryInterval value, applies it, and starts sending new telemetry events every 60 seconds.
Verify that the reported object in the device twin now has a telemetryInterval property with the correct value reported back from the device.
In the Azure IoT Explorer or device page in Azure Portal, navigate to the Direct method tab.
Enter led as the method name. In the payload field, enter the value 1 (or 0) and click Invoke method.
Observe that LED 1 on the development kit lights up (or switches off if 0 is entered as the payload). If you are using Azure IoT Explorer, you can observe a notification in the top right corner that shows if the direct method was successfully invoked, based on the report received from the device.
In the Azure IoT Explorer, navigate to the Telemetry tab and click start.
Observe that the event messages from the device are displayed in the Azure IoT Explorer within the specified telemetry interval.

To test FOTA update:

Navigate to the view where you can update the device twin using the Azure IoT Explorer or Azure Portal.

Create a firmware JSON object inside the desired object of the device twin document, containing information about the binary to download:

{
    "firmware": {
        "fwVersion": "v0.0.2-dev",
        "jobId": "ca186d4b-4171-4209-a49d-700c35567d1d",
        "fwLocation": {
            "host": "example.com",
            "path": "firmware/my-app-update.bin"
        },
        "fwFragmentSize": 1800
    }
}

Click Save to apply the changes to the device twin. Updating the device twin causes a message to be sent to the device, containing the updates to the desired object.
In the terminal emulator, observe that the new firmware image is downloaded and installed as shown in Sample output.
Observe that the sample displays the logs from the new application when the development kit reboots.
Confirm that the device twin contains the updated application version in the reported.firmware.fwVersion field in Azure IoT Explorer or Azure Portal.

Sample output 

When the sample runs, the device boots, and the sample displays the following output in the terminal over UART:

*** Booting Zephyr OS build v2.3.0-rc1-ncs1-1453-gf41496cd30d5  ***
<inf> azure_iot_hub_sample: Azure IoT Hub sample started
<inf> azure_iot_hub_sample: Bringing network interface up and connecting to the network
<inf> azure_iot_hub_sample: Device ID: my-device
<inf> azure_iot_hub_sample: Connecting...
<inf> azure_iot_hub_sample: Network connectivity established and IP address assigned
<inf> azure_fota: Current firmware version: 0.0.1-dev
<inf> azure_iot_hub_sample: Azure IoT Hub library initialized
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_CONNECTING
<inf> azure_iot_hub_sample: Connection request sent to IoT Hub
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_CONNECTED
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_READY
<inf> azure_iot_hub_sample: Sending event:
<inf> azure_iot_hub_sample: {"temperature":25.9,"timestamp":16849}
<inf> azure_iot_hub_sample: Event was successfully sent
<inf> azure_iot_hub_sample: Next event will be sent in 60 seconds

If a new telemetry interval is set in the device twin, the console output is like this:

<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_DESIRED_RECEIVED
<inf> azure_iot_hub_sample: New telemetry interval has been applied: 60
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_RESULT_SUCCESS, ID: 42740
<inf> azure_iot_hub_sample: Sending event:
<inf> azure_iot_hub_sample: {"temperature":25.5,"timestamp":47585}
<inf> azure_iot_hub_sample: Event was successfully sent
<inf> azure_iot_hub_sample: Next event will be sent in 60 seconds

If a new FOTA update is initiated, the console output is like this:

<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_RESULT_SUCCESS, ID: 140
<inf> azure_fota: Attempting to download firmware (version 'v0.0.2-dev') from example.com/firmware/app_update.bin
<inf> downloader: Downloading: firmware/app_update.bin [0]
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_FOTA_START
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_DESIRED_RECEIVED
<inf> downloader: Setting up TLS credentials, sec tag count 1
<inf> downloader: Connecting to example.com
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_RESULT_SUCCESS, ID: 190
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_RESULT_SUCCESS, ID: 190
<inf> downloader: Downloaded 1800/674416 bytes (0%)
...
<inf> downloader: Downloaded 674416/674416 bytes (100%)
<inf> downloader: Download complete
<inf> dfu_target_mcuboot: MCUBoot image-0 upgrade scheduled. Reset device to apply
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_FOTA_DONE
<inf> azure_iot_hub_sample: The device will reboot in 5 seconds to apply update
<inf> azure_iot_hub_sample: AZURE_IOT_HUB_EVT_TWIN_RESULT_SUCCESS, ID: 109

Troubleshooting 

If you have issues with connectivity on nRF91 Series devices, see the Cellular Monitor app documentation to learn how to capture modem traces to debug network traffic in Wireshark. To enable modem traces, build the sample with the following command:

west build -p -b nrf9161dk/nrf9161/ns -- -Dazure_iot_hub_SNIPPET="nrf91-modem-trace-uart"

If you have issues with connectivity on nRF71 Series or nRF70 Series devices, see the Wi-Fi: Monitor sample documentation to learn how to capture and analyze Wi-Fi traffic to debug connectivity issues. Also verify that the Wi-Fi credentials configured for your device match your access point, as described in the Configuration options section on this page.

Dependencies 

This sample uses the following nRF Connect SDK and Zephyr libraries:

It uses the following libraries and secure firmware component for nRF91 Series builds:

It uses the following libraries for nRF71 Series and nRF70 Series builds: