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

Note

STATUS replies are matched on the unauthenticated source address (see the espnow_set_key note), so a replayed STATUS frame can mark a device as finished or stopped. The result is a progress indication, not proof of installation: verify the running version on each responder and rerun for any device that did not update. A replayed STATUS frame cannot change what a responder installs.

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.

Note

The responder installs any image that passes the OTA security check (CONFIG_ESPNOW_OTA_SECURITY) and the header check; it does not verify the project name, the header check only rejects the version that is already running, and the initiator’s address list is not an authorization. The library does not verify image authenticity: a deployment using espnow_ota must enable Secure Boot v2, Flash Encryption and CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK. OTA frames can be replayed like any other frame (see the espnow_set_key note): a recorded session can reinstall a different older image while its secure_version is still accepted (the running image is rejected by hash, an equal version only when skip_version_check is false), so increment secure_version with every release. Replaying STATUS frames of two different images in turn erases the update partition once per CONFIG_ESPNOW_OTA_RESTART_MIN_INTERVAL_MS. All devices sharing one application key form a single trust domain; use a distinct key per product line.

Note

Recommended usage: the responder runs only during an upgrade. Start it when an upgrade is expected, refuse to start if esp_secure_boot_enabled() is false, and afterwards call espnow_ota_responder_stop() followed by espnow_set_config_for_data_type(ESPNOW_DATA_TYPE_OTA_DATA, false, NULL) (stop alone leaves the handler registered). Leaving the responder running for the whole uptime is not recommended: the replays above then remain possible at any time.

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_LEGACY_DATA_LEN

Firmware subcontract upgrade.

OTA chunk sizes are pinned to the legacy 230-byte budget so frames remain byte-compatible with esp-now <= v2.5.3 and fit in the uint8_t espnow_ota_packet_t::size field. The wider ESP-NOW v2 frame budget benefits general application traffic; OTA does not require it and preserves interoperability with older responders by keeping the legacy sizing.

ESPNOW_OTA_PROGRESS_MAX_SIZE

Maximum length of the array which indicates the packet processed

ESPNOW_OTA_PACKET_MAX_SIZE

Maximum length of a single packet transmitted Max OTA firmware the responder accepts, set via menuconfig (CONFIG_ESPNOW_OTA_FIRMWARE_SIZE_MAX, default 4 MB; set to the OTA partition size). Packets needed for it (ceil, matching the initiator’s count).

ESPNOW_OTA_PACKET_MAX_NUM

Whole ESPNOW_OTA_PROGRESS_MAX_SIZE-byte chunks of progress bitmap needed to track those packets. progress_array rows are that size and are reported one whole chunk at a time, so the byte count is rounded up to whole chunks.

ESPNOW_OTA_PROGRESS_CHUNK_NUM
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