SmartConfig

[English]

SmartConfigTM 是由 TI 开发的配网技术,用于将新的 Wi-Fi 设备连接到 Wi-Fi 网络。它使用移动应用程序将无线网凭据从智能手机或平板电脑端广播给未配网的 Wi-Fi 设备。

这项技术的优势在于,设备无需直接获知 AP 的 SSID 或密码,而是通过智能手机获取。这对于没有用户界面的无头设备和系统而言十分重要。

如需通过其他方式为 ESP32 设备配网,请参阅 配网 API

应用示例

前往 wifi/smart_config,查看使用 SmartConfig 将 ESP32 连接到目标 AP 的应用示例。

API 参考

Header File

  • components/esp_wifi/include/esp_smartconfig.h

  • 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 on esp_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

esp_err_t esp_smartconfig_get_rvd_data(uint8_t *rvd_data, uint8_t len)

Get reserved data of ESPTouch v2.

参数
  • rvd_data -- reserved data

  • len -- length of reserved data

返回

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

struct smartconfig_start_config_t

Configure structure for esp_smartconfig_start

Public Members

bool enable_log

Enable smartconfig logs.

bool esp_touch_v2_enable_crypt

Enable ESPTouch v2 crypt.

char *esp_touch_v2_key

ESPTouch v2 crypt key, len should be 16.

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

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