OTA API

OTA(Over The Air) layer related APIs for ESP-NOW.

API Reference

Header File

Functions

esp_err_t espnow_ota_initiator_send(const espnow_addr_t *addrs_list, size_t addrs_num, const uint8_t sha_256[ESPNOW_OTA_HASH_LEN], size_t size, espnow_ota_initiator_data_cb_t ota_data_cb, espnow_ota_result_t *res)

Root sends firmware to other nodes.

Attention

Only called at the root

Parameters:

  • addrs_list – [in] destination node mac list

  • addrs_num – [in] number of destination nodes

  • sha_256 – [in] SHA-256 digest for the upgrade partition

  • size – [in] upgrade firmware total size

  • ota_data_cb – [in] upgrade data callback function

  • res – [out] must call espnow_ota_initiator_result_free to free memory

Returns:

  • ESP_OK

  • ESP_ERR_ESPNOW_OTA_FIRMWARE_NOT_INIT

  • ESP_ERR_ESPNOW_OTA_DEVICE_NO_EXIST

esp_err_t espnow_ota_initiator_stop()

Stop root to send firmware to other nodes.

Returns:

  • ESP_OK

  • ESP_ERR_NOT_SUPPORTED

esp_err_t espnow_ota_initiator_result_free(espnow_ota_result_t *result)

Free memory in the result list.

Parameters:

result – [in] pointer to device upgrade status

Returns:

  • ESP_OK

  • ESP_ERR_INVALID_ARG

esp_err_t espnow_ota_initiator_scan(espnow_ota_responder_t **info_list, size_t *num, TickType_t wait_ticks)

Root scans other nodes.

Parameters:

  • info_list – [out] responder information list

  • num – [out] responder number

  • wait_ticks – [in] the maximum scanning time in ticks

Returns:

  • ESP_OK

  • ESP_ERR_INVALID_ARG

esp_err_t espnow_ota_initiator_scan_result_free(void)

Free memory in the responder information list.

Returns:

  • ESP_OK

esp_err_t espnow_ota_responder_get_status(espnow_ota_status_t *status)

Get the status of the upgrade.

Parameters:

status – [out] the status of the upgrade

Returns:

  • ESP_OK

  • ESP_ERR_INVALID_ARG

  • ESP_ERR_NOT_SUPPORTED

esp_err_t espnow_ota_responder_stop()

Stop upgrading.

Returns:

  • ESP_OK

  • ESP_FAIL

esp_err_t espnow_ota_responder_start(const espnow_ota_config_t *config)

Start upgrading.

Parameters:

config – [in] upgrade configuration

Returns:

  • ESP_OK

  • ESP_FAIL _cplusplus

Structures

struct espnow_ota_info_s

Firmware upgrade information.

Public Members

uint8_t type

Packet type

esp_app_desc_t app_desc

Description about application

struct espnow_ota_responder_s

Responder upgrade information.

Public Members

uint8_t mac[6]

Mac address of responder

int8_t rssi

Packet rssi

uint8_t channel

Responder channel

esp_app_desc_t app_desc

Application description of responder

struct espnow_ota_packet_s

Firmware packet.

Public Members

uint8_t type

Type of packet, ESPNOW_OTA_TYPE_DATA

uint16_t seq

Sequence

uint8_t size

Size

uint8_t data[ESPNOW_OTA_PACKET_MAX_SIZE]

Firmware

struct espnow_ota_config_s

Upgrade configuration.

Public Members

bool skip_version_check

Skip checking the running version with the upgrade version

uint8_t progress_report_interval

Percentage interval to save OTA status and report ota status event

struct espnow_ota_status_s

Status packet.

Public Members

uint8_t type

Type of packet, ESPNOW_OTA_TYPE_STATUS

uint8_t sha_256[ESPNOW_OTA_HASH_LEN]

Unique identifier of the firmware

int16_t error_code

Upgrade status

uint16_t packet_num

Identify if each packet of data has been written

uint32_t total_size

Total length of the firmware

uint32_t written_size

The length of the flash has been written

uint8_t progress_index

Identify if each packet of data has been written

uint8_t progress_array[0][ESPNOW_OTA_PROGRESS_MAX_SIZE]

Identify if each packet of data has been written

struct espnow_ota_result_s

List of device status during the upgrade process.

Public Members

size_t unfinished_num

The number of devices to be upgraded

espnow_addr_t *unfinished_addr

MAC address of devices to be upgraded

size_t successed_num

The number of devices that succeeded to upgrade

espnow_addr_t *successed_addr

MAC address of devices that succeeded to upgrade

size_t requested_num

The number of devices that not completed to upgrade

espnow_addr_t *requested_addr

MAC address of devices that not completed to upgrade

Macros

ESPNOW_OTA_HASH_LEN

< _cplusplus

ESP_ERR_ESPNOW_OTA_BASE
ESP_ERR_ESPNOW_OTA_FIRMWARE_NOT_INIT

Upgrade error code definition.

Uninitialized firmware configuration

ESP_ERR_ESPNOW_OTA_FIRMWARE_PARTITION

Partition table error

ESP_ERR_ESPNOW_OTA_FIRMWARE_INVALID

Non-project generated firmware

ESP_ERR_ESPNOW_OTA_FIRMWARE_INCOMPLETE

The firmware received by the device is incomplete

ESP_ERR_ESPNOW_OTA_FIRMWARE_DOWNLOAD

Firmware write flash error

ESP_ERR_ESPNOW_OTA_FIRMWARE_FINISH

The firmware has been written to completion

ESP_ERR_ESPNOW_OTA_DEVICE_NO_EXIST

The device that needs to be upgraded does not exist

ESP_ERR_ESPNOW_OTA_SEND_PACKET_LOSS

Request device upgrade status failed

ESP_ERR_ESPNOW_OTA_NOT_INIT

Upgrade configuration is not initialized

ESP_ERR_ESPNOW_OTA_STOP

Upgrade stops with error

ESP_ERR_ESPNOW_OTA_FINISH

The running firmware has been upgraded

ESP_EVENT_ESPNOW_OTA_STARTED

enumerated list of upgrade event id

The device starts to upgrade

ESP_EVENT_ESPNOW_OTA_STATUS

Proactively report progress

ESP_EVENT_ESPNOW_OTA_FINISH

The upgrade is complete and the new firmware will run after the reboot

ESP_EVENT_ESPNOW_OTA_STOPED

Stop upgrading

ESP_EVENT_ESPNOW_OTA_FIRMWARE_DOWNLOAD

Start writing firmware to flash

ESP_EVENT_ESPNOW_OTA_SEND_FINISH

Send the firmware to other devices to complete

ESPNOW_OTA_PROGRESS_MAX_SIZE

Firmware subcontract upgrade.

Maximum length of the array which indicates the packet processed

ESPNOW_OTA_PACKET_MAX_SIZE

Maximum length of a single packet transmitted

ESPNOW_OTA_PACKET_MAX_NUM

The maximum number of packets

ESPNOW_OTA_GET_BITS(data, bits)

Bit operations to get and modify a bit in an array.

ESPNOW_OTA_SET_BITS(data, bits)
CONFIG_ESPNOW_OTA_SECURITY

Type Definitions

typedef struct espnow_ota_info_s espnow_ota_info_t

Firmware upgrade information.

typedef struct espnow_ota_responder_s espnow_ota_responder_t

Responder upgrade information.

typedef struct espnow_ota_packet_s espnow_ota_packet_t

Firmware packet.

typedef struct espnow_ota_config_s espnow_ota_config_t

Upgrade configuration.

typedef struct espnow_ota_status_s espnow_ota_status_t

Status packet.

typedef struct espnow_ota_result_s espnow_ota_result_t

List of device status during the upgrade process.

typedef esp_err_t (*espnow_ota_initiator_data_cb_t)(size_t src_offset, void *dst, size_t size)

The upgrade data callback function Read firmware data from flash to send to unfinished device.

Param src_offset:

[in] address of the data to be read, relative to the beginning of the partition.

Param dst:

[out] pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least ‘size’ bytes long.

Param size:

[in] size of data to be read, in bytes.

Return:

  • ESP_OK

  • ESP_FAIL

Enumerations

enum espnow_ota_type_t

Type of packet.

Values:

enumerator ESPNOW_OTA_TYPE_REQUEST
enumerator ESPNOW_OTA_TYPE_INFO
enumerator ESPNOW_OTA_TYPE_DATA
enumerator ESPNOW_OTA_TYPE_STATUS