ESPNOW API
espnow commissioning related APIs for ESP-NOW.
API Reference
Header File
Functions
-
ESP_EVENT_DECLARE_BASE(ESP_EVENT_ESPNOW)
Declaration of the task events family.
-
esp_err_t espnow_add_peer(const espnow_addr_t addr, const uint8_t *lmk)
When used for unicast, add the target device.
- Parameters:
addr – [in] peer MAC address
lmk – [in] peer local master key that is used to encrypt data. It can be null or ESP_NOW_KEY_LEN length data
-
esp_err_t espnow_del_peer(const espnow_addr_t addr)
When used for unicast, delete the target device.
- Parameters:
addr – [in] MAC address
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_send(espnow_data_type_t type, const espnow_addr_t dest_addr, const void *data, size_t size, const espnow_frame_head_t *frame_config, TickType_t wait_ticks)
Send ESP-NOW data.
Note
With sec_enable set, the payload is encrypted only if frame_config->security is true. A frame head without the bit is sent in plaintext without error, and so is a NULL frame_config: ESPNOW_FRAME_CONFIG_DEFAULT leaves the bit clear whatever CONFIG_ESPNOW_*_SECURITY is set to. Always pass a frame head with security set for data that must be encrypted.
- Parameters:
type – [in] ESP-NOW data type defined by espnow_data_type_t
dest_addr – [in] destination mac address
data – [in] the sending data which must not be NULL
size – [in] the maximum length of data, must be no more than ESPNOW_DATA_LEN
frame_config – [in] if frame_config is NULL, Use ESPNOW_FRAME_CONFIG_DEFAULT configuration
wait_ticks – [in] the maximum sending time in ticks
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
ESP_ERR_TIMEOUT
ESP_ERR_WIFI_TIMEOUT
-
esp_err_t espnow_deinit(void)
De-initialize ESP-NOW function.
- Returns:
ESP_OK
ESP_ERR_ESPNOW_NOT_INIT
-
esp_err_t espnow_init(const espnow_config_t *config)
Initialize ESP-NOW function.
- Parameters:
config – [in] configuration of ESP-NOW
- Returns:
ESP_OK
ESP_FAIL
-
esp_err_t espnow_get_config(espnow_config_t *config)
Get the configuration ESP-NOW was initialized with.
- Parameters:
config – [out] copy of the configuration passed to espnow_init()
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
ESP_ERR_ESPNOW_NOT_INIT
-
esp_err_t espnow_set_config_for_data_type(espnow_data_type_t type, bool enable, handler_for_data_t handle)
Set configuration when receiving the corresponding ESP-NOW data type Include: Set to enable/disable handling the corresponding ESP-NOW data type Set the callback function when receiving the corresponding ESP-NOW data type.
- Parameters:
type – [in] data type defined by espnow_data_type_t
enable – [in] enable or disable the receive of data type, false - disable, true - enable
handle – [in] the receive callback function for data type
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_get_config_for_data_type(espnow_data_type_t type, bool *enable)
Get the configuration that whether to handle the corresponding ESP-NOW data type.
- Parameters:
type – [in] data type defined by espnow_data_type_t
enable – [out] store the current receiving status of this data type
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_set_security_required_for_data_type(espnow_data_type_t type, bool required)
Set whether frames of a data type must arrive encrypted when sec_enable is on.
With sec_enable set, a plaintext frame of a required type is dropped before the receive callback, which cannot tell a forged plaintext frame from an encrypted one. Built-in types default to their CONFIG_ESPNOW_*_SECURITY option; DATA and RESERVED default to required. ACK, FORWARD, GROUP and SECURITY* are plaintext by design.
Note
The drop only happens when CONFIG_ESPNOW_SEC_REJECT_PLAINTEXT is enabled (default n, recommended y). Without it this setting is recorded but has no effect and plaintext frames of every type are accepted.
Note
May be called from any task. Calls for different data types do not affect each other’s setting; for one data type the last call wins.
- Parameters:
type – [in] data type defined by espnow_data_type_t
required – [in] true - drop plaintext frames of this type, false - accept them
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_get_security_required_for_data_type(espnow_data_type_t type, bool *required)
Get whether frames of a data type must arrive encrypted when sec_enable is on.
- Parameters:
type – [in] data type defined by espnow_data_type_t
required – [out] current setting for this data type
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_add_group(const espnow_group_t group_id)
Set group ID addresses.
- Parameters:
group_id – [in] pointer to new group ID addresses
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_del_group(const espnow_group_t group_id)
Delete group ID addresses.
- Parameters:
group_id – [in] pointer to deleted group ID address
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
int espnow_get_group_num(void)
Get the number of group ID addresses.
- Returns:
the number of group ID addresses
-
esp_err_t espnow_get_group_list(espnow_group_t *group_id_list, size_t num)
Get group ID addresses.
- Parameters:
group_id_list – [out] pointer to group ID addresses
num – [in] the number of group ID addresses
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
bool espnow_is_my_group(const espnow_group_t group_id)
Check whether the specified group address is my group.
- Parameters:
group_id – [in] pointer to the specified group ID addresses
- Returns:
true/false
-
esp_err_t espnow_set_group(const espnow_addr_t *addrs_list, size_t addrs_num, const espnow_group_t group_id, espnow_frame_head_t *frame_head, bool enable, TickType_t wait_ticks)
Dynamically set the grouping of devices through commands.
Note
GROUP frames are plaintext and unauthenticated, because devices must be grouped before any key is distributed. Any device in range can change group membership, and can evict an application group once the list is full; this exposes no data and grants no control, but it interrupts the current and later group traffic until membership is restored. Do not use membership for access control. Recommended usage: configure groups locally with espnow_add_group() and clear receive_enable.group so no GROUP frame is processed. Over-the-air grouping is a commissioning convenience; keeping it enabled afterwards is not recommended, and an application that does must resend membership before each group session and fall back to unicast.
- Parameters:
addrs_list – [in] MAC address list of the grouping devices
addrs_num – [in] number of the grouping devices
group_id – [in] pointer to the specified group ID addresses
frame_head – [in] use ESPNOW_FRAME_CONFIG_DEFAULT configuration if frame_config is NULL
enable – [in] true: add group, false: delete group
wait_ticks – [in] the maximum sending time in ticks
- Returns:
ESP_OK
ESP_ERR_INVALID_ARG
-
esp_err_t espnow_set_key(uint8_t key_info[APP_KEY_LEN])
Set the security key info The security key info is used to derive key and stored to flash. The derived key is used to encrypt ESP-NOW data payload when send and decrypt ESP-NOW data payload when receive.
These are design limitations of the frame format: the 32-entry duplicate cache is filled before authentication and is not anti-replay, and the AEAD has no associated data, so a ciphertext of one type is accepted under another. Recommended usage: application data carries a type tag and a monotonic counter or receiver challenge inside the encrypted payload and rejects stale values (see handler_for_data_t); no irreversible action is triggered from a single frame; the key is rotated (new handshake) to invalidate recordings. The built-in protocols are designed for uses where a replay is harmless or the receive window is closed; see the recommended usage in the espnow_config_t note.
- Attention
Set sec_enable in espnow_config to true when ESP-NOW initializes, or the function will return failed.
ESP_OK
ESP_ERR_INVALID_ARG
Note
Encryption covers the payload only and there is no anti-replay (random IV). The outer type, magic, source and destination address are not authenticated: a device without the key can record an encrypted frame, rewrite them (including the source address) and replay it. The key proves who created a payload, not who sent this frame. Put sender identity and a sequence number inside the payload where either matters, and prefer absolute values over relative ones.
- Parameters:
key_info – [in] security key info
-
esp_err_t espnow_get_key(uint8_t key_info[APP_KEY_LEN])
Get the security key info stored in flash If no security key info is stored in flash, the function will return failed.
ESP_OK
ESP_ERR_INVALID_ARG
Note
The key is stored in NVS in plaintext and is shared by the whole trust domain: enable Flash Encryption, and re-key when a device is lost.
- Parameters:
key_info – [out] security key info
-
esp_err_t espnow_erase_key(void)
Erase the security key info stored in flash.
ESP_OK
ESP_ERR_NVS_NOT_FOUND
-
esp_err_t espnow_set_dec_key(uint8_t key_info[APP_KEY_LEN])
Set the security key info The security key info is used to derive key and stored to flash. The derived key is used to encrypt ESP-NOW data payload when send and decrypt ESP-NOW data payload when receive.
ESP_OK
ESP_ERR_INVALID_ARG
- Attention
Set sec_enable in espnow_config to true when ESP-NOW initializes, or the function will return failed.
- Parameters:
key_info – [in] security key info
-
esp_err_t espnow_get_dec_key(uint8_t key_info[APP_KEY_LEN])
Get the security key info stored in flash If no security key info is stored in flash, the function will return failed.
ESP_OK
ESP_ERR_INVALID_ARG
- Parameters:
key_info – [out] security key info
-
esp_err_t espnow_erase_dec_key(void)
Erase the security key info stored in flash.
ESP_OK
ESP_ERR_NVS_NOT_FOUND _cplusplus
Structures
-
struct espnow_config_t
Initialize the configuration of espnow.
Recommended security configuration; without all of it the library provides no authentication:
sec_enable set and the key handshake completed before protected traffic;
CONFIG_ESPNOW_ALL_SECURITY, or CONFIG_ESPNOW_*_SECURITY for every protected type;
CONFIG_ESPNOW_SEC_REJECT_PLAINTEXT and CONFIG_ESPNOW_SEC_IGNORE_REST;
forward_enable cleared unless unauthenticated multi-hop relay is needed;
a non-public, random PoP with enough entropy to be unpredictable, per deployment or per device, provisioned to both sides over a trusted channel, never the examples’ public espnow_pop: the PoP is the only secret protecting the application key. Use at least ESPNOW_SEC_POP_RECOMMENDED_LEN random characters;
the handshake run as a commissioning step and every node verified afterwards (see the espnow_sec_initiator_start note);
espnow_sec_initiator_start called only with the addresses of responders that the application has approved. An address can be spoofed, so this narrows the handshake but does not replace the PoP;
Flash Encryption (the application key is stored in NVS in plaintext), plus Secure Boot v2 and CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK when espnow_ota is used;
the ESP-NOW debug console disabled (espnow_console_config_t monitor_command.espnow cleared);
log level at most INFO (DEBUG prints the key); espnow_log flash level above ERROR while a handshake can run, and CONFIG_ESPNOW_DEBUG_LOG_FLASH_ERASE_MIN_INTERVAL_MS set non-zero (default 0; rejected frames produce log lines and only the rotation floor bounds flash wear).
Design limitations and recommended usage. ESP-NOW frames have no sequence number and the header is not authenticated, so a recorded frame can be replayed and its type or source address rewritten (espnow_set_key note); GROUP and ACK are plaintext by design (espnow_set_group and espnow_frame_head_t notes). The recommended usage within these limits:
application data carries its own type tag and counter in the payload;
built-in protocols are used only for what they are designed for: espnow_ctrl for reversible convenience control, espnow_time for non-security time, groups configured locally, ACK as a transport hint;
every receive window (handshake, bind, OTA, provisioning request and reply, time sync) is open only for the operation it serves, on an explicit action, and closed afterwards; a recorded encrypted frame can be replayed without the key, so an open window is the exposure. Using the library outside this usage (for example unlock or alarm control over espnow_ctrl, a handshake responder left running after commissioning, over-the-air grouping outside commissioning) is not recommended and is not protected.
The recommended security configuration is both parts of this note, the build options and the usage. The examples, including examples/solution, are lab demos that implement neither (plaintext defaults, public PoP, handlers registered for the whole uptime, no token or counter checks); building one with the options above does not make it the recommended configuration. Behaviour reproduced on an example is a property of the example, not of the library under the recommended configuration.
Note
ESP-NOW does not authenticate the sender address. The library only verifies possession of the application key (AES128-CCM on the payload), so a plaintext data type accepts frames from any device in range and all key holders form one trust domain. There is no anti-replay; see the espnow_set_key note.
Public Members
-
const uint8_t pmk[16]
Primary master key
-
bool forward_enable
Forward when packets are received. A broadcast frame is relayed before it is decrypted or authenticated, bounded by forward_ttl and retransmit_count, so any device in range can make the network repeat a frame. Clear it when multi-hop relay is not needed.
-
bool forward_switch_channel
Forward data packet with exchange channel
-
bool sec_enable
Enable ESP-NOW data payload encryption when send and decryption when receive. It encrypts nothing by itself: a frame is encrypted only when it is sent with a frame head that has security set (see the espnow_send note). With CONFIG_ESPNOW_SEC_REJECT_PLAINTEXT (recommended) plaintext frames of types built with CONFIG_ESPNOW_*_SECURITY, DATA and RESERVED are rejected; see espnow_set_security_required_for_data_type().
-
uint8_t reserved1
Reserved
-
uint8_t qsize
Size of packet buffer queue. A received frame takes one entry to be handled by this device and one more to be forwarded. A frame that needs both while only one is free is handled and not forwarded, so use at least 2 together with forward_enable.
-
uint8_t send_retry_num
Number of retransmissions
-
uint32_t send_max_timeout
Maximum timeout
-
bool ack
Enable or disable ACK
-
bool forward
Enable or disable forward
-
bool group
Enable or disable group
-
bool provisioning
Enable or disable provisioning
-
bool control_bind
Enable or disable control bind
-
bool control_data
Enable or disable control data
-
bool ota_status
Enable or disable OTA status
-
bool ota_data
Enable or disable OTA data
-
bool debug_log
Enable or disable debug LOG
-
bool debug_command
Enable or disable debug command
-
bool data
Enable or disable data
-
bool sec_status
Enable or disable security status
-
bool sec
Enable or disable security
-
bool sec_data
Enable or disable security data
-
bool timesync
Enable or disable time synchronization
-
uint32_t reserved2
Reserved
-
struct espnow_config_t::[anonymous] receive_enable
Set 1 to enable receiving the corresponding ESP-NOW data type
-
struct espnow_frame_head_s
Frame header of espnow.
Public Members
-
uint16_t magic
Unique identifier of each packet. Packets with the same identifier will be filtered. 0: a random number
-
uint8_t channel
Set the channel where the packet is sent, ESPNOW_CHANNEL_CURRENT or ESPNOW_CHANNEL_ALL
-
bool filter_adjacent_channel
Because ESP-NOW is sent through HT20, it can receive packets from adjacent channels
-
bool filter_weak_signal
When the signal received by the receiving device is lower than forward_rssi, frame_head data will be discarded
-
bool security
The payload data is encrypted if security is true
-
uint16_t __pad0__
Reserved
-
bool broadcast
Configure broadcast.
Packet sent in broadcast mode or unicast mode
-
bool group
Only the group set as broadcast transmission mode is valid
-
bool ack
Wait for the receiving device to return ack to ensure transmission reliability. ACK frames are plaintext and matched on magic only: they signal delivery, not that the peer holds the key. By design a forged ACK (the magic is readable) can stop retransmission; ACK is a transport hint only. Using it as an application-level confirmation is not recommended: require a secured application reply when delivery matters.
-
uint16_t retransmit_count
Too many packet retransmissions will lead to network congestion
-
uint8_t forward_ttl
Remaining hops; decremented on every forward, dropped at 0
-
int8_t forward_rssi
When the data packet signal received by the receiving device is lower than forward_rssi, it will not be transferred, in order to avoid network congestion caused by packet transfer
-
uint16_t magic
Macros
-
ESPNOW_PACKED_STRUCT
< _cplusplus
-
ESPNOW_PAYLOAD_LEN
-
ESPNOW_DATA_LEN
-
ESPNOW_ADDR_LEN
-
ESPNOW_ADDR_IS_EMPTY(addr)
-
ESPNOW_ADDR_IS_BROADCAST(addr)
-
ESPNOW_ADDR_IS_SELF(addr)
-
ESPNOW_ADDR_IS_EQUAL(addr1, addr2)
-
ESP_EVENT_ESPNOW_PROV_BASE
-
ESP_EVENT_ESPNOW_CTRL_BASE
-
ESP_EVENT_ESPNOW_OTA_BASE
-
ESP_EVENT_ESPNOW_DEBUG_BASE
-
ESP_EVENT_ESPNOW_TIMESYNC_BASE
-
ESP_EVENT_ESPNOW_RESERVED_BASE
-
ESPNOW_CHANNEL_CURRENT
The channel on which the device sends packets.
Only in the current channel
-
ESPNOW_CHANNEL_ALL
All supported channels
-
ESPNOW_RETRANSMIT_MAX_COUNT
Maximum number of retransmissions
-
ESPNOW_FORWARD_MAX_COUNT
Maximum number of forwards
-
ESPNOW_INIT_CONFIG_DEFAULT()
-
ESPNOW_FRAME_CONFIG_DEFAULT()
Type Definitions
-
typedef uint8_t espnow_addr_t[6]
-
typedef uint8_t espnow_group_t[6]
-
typedef struct espnow_frame_head_s espnow_frame_head_t
Frame header of espnow.
-
typedef esp_err_t (*handler_for_data_t)(uint8_t *src_addr, void *data, size_t size, wifi_pkt_rx_ctrl_t *rx_ctrl)
ESP-NOW data receive callback function for the corresponding data type.
Note
src_addr and the data type come from the unauthenticated header, even for an encrypted frame (see the espnow_set_key note): never authorize on src_addr alone, start every encrypted payload with its own type tag, and check tag and length before using any field.
- Param src_addr:
[in] peer MAC address
- Param data:
[in] received data
- Param size:
[in] length of received data
- Param rx_ctrl:
[in] received packet radio metadata header
- Return:
ESP_OK
ESP_ERR_INVALID_ARG
Enumerations
-
enum espnow_data_type_t
Divide ESP-NOW data into multiple pipes.
Values:
-
enumerator ESPNOW_DATA_TYPE_ACK
For reliable data transmission
-
enumerator ESPNOW_DATA_TYPE_FORWARD
Set to forward packets
-
enumerator ESPNOW_DATA_TYPE_GROUP
Send a packet that sets the group type
-
enumerator ESPNOW_DATA_TYPE_PROV
Network configuration packet
-
enumerator ESPNOW_DATA_TYPE_CONTROL_BIND
Binding or unbinding packet
-
enumerator ESPNOW_DATA_TYPE_CONTROL_DATA
Control data packet
-
enumerator ESPNOW_DATA_TYPE_OTA_STATUS
Status packet for rapid upgrade of batch Device
-
enumerator ESPNOW_DATA_TYPE_OTA_DATA
Data packet for rapid upgrade of batch Device
-
enumerator ESPNOW_DATA_TYPE_DEBUG_LOG
Equipment debugging log packet
-
enumerator ESPNOW_DATA_TYPE_DEBUG_COMMAND
Equipment debugging command packet
-
enumerator ESPNOW_DATA_TYPE_DATA
User-defined use
-
enumerator ESPNOW_DATA_TYPE_SECURITY_STATUS
Security status packet
-
enumerator ESPNOW_DATA_TYPE_SECURITY
Security handshake packet
-
enumerator ESPNOW_DATA_TYPE_SECURITY_DATA
Security packet
-
enumerator ESPNOW_DATA_TYPE_TIMESYNC
Time synchronization packet
-
enumerator ESPNOW_DATA_TYPE_RESERVED
Reserved for other function
-
enumerator ESPNOW_DATA_TYPE_MAX
-
enumerator ESPNOW_DATA_TYPE_ACK