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

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

应用示例

  • wifi/wifi_easy_connect/dpp-enrollee 演示如何使用 DPP 将 ESP32 配置为注册设备，通过二维码和 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(esp_supp_dpp_event_cb_t evt_cb)

Initialize DPP Supplicant. 

   Starts DPP Supplicant and initializes related Data Structures.
return

  • ESP_OK: Success

  • ESP_FAIL: Failure

备注

The evt_cb parameter is deprecated and will be ignored in future IDF versions. Directly register for WiFi events to get DPP events.

参数:

evt_cb -- (Deprecated) Callback function to receive DPP related events

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 -- List of channels device will be available on for listening

  • 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_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

Macros

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

typedef void (*esp_supp_dpp_event_cb_t)(esp_supp_dpp_event_t evt, void *data)

Callback function for receiving DPP Events from Supplicant. 

   Callback function will be called with DPP related information.

Param evt:

DPP event ID

Param data:

Event data payload

Enumerations

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

enum esp_supp_dpp_event_t

Types of Callback Events received from DPP Supplicant.

Values:

enumerator ESP_SUPP_DPP_URI_READY

URI is ready through Bootstrapping

enumerator ESP_SUPP_DPP_CFG_RECVD

Config received via DPP Authentication

enumerator ESP_SUPP_DPP_PDR_RECVD

Peer Discovery Response is received

enumerator ESP_SUPP_DPP_FAIL

DPP Authentication failure

此文档对您有帮助吗？