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
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.

When built for an _ns build target, the sample is configured to compile and run as a non-secure application. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

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, you must provision the required certificates 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, you can use the same root certificate (Baltimore CyberTrust Root certificate) that is used in the Azure IoT Hub connection. 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. You can provision the certificates using the same procedure as described in Provisioning of the certificates.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Additional configuration

Check and configure the following library Kconfig 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 enabled, CONFIG_AZURE_FOTA_APP_VERSION is ignored.

• CONFIG_AZURE_FOTA_TLS - Enables HTTPS for downloads. By default, TLS is enabled and currently, the transport protocol must be configured at compile time.

• CONFIG_AZURE_FOTA_SEC_TAG - Sets the security tag for TLS credentials when using HTTPS as the transport layer. See Certificates for using TLS for more details.

• CONFIG_AZURE_IOT_HUB_HOSTNAME - Sets the Azure IoT Hub host name. If DPS is used, the sample assumes that the IoT hub host name is unknown, and the configuration is ignored.

• CONFIG_AZURE_IOT_HUB_DEVICE_ID - Specifies the device ID, which is used when connecting to Azure IoT Hub.

• CONFIG_AZURE_IOT_HUB_DPS_REG_ID - Specifies the device registration ID used for DPS.

Note

To provide the device ID used in the connection towards Azure IoT Hub at run time, set the device_id member of the azure_iot_hub_config structure when calling the azure_iot_hub_connect() function. If the device_id.size buffer size is zero, the compile-time option CONFIG_AZURE_IOT_HUB_DEVICE_ID` is used.

Building and running

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

When built as a non-secure firmware image for the _ns build target, the sample automatically includes the Trusted Firmware-M (TF-M).

To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing

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

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 Device Twin.

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:

• Azure FOTA

• Azure IoT Hub

• LTE link controller

It uses the following sdk-nrfxlib library:

• Modem library

It uses the following Zephyr library:

• MQTT

In addition, it uses the following secure firmware component:

• Trusted Firmware-M