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
struct	ota_target_handler_t
struct	ota_image_version_t Represents the version number information of an OTA image.
struct	ota_server_t Represents an OTA (Over-The-Air) server.
struct	ota_t Represents an Over-The-Air (OTA) update.
enum	ota_protocol_t Enumeration for OTA (Over-The-Air) protocol types.
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
int	ota_download(ota_t * ota)
int	ota_register_target_handler(int update_target_id, ota_target_handler_t * hnd) Registers an update target handler.

Defines

Name
OTA_MAX_UPDATE_TARGETS	maximum number of external targets for firmware updates
OTA_FLG_IDLE	no OTA is currently active
OTA_FLG_SUCCEEDED	a firmware update was downloaded and installed successfully
OTA_FLG_FAILED	the firmware update failed
OTA_FLG_FAILED_CONNECT	a connection to the update server could not be established
OTA_FLG_FAILED_UPDATE_RUNNING	a firmware update was requested, while another update already was running
OTA_FLG_FAILED_FLASH	an error occured during firmware update while writing to the flash
OTA_FLG_FAILED_IMAGE_TOO_BIG	the update to be installed is too big for the available flash space
OTA_FLG_FAILED_UNSUP_ALGO	the signature/checksum algorithm requested is not suported.
OTA_FLG_FAILED_CHECKSUM	the firmware checksum didn't match the one provided with the update-request
OTA_FLG_FAILED_REMAINING_BYTES	the download process finished before all expected bytes could be downloaded
OTA_FLG_FAILED_TIMEOUT	a timeout occured while downloading the firmware update
OTA_FLG_FAILED_SIGNATURE	the firmware wasn't signed by a trusted fota server
OTA_FLG_FAILED_TARGET	the target isn't supported
OTA_FLG_FAILED_RESOLVE_HOST	couldn't resolve hostname
OTA_FLG_FAILED_METADATA	metadata is missing relevant information
OTA_FLG_UPDATE_STARTED	a firmware update was started and is currently executing
OTA_FLG_PENDING_UPDATE	a firmware update was donwloaded but not yet installed or activated

Types Documentation

enum ota_protocol_t

Enumerator	Description
OTA_PROTO_TCP	OTA over TCP protocol. (used for broadband connections)
OTA_PROTO_TFTP	OTA over TFTP (Trivial File Transfer Protocol, used for narrowband connections)

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

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_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. The target handler is a structure that contains callbacks to be invoked during the update process for the specific target.

Macros Documentation

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_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

Firmware Updates ​

Types ​

Functions Overview ​

Defines ​

Types Documentation ​

enum ota_protocol_t ​

typedef ota_begin_t ​

typedef ota_append_t ​

typedef ota_finalize_t ​

typedef ota_abort_t ​

typedef ota_context_t ​

Function Details ​

function ota_download ​

function ota_register_target_handler ​

Macros Documentation ​

define OTA_MAX_UPDATE_TARGETS ​

define OTA_FLG_IDLE ​

define OTA_FLG_SUCCEEDED ​

define OTA_FLG_FAILED ​

define OTA_FLG_FAILED_CONNECT ​

define OTA_FLG_FAILED_UPDATE_RUNNING ​

define OTA_FLG_FAILED_FLASH ​

define OTA_FLG_FAILED_IMAGE_TOO_BIG ​

define OTA_FLG_FAILED_UNSUP_ALGO ​

define OTA_FLG_FAILED_CHECKSUM ​

define OTA_FLG_FAILED_REMAINING_BYTES ​

define OTA_FLG_FAILED_TIMEOUT ​

define OTA_FLG_FAILED_SIGNATURE ​

define OTA_FLG_FAILED_TARGET ​

define OTA_FLG_FAILED_RESOLVE_HOST ​

define OTA_FLG_FAILED_METADATA ​

define OTA_FLG_UPDATE_STARTED ​

define OTA_FLG_PENDING_UPDATE ​