Contributed by WildboarG, organized by Ai-Thinker

AI-WB2 Provisioning [Part 2]

AI-WB2 SmartConfig Provisioning

---

One-Key Provisioning (Smart Config)

---

smartConfig is a technology for quickly connecting Wi-Fi devices to a network, first proposed by TI (Texas Instruments). It allows IoT devices without a display or input interface (such as the AI-WB2) to obtain Wi-Fi connection information through a smartphone, achieving fast networking.

Principle

Using the broadcast and multicast frames of the IEEE 802.11 protocol, the Wi-Fi SSID and password are encoded with a specific data encoding scheme, packed into Wi-Fi packets, and sent out. The IoT device listens for and parses these Wi-Fi packets, extracts the Wi-Fi information, and connects.

• Encode Wi-Fi information
  • The phone app (e.g. ESPTouch, TI SmartConfig App) encodes the Wi-Fi name (SSID) and password (passphrase) into multiple packets.
  • These packets are usually sent via UDP broadcast or multicast, or the information is encoded through data frame lengths, intervals, and similar means.
• The device listens and parses
  1. The device enters sniffer mode (also called promiscuous mode — no packet filtering) and listens to all 802.11 frames in the environment;
  2. The device needs to poll across its supported channels (usually 1-13 on 2.4G), because the device does not know the channel of the user's phone or the target router;
  3. Once a data frame matching the provisioning rules is captured, stop channel polling and try to receive all frames on that channel;
  4. If reception fails or times out on the current channel, return to step 2;
  5. Once all data frames are received, turn off sniffer mode
• The device connects to Wi-Fi
  • After parsing out the Wi-Fi account and password, the IoT device exits SmartConfig mode and connects to Wi-Fi in STA mode.
  • Once connected, it can report back to the phone app to complete the configuration.

Flow

The device enters SmartConfig mode

• The device enables Wi-Fi and enters listening mode (promiscuous mode).
• It waits for the broadcast of Wi-Fi connection information.

The phone sends the provisioning information

• The user opens the phone app, enters the Wi-Fi name and password, and taps "Provision".
• The phone sends the encoded SSID and password over the network via UDP broadcast / multicast.

The device parses the data

• The device listens for UDP packets on the Wi-Fi network and parses out the SSID and password.
• After parsing, the device exits SmartConfig mode and switches to Wi-Fi STA mode.

The device connects to Wi-Fi and reports the result

• The device connects to Wi-Fi using the obtained Wi-Fi account and password.
• Once connected, the device can send an ACK (acknowledgment packet) to the phone over UDP to indicate successful provisioning.

Flow chart:

Data transfer methods

There are two ways to carry the data: broadcast and multicast. They are described separately below.

Before joining the router, the device has not obtained the corresponding key, so it cannot decrypt data frames inside the router's LAN (including frames from the user's phone connected to the target router).

As shown below, in sniffer mode the body of the data frame the device receives — the Frame Body — is encrypted; only the frame header and the overall frame length are unencrypted. To deliver provisioning information from the phone to the device, you have to make use of this information.

MAC frame format:

Field	Length (bytes)	Description
Frame Control	2	Indicates the frame type, subtype, etc.
Duration/ID	2	Network fragmentation, QoS related
Address 1 (DA)	6	Destination MAC address
Address 2 (SA)	6	Source MAC address
Address 3 (MESHBSSID)	6	AP's MAC address
Sequence Control	2	Data fragmentation information
Frame Body	Variable	Data portion, e.g. SSID, data payload
FCS (Frame Check Sequence)	4	Used to verify frame integrity

1. Broadcast Packet Length

Principle

• Transmit the Wi-Fi SSID and password via UDP broadcast packets.
• Data is encoded mainly through the broadcast packet length, not the packet content.
• The IoT device enables promiscuous mode to listen for broadcast packets and decodes the Wi-Fi information from packets of different lengths.

Transfer process

1. Phone side:
   • Send multiple UDP broadcast packets; each packet's length represents the Wi-Fi SSID and password according to a specific encoding rule.
   • For example, packet length 100 represents the character A , 101 represents B`, and so on.
2. Device side:
   • Capture all broadcast packets in listening mode.
   • Parse the packet lengths to recover the Wi-Fi SSID and password.
   • Exit promiscuous mode and connect to Wi-Fi.

Pros and cons

✅ Advantages:

• Compatible with most routers; does not rely on multicast support.
• Only one-way data transfer is needed (phone → device); the device does not need to respond.

❌ Disadvantages:

• In some Wi-Fi environments, broadcast packets may be dropped or rate-limited, lowering the success rate.
• The amount of data transferable is limited; not suitable for complex data exchanges.

---

2. Multicast Addressing

Principle

• Send the Wi-Fi SSID and password via UDP multicast.
• Data is encoded mainly through the multicast IP address, rather than the packet content or length.
• The IoT device listens on a specific multicast IP address and decodes the Wi-Fi information.

Transfer process

1. Phone side (sender)

• Generate a UDP multicast packet containing the Wi-Fi SSID and password (possibly encrypted or encoded).
• The destination IP multicast address is usually 239.x.x.x (a private multicast address).
• Send the data to that multicast address via the UDP protocol.

2. Wi-Fi router (AP)

• Receives the IP multicast packet, converts it into a MAC multicast frame, and broadcasts it across the LAN.
• The destination MAC multicast address is derived from the IP multicast address, usually in the form of 01:00:5E:XX:XX:XX.

3. AI-WB2 device (receiver)

• Enters Wi-Fi promiscuous mode and listens for MAC frames.
• Filters out MAC multicast frames, extracts the UDP payload, and parses the Wi-Fi SSID and password.
• Exits promiscuous mode and connects to Wi-Fi.

Pros and cons

✅ Advantages:

• Compared with broadcasting, multicast frames are more easily captured by devices on the LAN, with a lower packet loss rate.
• Avoids the broadcast packet length limit; suitable for more complex Wi-Fi information encoding.

❌ Disadvantages:

• Some routers disable or block UDP multicast, preventing the device from parsing the data.
• The device needs to parse IP addresses, slightly increasing the computational burden.

---

3. Comparison of the Two Methods

Method	Data encoding	Advantages	Disadvantages	Suitable scenarios
Broadcast packet length	Transmits Wi-Fi information via UDP broadcast packet length	Better compatibility; works on most Wi-Fi networks	Some Wi-Fi networks may drop broadcast packets	Suitable for low-interference environments or networks with good Wi-Fi compatibility
Multicast address	Transmits Wi-Fi information via the UDP multicast IP address (actually the MAC address)	Multicast packets are more stable with low packet loss	Some routers may block UDP multicast	Suitable for newer routers and environments with reduced broadcast congestion

Example

Click to expand full code

typedef

enum
 {

  smartconfig,
  airkiss,
} wifi_network_configuration_mode;

wifi_network_configuration_mode network_configuration_mode =
    smartconfig;
// 这里选择对应的配网方式

static

wifi_conf_t
 conf = {
    .country_code =
"CN"
,
};

The wb2 SDK provided by Ai-Thinker includes examples for two different quick provisioning methods: smartconfig and airkiss

Airkiss uses the Wi-Fi packet length encoding method:

• The sender (phone) encodes the Wi-Fi SSID and password by controlling the packet length of UDP/TCP.
• The receiver (device) listens for Wi-Fi packets of different lengths and decodes the Wi-Fi information.

Because AirKiss uses the packet length directly rather than the UDP payload content, some low-end routers without UDP multicast support may also work.

Comparison	smartconfig	Airkiss
Data transfer	Broadcast/multicast packets	Wi-Fi packet length encoding
Encoding	Variable-length UDP (broadcast/multicast)	UDP/TCP packet length
Scope	General Wi-Fi devices (esp8266/esp32/ai-wb2)	Tencent ecosystem (WeChat IoT, mini programs)

Testing:

Here, the one-key provisioning of Bafa Cloud is used in the WeChat mini program.

SmartConfig mode

Received data [0x18 0x08 0xd7 0x10 0xbd 0xc0 0xa8 0x00 0x01 0x48 0x59 0x47 0x53 0x33 0x33 0x30 0x35]

Looking at the last 8 bytes of the data, they exactly match my password HYGS3305. The encoding before that is hard to analyze without source code — inside the SDK it is compiled .a library files, with no source code.

It is connected and has been assigned an IP.

Airkiss mode

In the example, modify it to select the airkiss method for provisioning

Click to expand full code

wifi_network_configuration_mode network_configuration_mode =airkiss;

Compile, flash, and test:

Switch to the airkiss provisioning method;