How does ESP32 connect to Wi-Fi without a screen or keyboard?

SmartConfig is a provisioning technology originally developed by Texas Instruments. It solves a simple problem: a brand-new Wi-Fi module has no display, no buttons, and no way to type a network name.

A smartphone app broadcasts the credentials in special packets. The ESP32 sniffs those packets, extracts the SSID and password, and joins the access point. The process starts when firmware calls esp_smartconfig_start with a configuration structure. The radio enters a promiscuous scanning mode. It hops channels until it detects the encoded broadcast from the phone. Once the target channel is found, the device locks on, decodes the payload, and emits an event containing the SSID, password, optional BSSID, and a token used to acknowledge the phone. After the acknowledgement is sent, the firmware must call esp_smartconfig_stop to release the internal buffers — whether the connection succeeded or not.

Three protocols share one API

ESP32 supports three distinct SmartConfig flavours. Airkiss comes from WeChat's ecosystem. ESPTouch is TI's original method. ESPTouch v2 arrived with SmartConfig library version 3.0. The firmware can query the version at runtime through esp_smartconfig_get_version. The version string is the only way to confirm v2 support on a given chip.

ESPTouch v2 uses a completely different encoding algorithm. The documentation states it yields faster setup times. It also adds AES encryption and a reserved data field for custom payloads. The encryption key must be exactly 16 bytes and is supplied in the start configuration structure. If the key is present, the phone app must encrypt the broadcast; the ESP32 decrypts on the fly.

Airkiss and the two ESPTouch variants can be enabled simultaneously. The enumeration smartconfig_type_t offers four values: SC_TYPE_ESPTOUCH, SC_TYPE_AIRKISS, SC_TYPE_ESPTOUCH_AIRKISS, and SC_TYPE_ESPTOUCH_V2. The default combines classic ESPTouch and Airkiss. Switching to v2 alone or adding it to the mix requires a call to esp_smartconfig_set_type before esp_smartconfig_start.

Encryption adds a random IV option

Starting with SmartConfig library version 3.0.2, ESPTouch v2 can use a random initialization vector for AES. The start configuration contains a boolean flag esp_touch_v2_enable_crypt. When encryption is enabled but the random-IV option is disabled, the IV defaults to zero — preserving compatibility with older phone apps. When the random-IV option is enabled, the IV becomes a random value for each provisioning session.

The trade-off is explicit: transmitting the random IV to the provisioning device extends the overall provisioning time. The ESP32 detects which mode is in use by inspecting a flag inside the received provisioning packet. No separate handshake is required. The reserved data field introduced in v2 remains available regardless of encryption settings; its length and content are application-defined.

Timeouts and fast mode

A global timeout governs the whole procedure. esp_esptouch_set_timeout accepts a value between 15 and 255 seconds with an offset of 45 seconds. The timer starts when the device reaches the SC_STATUS_FIND_CHANNEL state. If the timeout expires, SmartConfig restarts automatically from the beginning.

Fast mode is a separate toggle. esp_smartconfig_fast_mode(true) must be called before esp_smartconfig_start. It requires a matching phone application. The documentation notes the two modes are compatible but does not describe the encoding difference.

Reserved data and events

After a successful SC_EVENT_GOT_SSID_PSWD event, the firmware can retrieve the reserved data sent by an ESPTouch v2 phone app. esp_smartconfig_get_rvd_data copies up to the provided buffer length into a caller-allocated array. The event structure also carries the phone's IPv4 address and a token byte that the ESP32 uses to send the final acknowledgement.

Four events mark the provisioning flow. SC_EVENT_SCAN_DONE signals that the initial channel scan completed. SC_EVENT_FOUND_CHANNEL means the target AP channel was identified. SC_EVENT_GOT_SSID_PSWD delivers the credentials and metadata. SC_EVENT_SEND_ACK_DONE confirms the acknowledgement packet left the radio. The firmware typically transitions to normal station mode after the third event and calls esp_smartconfig_stop after the fourth.

The start configuration structure includes an enable_log boolean. When set, the library prints verbose diagnostic output to the serial console. The default configuration macro SMARTCONFIG_START_CONFIG_DEFAULT initializes all fields to their standard values: logging off, v2 encryption off, key pointer null.

No provisioning method is universally superior. The choice depends on the phone apps available to end users and whether the product requires encrypted credential transfer. The API surface remains small — seven functions, two structures, two enumerations — but the combination of protocol selection, encryption flags, and timeout tuning covers a wide range of headless deployment scenarios.