Firmware Over-the-Air over HTTP. More...

Data Structures
struct	fota_http_progress
	Transfer state reported while an image is being written. More...
struct	fota_http_download_params
	Parameters of a download. More...

Typedefs
typedef void(*	fota_http_progress_cb_t) (const struct fota_http_progress progress, void user_data)
	Progress callback.
typedef void(*	fota_http_done_cb_t) (int result, void *user_data)
	Completion callback of fota_http_download_async().

Functions
int	fota_http_download (const struct fota_http_download_params *params)
	Download a firmware image into the MCUboot secondary slot.
int	fota_http_download_async (const struct fota_http_download_params *params, fota_http_done_cb_t done_cb)
	Download a firmware image on the library thread.
int	fota_http_cancel (void)
	Abort the download in progress.
int	fota_http_apply (uint8_t image_index, bool permanent)
	Request MCUboot to boot a downloaded image on the next reset.
int	fota_http_confirm (uint8_t image_index)
	Confirm a running image so the bootloader stops reverting it.
bool	fota_http_confirm_pending (void)
	Check whether the running image still has to be confirmed.
int	fota_http_get_download_slot (uint8_t image_index)
	Flash area identifier of the slot a download is written to.
int	fota_http_get_image_header (uint8_t image_index, struct mcuboot_img_header *header)
	Read the MCUboot header of the image in the secondary slot.
size_t	fota_http_nvm_bytes_written (void)
	Bytes written to non-volatile memory by the most recent download.
int	fota_http_tls_add_ca (const void *cert, size_t len)
	Register the CA certificate used to authenticate https servers.
int	fota_http_tls_add_client_cert (const void cert, size_t cert_len, const void key, size_t key_len)
	Register a client certificate and key for mutual TLS.

Detailed Description

Firmware Over-the-Air over HTTP.

Since: 4.5

Version: 0.1.0

Typedef Documentation

◆ fota_http_done_cb_t

typedef void(* fota_http_done_cb_t) (int result, void *user_data)

#include <zephyr/mgmt/fota_http.h>

Completion callback of fota_http_download_async().

Invoked from the library thread once the download has finished.

Parameters

result	Return value of the download, 0 on success.
user_data	Pointer from fota_http_download_params.

◆ fota_http_progress_cb_t

typedef void(* fota_http_progress_cb_t) (const struct fota_http_progress *progress, void *user_data)

#include <zephyr/mgmt/fota_http.h>

Progress callback.

Invoked from the downloading thread every time a body fragment has been written to flash.

Parameters

progress	Current state of the transfer.
user_data	Pointer from fota_http_download_params.

Function Documentation

◆ fota_http_apply()

int fota_http_apply	(	uint8_t	image_index,
		bool	permanent )

#include <zephyr/mgmt/fota_http.h>

Request MCUboot to boot a downloaded image on the next reset.

The secondary slot must hold an image with a valid MCUboot header, and the last download into it since boot, if any, must have succeeded. The signature is only checked by the bootloader itself.

When several images must be updated together, download and apply every one of them before rebooting: MCUboot validates the whole set and swaps it in one go, so a reboot with only part of the set applied swaps only what was marked.

Parameters

image_index	Image to boot, 0 for the only image.
permanent	When true the image is marked confirmed right away. When false it boots once for evaluation and the bootloader reverts to the current image unless fota_http_confirm() is called before the following reset. A revert needs an MCUboot mode that supports it, such as swap-using-move or swap-using-offset.

Return values

0	The upgrade was requested.
-ENODEV	No slot exists for `image_index`.
-EBUSY	A download is in progress.
-ENOEXEC	The secondary slot holds no valid image, or the last download into it failed.
-errno	Any flash or bootloader error.

◆ fota_http_cancel()

int fota_http_cancel ( void )

#include <zephyr/mgmt/fota_http.h>

Abort the download in progress.

The transfer stops when the next fragment arrives or the request times out, and reports -ECANCELED.

Return values

0	A download was running and will stop.
-EALREADY	No download is running.

◆ fota_http_confirm()

int fota_http_confirm ( uint8_t image_index )

#include <zephyr/mgmt/fota_http.h>

Confirm a running image so the bootloader stops reverting it.

Only the image named by image_index is confirmed, so a layout that carries firmware for a second device confirms just what this device validated. Confirm every image of a set that must run together.

Parameters

image_index Image to confirm, 0 for the only image.

Return values

0	The image was confirmed.
-ENODEV	No slot exists for `image_index`.
-errno	Any flash or bootloader error.

◆ fota_http_confirm_pending()

bool fota_http_confirm_pending ( void )

#include <zephyr/mgmt/fota_http.h>

Check whether the running image still has to be confirmed.

Reports the state of image 0 only, because the bootloader interface has no per-image query. An application updating several images tracks the rest itself.

Returns: true after a test upgrade until fota_http_confirm() is called.

◆ fota_http_download()

int fota_http_download ( const struct fota_http_download_params * params )

#include <zephyr/mgmt/fota_http.h>

Download a firmware image into the MCUboot secondary slot.

Blocks until the whole image is written or the transfer fails. A failed download leaves the slot partially written, which MCUboot rejects, and fota_http_apply() refuses it until a later download succeeds. An image rejected by the SHA-256 or downgrade check is erased.

Only the image is stored. Call fota_http_apply() to boot it.

While the running image is a test image the secondary slot holds the image MCUboot reverts to, so downloads are refused until fota_http_confirm() has been called.

The caller's stack must fit the HTTP client and, with https, the TLS handshake; fota_http_download_async() uses a library thread instead.

Parameters

params Download parameters. Pointed-to data must stay valid until the call returns.

Return values

0	The image was written and its header is valid.
-EINVAL	The URL could not be parsed or exceeds the buffer sizes.
-ENOTSUP	The URL scheme is not supported.
-ENODEV	No slot exists for `image_index`.
-EBUSY	Another download is in progress.
-EBADMSG	The server answered with an unexpected status.
-ELOOP	More redirects than `CONFIG_FOTA_HTTP_MAX_REDIRECTS`.
-ENODATA	The server sent an empty body.
-EMSGSIZE	Fewer bytes arrived than the server announced.
-ECANCELED	fota_http_cancel() was called.
-EILSEQ	The SHA-256 digest does not match, the image was erased.
-ENOEXEC	The data written is not an MCUboot image.
-EPERM	The running image is not confirmed, or the image is older than the running one and was erased.
-errno	Any socket, HTTP client or flash error.

◆ fota_http_download_async()

int fota_http_download_async	(	const struct fota_http_download_params *	params,
		fota_http_done_cb_t	done_cb )

#include <zephyr/mgmt/fota_http.h>

Download a firmware image on the library thread.

Returns as soon as the transfer is queued. done_cb is invoked with the result fota_http_download() would have returned.

Requires CONFIG_FOTA_HTTP_ASYNC.

Parameters

params	Download parameters. The structure and the URL are copied, the other data it points to must stay valid until `done_cb` runs.
done_cb	Completion callback, may be NULL.

Return values

0	The download was queued.
-EINVAL	`params` or its URL is NULL, or the URL is too long.
-ENOTSUP	`CONFIG_FOTA_HTTP_ASYNC` is disabled.
-EPERM	The running image is not confirmed.
-EBUSY	Another download is in progress.

◆ fota_http_get_download_slot()

int fota_http_get_download_slot ( uint8_t image_index )

#include <zephyr/mgmt/fota_http.h>

Flash area identifier of the slot a download is written to.

With direct-XIP bootloaders the slot is fixed at link time, so the caller must fetch the image variant built for it.

Parameters

image_index Image whose secondary slot is queried.

Returns: Flash area identifier, or negative errno code when the image has no secondary slot.

◆ fota_http_get_image_header()

int fota_http_get_image_header	(	uint8_t	image_index,
		struct mcuboot_img_header *	header )

#include <zephyr/mgmt/fota_http.h>

Read the MCUboot header of the image in the secondary slot.

Parameters

image_index	Image whose secondary slot is read.
header	Output header.

Return values

0	A valid header was read.
-EIO	The slot holds no valid image.
-errno	Any flash error.

◆ fota_http_nvm_bytes_written()

size_t fota_http_nvm_bytes_written ( void )

#include <zephyr/mgmt/fota_http.h>

Bytes written to non-volatile memory by the most recent download.

Returns: Number of bytes in the slot, 0 if no download ran.

◆ fota_http_tls_add_ca()

int fota_http_tls_add_ca	(	const void *	cert,
		size_t	len )

#include <zephyr/mgmt/fota_http.h>

Register the CA certificate used to authenticate https servers.

The certificate is stored under CONFIG_FOTA_HTTP_TLS_SEC_TAG. An application that already registered a certificate under that tag with tls_credential_add() does not need to call this.

Parameters

cert	DER or PEM encoded certificate. It is not copied, so it must remain valid for as long as https downloads are performed.
len	Size of `cert` in bytes.

Returns: 0 on success, negative errno code on failure.

◆ fota_http_tls_add_client_cert()

int fota_http_tls_add_client_cert	(	const void *	cert,
		size_t	cert_len,
		const void *	key,
		size_t	key_len )

#include <zephyr/mgmt/fota_http.h>

Register a client certificate and key for mutual TLS.

Both are stored under CONFIG_FOTA_HTTP_TLS_SEC_TAG and are not copied.

Parameters

cert	DER or PEM encoded client certificate.
cert_len	Size of `cert` in bytes.
key	DER or PEM encoded private key.
key_len	Size of `key` in bytes.

Returns: 0 on success, negative errno code on failure.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ fota_http_done_cb_t

◆ fota_http_progress_cb_t

Function Documentation

◆ fota_http_apply()

◆ fota_http_cancel()

◆ fota_http_confirm()

◆ fota_http_confirm_pending()

◆ fota_http_download()

◆ fota_http_download_async()

◆ fota_http_get_download_slot()

◆ fota_http_get_image_header()

◆ fota_http_nvm_bytes_written()

◆ fota_http_tls_add_ca()

◆ fota_http_tls_add_client_cert()