这是最新(主)开发分支的文档。如果您正在查找以前版本的文档，使用左侧的下拉菜单选择所需的版本。

OTA_OPS API 参考

Macros

OTA_FW_HEADER_SIZE_IN_BIN

Firmware header size in binary: 64 bytes

OTA_SIZE_UNKNOWN

Unknown new image size

OTA_WITH_SEQUENTIAL_WRITES

Unknown size, incremental erase possible

Enumerations

enum wm_ota_ops_compress_type_t

Values:

enumerator WM_OTA_OPS_COMPRESS_NONE

No compression

enumerator WM_OTA_OPS_COMPRESS_XZ

xz compression

enumerator WM_OTA_OPS_COMPRESS_MAX
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

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

struct wm_img_attr_t::[anonymous] bits
uint32_t val

The raw value of the image attribute

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

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_addr

Address of the application partition

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

Address of the data written to the OTA partition

wm_ota_header_t ota_header

OTA Header containing metadata about the firmware image

wm_drv_crc_cfg_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.

This function is used to determine the location and size of the OTA (Over-The-Air) partitions before performing an OTA upgrade, and it then stores this information in the OTA operation context structure.

参数:

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

返回:

  • 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.

This function is used to initialize the resources and state necessary for OTA (Over-The-Air) updates, which includes erasing the required flash memory areas and preparing to receive new firmware data.

备注

Determine whether a full erase of the OTA partition is necessary based on the image_size value:

  • 0 or OTA_SIZE_UNKNOWN: Perform a full erase of the ‘app_ota’ partition.

  • OTA_WITH_SEQUENTIAL_WRITES: No need to erase now; the erase will occur during the subsequent write process.

  • Actual image size: Erase the ‘app_ota’ partition to match the actual size of the image.

参数:

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

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

返回:

  • 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.

This function is used to write firmware data into the device’s flash memory during the OTA (Over-The-Air) update process, handling necessary sector erasure and performing CRC verification to ensure the integrity and consistency of the data.

参数:

  • 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.

返回:

  • 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.

This function is used to complete the final step of the OTA (Over-The-Air) process, with its primary task being to verify the newly written firmware image to ensure its integrity and executability.

参数:

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

返回:

  • 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.

This function is used to trigger a system reboot in order to apply an OTA (Over-The-Air) update. It is called in the final stage of the OTA update process, after the new firmware has been successfully written to the device’s flash memory and verified, to restart the device.

返回:

  • 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.

The function is used to terminate the current OTA (Over-The-Air) operation. When an error occurs during the OTA upgrade process or the user wishes to cancel the ongoing upgrade, this function can clear all information in the OTA context structure and reset the OTA status.

参数:

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

返回:

  • 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 of the currently running firmware.

This function is used to obtain the version number of the firmware that is currently running on the device. It copies the version string to the provided character array.

参数:

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

返回:

  • WM_ERR_SUCCESS: Successfully retrieved the current firmware version.

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