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.

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 bind frame will be processed if the callback function returns true and wait time is not timeout, and bind frame’s RSSI is higher than the set RSSI.

Attention

The responder will bind or unbind with the sender according to the value in bind frame.

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.

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]

NULL terminated 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.

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