OTA Service

[中文]

OTA service can upgrade firmware over the air (OTA). The firmware can be fetched from local files or the network.

Application Example

Implementation of this API is demonstrated in the following example:

Header File

Functions

periph_service_handle_t ota_service_create(ota_service_config_t *config)

Create the OTA service instance.

Parameters

config – configuration of the OTA service

Returns

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

Parameters

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

Returns

  • 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

Parameters

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

Parameters

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

Parameters

  • handle – [in] pointer to upgrade handle

  • buf – [in] pointer to receive buffer

  • wanted_size – [in] bytes to read

Returns

  • 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

Parameters

  • handle – [in] pointer to upgrade handle

  • buf – [in] pointer to data buffer

  • size – [in] bytes to write

Returns

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

Parameters

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)

Parameters

version – [in] pointer to the string of version

Returns

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

Note

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.

Parameters

ota_config – [in] pointer to esp_fs_ota_config_t structure.

Returns

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

Parameters

  • 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

Returns

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

Parameters

fs_ota_handle – [in] pointer to esp_fs_ota_handle_t structure

Returns

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

Note

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

Parameters

fs_ota_handle – [in] pointer to esp_fs_ota_handle_t structure

Returns

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

Note

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

Parameters

  • 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

Returns

  • 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

Provide feedback about this document