使用Arduino开发ESP32（二十八）：WiFiProvisioning 官方说明文档自翻

## 官方文档（自行翻译）

Provisioningfor Arduino 基于Arduino的配置

This sketch implements provisioning using various IDF components

Introductions 描述

This example allows Arduino user to choose either BLE or SOFTAP as a mode of transport, over which the provisioning related communication is to take place, between the device (to be provisioned) and the client (owner of the device).
这个例子允许Arduino用户选择BLE或SOFTAP作为传输方式，在此基础上进行配置相关通信，在设备(要供应的)和客户端(设备的所有者)之间。

APIs introduced for provisioning 为Provisioning引入的API们

WiFi.onEvent()函数

Using this API user can register to receive WiFi Events and Provisioning Events
使用这个API，用户可以注册接收WiFi事件和配置事件

Parameters passed 该函数传递的参数

A function with following signature 具有以下声明的函数

• void SysProvEvent(system_event_t * , wifi_prov_event_t * );

structure [ wifi_prov_event_t ] 结构体：wifi_prov_event_t

• wifi_prov_cb_event_t event;
• void * event_data;

WiFi.beginProvision()函数

WiFi.beginProvision(void ( * scheme_cb)(), wifi_prov_scheme_event_handler_t scheme_event_handler, wifi_prov_security_t security, char * pop, char * service_name, char * service_key, uint8_t * uuid);

Parameters passed 该函数传递的参数

• function pointer : choose the mode of transfer 函数指针：选择通信模式

  • provSchemeBLE - Using BLE 使用BLE
  • provSchemeSoftAP - Using SoftAP 使用SoftAP

• security : choose security type 安全措施：选择保密类型

  • WIFI_PROV_SECURITY_1 - It allows secure communication which consists of secure handshake using key exchange and proof of possession (pop) and encryption/decryption of messages.
    它允许安全通信，包括使用密钥交换、拥有证明(pop)和消息的加密/解密的安全握手。

  • WIFI_PROV_SECURITY_0 - It do not provide application level security, it involve simply plain text communication.
    它不提供应用程序级别的安全性，只涉及纯文本通信。

• scheme_event_handler : specify the handlers according to the mode chosen scheme事件句柄：根据选择的模式指定句柄

  • BLE :

    • WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM - This scheme event handler is used when application doesn’t need BT and BLE after provisioning is finised 当配置完成后，应用程序不需要BT和BLE时，使用此scheme事件处理程序
    • WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE - This scheme event handler is used when application doesn’t need BLE to be active after provisioning is finised 此scheme事件处理程序用于在配置完成后应用程序不需要BLE处于活动状态时使用
    • WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT - This scheme event handler is used when application doesn’t need BT to be active after provisioning is finised 此方案事件处理程序用于配置完成后应用程序不需要BT处于活动状态时

  • SoftAp :

    • WIFI_PROV_EVENT_HANDLER_NONE

• pop : It is the string that is used to provide the authentication. 它是用于提供身份验证的字符串。

• service_name : Specify service name for the device, if it is not specified then default chosen name is PROV_XXX where XXX are the last 3 bytes of the MAC address.
  为设备指定服务名称，如果它没有指定，那么默认选择的名称是PROV XXx，其中XXx是MAC地址的最后3个字节。

• service_key : Specify service key, if chosen mode of provisioning is BLE then service_key is always NULL
  指定服务密钥，如果选择的供应模式为BLE，则服务密钥始终为NULL

• uuid : user can specify there own 128 bit UUID while provisioning using BLE, if not specified then default value taken is 用户可以在使用BLE时指定自己的128位UUID，如果没有指定，则默认值为
  - { 0xb4, 0xdf, 0x5a, 0x1c, 0x3f, 0x6b, 0xf4, 0xbf,
  0xea, 0x4a, 0x82, 0x03, 0x04, 0x90, 0x1a, 0x02, }

NOTE 注意

• If none of the parameters are specified in beginProvision then default provisioning takes place using SoftAP with
  如果在beginProvision中没有指定任何参数，则使用SoftAP 进行以下默认配置
  • scheme = WIFI_PROV_SCHEME_SOFTAP
  • scheme_event_handler = WIFI_PROV_EVENT_HANDLER_NONE
  • security = WIFI_PROV_SECURITY_1
  • pop = “abcd1234”
  • service_name = “PROV_XXX”
  • service_key = NULL
  • uuid = NULL

Log Output 日志输出

• Enable debuger : [ Tools -> Core Debug Level -> Info ]

Provisioning Tools 配置工具

https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/provisioning/wifi_provisioning.html#provisioning-tools

Example output 输出样例

Provisioning using SoftAP

[I][WiFiProv.cpp:117] beginProvision(): Starting AP using SOFTAP
 service_name : PROV_XXX
 password : 123456789
 pop : abcd1234

Provisioning started
Give Credentials of your access point using " Android app "

Received Wi-Fi credentials
	SSID : GIONEE M2
	Password : 123456789

Connected IP address : 192.168.43.120
Provisioning Successful
Provisioning Ends

Provisioning using BLE

[I][WiFiProv.cpp:115] beginProvision(): Starting AP using BLE
 service_name : PROV_XXX
 pop : abcd1234

Provisioning started
Give Credentials of your access point using " Android app "

Received Wi-Fi credentials
	SSID : GIONEE M2
	Password : 123456789

Connected IP address : 192.168.43.120
Provisioning Successful
Provisioning Ends

Credentials are available on device

[I][WiFiProv.cpp:146] beginProvision(): Aleardy Provisioned, starting Wi-Fi STA
[I][WiFiProv.cpp:150] beginProvision(): SSID : Wce*****
[I][WiFiProv.cpp:152] beginProvision(): CONNECTING TO THE ACCESS POINT : 
Connected IP address : 192.168.43.120

例程代码

#include "WiFi.h"

void SysProvEvent(system_event_t *sys_event,wifi_prov_event_t *prov_event)
{
    if(sys_event) {
      switch (sys_event->event_id) {
      case SYSTEM_EVENT_STA_GOT_IP:
          Serial.print("\nConnected IP address : ");
          Serial.println(ip4addr_ntoa(&sys_event->event_info.got_ip.ip_info.ip));
          break;
      case SYSTEM_EVENT_STA_DISCONNECTED:
          Serial.println("\nDisconnected. Connecting to the AP again... ");
          break;
      default:
          break;
      }      
    }

    if(prov_event) {
        switch (prov_event->event) {
        case WIFI_PROV_START:
            Serial.println("\nProvisioning started\nGive Credentials of your access point using \" Android app \"");
            break;
        case WIFI_PROV_CRED_RECV: { 
            Serial.println("\nReceived Wi-Fi credentials");
            wifi_sta_config_t *wifi_sta_cfg = (wifi_sta_config_t *)prov_event->event_data;
            Serial.print("\tSSID : ");
            Serial.println((const char *) wifi_sta_cfg->ssid);
            Serial.print("\tPassword : ");
            Serial.println((char const *) wifi_sta_cfg->password);
            break;
        }
        case WIFI_PROV_CRED_FAIL: { 
            wifi_prov_sta_fail_reason_t *reason = (wifi_prov_sta_fail_reason_t *)prov_event->event_data;
            Serial.println("\nProvisioning failed!\nPlease reset to factory and retry provisioning\n");
            if(*reason == WIFI_PROV_STA_AUTH_ERROR) 
                Serial.println("\nWi-Fi AP password incorrect");
            else
                Serial.println("\nWi-Fi AP not found....Add API \" nvs_flash_erase() \" before beginProvision()");        
            break;
        }
        case WIFI_PROV_CRED_SUCCESS:
            Serial.println("\nProvisioning Successful");
            break;
        case WIFI_PROV_END:
            Serial.println("\nProvisioning Ends");
            break;
        default:
            break;
        }      
    }
}

void setup() {
  Serial.begin(115200);
  //Sample uuid that user can pass during provisioning using BLE
  /* uint8_t uuid[16] = {0xb4, 0xdf, 0x5a, 0x1c, 0x3f, 0x6b, 0xf4, 0xbf,
                   0xea, 0x4a, 0x82, 0x03, 0x04, 0x90, 0x1a, 0x02 };*/
  WiFi.onEvent(SysProvEvent);
  WiFi.beginProvision(provSchemeBLE, WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM, WIFI_PROV_SECURITY_1, "abcd1234", "PROV_XXX", NULL, NULL);
}

void loop() {
}

说实话，没怎么理解这例程，暂且留待日后揣摩吧