Azure FOTA

The Azure firmware over-the-air (Azure FOTA) library provides a way to parse Azure IoT Hub device twin messages to obtain firmware upgrade information and perform FOTA downloads. This library is used by the Azure IoT Hub sample.

The JSON format and content used in this library are based on the recommendations in Azure Firmware Over The Air (FOTA). The library processes the incoming JSON string and searches for a specific object in the device twin that contains the firmware upgrade information. The expected format of a firmware object is as shown below:

{
     "firmware": {
             "fwVersion": "v1.0.3",
             "fwLocation": {
                     "protocol": "https:",
                     "host": "<hostname>",
                     "path": "<filename>.bin"
             },
             "fwFragmentSize": 1800
     }
}

The library uses fwVersion to determine whether the firmware should be downloaded or not. Currently, a new version of the firmware is downloaded and applied only if the version is different from the current firmware version.

Currently, the library does not use the protocol field. Instead, the CONFIG_AZURE_FOTA_TLS option is used at compile time to specify if HTTPS should be used as the transport protocol.

The fwFragmentSize field specifies the maximum fragment size for the file that should be downloaded in each HTTP request. Below are the maximum total fragment sizes in different scenarios:

• With TLS: 2 KB including the HTTP header

• Without TLS: 4 KB

fwFragmentSize should therefore be set to a value lower than the maximum buffer size to reserve space for the HTTP header.

It is up to the application that uses the library to restart the device when the FOTA completes and an AZURE_FOTA_EVT_DONE event is received.

Note

The current implementation is experimental.

Configuration

Configure the following parameters when using this library:

• 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 Provision root CA certificates for more details.

Additionally, configure the Download client library:

• CONFIG_DOWNLOAD_CLIENT_MAX_HOSTNAME_SIZE - Sets the maximum length of the host name for the download client.

• CONFIG_DOWNLOAD_CLIENT_MAX_FILENAME_SIZE - Sets the maximum length of the file name for the download client.

Limitations

The library requires a Content-Range header to be present in the HTTP response from the server. This limitation is inherited from the Download client library.

API documentation

Header file: include/net/azure_fota.h

Source files: subsys/net/lib/azure_fota/

Azure FOTA library