SmartConfig
概述
SmartConfigTM 是由 TI 开发的配网技术,用于将新的 Wi-Fi 设备连接到 Wi-Fi 网络。它使用移动应用程序将无线网凭据从智能手机或平板电脑端广播给未配网的 Wi-Fi 设备。
这项技术的优势在于,设备无需直接获知 AP 的 SSID 或密码,而是通过智能手机获取。这对于没有用户界面的无头设备和系统而言十分重要。
目前, ESP32-C2 支持三种类型的 SmartConfig 配网: Airkiss、ESPTouch 和 ESPTouch v2。ESPTouch v2 自 SmartConfig v3.0 (SmartConfig 的版本可以从 esp_smartconfig_get_version()
获取)起开始支持,ESPTouch v2 和 vESPTouch 采用完全不同的配网算法,因此配网速度更快。此外,ESPTouch v2 还增加了 AES 加密功能和自定义数据字段。
从 SmartConfig v3.0.2 开始,ESPTouch v2 的 AES 加密支持随机 IV。在应用程序端,当随机 IV 的选项关闭的时候,默认的 IV 为 0,与旧版本保持一致,当随机 IV 的选项打开的时候,IV 为随机值。需要注意的是,当启用 AES 加密且 IV 为随机值时,配网时间会延长,因为需要将 IV 传输到配网设备。在配网设备端,设备会根据配网包中的 flag 来识别 AES 的随机 IV 是否开启。
如需通过其他方式为 ESP32-C2 设备配网,请参阅 配网 API。
应用示例
前往 wifi/smart_config,查看使用 SmartConfig 将 ESP32-C2 连接到目标 AP 的应用示例。
API 参考
Header File
This header file can be included with:
#include "esp_smartconfig.h"
This header file is a part of the API provided by the
esp_wifi
component. To declare that your component depends onesp_wifi
, add the following to your CMakeLists.txt:REQUIRES esp_wifi
or
PRIV_REQUIRES esp_wifi
Functions
-
const char *esp_smartconfig_get_version(void)
Get the version of SmartConfig.
- 返回
SmartConfig version const char.
-
esp_err_t esp_smartconfig_start(const smartconfig_start_config_t *config)
Start SmartConfig, config ESP device to connect AP. You need to broadcast information by phone APP. Device sniffer special packets from the air that containing SSID and password of target AP.
- Attention
1. This API can be called in station or softAP-station mode.
- Attention
2. Can not call esp_smartconfig_start twice before it finish, please call esp_smartconfig_stop first.
- 参数
config -- pointer to smartconfig start configure structure
- 返回
ESP_OK: succeed
others: fail
-
esp_err_t esp_smartconfig_stop(void)
Stop SmartConfig, free the buffer taken by esp_smartconfig_start.
- Attention
Whether connect to AP succeed or not, this API should be called to free memory taken by smartconfig_start.
- 返回
ESP_OK: succeed
others: fail
-
esp_err_t esp_esptouch_set_timeout(uint8_t time_s)
Set timeout of SmartConfig process.
- Attention
Timing starts from SC_STATUS_FIND_CHANNEL status. SmartConfig will restart if timeout.
- 参数
time_s -- range 15s~255s, offset:45s.
- 返回
ESP_OK: succeed
others: fail
-
esp_err_t esp_smartconfig_set_type(smartconfig_type_t type)
Set protocol type of SmartConfig.
- Attention
If users need to set the SmartConfig type, please set it before calling esp_smartconfig_start.
- 参数
type -- Choose from the smartconfig_type_t.
- 返回
ESP_OK: succeed
others: fail
-
esp_err_t esp_smartconfig_fast_mode(bool enable)
Set mode of SmartConfig. default normal mode.
- Attention
1. Please call it before API esp_smartconfig_start.
- Attention
2. Fast mode have corresponding APP(phone).
- Attention
3. Two mode is compatible.
- 参数
enable -- false-disable(default); true-enable;
- 返回
ESP_OK: succeed
others: fail
Structures
-
struct smartconfig_event_got_ssid_pswd_t
Argument structure for SC_EVENT_GOT_SSID_PSWD event
Public Members
-
uint8_t ssid[32]
SSID of the AP. Null terminated string.
-
uint8_t password[64]
Password of the AP. Null terminated string.
-
bool bssid_set
whether set MAC address of target AP or not.
-
uint8_t bssid[6]
MAC address of target AP.
-
smartconfig_type_t type
Type of smartconfig(ESPTouch or AirKiss).
-
uint8_t token
Token from cellphone which is used to send ACK to cellphone.
-
uint8_t cellphone_ip[4]
IP address of cellphone.
-
uint8_t ssid[32]
-
struct smartconfig_start_config_t
Configure structure for esp_smartconfig_start
Macros
-
SMARTCONFIG_START_CONFIG_DEFAULT()
Enumerations
-
enum smartconfig_type_t
Values:
-
enumerator SC_TYPE_ESPTOUCH
protocol: ESPTouch
-
enumerator SC_TYPE_AIRKISS
protocol: AirKiss
-
enumerator SC_TYPE_ESPTOUCH_AIRKISS
protocol: ESPTouch and AirKiss
-
enumerator SC_TYPE_ESPTOUCH_V2
protocol: ESPTouch v2
-
enumerator SC_TYPE_ESPTOUCH
-
enum smartconfig_event_t
Smartconfig event declarations
Values:
-
enumerator SC_EVENT_SCAN_DONE
Station smartconfig has finished to scan for APs
-
enumerator SC_EVENT_FOUND_CHANNEL
Station smartconfig has found the channel of the target AP
-
enumerator SC_EVENT_GOT_SSID_PSWD
Station smartconfig got the SSID and password
-
enumerator SC_EVENT_SEND_ACK_DONE
Station smartconfig has sent ACK to cellphone
-
enumerator SC_EVENT_SCAN_DONE