Provisioning API

Provisioning layer related APIs for ESP-NOW.

API Reference

Header File

• src/provisioning/include/espnow_prov.h

Functions

esp_err_t espnow_prov_initiator_scan(espnow_addr_t responder_addr, espnow_prov_responder_t *responder_info, wifi_pkt_rx_ctrl_t *rx_ctrl, TickType_t wait_ticks)

Initiator scans provision beacon.

Parameters:

• responder_addr – [out] mac address of responder

• responder_info – [out] information of responder

• rx_ctrl – [out] received packet radio metadata header

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

Returns:

• ESP_OK

• ESP_ERR_INVALID_ARG

esp_err_t espnow_prov_initiator_send(const espnow_addr_t responder_addr, const espnow_prov_initiator_t *initiator_info, espnow_prov_cb_t cb, TickType_t wait_ticks)

Initiator sends information to request WiFi configuration.

Parameters:

• responder_addr – [in] mac address of responder

• initiator_info – [in] information of initiator

• cb – [in] WiFi configuration callback function

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

Returns:

• ESP_OK

• ESP_ERR_WIFI_TIMEOUT

• ESP_ERR_INVALID_ARG

esp_err_t espnow_prov_responder_start(const espnow_prov_responder_t *responder_info, TickType_t wait_ticks, const espnow_prov_wifi_t *wifi_config, espnow_prov_cb_t cb)

Responder starts to send provision beacon, receives initiator request and send WiFi configuration.

Parameters:

• responder_info – [in] information of responder

• wait_ticks – [in] provision beacon sending time in ticks

• wifi_config – [in] WiFi configuration information

• cb – [in] initiator information callback function

Returns:

• ESP_OK

• ESP_ERR_INVALID_ARG

Structures

struct espnow_prov_initiator_s

Initiator information.

Public Members

char product_id[16]

Product ID

char device_name[16]

Device name

espnow_prov_auth_mode_t auth_mode

Authentication mode of provisioning

char device_secret[32]

Device security key

char product_secret[32]

Product security key

char cert_secret[32]

Certify security key

uint8_t custom_size

Customer data size

uint8_t custom_data[0]

Customer data

struct espnow_prov_responder_s

Responder information.

Public Members

char product_id[16]

Product ID

char device_name[16]

Device name

struct espnow_prov_wifi_s

WiFi configuration.

Public Members

wifi_mode_t mode

WiFi mode

wifi_ap_config_t ap

Configuration of AP

wifi_sta_config_t sta

Configuration of STA

char token[32]

Token of the WiFi configuration

uint8_t custom_size

Customer data size

uint8_t custom_data[0]

Customer data

Macros

ESPNOW_PROV_CUSTOM_MAX_SIZE

Type Definitions

typedef struct espnow_prov_initiator_s espnow_prov_initiator_t

Initiator information.

typedef struct espnow_prov_responder_s espnow_prov_responder_t

Responder information.

typedef struct espnow_prov_wifi_s espnow_prov_wifi_t

WiFi configuration.

typedef esp_err_t (*espnow_prov_cb_t)(uint8_t *src_addr, void *data, size_t size, wifi_pkt_rx_ctrl_t *rx_ctrl)

The provision data callback function.

Attention

If it is WiFi configuration callback function, the data buffer stores WiFi configuration.

Attention

If it is initiator information callback function, the data buffer stores initiator information. Initiator information should be checked in the function. If the function returns true, responder will send WiFi configuration to initiator. If the function returns false, responder will not send WiFi configuration to initiator.

Param src_addr:

[in] mac address of sender

Param data:

[in] WiFi configuration from responder or initiator information from initiator

Param size:

[in] data size

Param rx_ctrl:

[in] received packet radio metadata header

Return:

• ESP_OK

• ESP_ERR_INVALID_ARG

Enumerations

enum espnow_prov_auth_mode_t

Enumerated list of provision authentication mode.

Values:

enumerator ESPNOW_PROV_AUTH_INVALID

Invalid mode

enumerator ESPNOW_PROV_AUTH_PRODUCT

Product authentication

enumerator ESPNOW_PROV_AUTH_DEVICE

Device authentication

enumerator ESPNOW_PROV_AUTH_CERT

Certificate authentication