# Wi-Fi Easy ConnectTM (DPP)

[English]

Wi-Fi Easy ConnectTM 是 Wi-Fi Alliance 认证的配网协议，也称为设备配网协议 (DPP) 或 Easy Connect，是一种安全和标准化的 Wi-Fi 设备配网协议。使用 Easy Connect 将新设备添加入网就像扫描二维码一样简单，特别是对于没有 UI 的智能家居和物联网产品而言，大大降低了联网复杂性，加强了的用户体验。与旧的协议如 Wi-Fi Protected Setup (WPS) 等旧协议相比，Wi-Fi Easy Connect 的公钥加密技术额外确保了添加新设备时的网络安全。

Easy Connect 从以下几个方面改善了用户体验：

> - 操作简单直观，设置新设备时无需阅读冗长的指南

> - 无需记住需配网设备的密码或输入密码

> - 支持电子/打印的二维码以及其他人类可读的字符串

> - 同时支持 WPA2 和 WPA3 网络

如需了解更多信息，请参考 Wi-Fi Alliance 的官方介绍：Easy Connect。

ESP32-C3 支持 Easy Connect 的二维码配网模式，用户需要使用显示器显示二维码，随后使用兼容的设备扫描此二维码，并将 ESP32-C3 添加到自己的 Wi-Fi 网络中。此兼容设备需连接到无需支持 Wi-Fi Easy ConnectTM 的 AP 上。

Easy Connect 协议仍在不断发展。目前已知支持二维码的平台为部分运行 Android 10 及更高系统版本的 Android 智能手机等。使用 Easy Connect 时，无需在智能手机上安装额外的应用程序。

## 应用示例

- wifi/wifi_easy_connect/dpp-enrollee 演示如何使用 DPP 将 ESP32-C3 配置为注册设备，通过二维码和 Android 10 及以上的设备安全地将 ESP 设备接入网络。

## API 参考

### 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.

  返回:

    - 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.

  参数:

    - chan_list -- Comma-separated list of channels for listening (must not be NULL). A single channel (e.g., "6") is recommended for reliable discovery. If using multiple, prefer non-overlapping channels (e.g., "1,6,11").

    - 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

  返回:

    - 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.

  返回:

    - 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.

  返回:

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

  参数:

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

  返回:

    - 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

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。