# SmartConfig

[中文]

## Introduction

The SmartConfigTM is a provisioning technology developed by TI to connect a new Wi-Fi device to a Wi-Fi network. It uses a mobile application to broadcast the network credentials from a smartphone, or a tablet, to an un-provisioned Wi-Fi device.

The advantage of this technology is that the device does not need to directly know SSID or password of an Access Point (AP). This information is provided using the smartphone. This is particularly important to headless device and systems, due to their lack of a user interface.

Currently, ESP32-S3 support three types of SmartConfig: Airkiss, ESPTouch, and ESPTouch v2. ESPTouch v2 has been supported since SmartConfig v3.0 (the version of SmartConfig can be get from `esp_smartconfig_get_version()`), and it employs a completely different algorithm compared to ESPTouch, resulting in faster setup times. Additionally, ESPTouch v2 introduces AES encryption and custom data fields.

Starting from SmartConfig v3.0.2, ESPTouch v2 introduces support for random IV in AES encryption. On the application side, when the option for random IV is disabled, the default IV is set to 0, maintaining consistency with previous versions. When the random IV option is enabled, the IV will be a random value. It is important to note that when AES encryption is enabled with a random IV, the provision time will be extended due to the need of transmitting the IV to the provisioning device. On the provisioning device side, the device will identify whether the random IV for AES is enabled based on the flag in the provisioning packet.

If you are looking for other options to provision your ESP32-S3 devices, check Provisioning API.

## Application Example

Connect ESP32-S3 to the target AP using SmartConfig: wifi/smart_config.

## API Reference

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

  Returns:

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

  Parameters:

    config -- pointer to smartconfig start configure structure

  Returns:

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

  Returns:

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

  Parameters:

    time_s -- range 15s~255s, offset:45s.

  Returns:

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

  Parameters:

    type -- Choose from the smartconfig_type_t.

  Returns:

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

  Parameters:

    enable -- false-disable(default); true-enable;

  Returns:

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

  Parameters:

    - rvd_data -- reserved data

    - len -- length of reserved data

  Returns:

    - 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

Provide feedback about this document