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)(const struct fota_download_evt *evt)

FOTA download asynchronous callback function.

Parameters

  • event_id: Event ID.

Enums

enum fota_download_evt_id

FOTA download event IDs.

Values:

enumerator FOTA_DOWNLOAD_EVT_PROGRESS

FOTA download progress report.

enumerator FOTA_DOWNLOAD_EVT_FINISHED

FOTA download finished.

enumerator FOTA_DOWNLOAD_EVT_ERASE_PENDING

FOTA download erase pending.

enumerator FOTA_DOWNLOAD_EVT_ERASE_DONE

FOTA download erase done.

enumerator FOTA_DOWNLOAD_EVT_ERROR

FOTA download error.

enum fota_download_error_cause

FOTA download error cause values.

Values:

enumerator FOTA_DOWNLOAD_ERROR_CAUSE_NO_ERROR

No error, used when event ID is not FOTA_DOWNLOAD_EVT_ERROR.

enumerator FOTA_DOWNLOAD_ERROR_CAUSE_DOWNLOAD_FAILED

Downloading the update failed. The download may be retried.

enumerator FOTA_DOWNLOAD_ERROR_CAUSE_INVALID_UPDATE

The update is invalid and was rejected. Retry will not help.

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(const char *host, const char *file, int sec_tag, const char *apn, size_t fragment_size)

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.

Parameters

  • host: Name of host to start downloading from. Can include scheme and port number, e.g. https://google.com:443

  • file: Filepath to the file you wish to download.

  • sec_tag: Security tag you want to use with HTTPS set to -1 to Disable.

  • apn: Access Point Name to use or NULL to use the default APN.

  • fragment_size: Fragment size to be used for the download. If 0, CONFIG_DOWNLOAD_CLIENT_HTTP_FRAG_SIZE is used.

Return Value

  • 0: If download has started successfully.

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

struct fota_download_evt
#include <fota_download.h>

FOTA download event data.

Public Members

enum fota_download_error_cause cause

Error cause.

int progress

Download progress %.