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.

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

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.

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

Public Members

const uint8_t pmk[16]

Primary master key

bool forward_enable

Forward when packets are received

bool forward_switch_channel

Forward data packet with exchange channel

bool sec_enable

Encrypt ESP-NOW data payload when send and decrypt when receive

uint8_t reserved1

Reserved

uint8_t qsize

Size of packet buffer queue

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 forword

bool group

Enable or disable group

bool provisoning

Enable or disable provisoning

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

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

uint16_t retransmit_count

Too many packet retransmissions will lead to network congestion

uint8_t forward_ttl

Number of hops in data transfer

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

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

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_RESERVED

Reserved for other function

enumerator ESPNOW_DATA_TYPE_MAX