# Wi-Fi Easy ConnectTM (DPP)

[中文]

Wi-Fi Easy ConnectTM, also known as Device Provisioning Protocol (DPP) or Easy Connect, is a provisioning protocol certified by Wi-Fi Alliance. It is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. With Easy Connect, adding a new device to a network is as simple as scanning a QR Code. This reduces complexity and enhances user experience while onboarding devices without UI like Smart Home and IoT products. Unlike old protocols like Wi-Fi Protected Setup (WPS), Wi-Fi Easy Connect incorporates strong encryption through public key cryptography to ensure networks remain secure as new devices are added.

Easy Connect brings many benefits in the user experience:

> - Simple and intuitive to use; no lengthy instructions to follow for new device setup

> - No need to remember and enter passwords into the device being provisioned

> - Works with electronic or printed QR codes, or human-readable strings

> - Supports both WPA2 and WPA3 networks

Please refer to Wi-Fi Alliance's official page on Easy Connect for more information.

ESP32 supports Enrollee mode of Easy Connect with QR Code as the provisioning method. A display is required to display this QR Code. Users can scan this QR Code using their capable device and provision the ESP32 to their Wi-Fi network. The provisioning device needs to be connected to the AP which need not support Wi-Fi Easy ConnectTM.

Easy Connect is still an evolving protocol. Of known platforms that support the QR Code method are some Android smartphones with Android 10 or higher. To use Easy Connect, no additional App needs to be installed on the supported smartphone.

## Application Examples

- wifi/wifi_easy_connect/dpp-enrollee demonstrates how to configure ESP32 as an enrollee using DPP to securely onboard ESP devices to a network with the help of a QR code and an Android 10+ device.

## API Reference

### Header File

- components/wpa_supplicant/esp_supplicant/include/esp_dpp.h

- This header file can be included with:

  >     #include "esp_dpp.h"

- This header file is a part of the API provided by the `wpa_supplicant` component. To declare that your component depends on `wpa_supplicant`, add the following to your CMakeLists.txt:

  >     REQUIRES wpa_supplicant

  > or

  >     PRIV_REQUIRES wpa_supplicant

### Functions

esp_err_t esp_supp_dpp_init(void)

  Initialize DPP Supplicant.

         Starts DPP Supplicant and initializes related Data Structures.

  return

  - ESP_OK: Success

  - ESP_FAIL: Failure

esp_err_t esp_supp_dpp_deinit(void)

  De-initialize DPP Supplicant.

         Frees memory from DPP Supplicant Data Structures.

  Returns:

    - ESP_OK: Success

esp_err_t esp_supp_dpp_bootstrap_gen(const char *chan_list, esp_supp_dpp_bootstrap_t type, const char *key, const char *info)

  Generates Bootstrap Information as an Enrollee.

         Generates Out Of Band Bootstrap information as an Enrollee which can be
         used by a DPP Configurator to provision the Enrollee.

  Parameters:

    - chan_list -- List of channels device will be available on for listening (must not be NULL)

    - type -- Bootstrap method type, only QR Code method is supported for now.

    - key -- (Optional) 32 byte Raw Private Key for generating a Bootstrapping Public Key

    - info -- (Optional) Ancillary Device Information like Serial Number

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: chan_list is NULL

    - ESP_ERR_DPP_INVALID_LIST: Channel list not valid

    - ESP_FAIL: Failure

esp_err_t esp_supp_dpp_start_listen(void)

  Start listening on Channels provided during esp_supp_dpp_bootstrap_gen.

         Listens on every Channel from Channel List for a pre-defined wait time.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Generic Failure

    - ESP_ERR_INVALID_STATE: ROC attempted before WiFi is started

    - ESP_ERR_NO_MEM: Memory allocation failed while posting ROC request

esp_err_t esp_supp_dpp_stop_listen(void)

  Stop listening on Channels.

         Stops listening on Channels and cancels ongoing listen operation.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_supp_dpp_set_config(const esp_dpp_config_data_t *config)

  Install or clear DPP AKM connector material in the supplicant.

         This function copies the given DPP AKM row (connector and related keys) into the
         supplicant; only one such row is retained, and a new row replaces the previous one.
         Pass NULL to clear the stored row. (If the first configuration object in the
         Configuration Response uses a DPP AKM with a connector, the stack may load it into the
         same store before the event is delivered; NULL clears that selection too.)

         Connection retry/fallback policy is application-owned. Typical sequence per selected
         row is: pick one row from WIFI_EVENT_DPP_CFG_RECVD, call esp_wifi_set_config(),
         call esp_supp_dpp_set_config() using connector values received from
         WIFI_EVENT_DPP_CFG_RECVD, call esp_wifi_connect().

  Parameters:

    config -- Pointer to one DPP AKM row from WIFI_EVENT_DPP_CFG_RECVD, or NULL to clear.

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: config is not a DPP AKM row, or key lengths are invalid

    - ESP_ERR_INVALID_STATE: DPP supplicant not initialized

    - ESP_ERR_NO_MEM: Allocation failed while storing the row

### Macros

ESP_DPP_MAX_CHAN_COUNT

ESP_DPP_MAX_CONFIG_COUNT

ESP_ERR_DPP_FAILURE

  Generic failure during DPP Operation

ESP_ERR_DPP_TX_FAILURE

  DPP Frame Tx failed OR not Acked

ESP_ERR_DPP_INVALID_ATTR

  Encountered invalid DPP Attribute

ESP_ERR_DPP_AUTH_TIMEOUT

  DPP Auth response was not received in time

ESP_ERR_DPP_INVALID_LIST

  Channel list given in esp_supp_dpp_bootstrap_gen() is not valid or too big

ESP_ERR_DPP_CONF_TIMEOUT

  DPP Configuration was not received in time

### Type Definitions

typedef enum dpp_bootstrap_type esp_supp_dpp_bootstrap_t

  Types of Bootstrap Methods for DPP.

### Enumerations

enum esp_dpp_akm_t

  AKM values for one DPP configuration row (which credentials apply and how to connect).

         Use this with fields in esp_dpp_config_data_t: legacy modes use password,
         DPP modes use connector and network access key via esp_supp_dpp_set_config().

  Values:

  enumerator ESP_DPP_AKM_UNKNOWN

    Not set or unrecognized

  enumerator ESP_DPP_AKM_DPP

    DPP-only: connector and network access key

  enumerator ESP_DPP_AKM_PSK

    WPA2-PSK: passphrase in password

  enumerator ESP_DPP_AKM_SAE

    WPA3-SAE: passphrase in password

  enumerator ESP_DPP_AKM_PSK_SAE

    WPA2/WPA3 transition: passphrase in password

  enumerator ESP_DPP_AKM_SAE_DPP

    SAE plus DPP: passphrase and DPP credentials

  enumerator ESP_DPP_AKM_PSK_SAE_DPP

    WPA2/WPA3 plus DPP: passphrase and DPP credentials

enum dpp_bootstrap_type

  Types of Bootstrap Methods for DPP.

  Values:

  enumerator DPP_BOOTSTRAP_QR_CODE

    QR Code Method

  enumerator DPP_BOOTSTRAP_PKEX

    Proof of Knowledge Method

  enumerator DPP_BOOTSTRAP_NFC_URI

    NFC URI record Method

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.