Control API

Control layer related APIs for ESP-NOW.

API Reference

Header File

Functions

esp_err_t espnow_ctrl_initiator_bind(espnow_attribute_t initiator_attribute, bool enable)

The initiator sends a broadcast bind frame.

Parameters:
  • initiator_attribute – [in] initiator attribute

  • enable – [in] bind or unbind

Returns:

  • TRUE

  • FALSE

esp_err_t espnow_ctrl_initiator_send(espnow_attribute_t initiator_attribute, espnow_attribute_t responder_attribute, uint32_t responder_value)

The initiator sends a broadcast control data frame.

Note

Design limitation: control frames carry no sequence number and can be replayed even when encrypted (see the espnow_set_key note). espnow_ctrl is designed for reversible convenience control (lights, switches, levels) where a replayed command repeats a visible, reversible state the user can undo. Recommended usage: absolute attributes (the *_ADD attributes accumulate on replay), an idempotent responder callback that also rate limits state changes (for example one per second; per responder, since src_addr is not authenticated, see espnow_ctrl_responder_data), and the bind window closed after binding (see espnow_ctrl_responder_bind). Within this usage a replay has no persistent effect: it repeats a reversible state only while the attacker keeps transmitting, writes nothing to flash, discloses nothing and cannot unbind the initiator. Driving unlock, arm/disarm, OTA triggers, credential changes or any action that must not repeat from espnow_ctrl is not recommended and not protected; carry such commands in an application DATA frame with a counter.

Parameters:
  • initiator_attribute – [in] the sending initiator’s attribute

  • responder_attribute – [in] the sending responder’s attribute

  • responder_value – [in] the sending responder value

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_responder_bind(uint32_t wait_ms, int8_t rssi, espnow_ctrl_bind_cb_t cb)

The responder creates a bind task to process the received bind frame.

Attention

The wait time, RSSI threshold and callback gate binding only. An unbind frame matching an entry in the bind list is accepted at any time and written to flash immediately.

Attention

The bind list is matched on the outer source address, which is never authenticated (see the espnow_set_key note). Without CONFIG_ESPNOW_CONTROL_SECURITY anyone can create a control frame in a bound initiator’s name; with it, a device without the key can still replay a captured frame with that address.

Attention

Recommended usage: binding is a user-triggered step. The CONTROL_BIND handler stays registered after wait_ms, so a replayed unbind frame is accepted at any time; this is the only persistent effect a replayed control frame can have, and it is removed by closing the window: after the bind window call espnow_set_config_for_data_type(ESPNOW_DATA_TYPE_CONTROL_BIND, false, NULL) and manage the list with espnow_ctrl_responder_*_bindlist. Reopen only on a user action with a short wait_ms and an RSSI threshold; leaving the bind handler registered permanently is not recommended.

Parameters:
  • wait_ms – [in] maximum waiting bind time in millisecond

  • rssi – [in] the minimum bind frame RSSI

  • cb – [in] the bind callback function

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_responder_data(espnow_ctrl_data_cb_t cb)

The responder registers control data callback function.

Note

The handler stays registered and the callback has no freshness information, so any frame a bound initiator ever sent can be replayed to it without the key (see espnow_ctrl_initiator_send). Use it only for reversible, idempotent, rate-limited state.

Note

src_addr comes from the outer ESP-NOW header, which is not authenticated (encryption covers the payload only, without associated data), and the bind list is matched on that address. A recorded ciphertext can therefore be re-sent under the address of any other bound initiator with the same attribute, so state kept per src_addr (counters, rate limits) is not a security measure: a counter kept only per src_addr is bypassed by replaying one initiator’s frame under another’s address. Where a repeated command matters, both the sender identity and a monotonic counter must be inside the encrypted payload (for example a custom attribute whose responder_value_s carries “<initiator MAC>:<counter>”), the receiver must keep the counter per that authenticated identity and accept a frame only if the identity equals src_addr (so the bind check applied to it) and the counter is greater than the last one accepted for it. This holds within the shared-key trust domain only: every key holder can create such a payload for any identity. Without this, restrict espnow_ctrl to actions whose replay is harmless.

Parameters:

cb – [in] the control data callback function

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_responder_get_bindlist(espnow_ctrl_bind_info_t *list, size_t *size)

The responder gets bound list.

Parameters:
  • list – [out] the buffer that stores the bound list

  • size – [inout] input maximum bound list size, output the real bound list size

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_responder_set_bindlist(const espnow_ctrl_bind_info_t *info)

The responder sets bound list.

Attention

The bound information will be stored to flash

Parameters:

info – [in] the bound information to be set

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_responder_remove_bindlist(const espnow_ctrl_bind_info_t *info)

The responder removes bound list.

Attention

The bound information will be removed from flash

Parameters:

info – [in] the bound information to be removed

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_responder_clear_bindlist(void)

Remove all bound devices from bindlist.

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_send(const espnow_addr_t dest_addr, const espnow_ctrl_data_t *data, const espnow_frame_head_t *frame_head, TickType_t wait_ticks)

Send control data frame.

Parameters:
  • dest_addr – [in] dest_addr is not used

  • data – [in] control data

  • frame_head – [in] frame header must not be NULL

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

Returns:

  • ESP_OK: succeed

  • others: fail

esp_err_t espnow_ctrl_recv(espnow_ctrl_data_raw_cb_t cb)

The responder registers raw control data callback function.

Parameters:

cb – [in] the raw control data callback function

Returns:

  • ESP_OK: succeed

  • others: fail _cplusplus

Structures

struct espnow_ctrl_bind_info_s

Bind information from initiator.

Public Members

uint8_t mac[6]

Initiator’s MAC address

espnow_attribute_t initiator_attribute

Initiator’s attribute

struct espnow_ctrl_data_s

Control data from initiator.

Public Members

espnow_attribute_t initiator_attribute

Initiator’s attribute

espnow_attribute_t responder_attribute

Responder’s attribute

bool responder_value_b

Boolean

int responder_value_i

Integer

float responder_value_f

Float

uint32_t responder_value_s_flag

String flag, the value is 0x00, 0x00, 0x00

uint8_t responder_value_s_size

String length

char responder_value_s[0]

String value, present when responder_value_s_flag == 0 and responder_value_s_size != 0. In the raw callback it is always responder_value_s_size bytes followed by a NUL. An integer or float with the low 24 bits 0 (0x02000000, 2.0f) has the same header bytes; when the frame does not hold the whole string the value is the one in responder_value_i and these bytes are all 0 (an empty string)

Macros

ESP_EVENT_ESPNOW_CTRL_BIND

Enumerated list of control event id.

< _cplusplus

ESP_EVENT_ESPNOW_CTRL_UNBIND
ESP_EVENT_ESPNOW_CTRL_BIND_ERROR
ESPNOW_BIND_LIST_MAX_SIZE

Maximum number of device in bind list.

Type Definitions

typedef struct espnow_ctrl_bind_info_s espnow_ctrl_bind_info_t

Bind information from initiator.

typedef struct espnow_ctrl_data_s espnow_ctrl_data_t

Control data from initiator.

typedef bool (*espnow_ctrl_bind_cb_t)(espnow_attribute_t initiator_attribute, uint8_t mac[6], int8_t rssi)

The bind callback function.

Attention

Each time a bind frame is received, the callback function will be called.

Param initiator_attribute:

[in] initiator attribute

Param mac:

[in] initiator mac address

Param rssi:

[in] rssi of bind information

Return:

  • TRUE

  • FALSE

typedef void (*espnow_ctrl_data_cb_t)(espnow_attribute_t initiator_attribute, espnow_attribute_t responder_attribute, uint32_t responder_value)

The control data callback function.

Param initiator_attribute:

[in] the received initiator’s attribute

Param responder_attribute:

[in] the received responder’s attribute

Param responder_value:

[in] the received responder value

typedef void (*espnow_ctrl_data_raw_cb_t)(espnow_addr_t src_addr, espnow_ctrl_data_t *data, wifi_pkt_rx_ctrl_t *rx_ctrl)

The raw control data callback function.

Note

data is only valid during the callback and comes without a length. What may be read is fixed by its header:

  • responder_value_s_flag != 0 or responder_value_s_size == 0: the header only; there is no responder_value_s.

  • otherwise: the header, responder_value_s[0 .. responder_value_s_size - 1] and a NUL at responder_value_s[responder_value_s_size]. This holds for every frame, whatever its length on the air. The union has no type tag: an integer or float whose low 24 bits are 0 (0x02000000, 2.0f) has the bytes of a string header and is sent without a string. When the frame does not hold the whole announced string, responder_value_s is all 0 (an empty string) and the value is the one in responder_value_i / responder_value_f. The callback runs on the espnow task. A frame that is shorter than its header announces, or that carries the string without the NUL, is copied to a buffer on that task’s stack first (up to sizeof(espnow_ctrl_data_t) + 256 bytes, no heap allocation); size CONFIG_ESPNOW_TASK_STACK_SIZE for the callback plus that.

Param src_addr:

[in] MAC address of sender

Param data:

[in] control data from sender

Param rx_ctrl:

[in] received packet radio metadata header

Enumerations

enum espnow_attribute_t

Control attribute. The high byte is device type, the low byte is device attribute.

Values:

enumerator ESPNOW_ATTRIBUTE_BASE
enumerator ESPNOW_ATTRIBUTE_POWER
enumerator ESPNOW_ATTRIBUTE_POWER_ADD
enumerator ESPNOW_ATTRIBUTE_ATTRIBUTE

light

enumerator ESPNOW_ATTRIBUTE_LIGHT_BASE
enumerator ESPNOW_ATTRIBUTE_BRIGHTNESS
enumerator ESPNOW_ATTRIBUTE_BRIGHTNESS_ADD
enumerator ESPNOW_ATTRIBUTE_HUE
enumerator ESPNOW_ATTRIBUTE_HUE_ADD
enumerator ESPNOW_ATTRIBUTE_SATURATION
enumerator ESPNOW_ATTRIBUTE_SATURATION_ADD
enumerator ESPNOW_ATTRIBUTE_WARM
enumerator ESPNOW_ATTRIBUTE_WARM_ADD
enumerator ESPNOW_ATTRIBUTE_COLD
enumerator ESPNOW_ATTRIBUTE_COLD_ADD
enumerator ESPNOW_ATTRIBUTE_RED
enumerator ESPNOW_ATTRIBUTE_RED_ADD
enumerator ESPNOW_ATTRIBUTE_GREEN
enumerator ESPNOW_ATTRIBUTE_GREEN_ADD
enumerator ESPNOW_ATTRIBUTE_BLUE
enumerator ESPNOW_ATTRIBUTE_BLUE_ADD
enumerator ESPNOW_ATTRIBUTE_MODE
enumerator ESPNOW_ATTRIBUTE_MODE_ADD

button

enumerator ESPNOW_ATTRIBUTE_BUTTON_BASE
enumerator ESPNOW_ATTRIBUTE_KEY_1
enumerator ESPNOW_ATTRIBUTE_KEY_2
enumerator ESPNOW_ATTRIBUTE_KEY_3
enumerator ESPNOW_ATTRIBUTE_KEY_4
enumerator ESPNOW_ATTRIBUTE_KEY_5
enumerator ESPNOW_ATTRIBUTE_KEY_6
enumerator ESPNOW_ATTRIBUTE_KEY_7
enumerator ESPNOW_ATTRIBUTE_KEY_8
enumerator ESPNOW_ATTRIBUTE_KEY_9
enumerator ESPNOW_ATTRIBUTE_KEY_10

battery

enumerator ESPNOW_ATTRIBUTE_BATTERY_BASE
enumerator ESPNOW_ATTRIBUTE_STATUS_LOW_BATTERY
enumerator ESPNOW_ATTRIBUTE_BATTERY_LEVEL
enumerator ESPNOW_ATTRIBUTE_CHARGING_STATE
enum espnow_ctrl_bind_error_t

Values:

enumerator ESPNOW_BIND_ERROR_NONE
enumerator ESPNOW_BIND_ERROR_TIMEOUT
enumerator ESPNOW_BIND_ERROR_RSSI
enumerator ESPNOW_BIND_ERROR_LIST_FULL