Coldwave Documentation

Appearance

Firmware Updates ​

Over The Air Firmware Update Functions.

Coldwave manages the whole OTA process for the main firmware internally, so you will need these functions only, if you have multiple targets (i.e. separate chips) on your hardware, whose firmware can be updated over the air as well

Types ​

Name
structota_target_handler_t
structota_image_version_t
Represents the version number information of an OTA image.
structota_server_t
Represents an OTA (Over-The-Air) server.
structota_t
Represents an Over-The-Air (OTA) update.
structota_downloader_t
structota_custom_t
Represents an Over-The-Air (OTA) update using a custom download mechanism.
structcw_ota_status_t
Live snapshot of the HW-slot-0 (Coldwave SW-OTA) firmware update.
enumota_protocol_t
Enumeration for OTA (Over-The-Air) protocol types.
typedef uint8_t[(64)]ota_checksum_t
typedef char[(15)+1]ota_checksum_algorithm_t
typedef int(*)(void *p)ota_begin_t
typedef int(*)(void *p, uint8_t const *const data, size_t const size)ota_append_t
typedef int(*)(void *p)ota_finalize_t
typedef int(*)(void *p)ota_abort_t
typedef void *ota_context_t

Functions Overview ​

Name
int8_tota_checksum_algorithm_supported(ota_checksum_algorithm_t const algorithm)
Checks whether the given checksum algorithm is supported.
uint8_tota_checksum_algorithm_digest_length(ota_checksum_algorithm_t const algorithm)
Returns the digest length (in bytes) of the given checksum algorithm.
int8_tota_checksum_match(const unsigned char * data, size_t datalen, ota_checksum_algorithm_t const algorithm, const ota_checksum_t cs)
Verifies that data matches a reference checksum.
voidota_sha1(ota_checksum_t out, char * begin, size_t size)
Computes the SHA-1 digest of a memory region.
voidota_sha256(ota_checksum_t out, char * begin, size_t size)
Computes the SHA-256 digest of a memory region.
intota_download(ota_t * ota)
intota_register_target_handler(int update_target_id, ota_target_handler_t * hnd)
Registers an update target handler.
intota_download_custom(ota_custom_t * ota)
Initiates an OTA download session using a custom OTA configuration structure.
intota_running(void )
Whether a download session currently holds the OTA slot.
intcw_ota_resume_point(uint32_t * size_bytes, uint32_t * committed)
intcw_ota_resume_matches(const uint8_t * cs, uint16_t cs_len, uint32_t size_bytes)
Whether an announced image may continue the recorded prefix.
intcw_ota_confirm(void )
Confirms the currently running firmware image with the bootloader.
intcw_ota_is_confirmed(void )
Queries whether the currently running image is confirmed.
intcw_ota_status_get(cw_ota_status_t * out)
Reads the current OTA status snapshot.

Defines ​

Name
OTA_CHECKSUM_NO_MATCH
OTA_CHECKSUM_UNSUPPORTED_ALGO
OTA_CHECKSUM_ALGO_OK
OTA_CHECKSUM_MATCH
OTA_CHECKSUM_VALUE_SIZE_MAX
OTA_CHECKSUM_ALGORITHM_NAME_STRLEN_MAX
OTA_CHECKSUM_ALGORITHM_SHA1
OTA_SHA1_DIGEST_LENGTH
OTA_CHECKSUM_ALGORITHM_SHA256
OTA_SHA256_DIGEST_LENGTH
OTA_MAX_UPDATE_TARGETSmaximum number of external targets for firmware updates
OTA_FLG_IDLEno OTA is currently active
OTA_FLG_SUCCEEDEDa firmware update was downloaded and installed successfully
OTA_FLG_FAILEDthe firmware update failed
OTA_FLG_FAILED_CONNECTa connection to the update server could not be established
OTA_FLG_FAILED_UPDATE_RUNNINGa firmware update was requested, while another update already was running
OTA_FLG_FAILED_FLASHan error occured during firmware update while writing to the flash
OTA_FLG_FAILED_IMAGE_TOO_BIGthe update to be installed is too big for the available flash space
OTA_FLG_FAILED_UNSUP_ALGOthe signature/checksum algorithm requested is not suported.
OTA_FLG_FAILED_CHECKSUMthe firmware checksum didn't match the one provided with the update-request
OTA_FLG_FAILED_REMAINING_BYTESthe download process finished before all expected bytes could be downloaded
OTA_FLG_FAILED_TIMEOUTa timeout occured while downloading the firmware update
OTA_FLG_FAILED_SIGNATUREthe firmware wasn't signed by a trusted fota server
OTA_FLG_FAILED_TARGETthe target isn't supported
OTA_FLG_FAILED_RESOLVE_HOSTcouldn't resolve hostname
OTA_FLG_FAILED_METADATAmetadata is missing relevant information
OTA_FLG_FAILED_ABORTEDthe running update was cancelled from outside (not a transport fault)
OTA_FLG_UPDATE_STARTEDa firmware update was started and is currently executing
OTA_FLG_PENDING_UPDATEa firmware update was donwloaded but not yet installed or activated
CW_OTA_HAS_RESUME_APIResume point left behind by an interrupted transfer.

Types Documentation ​

enum ota_protocol_t ​

EnumeratorDescription
OTA_PROTO_PLAINOTA over plain TCP w/o protocol. (used for broadband connections)
OTA_PROTO_TFTPOTA over TFTP (Trivial File Transfer Protocol, used for narrowband connections)
OTA_PROTO_HTTPOTA over HTTP.
OTA_PROTO_PLAIN_TLSOTA over plain TLS w/o protocol. (used for broadband connections)
OTA_PROTO_HTTPSOTA over HTTPS.
OTA_PROTO_CUSTOMOTA over implementor provided custom protocol.

Enumeration for OTA (Over-The-Air) protocol types.

typedef ota_checksum_t ​

cpp
typedef uint8_t ota_checksum_t[(64)];

A checksum value type, valid for any supported algorithm. Algorithms with shorter checksums will simply ignore a number of entries at the back of the array.

typedef ota_checksum_algorithm_t ​

cpp
typedef char ota_checksum_algorithm_t[(15)+1];

A fixed-size string type for checksum-algorithm names. It is safer to identify algorithms by name than with an enmeration so we have backwards compatibility between different versions of this library without worrying about preserving and documenting the value of each enum case.

typedef ota_begin_t ​

cpp
typedef int(* ota_begin_t) (void *p);

typedef ota_append_t ​

cpp
typedef int(* ota_append_t) (void *p, uint8_t const  *const data, size_t const size);

typedef ota_finalize_t ​

cpp
typedef int(* ota_finalize_t) (void *p);

typedef ota_abort_t ​

cpp
typedef int(* ota_abort_t) (void *p);

typedef ota_context_t ​

cpp
typedef void* ota_context_t;

Function Details ​

function ota_checksum_algorithm_supported ​

cpp
int8_t ota_checksum_algorithm_supported(
    ota_checksum_algorithm_t const algorithm
)

Checks whether the given checksum algorithm is supported.

Parameters:

  • algorithm Algorithm name, e.g. OTA_CHECKSUM_ALGORITHM_SHA256.

Return: OTA_CHECKSUM_ALGO_OK if supported, OTA_CHECKSUM_UNSUPPORTED_ALGO otherwise.

function ota_checksum_algorithm_digest_length ​

cpp
uint8_t ota_checksum_algorithm_digest_length(
    ota_checksum_algorithm_t const algorithm
)

Returns the digest length (in bytes) of the given checksum algorithm.

Parameters:

  • algorithm Algorithm name, e.g. OTA_CHECKSUM_ALGORITHM_SHA256.

Return: Number of digest bytes used in an ota_checksum_t, or 0 if the algorithm is not supported.

function ota_checksum_match ​

cpp
int8_t ota_checksum_match(
    const unsigned char * data,
    size_t datalen,
    ota_checksum_algorithm_t const algorithm,
    const ota_checksum_t cs
)

Verifies that data matches a reference checksum.

Parameters:

  • data Pointer to the data buffer to verify.
  • datalen Length of data in bytes.
  • algorithm Checksum algorithm to apply.
  • cs Expected reference checksum.

Return: OTA_CHECKSUM_MATCH on match, OTA_CHECKSUM_NO_MATCH on mismatch, or OTA_CHECKSUM_UNSUPPORTED_ALGO if algorithm is not supported.

Computes the digest of the datalen bytes starting at data using algorithm and compares it against cs.

function ota_sha1 ​

cpp
void ota_sha1(
    ota_checksum_t out,
    char * begin,
    size_t size
)

Computes the SHA-1 digest of a memory region.

Parameters:

  • out Output buffer; the first OTA_SHA1_DIGEST_LENGTH bytes receive the digest, remaining bytes are left untouched.
  • begin Pointer to the first byte of the input region.
  • size Size of the input region in bytes.

Deprecated:

SHA-1 is kept only for backward compatibility with pre-2.2.0 images. New image-build tools must use SHA-256.

function ota_sha256 ​

cpp
void ota_sha256(
    ota_checksum_t out,
    char * begin,
    size_t size
)

Computes the SHA-256 digest of a memory region.

Parameters:

  • out Output buffer; the first OTA_SHA256_DIGEST_LENGTH bytes receive the digest, remaining bytes are left untouched.
  • begin Pointer to the first byte of the input region.
  • size Size of the input region in bytes.

function ota_download ​

cpp
int ota_download(
    ota_t * ota
)

Parameters:

  • ota Pointer to the ota_t structure specifying the OTA update details.

Return: 0 if the OTA download was started successfully, otherwise an error code is returned. Possible return values:

  • OTA_FLG_FAILED_TARGET: The specified target is invalid.
  • OTA_FLG_FAILED_UPDATE_RUNNING: An OTA update is already in progress.

Downloads the OTA firmware update.

function ota_register_target_handler ​

cpp
int ota_register_target_handler(
    int update_target_id,
    ota_target_handler_t * hnd
)

Registers an update target handler.

Parameters:

  • update_target_id The ID of the update target.
  • hnd The target handler structure pointer.

Return: 0 on success, -1 if the update target ID is out of range.

This function is used to register a target handler for the given update target ID. This is to update external, secondary MCUs or other ICs with firmware. The target handler ota_target_handler_t is a structure that contains callbacks to be invoked during the update process for the specific target.

function ota_download_custom ​

cpp
int ota_download_custom(
    ota_custom_t * ota
)

Initiates an OTA download session using a custom OTA configuration structure.

Parameters:

  • ota A pointer to an [ota_custom_t](/embed/2.2.0/API/Classes/structota__custom__t.md) structure that contains the custom OTA configuration, including target identification, downloader callbacks, and size of the OTA update.

Return: Returns 0 on success or an error code indicating the failure.

  • OTA_FLG_FAILED_TARGET: Invalid target or missing handler functions.
  • OTA_FLG_FAILED_UPDATE_RUNNING: An existing OTA process is already running.

The function validates the provided input, sets up the OTA session, and starts a new thread for handling the OTA download process. The configuration includes the target information and the downloader callbacks required for communication.

function ota_running ​

cpp
int ota_running(
    void 
)

Whether a download session currently holds the OTA slot.

The slot is single-flight: a second ota_download*() while one runs is refused. Callers that keep their own state around a transfer need to know this BEFORE they touch it — refusing early leaves a running transfer untouched instead of resetting bookkeeping that belongs to it.

function cw_ota_resume_point ​

cpp
int cw_ota_resume_point(
    uint32_t * size_bytes,
    uint32_t * committed
)

function cw_ota_resume_matches ​

cpp
int cw_ota_resume_matches(
    const uint8_t * cs,
    uint16_t cs_len,
    uint32_t size_bytes
)

Whether an announced image may continue the recorded prefix.

Parameters:

  • cs checksum as carried in ota_t::cs — zero-padded to OTA_CHECKSUM_VALUE_SIZE_MAX
  • cs_len used length, or 0 when the update carried no checksum. 0 refuses: an all-zero buffer compares equal to every other all-zero buffer, so treating "absent" as a value would let any image continue any prefix
  • size_bytes announced image size

Return: 1 if the record describes the same image, 0 otherwise. A resume that cannot be verified is refused: continuing a different image splices two firmwares into one, which only the mcuboot signature check catches, one reboot later.

function cw_ota_confirm ​

cpp
int cw_ota_confirm(
    void 
)

Confirms the currently running firmware image with the bootloader.

Return: 0 on success (or already confirmed); nonzero if the confirm could not be written — the image will then revert on the next reset. Always fails on TF-M builds, where image acceptance is handled by PSA Firmware Update instead.

After an OTA update the new image boots in mcuboot test state: unless it is confirmed before the next reset, the bootloader reverts to the previous image. By default Coldwave confirms automatically during kernel boot. When the product is built with CONFIG_OTA_DEFERRED_CONFIRM, confirmation is deferred to a stability milestone instead — either the kernel's automatic uptime/watchdog milestone (CONFIG_OTA_CONFIRM_UPTIME_S, default 420 s) or, if that is set to 0, an explicit call to this function from the application once it considers itself healthy (e.g. after backend attach).

Safe to call from any thread and at any time; repeat calls are no-ops.

function cw_ota_is_confirmed ​

cpp
int cw_ota_is_confirmed(
    void 
)

Queries whether the currently running image is confirmed.

Return: 1 if confirmed (or no update is staged), 0 if the image is still in test state and will revert on the next reset, negative on error (and always on TF-M builds).

function cw_ota_status_get ​

cpp
int cw_ota_status_get(
    cw_ota_status_t * out
)

Reads the current OTA status snapshot.

Parameters:

  • out receives the snapshot; the call is a no-op if out is NULL.

Return: 1 if an OTA has been active since boot, 0 while still idle.

Macros Documentation ​

define OTA_CHECKSUM_NO_MATCH ​

cpp
#define OTA_CHECKSUM_NO_MATCH (-3)

define OTA_CHECKSUM_UNSUPPORTED_ALGO ​

cpp
#define OTA_CHECKSUM_UNSUPPORTED_ALGO (-1)

define OTA_CHECKSUM_ALGO_OK ​

cpp
#define OTA_CHECKSUM_ALGO_OK (0)

define OTA_CHECKSUM_MATCH ​

cpp
#define OTA_CHECKSUM_MATCH (0)

define OTA_CHECKSUM_VALUE_SIZE_MAX ​

cpp
#define OTA_CHECKSUM_VALUE_SIZE_MAX (64)

The maximum size of a checksum, for any algorithm currently used or that might be used in the foreseeable future.

define OTA_CHECKSUM_ALGORITHM_NAME_STRLEN_MAX ​

cpp
#define OTA_CHECKSUM_ALGORITHM_NAME_STRLEN_MAX (15)

The maximum length of a string representing the name of a checksum-algorithm (as given by strlen, i.e. not counting the terminating '\0').

define OTA_CHECKSUM_ALGORITHM_SHA1 ​

cpp
#define OTA_CHECKSUM_ALGORITHM_SHA1 "SHA1"

BEGIN: SHA-1 support — DEPRECATED (collision-anfällig seit SHAttered, 2017). SHA-1 wird nur noch zur Backward-Kompatibilität mit Pre-2.2.0-Images akzeptiert. Neue Image-Build-Tools MÜSSEN SHA-256 als Default schreiben. Identifier string for algorithm SHA-1.

define OTA_SHA1_DIGEST_LENGTH ​

cpp
#define OTA_SHA1_DIGEST_LENGTH (20)

Actual length of a checksum returned from the SHA-1 algorithm. These many bytes at the beginning of the ota_checksum_t array are used, while the remaining bytes are ignored.

define OTA_CHECKSUM_ALGORITHM_SHA256 ​

cpp
#define OTA_CHECKSUM_ALGORITHM_SHA256 "SHA256"

END: SHA-1 support BEGIN: SHA-256 support — bevorzugt seit coldwave-os 2.2.0. Identifier string for algorithm SHA-256.

define OTA_SHA256_DIGEST_LENGTH ​

cpp
#define OTA_SHA256_DIGEST_LENGTH (32)

Actual length of a checksum returned from the SHA-256 algorithm. These many bytes at the beginning of the ota_checksum_t array are used, while the remaining bytes are ignored.

define OTA_MAX_UPDATE_TARGETS ​

cpp
#define OTA_MAX_UPDATE_TARGETS (16)

maximum number of external targets for firmware updates

define OTA_FLG_IDLE ​

cpp
#define OTA_FLG_IDLE (0)

no OTA is currently active

define OTA_FLG_SUCCEEDED ​

cpp
#define OTA_FLG_SUCCEEDED (1)

a firmware update was downloaded and installed successfully

define OTA_FLG_FAILED ​

cpp
#define OTA_FLG_FAILED (2)

the firmware update failed

define OTA_FLG_FAILED_CONNECT ​

cpp
#define OTA_FLG_FAILED_CONNECT (5)

a connection to the update server could not be established

define OTA_FLG_FAILED_UPDATE_RUNNING ​

cpp
#define OTA_FLG_FAILED_UPDATE_RUNNING (6)

a firmware update was requested, while another update already was running

define OTA_FLG_FAILED_FLASH ​

cpp
#define OTA_FLG_FAILED_FLASH (7)

an error occured during firmware update while writing to the flash

define OTA_FLG_FAILED_IMAGE_TOO_BIG ​

cpp
#define OTA_FLG_FAILED_IMAGE_TOO_BIG (8)

the update to be installed is too big for the available flash space

define OTA_FLG_FAILED_UNSUP_ALGO ​

cpp
#define OTA_FLG_FAILED_UNSUP_ALGO (9)

the signature/checksum algorithm requested is not suported.

define OTA_FLG_FAILED_CHECKSUM ​

cpp
#define OTA_FLG_FAILED_CHECKSUM (10)

the firmware checksum didn't match the one provided with the update-request

define OTA_FLG_FAILED_REMAINING_BYTES ​

cpp
#define OTA_FLG_FAILED_REMAINING_BYTES (11)

the download process finished before all expected bytes could be downloaded

define OTA_FLG_FAILED_TIMEOUT ​

cpp
#define OTA_FLG_FAILED_TIMEOUT (12)

a timeout occured while downloading the firmware update

define OTA_FLG_FAILED_SIGNATURE ​

cpp
#define OTA_FLG_FAILED_SIGNATURE (13)

the firmware wasn't signed by a trusted fota server

define OTA_FLG_FAILED_TARGET ​

cpp
#define OTA_FLG_FAILED_TARGET (14)

the target isn't supported

define OTA_FLG_FAILED_RESOLVE_HOST ​

cpp
#define OTA_FLG_FAILED_RESOLVE_HOST (15)

couldn't resolve hostname

define OTA_FLG_FAILED_METADATA ​

cpp
#define OTA_FLG_FAILED_METADATA (16)

metadata is missing relevant information

define OTA_FLG_FAILED_ABORTED ​

cpp
#define OTA_FLG_FAILED_ABORTED (17)

the running update was cancelled from outside (not a transport fault)

define OTA_FLG_UPDATE_STARTED ​

cpp
#define OTA_FLG_UPDATE_STARTED (20)

a firmware update was started and is currently executing

define OTA_FLG_PENDING_UPDATE ​

cpp
#define OTA_FLG_PENDING_UPDATE (0xAA)

a firmware update was donwloaded but not yet installed or activated

define CW_OTA_HAS_RESUME_API ​

cpp
#define CW_OTA_HAS_RESUME_API 1

Resume point left behind by an interrupted transfer.

Parameters:

  • size_bytes out: full size of the image that was being written
  • committed out: bytes known to be in flash (sector-aligned)

Return: 1 if a resumable prefix is on record, 0 otherwise. Marks the OTA API level that carries ota_running() and the cw_ota_resume_* family. libcoldwave's streamed-OTA control plane requires it and refuses to build without it, so a mismatched pair of repos fails at compile time rather than at link time or, worse, silently.

Survives the reset that interrupted it: the written prefix is still in the secondary slot, and this is how far it reaches. Report it to the backend as P_OTA_OFFSET's counterpart so the next attempt continues instead of starting over.