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.
-
struct espnow_ota_responder_s
Responder upgrade information.
-
struct espnow_ota_packet_s
Firmware packet.
-
struct espnow_ota_config_s
Upgrade configuration.
-
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
-
uint8_t type
-
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
-
size_t unfinished_num
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