nRF9160: Azure FOTA

The Azure firmware over-the-air (Azure FOTA) sample demonstrates how to perform an over-the-air firmware update of an nRF9160-based device using the Azure FOTA and Azure IoT Hub libraries of nRF Connect SDK.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

Thingy:91

PCA20035

thingy91_nrf9160

thingy91_nrf9160_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

The sample also requires an Azure IoT Hub instance, and optionally an Azure IoT Hub Device Provisioning Service (DPS) instance, if the device is not already registered with the IoT hub.

The sample is configured to compile and run as a non-secure application on nRF91’s Cortex-M33. Therefore, it automatically includes the Secure Partition Manager that prepares the required peripherals to be available for the application.

You can also configure it to use TF-M instead of Secure Partition Manager.

Overview

The sample connects to the configured Azure IoT Hub and waits for incoming Azure IOT Hub device twin messages that contain the firmware update information. By default, the device twin document is requested upon connecting to the IoT hub. Thus, any existing firmware information in the desired property will be parsed. 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 that shares the same root certificate as the Azure IoT Hub instance.

Certificates for using TLS

If TLS is used as the transport layer, the required certificates must be provisioned to the device. The certificates that need to be provisioned depends on the location of the hosted FOTA image, and the TLS settings that are configured at the endpoint from where the file is downloaded. If, for instance, Azure Blob Storage is used for hosting, the same root certificate (Baltimore CyberTrust Root certificate) that is used in the Azure IoT Hub connection can be used. See Prerequisites for connecting to Azure IoT Hub for more information.

If a host other than Azure is used, the certificate requirements might be different. See the documentation for the respective host to locate the correct certificates. The certificates can be provisioned using the same procedure as described in Provisioning of the certificates.

Additional configuration

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

Note

If the CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP option is disabled, the device ID must be set in prj.conf. If the CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP option is enabled, the device ID must be provided using the azure_iot_hub_config configuration struct in a call to the azure_iot_hub_init() function.

Building and running

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

The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160_ns build target. Because of this, it automatically includes the Secure Partition Manager. You can also configure it to use TF-M instead of SPM.

See Building and programming an application for information about how to build and program the application.

Testing

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

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  3. Reset the development kit.

  4. Observe that the sample displays the configured application version in the terminal and connects to Azure IoT Hub as shown below:

    *** Booting Zephyr OS build v2.3.0-rc1-ncs1-1453-gf41496cd30d5  ***
Traces enabled
Azure FOTA sample started
Initializing Modem library
This may take a while if a modem firmware update is pending
Modem library initialized
Connecting to LTE network
AZURE_IOT_HUB_EVT_CONNECTING
AZURE_IOT_HUB_EVT_CONNECTED
AZURE_IOT_HUB_EVT_READY

  5. Log in to the Azure Portal, navigate to IoT Hub and select your IoT hub.

  6. Navigate to IoT devices and select the device to update.

  7. In the device view, click the Device Twin button.

  8. 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.0-dev",
          "jobId": "ca186d4b-4171-4209-a49d-700c35567d1d",
          "fwLocation": {
              "host": "my-storage-account.blob.core.windows.net",
              "path": "my-app-update.bin"
          },
          "fwFragmentSize": 1800
      }
  }

    See the documentation on Azure FOTA library for more details.

  9. Apply the changes to the device twin by clicking Save. Updating the device twin causes a message to be sent to the device, containing the updates to the desired object.

  10. In the terminal emulator, observe that the new firmware image is downloaded and installed as shown below:

    ...
[00:00:20.089,416] <inf> download_client: Downloaded 19800/300860 bytes (6%)
[00:00:20.338,653] <inf> download_client: Downloaded 21600/300860 bytes (7%)
[00:00:20.359,924] <inf> STREAM_FLASH: Erasing page at offset 0x0008c000
[00:00:20.729,644] <inf> download_client: Downloaded 23400/300860 bytes (7%)
[00:00:20.979,675] <inf> download_client: Downloaded 25200/300860 bytes (8%)
[00:00:21.007,385] <inf> STREAM_FLASH: Erasing page at offset 0x0008d000
...
[00:01:22.750,946] <inf> download_client: Download complete
[00:01:22.761,657] <inf> STREAM_FLASH: Erasing page at offset 0x000fd000
[00:01:22.857,238] <inf> dfu_target_mcuboot: MCUBoot image upgrade scheduled. Reset the device to apply
[2020-08-28 00:38:18] [00:01:15.665,679] <inf> azure_fota: FOTA download completed evt received
[2020-08-28 00:38:18] AZURE_IOT_HUB_EVT_FOTA_DONE
[2020-08-28 00:38:18] The device will reboot in 5 seconds to apply update

  11. When the development kit reboots, observe that the sample displays the logs from the new application.

  12. In Azure Portal, confirm that the device twin contains the updated application version in the reported.firmware.fwVersion field.

Dependencies

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr library:

In addition, it uses the following sample: