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/

group azure_fota

Library for performing Firmware Over The Air updates using firmware information in JSON format.

Typedefs

typedef void (*azure_fota_callback_t)(struct azure_fota_event *evt)

Callback to receive Azure FOTA events.

Param evt:

Pointer to event structure.

Enums

enum azure_fota_evt_type

Values:

enumerator AZURE_FOTA_EVT_REPORT

Azure FOTA state report is created and ready to be sent

enumerator AZURE_FOTA_EVT_START

Azure FOTA download has started

enumerator AZURE_FOTA_EVT_DONE

Azure FOTA complete and status reported to job document

enumerator AZURE_FOTA_EVT_ERROR

Azure FOTA error

enumerator AZURE_FOTA_EVT_ERASE_PENDING

Azure FOTA erase pending

enumerator AZURE_FOTA_EVT_ERASE_DONE

Azure FOTA erase done

Functions

int azure_fota_init(azure_fota_callback_t evt_handler)

Initialize the Azure Firmware Over the Air library.

Parameters:

• evt_handler – Callback function to receive events.

Return values:

0 – If successfully initialized. Otherwise, a negative value is returned.

int azure_fota_msg_process(const char *const buf, size_t size)

Process an Azure IoT Hub device twin JSON object, check for FOTA information and act accordingly if found.

Parameters:

• buf – Pointer to buffer.

• size – Size of buffer.

Return values:

• 0 – If no FOTA information found.

• 1 – If FOTA information was processed. If an error occurs, a negative value is returned.

struct azure_fota_event

#include <azure_fota.h>

Azure FOTA event.

Public Members

enum azure_fota_evt_type type

Event type, azure_fota_evt_type.

char *report

Pointer to the report associated with the event. A report is a JSON string with information of the state of the FOTA process intended to be sent to Azure IoT Hub device twin’s reported property. A valid report is provided if the pointer is not NULL.