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_TIMEOUT

Deletion of the downloaded FOTA image has reached the defined timeout. It will continue.

   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.

enumerator FOTA_DOWNLOAD_EVT_RESUME_OFFSET: Resume the download at offset. Only generated if CONFIG_FOTA_DOWNLOAD_EXTERNAL_DL is enabled.

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_CONNECT_FAILED: Connecting to the FOTA server failed. A possible reason could be wrong TLS credentials. A retry is unlikely to help with the same credentials.

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(const char *host, const char *file, const int *sec_tag_list, uint8_t sec_tag_count, uint8_t pdn_id, size_t fragment_size, const enum dfu_target_image_type expected_type)

Download the given file with the specified image type from the given host.

Validate that the file type matches the expected type before proceeding with the download. 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_any() for details on expected format.
sec_tag_list – Security tags that you want to use with HTTPS. Pass NULL to disable TLS.
sec_tag_count – Number of TLS security tags in list. Pass 0 to disable TLS.
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.
-E2BIG – If sec_tag_count is larger than CONFIG_FOTA_DOWNLOAD_SEC_TAG_LIST_SIZE_MAX Otherwise, a negative value is returned.

int fota_download_any(const char *host, const char *file, const int *sec_tag_list, uint8_t sec_tag_count, uint8_t pdn_id, size_t fragment_size)

Start downloading the given file of any image type 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.

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, 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_list – Security tags that you want to use with HTTPS. Pass NULL to disable TLS.
sec_tag_count – Number of TLS security tags in list. Pass 0 to disable TLS.
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.
-E2BIG – If sec_tag_count is larger than CONFIG_FOTA_DOWNLOAD_SEC_TAG_LIST_SIZE_MAX 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 of any image type 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.

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, e.g. https://google.com:443
file – Path to the file you wish to download. See fota_download_any() for details on expected format.
sec_tag – Security tag you want to use with HTTPS. Pass -1 to disable TLS.
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)

Download the given file with the specified image type from the given host.

Validate that the file type matches the expected type before proceeding with the download. 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_any() for details on expected format.
sec_tag – Security tag you want to use with HTTPS. Pass -1 to disable TLS.
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.

int fota_download_b1_file_parse(char *s0_s1_files)

Parse and modify the provided file path so that it points to the bootloader file that should be used for a bootloader (B1) FOTA update.

Parameters:

s0_s1_files – Null-terminated file path that may contain two files separated by a space. On successful return of this function, this file path will be modified.

Return values:

-EIO – Failed to determine the active bootloader (B1) slot, s0 or s1.
-ENOEXEC – Failed to parse file path.
-EOPNOTSUPP – B1 upgrade is not supported by the build configuration.
-ENOMSG – No delimeter (space) was found in the file path.
0 – File path was modified and now points to the correct bootloader file to be downloaded.

int fota_download_external_start(const char *host, const char *file, const enum dfu_target_image_type expected_type, const size_t image_size)

Start a FOTA download using an external download client. Requires.

CONFIG_FOTA_DOWNLOAD_EXTERNAL_DL to be enabled.

Parameters:

host – Name of host.
file – File path of the firmware image.
expected_type – Type of firmware image to be installed.
image_size – Size of the firmware image.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int fota_download_external_evt_handle(struct download_client_evt const *const evt)

Handle a download event from an external download client. Requires.

CONFIG_FOTA_DOWNLOAD_EXTERNAL_DL to be enabled.

Parameters:

evt – Download event.

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

size_t resume_offset: Resume at offset FOTA_DOWNLOAD_EVT_RESUME_OFFSET

FOTA download

Configuration and implementation

HTTPS downloads

Second-stage bootloader upgrades

API documentation

Configuration and implementation 

HTTPS downloads 

Second-stage bootloader upgrades 

API documentation 