Provisioning API
Provisioning layer related APIs for ESP-NOW.
API Reference
Header File
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.
Note
The WIFI reply is accepted from any address, not only responder_addr: a device in range that answers first can hand the initiator its own Wi-Fi credentials. Without CONFIG_ESPNOW_PROV_SECURITY the reply is plaintext and cannot be told apart. To provision only from trusted responders, run the security handshake first and enable CONFIG_ESPNOW_PROV_SECURITY with CONFIG_ESPNOW_SEC_REJECT_PLAINTEXT, so that only a key holder can produce a reply that is accepted.
Note
Design limitation: the WIFI reply is not bound to the request, so a reply recorded earlier, even encrypted, can be replayed into a later window without the key. It carries the credentials valid at recording time: nothing is disclosed, but the initiator can be handed an old network or password. Recommended usage: call this only on an explicit user action with a short wait_ticks, never automatically after a connection failure; the responder puts a provisioning generation in wifi_config->token, incremented whenever the credentials change, and the initiator’s cb returns an error for a reply that is not newer (the window then stays open); credentials that fail to connect are not stored. Within this usage a replay can only delay one provisioning run.
Note
cb runs in the ESP-NOW task. A reply counts only for the call whose cb accepted it, and only if cb returned ESP_OK before that call ended. A cb that is still running when the call times out is not interrupted: the call returns an error, the result of cb is discarded and does not complete a following call, which waits for a reply accepted by its own cb. What cb itself did with the configuration (stored it, started a connection) is not undone, so keep cb short compared to wait_ticks.
- 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.
Note
cb is the authentication point: wifi_config is sent to every initiator for which it returns ESP_OK, and the request’s source address is not authenticated. A NULL cb approves every request, so any device in range receives the credentials; the application must register a callback. Without CONFIG_ESPNOW_PROV_SECURITY the WIFI reply is also plaintext; to keep the credentials confidential, run the security handshake first and provision only key holders (CONFIG_ESPNOW_PROV_SECURITY encrypts the frames; plaintext requests are only rejected with CONFIG_ESPNOW_SEC_REJECT_PLAINTEXT). The examples keep both options off and are lab demos only.
Note
The initiator’s DEVICE frame (including device_secret / product_secret / cert_secret) is plaintext, so a static secret in those fields is readable and replayable by any device in range, so cb cannot authenticate on them. Approve in cb only during a user-triggered window, for a bounded number of devices, with a short wait_ticks.
Note
Calling this again while a session is running replaces wifi_config and cb and extends the window. A request that the previous cb was authenticating at that moment is not answered (its approval applied to the previous credentials, not the new ones); the initiator retries. Likewise a request still being authenticated when the window expires gets no reply.
- 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
-
char product_id[16]
-
struct espnow_prov_responder_s
Responder information.
-
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. Not checked by the library; see espnow_prov_initiator_send()
-
uint8_t custom_size
Customer data size
-
uint8_t custom_data[0]
Customer data
-
wifi_mode_t mode
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
-
enumerator ESPNOW_PROV_AUTH_INVALID