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 (protocomm protocomm_req_handler_t) using protocomm_add_endpoint()

Structures

struct wifi_prov_sta_conn_info_t

WiFi STA connected status information.

Public Members

char ip_addr[IP4ADDR_STRLEN_MAX]

IP Address received by station

char bssid[6]

BSSID of the AP to which connection was estalished

char ssid[33]

SSID of the to which connection was estalished

uint8_t channel

Channel of the AP

uint8_t auth_mode

Authorization mode of the AP

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 is WIFI_STATION_DISCONNECTED)

wifi_prov_sta_conn_info_t conn_info

Connection information (valid only when wifi_state is WIFI_STATION_CONNECTED)

struct wifi_prov_config_set_data_t

WiFi config data received by slave during set_config request from master.

Public Members

char ssid[33]

SSID of the AP to which the slave is to be connected

char password[64]

Password of the AP

char bssid[6]

BSSID of the AP

uint8_t channel

Channel of the AP

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 calling protocomm_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 when get_status_handler is invoked again by the master.

wifi_prov_ctx_t *ctx

Context pointer to be passed to above handler functions upon invocation

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 calling protocomm_add_endpoint().

Enumerations

enum wifi_prov_sta_state_t

WiFi STA status for conveying back to the provisioning master.

Values:

WIFI_PROV_STA_CONNECTING
WIFI_PROV_STA_CONNECTED
WIFI_PROV_STA_DISCONNECTED
enum wifi_prov_sta_fail_reason_t

WiFi STA connection fail reason.

Values:

WIFI_PROV_STA_AUTH_ERROR
WIFI_PROV_STA_AP_NOT_FOUND