FOTA download

The firmware over-the-air (FOTA) download library provides functions for downloading a firmware file as an upgrade candidate to the DFU target that is used in the DFU target library.

To start a FOTA download, you must provide the URL for the file that should be downloaded. The required arguments are host (for example, my_domain.com) and file (for example, path/to/resource/file.bin).

Note

To upgrade the upgradable bootloader, you must provide two firmware files: one linked against the S0 partition and one linked against the S1 partition. See Upgradable bootloader for more information.

To do this, you must provide two paths in the file argument, separated by a space character. The first entry must point to the MCUboot variant linked against the S0 partition. The second entry must point to the MCUboot variant linked against the S1 partition.

If an upgradeable bootloader is included in the project, the FOTA download library uses the Secure Services library to deduce the active MCUboot partition (S0 or S1). If the file argument contains a space character, it is internally updated to contain only the entry that corresponds to the non-active slot. This updated path is then used to download the image.

The library uses the Download client to download the image. After downloading the first fragment, the DFU target library is used to identify the type of the image that is being downloaded. Examples of image types are modem upgrades and upgrades handled by MCUboot.

Once the download has been started, all received data fragments are passed to the DFU target library. The DFU target library takes care of where the upgrade candidate is stored, depending on the image type that is being downloaded.

When the download client sends the event indicating that the download has completed, the received firmware is tagged as an upgrade candidate, and the download client is instructed to disconnect from the server. The library then sends a FOTA_DOWNLOAD_EVT_FINISHED callback event. When the consumer of the library receives this event, it should issue a reboot command to apply the upgrade.

By default, the FOTA download library uses HTTP for downloading the firmware file. To use HTTPS instead, apply the changes described in the HTTPS section of the download client documentation to the library.

The FOTA download library is used in the nRF9160: HTTP application update sample.

API documentation

Header file: include/net/fota_download.h
Source files: subsys/net/lib/fota_download/src/
group fota_download

Library for downloading a firmware update over the air.

Downloads the specified file from the specified host to the secondary partition of MCUboot. After the file has been downloaded, the secondary slot is tagged as having valid firmware inside it.

Typedefs

typedef void (*fota_download_callback_t)(enum fota_download_evt_id evt_id)

FOTA download asynchronous callback function.

Parameters
  • event_id: Event ID.

Enums

enum fota_download_evt_id

FOTA download event IDs.

Values:

FOTA_DOWNLOAD_EVT_FINISHED

FOTA download finished.

FOTA_DOWNLOAD_EVT_ERROR

FOTA download error.

Functions

int fota_download_init(fota_download_callback_t client_callback)

Initialize the firmware over-the-air download library.

Parameters
  • client_callback: Callback for the generated events.

Return Value
  • 0: If successfully initialized. Otherwise, a negative value is returned.

int fota_download_start(char *host, char *file)

Start downloading the given file from the given host.

When the download is complete, the secondary slot of MCUboot is tagged as having valid firmware inside it. The completion is reported through an event.

Return Value
  • 0: If download has started successfully.

  • -EALREADY: If download is already ongoing. Otherwise, a negative value is returned.