OTA 服务

[English]

OTA 服务 (OTA service) 提供对固件进行 OTA 的功能，支持从本地文件、网络获取固件进行升级。

应用示例

以下示例展示了该 API 的实现方式。

Header File

Functions

periph_service_handle_t ota_service_create(ota_service_config_t *config)

Create the OTA service instance.

参数

config – configuration of the OTA service

返回

  • NULL: Failed

  • Others: Success

esp_err_t ota_service_set_upgrade_param(periph_service_handle_t handle, ota_upgrade_ops_t *list, int list_len)

Configure the upgrade parameter This function is not thread safe.

This function will set the parameter table to ota service, and the ota service will upgrade the partitions defined in the table one by one,

参数

  • handle – [in] pointer to ‘periph_service_handle_t’ structure

  • list – [in] pointer to ‘ota_upgrade_ops_t’ structure

  • list_len – [in] length of the ‘list’

返回

  • ESP_OK: Success

  • Others: Failed

Structures

struct ota_service_config_t

The OTA service configuration.

Public Members

int task_stack

>0 Service task stack; =0 with out task created

int task_prio

Service task priority (based on freeRTOS priority)

int task_core

Service task running in core (0 or 1)

periph_service_cb evt_cb

Service callback function

void *cb_ctx

Callback context

struct ota_node_attr_t

The OTA node attributions.

Public Members

esp_partition_type_t type

Partition type

char *label

Partition label

char *uri

The upgrade URL

char *cert_pem

SSL server certification, PEM format as string, if the client requires to verify server

struct ota_upgrade_ops_t

The upgrade operation.

Public Members

ota_node_attr_t node

The OTA node

ota_service_err_reason_t (*prepare)(void **handle, ota_node_attr_t *node)

Functions ready for upgrade

ota_service_err_reason_t (*need_upgrade)(void *handle, ota_node_attr_t *node)

Detect whether an upgrade is required

ota_service_err_reason_t (*execute_upgrade)(void *handle, ota_node_attr_t *node)

For execute upgrade

ota_service_err_reason_t (*finished_check)(void *handle, ota_node_attr_t *node, ota_service_err_reason_t result)

Check result of upgrade

bool reboot_flag

Reboot or not after upgrade

bool break_after_fail

Abort upgrade when got failed

struct ota_result_t

The result of the OTA upgrade.

Public Members

uint8_t id

The result ID

ota_service_err_reason_t result

The error reason

Macros

OTA_SERVICE_ERR_REASON_BASE
OTA_SERVICE_DEFAULT_CONFIG()

Enumerations

enum ota_service_event_type_t

The OTA service event type.

Values:

enumerator OTA_SERV_EVENT_TYPE_RESULT
enumerator OTA_SERV_EVENT_TYPE_FINISH
enum ota_service_err_reason_t

The OTA service error reasons.

Values:

enumerator OTA_SERV_ERR_REASON_UNKNOWN
enumerator OTA_SERV_ERR_REASON_SUCCESS
enumerator OTA_SERV_ERR_REASON_NULL_POINTER
enumerator OTA_SERV_ERR_REASON_URL_PARSE_FAIL
enumerator OTA_SERV_ERR_REASON_ERROR_VERSION
enumerator OTA_SERV_ERR_REASON_NO_HIGHER_VERSION
enumerator OTA_SERV_ERR_REASON_ERROR_MAGIC_WORD
enumerator OTA_SERV_ERR_REASON_ERROR_PROJECT_NAME
enumerator OTA_SERV_ERR_REASON_FILE_NOT_FOUND
enumerator OTA_SERV_ERR_REASON_PARTITION_NOT_FOUND
enumerator OTA_SERV_ERR_REASON_PARTITION_WT_FAIL
enumerator OTA_SERV_ERR_REASON_PARTITION_RD_FAIL
enumerator OTA_SERV_ERR_REASON_STREAM_INIT_FAIL
enumerator OTA_SERV_ERR_REASON_STREAM_RD_FAIL
enumerator OTA_SERV_ERR_REASON_GET_NEW_APP_DESC_FAIL

Header File

Functions

void ota_app_get_default_proc(ota_upgrade_ops_t *ops)

get the default process of app partition upgrade

参数

ops – [in] pointer to ota_upgrade_ops_t structure

void ota_data_get_default_proc(ota_upgrade_ops_t *ops)

get the default process of data partition upgrade

参数

ops – [in] pointer to ota_upgrade_ops_t structure

ota_service_err_reason_t ota_data_image_stream_read(void *handle, char *buf, int wanted_size)

read from the stream of upgrading

参数

  • handle – [in] pointer to upgrade handle

  • buf – [in] pointer to receive buffer

  • wanted_size – [in] bytes to read

返回

  • OTA_SERV_ERR_REASON_SUCCESS: Success

  • Others: Failed

ota_service_err_reason_t ota_data_partition_write(void *handle, char *buf, int size)

write to the data partition under upgrading

参数

  • handle – [in] pointer to upgrade handle

  • buf – [in] pointer to data buffer

  • size – [in] bytes to write

返回

  • OTA_SERV_ERR_REASON_SUCCESS: Success

  • Others: Failed

void ota_data_partition_erase_mark(void *handle)

Indicates that the ota partition has been erased By default, this part of flash will be erased during ota. If the behavior of erasing is called in applition, this API needs to be called.

参数

handle – [in] pointer to upgrade handle

int ota_get_version_number(char *version)

Convert string of version to integer The version should be (V0.0.0 - V255.255.255)

参数

version – [in] pointer to the string of version

返回

  • -1: Failed

  • Others: version number

Header File

Functions

esp_err_t esp_fs_ota(esp_fs_ota_config_t *ota_config)

Upgrade the firmware from filesystem.

备注

This API handles the entire OTA operation, so if this API is being used then no other APIs from esp_fs_ota component should be called. If more information and control is needed during the FS OTA process, then one can use esp_fs_ota_begin and subsequent APIs. If this API returns successfully, esp_restart() must be called to boot from the new firmware image.

参数

ota_config – [in] pointer to esp_fs_ota_config_t structure.

返回

  • ESP_OK: OTA data updated, next reboot will use specified partition.

  • ESP_FAIL: For generic failure.

  • ESP_ERR_INVALID_ARG: Invalid argument

  • ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image

  • ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation.

  • ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed.

  • For other return codes, refer OTA documentation in esp-idf’s app_update component.

esp_err_t esp_fs_ota_begin(esp_fs_ota_config_t *ota_config, esp_fs_ota_handle_t *handle)

Start FS OTA Firmware upgrade.

This function initializes ESP FS OTA context and open the firmware file. This function must be invoked first. If this function returns successfully, then esp_fs_ota_perform should be called to continue with the OTA process and there should be a call to esp_fs_ota_finish on completion of OTA operation or on failure in subsequent operations.

参数

  • ota_config – [in] pointer to esp_fs_ota_config_t structure

  • handle – [out] pointer to an allocated data of type esp_fs_ota_handle_t which will be initialised in this function

返回

  • ESP_OK: FS OTA Firmware upgrade context initialised and file opened successful

  • ESP_FAIL: For generic failure.

  • ESP_ERR_INVALID_ARG: Invalid argument (missing/incorrect config, etc.)

  • For other return codes, refer documentation in app_update component and esp_http_client component in esp-idf.

esp_err_t esp_fs_ota_perform(esp_fs_ota_handle_t fs_ota_handle)

Read image data from file stream and write it to OTA partition.

This function reads image data from file stream and writes it to OTA partition. This function must be called only if esp_fs_ota_begin() returns successfully. This function must be called in a loop since it returns after every file read operation thus giving you the flexibility to stop OTA operation midway.

参数

fs_ota_handle – [in] pointer to esp_fs_ota_handle_t structure

返回

  • ESP_ERR_FS_OTA_IN_PROGRESS: OTA update is in progress, call this API again to continue.

  • ESP_OK: OTA update was successful

  • ESP_FAIL: OTA update failed

  • ESP_ERR_INVALID_ARG: Invalid argument

  • ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image

  • ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation.

  • ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed.

  • For other return codes, refer OTA documentation in esp-idf’s app_update component.

esp_err_t esp_fs_ota_finish(esp_fs_ota_handle_t fs_ota_handle)

Clean-up FS OTA Firmware upgrade and close the file stream.

This function closes the file stream and frees the ESP FS OTA context. This function switches the boot partition to the OTA partition containing the new firmware image.

备注

If this API returns successfully, esp_restart() must be called to boot from the new firmware image

参数

fs_ota_handle – [in] pointer to esp_fs_ota_handle_t structure

返回

  • ESP_OK: Clean-up successful

  • ESP_ERR_INVALID_STATE

  • ESP_ERR_INVALID_ARG: Invalid argument

  • ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image

esp_err_t esp_fs_ota_get_img_desc(esp_fs_ota_handle_t fs_ota_handle, esp_app_desc_t *new_app_info)

Reads app description from image header. The app description provides information like the “Firmware version” of the image.

备注

This API can be called only after esp_fs_ota_begin() and before esp_fs_ota_perform(). Calling this API is not mandatory.

参数

  • fs_ota_handle – [in] pointer to esp_fs_ota_handle_t structure

  • new_app_info – [out] pointer to an allocated esp_app_desc_t structure

返回

  • ESP_ERR_INVALID_ARG: Invalid arguments

  • ESP_FAIL: Failed to read image descriptor

  • ESP_OK: Successfully read image descriptor

int esp_fs_ota_get_image_len_read(esp_fs_ota_handle_t fs_ota_handle)

Structures

struct esp_fs_ota_config_t

ESP FS OTA configuration.

Public Members

const char *path

file path

const int buffer_size

Size of buffer

Macros

ESP_ERR_FS_OTA_BASE
ESP_ERR_FS_OTA_IN_PROGRESS

Type Definitions

typedef void *esp_fs_ota_handle_t

提供有关此文档的反馈