Skip to content

Per-HW firmware-update tracking ​

Hooks libcoldwave into the coldwave-os OTA target callbacks so it can publish per-slot FU-state on the device service. Slot 0 is always libcoldwave's own SW-OTA — slots 1..(COLDWAVE_HW_SLOTS_MAX-1) are subprocessor targets that the integrator wires up. If libcoldwave is not registered for a slot, the application is free to call ota_register_target_handler itself for that slot.

Types ​

Name
structcw_hw_ota_target_t
typedef int(*)(void *ctx)cw_hw_ota_begin_t
typedef int(*)(void *ctx, const uint8_t *data, size_t size)cw_hw_ota_append_t
typedef int(*)(void *ctx)cw_hw_ota_finalize_t
typedef int(*)(void *ctx)cw_hw_ota_abort_t

Functions Overview ​

Name
intcoldwave_register_hw_ota_target(const cw_hw_ota_target_t * t)
intcoldwave_hw_ota_job(uint8_t slot, cw_hw_ota_job_t * out)
intcoldwave_hw_set_unit_info(uint8_t slot, const char * hw_id, const char * fw_version)

Defines ​

Name
COLDWAVE_HW_OTA_TARGET_SELECT

Types Documentation ​

typedef cw_hw_ota_begin_t ​

cpp
typedef int(* cw_hw_ota_begin_t) (void *ctx);

Append callback signature mirrors ota_append_t from <ota/ota.h> but is kept stand-alone here to avoid leaking the ota.h types into coldwave.h.

typedef cw_hw_ota_append_t ​

cpp
typedef int(* cw_hw_ota_append_t) (void *ctx, const uint8_t *data, size_t size);

typedef cw_hw_ota_finalize_t ​

cpp
typedef int(* cw_hw_ota_finalize_t) (void *ctx);

typedef cw_hw_ota_abort_t ​

cpp
typedef int(* cw_hw_ota_abort_t) (void *ctx);

Function Details ​

function coldwave_register_hw_ota_target ​

cpp
int coldwave_register_hw_ota_target(
    const cw_hw_ota_target_t * t
)

Return: CW_OK on success, CW_ERR_INVALID_ARG for bad slot/target, CW_ERR_NOT_INITIALIZED if libcoldwave is not yet initialized.

Registers a wrapping target handler with the OS so libcoldwave observes state transitions (DOWNLOADING/INSTALLING/SUCCESS/FAILED) for the given slot. The integrator's callbacks in t are invoked verbatim — libcoldwave only sniffs the lifecycle around them. Calling this for slot 0 is rejected with CW_ERR_INVALID_ARG.

function coldwave_hw_ota_job ​

cpp
int coldwave_hw_ota_job(
    uint8_t slot,
    cw_hw_ota_job_t * out
)

Return: CW_OK, CW_ERR_INVALID_ARG for a bad slot or null out, CW_ERR_FAILED while no update is announced for the slot.

A FW_UPDATE for a registered slot arrives as the integrator's callbacks: on_begin (synchronously inside the update request, so it has to return within the flake timeout), on_append for the stream, then on_finalize, or on_abort after any failure or cancel. Callbacks return 0 on success. The device neither stages an image nor reboots; the handler installs the image itself in on_finalize. The slot's FU state (0x21n0..) follows the callbacks; a failing on_begin is recorded as CW_FU_ERR_INCOMPATIBLE, a failing on_append as CW_FU_ERR_FLASH_WRITE and a failing on_finalize as CW_FU_ERR_INSTALL.

The image the running update announced. Valid from on_begin until on_finalize or on_abort has returned.

function coldwave_hw_set_unit_info ​

cpp
int coldwave_hw_set_unit_info(
    uint8_t slot,
    const char * hw_id,
    const char * fw_version
)

Return: CW_OK, CW_ERR_INVALID_ARG for a bad slot, a slot without a registered target or a bad string, CW_ERR_NOT_INITIALIZED before coldwave_init() has completed.

Publishes hardware id and firmware version of a registered unit (P_HW_UNITn_ID_STR / P_HW_UNITn_FW_VERSION_STR) and reports the version as the slot's installed FU version. Call again whenever the version changes, e.g. after an update. A null hw_id or fw_version leaves that value as it is; given strings must be 1..CW_HW_UNIT_STR_MAX-1 characters.

Macros Documentation ​

define COLDWAVE_HW_OTA_TARGET_SELECT ​

cpp
#define COLDWAVE_HW_OTA_TARGET_SELECT 1

Defined when the library selects the receiving unit from the FW_UPDATE parameter P_OTA_TARGET and offers the two calls below. Integrators that must build against older SDK drops test for it.