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.

Configuration and implementation

To start a FOTA download, provide the URL for the file that should be downloaded, specifying the required arguments as follows:

  • host - It indicates the hostname of the target host. For example, my_domain.com.

  • file - It indicates the path to the file. For example, path/to/resource/file.bin.

The FOTA library downloads the image using the Download client library. After downloading the first fragment, it uses the DFU target library to identify the type of image that is being downloaded. Examples of image types are modem upgrades and upgrades handled by a second-stage bootloader.

Once the library starts the download, all received data fragments are passed to the DFU target library. The DFU target library handles the location 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 been completed, the FOTA library tags the received firmware as an upgrade candidate, and it instructs the download client to disconnect from the server. The library then sends a FOTA_DOWNLOAD_EVT_FINISHED callback event. When the application using the library receives this event, it must issue a reboot command to apply the upgrade.

You can set CONFIG_FOTA_DOWNLOAD_NATIVE_TLS to configure the socket to be native for TLS instead of offloading TLS operations to the modem.

HTTPS downloads

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

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

Second-stage bootloader upgrades

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

To do this, provide two paths in the file argument, separated by a space character:

  • The first entry must point to the second-stage upgradable bootloader variant linked against the S0 partition.

  • The second entry must point to the second-stage upgradable bootloader variant linked against the S1 partition.

When an upgradeable bootloader, like MCUboot, is included in the project, the FOTA download library uses Trusted Firmware-M (TF-M) to detect the active second-stage upgradable bootloader 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. A device reset triggers the second-stage upgradable bootloader to copy the image from the update bank to the non-active slot. An additional reset is then required for the first-stage immutable bootloader to select and use the upgraded second-stage bootloader.

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.

Param evt:

Event.

Enums

enum fota_download_evt_id

FOTA download event IDs.

After FINISHED, ERROR or CANCELLED event, the FOTA client is ready to accept new request.

Values:

enumerator FOTA_DOWNLOAD_EVT_PROGRESS

FOTA download progress report.

enumerator FOTA_DOWNLOAD_EVT_FINISHED

FOTA download was completed successfully.

enumerator FOTA_DOWNLOAD_EVT_ERASE_PENDING

Deletion of the downloaded FOTA image is in progress (after upgrade success or failure). 

   Not fired for all FOTA types.

enumerator FOTA_DOWNLOAD_EVT_ERASE_DONE

Deletion of the downloaded FOTA image is complete. 

   Not fired for all FOTA types.

enumerator FOTA_DOWNLOAD_EVT_ERROR

FOTA download abandoned due to an error.

enumerator FOTA_DOWNLOAD_EVT_CANCELLED

FOTA download abandoned due to a cancellation request.

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.

enumerator FOTA_DOWNLOAD_ERROR_CAUSE_TYPE_MISMATCH

Actual firmware type does not match expected. Retry will not help.

enumerator FOTA_DOWNLOAD_ERROR_CAUSE_INTERNAL

Generic error on device side.

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 values:

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

int fota_download_start(const char *host, const char *file, int sec_tag, uint8_t pdn_id, 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 – Path to the file you wish to download. May be either a single file path, relative to host (for example “path/to/binary.bin”), or, if bootloader FOTA is enabled, can be two paths (both relative to host), separated by a space (for example “path/to/s0.bin path/to/s1.bin”). If two paths are provided, the download will be assumed to be a bootloader download, both paths will be treated as upgradable bootloader slot 0 and slot 1 binaries respectively, and only the binary corresponding to the currently inactive bootloader slot will be selected and downloaded. See Secure Bootloader Chain Docs for details regarding the upgradable bootloader slots.

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

  • pdn_id – Packet Data Network ID to use for the download, or 0 to use the default.

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

Return values:

  • 0 – If download has started successfully.

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

int fota_download_start_with_image_type(const char *host, const char *file, int sec_tag, uint8_t pdn_id, size_t fragment_size, const enum dfu_target_image_type expected_type)

Start downloading the given file from the given host. Validate that the file type matches the expected type before starting the installation.

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.

URI parameters (host and file) are not copied, so pointers must stay valid until download is finished.

Parameters:

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

  • file – Path to the file you wish to download. See fota_download_start() for details on expected format.

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

  • pdn_id – Packet Data Network ID to use for the download, or 0 to use the default.

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

  • expected_type – Type of firmware file to be downloaded and installed.

Return values:

  • 0 – If download has started successfully.

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

int fota_download_cancel(void)

Cancel FOTA image downloading.

Return values:

  • 0 – If FOTA download is cancelled successfully.

  • -EAGAIN – If download is not started, aborted or completed. Otherwise, a negative value is returned.

int fota_download_target(void)

Get target image type.

Image type becomes known after download starts.

Return values:

0 – Unknown type before download starts. Otherwise, a type defined in enum dfu_target_image_type.

int fota_download_s0_active_get(bool *const s0_active)

Get the active bootloader (B1) slot, s0 or s1.

Parameters:

  • s0_active – [out] Set to ‘true’ if s0 is active slot, ‘false’ otherwise

Return values:

0 – If successful. Otherwise, a (negative) error code 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 %.