The latest development version of this page may be more current than this released 0.4.3 version.

OTA_OPS API Reference

Macros

FW_HEADER_SIZE_IN_BIN

Firmware header size in binary: 64 bytes

FLASH_SECTOR_SIZE

Flash sector size: 4096 bytes

MAGIC_NO

OTA firmware header magic number

OTA_SIZE_UNKNOWN

Unknown new image size

OTA_WITH_SEQUENTIAL_WRITES

Unknown size, incremental erase possible

Enumerations

enum wm_ota_ops_err_t

Values:

enumerator WM_ERR_OTA_NO_INIT

Error: OTA not initialized

enumerator WM_ERR_OTA_HEADER_INVALID

Error: Invalid OTA header

enumerator WM_ERR_OTA_SAME_VERSION

Error: Version unchanged

enumerator WM_ERR_OTA_CRC_ERROR

Error: CRC error in OTA data

enumerator WM_ERR_OTA_FW_OVERFLOW

Error: Firmware overflow during OTA

enumerator WM_ERR_OTA_TIMEOUT

Error: Timeout occurred during OTA

enumerator WM_ERR_OTA_NO_GOT_IP

Error: No IP address obtained for OTA

enumerator WM_ERR_OTA_CONNECTION_FAILED

Error: Connection failed for OTA

enumerator WM_ERR_OTA_ALREADY_RUNNING

Error: OTA operation already running

enumerator WM_ERR_OTA_SHA256_ECDSA

Error: SHA256-ECDSA verification error

Unions

union wm_img_attr_t

Image attribute union.

This union allows access to image attributes either through individual bitfields or as a whole 32-bit unsigned integer. It includes flags for image type, encryption, private key selection, signature presence, zip type, PSRAM I/O, and reserved bits.

Public Members

struct wm_img_attr_t::img_attr img_attr_t
uint32_t val

The raw value of the image attribute

struct img_attr

Public Members

uint32_t img_type

[3:0] Image type enumeration

uint32_t code_encrypt

[4] Indicates if the code in flash is encrypted

uint32_t prikey_sel

[7:5] Private key selection for encryption

uint32_t signature

[8] Presence of a 128-byte signature at the end of the image

uint32_t reserved_9

[15:9] Reserved for future use

uint32_t gzip_enable

[16] Enable gzip compression for the image

uint32_t psram_io

[17] PSRAM I/O configuration

uint32_t erase_block_en

[18] Flash erase block enable bit

uint32_t erase_always

[19] Flash erase always bit

uint32_t compress_type

[21:20] Compression algorithm type, 1:xz

uint32_t reserved_22

[31:22] Reserved for future use

Structures

struct wm_ota_header_t

OTA Header structure.

The OTA Header structure contains various attributes and metadata required for Over-The-Air (OTA) update functionality. It includes image attributes, addresses, lengths, version strings, and checksums.

Public Members

uint32_t magic_no

Magic number to identify the OTA image

wm_img_attr_t img_attr

Bitfields for image attributes

uint32_t img_addr

Address where the image will be executed

uint32_t img_len

Length of the binary image in bytes

uint32_t img_header_addr

Address of the image header

uint32_t upgrade_img_addr

Address of the upgrade image

uint32_t org_checksum

Original checksum of the image for verification

uint32_t upd_no

Update number for version tracking

unsigned char ver[16]

Version string, 16 bytes long

uint32_t _reserved0

Reserved for future use

uint32_t _reserved1

Reserved for future use

struct wm_ota_header_t *next

Pointer to the next header for a possible linked list

uint32_t hd_checksum

Checksum of the header for integrity verification

struct wm_ota_ops_ctx_t

OTA Operations Context structure.

The `wm_ota_ops_ctx_t` structure holds the context information required for performing Over-The-Air (OTA) updates. It includes the application size, OTA addresses, flags indicating erase needs, OTA header, and CRC context for data integrity verification.

Public Members

uint32_t app_size

Size of the application partition

uint32_t app_ota_addr

Address in flash where the OTA image is stored

uint32_t app_ota_size

Size of the OTA partition

uint32_t need_erase

Flag indicating if the flash needs to be erased before writing

uint32_t wrote_addr

Addr of the data written to the OTA partition

wm_ota_header_t ota_header

OTA Header containing metadata about the firmware image

psCrcContext_t crc_ctx

CRC context used for calculating the checksum of the OTA data

Functions

int wm_ota_ops_get_ota_partition(wm_ota_ops_ctx_t *wm_ota_ops_ctx)

Retrieve the partition information for the OTA update.

Parameters:

wm_ota_ops_ctx – [in] Pointer to the OTA context structure.

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_INVALID_PARAM: invalid argument

  • WM_ERR_FAILED: failed to find the partition

int wm_ota_ops_begin(wm_ota_ops_ctx_t *wm_ota_ops_ctx, size_t image_size)

Begin the OTA update process.

Parameters:

  • wm_ota_ops_ctx – [in] Pointer to the OTA context structure.

  • image_size – [in] The size of the OTA image in bytes.

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_INVALID_PARAM: invalid argument

  • WM_ERR_FAILED: failed to erase the flash

int wm_ota_ops_write(wm_ota_ops_ctx_t *wm_ota_ops_ctx, const uint8_t *data, uint32_t size)

Write data to the OTA partition.

Parameters:

  • wm_ota_ops_ctx – [in] Pointer to the OTA context structure.

  • data – [in] Pointer to the data buffer to be written.

  • size – [in] Size of the data buffer in bytes.

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_INVALID_PARAM: invalid argument

  • Other error codes based on the underlying flash write operation

int wm_ota_ops_end(wm_ota_ops_ctx_t *wm_ota_ops_ctx)

Finalize the OTA update process and verify the integrity of the written data.

Parameters:

wm_ota_ops_ctx – [in] Pointer to the OTA context structure.

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_INVALID_PARAM: invalid argument

  • WM_ERR_OTA_CRC_ERROR: CRC error indicating data corruption

int wm_ota_ops_reboot(void)

Reboot the system to apply the OTA update.

Returns:

  • WM_ERR_SUCCESS: succeed

  • Other error codes based on the underlying system reset operation

int wm_ota_ops_abort(wm_ota_ops_ctx_t *wm_ota_ops_ctx)

Abort the OTA update process and clean up the OTA context.

Parameters:

wm_ota_ops_ctx – [in] Pointer to the OTA context structure to be cleared.

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_INVALID_PARAM: invalid argument if wm_ota_ops_ctx is NULL

int wm_ota_ops_get_version(char *version)

Retrieves the version information for the OTA update.

This function is used to obtain the version number of the current build configuration. It copies the version string to the provided character array.

Parameters:

version – [out] Pointer to a character array where the version number will be stored.

Returns:

  • WM_ERR_SUCCESS: Successfully retrieved the version information.

  • WM_ERR_INVALID_PARAM: If the provided version pointer is NULL, this error code is returned.