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 nRF9160: Azure FOTA 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.


The current implementation is experimental.


Configure the following parameters when using this library:


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.


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

Callback to receive Azure FOTA events.

Param evt:

Pointer to event structure.


enum azure_fota_evt_type



Azure FOTA state report is created and ready to be sent


Azure FOTA download has started


Azure FOTA complete and status reported to job document


Azure FOTA error


Azure FOTA erase pending


Azure FOTA erase done


int azure_fota_init(azure_fota_callback_t evt_handler)

Initialize the Azure Firmware Over the Air library.

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

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