Wi-Fi Provisioning¶
Overview¶
This component provides protocomm endpoint handler - wifi_prov_config_data_handler - and related protobuf framework which can be used for Wi-Fi configuration in the context of device provisioning, though it may be used in non-provisioning cases as well.
- The configuration consists of three commands :
- get_status - For querying the Wi-Fi connection status
- set_config - For setting the Wi-Fi connection credentials
- apply_config - For applying the credentials saved during set_config and (re)start the Wi-Fi station
The way this is supposed to work is that the desired Wi-Fi configuration for the ESP32, which is to run as a station and thus connect to an AP with certain credentials, is to be sent during set_config. Then apply_config is supposed to start (or restart) the Wi-Fi in station mode with the previously set AP credentials. Afterwords, get_config command is used to probe the device continuously for Wi-Fi connection status, to ensure that the connection was indeed successful. If the connection failed, then appropriate status code along with disconnection reason, is to be conveyed through get_config.
Application Example¶
esp_err_t get_status_handler(wifi_prov_config_get_data_t *resp_data, wifi_prov_ctx_t **ctx) { /* Fill the wifi_prov_config_get_data_t structure * with Wi-Fi station connection status information. */ return ESP_OK; } esp_err_t set_config_handler(const wifi_prov_config_set_data_t *req_data, wifi_prov_ctx_t **ctx) { /* Copy contents of req_data->ssid and req_data->password * which are Wi-Fi AP credentials to which the device will connect */ return ESP_OK; } esp_err_t apply_config_handler(wifi_prov_ctx_t **ctx) { /* Apply the Wi-Fi STA credentials saved during set_config */ return ESP_OK; } /* Structure with various config command handlers to be passed * as private data during endpoint registration with protocomm */ wifi_prov_config_handlers_t wifi_prov_handlers = { .get_status_handler = get_status_handler, .set_config_handler = set_config_handler, .apply_config_handler = apply_config_handler, .ctx = NULL }; /* Set the endpoint handler */ protocomm_add_endpoint(pc, "wifi_config_endpoint", wifi_prov_config_data_handler, (void *) &wifi_prov_handlers);
API Reference¶
Functions¶
-
esp_err_t
wifi_prov_config_data_handler
(uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen, void *priv_data)¶ Handler for receiving and responding to requests from master.
This is to be registered as the
wifi_config
endpoint handler (protocommprotocomm_req_handler_t
) usingprotocomm_add_endpoint()
Structures¶
-
struct
wifi_prov_sta_conn_info_t
¶ WiFi STA connected status information.
-
struct
wifi_prov_config_get_data_t
¶ WiFi status data to be sent in response to
get_status
request from master.Public Members
-
wifi_prov_sta_state_t
wifi_state
¶ WiFi state of the station
-
wifi_prov_sta_fail_reason_t
fail_reason
¶ Reason for disconnection (valid only when
wifi_state
isWIFI_STATION_DISCONNECTED
)
-
wifi_prov_sta_conn_info_t
conn_info
¶ Connection information (valid only when
wifi_state
isWIFI_STATION_CONNECTED
)
-
wifi_prov_sta_state_t
-
struct
wifi_prov_config_set_data_t
¶ WiFi config data received by slave during
set_config
request from master.
-
struct
wifi_prov_config_handlers
¶ Internal handlers for receiving and responding to protocomm requests from master.
This is to be passed as priv_data for protocomm request handler (refer to
wifi_prov_config_data_handler()
) when callingprotocomm_add_endpoint()
.Public Members
-
esp_err_t (*
get_status_handler
)(wifi_prov_config_get_data_t *resp_data, wifi_prov_ctx_t **ctx)¶ Handler function called when connection status of the slave (in WiFi station mode) is requested
-
esp_err_t (*
set_config_handler
)(const wifi_prov_config_set_data_t *req_data, wifi_prov_ctx_t **ctx)¶ Handler function called when WiFi connection configuration (eg. AP SSID, password, etc.) of the slave (in WiFi station mode) is to be set to user provided values
-
esp_err_t (*
apply_config_handler
)(wifi_prov_ctx_t **ctx)¶ Handler function for applying the configuration that was set in
set_config_handler
. After applying the station may get connected to the AP or may fail to connect. The slave must be ready to convey the updated connection status information whenget_status_handler
is invoked again by the master.
-
wifi_prov_ctx_t *
ctx
¶ Context pointer to be passed to above handler functions upon invocation
-
esp_err_t (*
Type Definitions¶
-
typedef struct wifi_prov_ctx
wifi_prov_ctx_t
¶ Type of context data passed to each get/set/apply handler function set in
wifi_prov_config_handlers
structure.This is passed as an opaque pointer, thereby allowing it be defined later in application code as per requirements.
-
typedef struct wifi_prov_config_handlers
wifi_prov_config_handlers_t
¶ Internal handlers for receiving and responding to protocomm requests from master.
This is to be passed as priv_data for protocomm request handler (refer to
wifi_prov_config_data_handler()
) when callingprotocomm_add_endpoint()
.