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
-
uint8_t mac[6]
-
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)
-
espnow_attribute_t initiator_attribute
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
datais 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
-
enumerator ESPNOW_ATTRIBUTE_BASE