Overview

The Ai-WB2 series (BL602/BL702 chips) has a built-in 2.4GHz Wi-Fi (note: it cannot connect to a phone's 5GHz Wi-Fi), supports the IEEE 802.11 b/g/n protocol, and works in STA (connect to a router) and AP (hotspot) modes. The SDK (the official development kit) provides a complete network stack built on FreeRTOS + lwIP (the software module responsible for network send/receive), managing connection state through a Wi-Fi event-driven framework. This page opens the wireless network series, introducing the basic concepts and the SDK network framework.

In plain words: Wi-Fi is the board's "wireless phone". STA mode makes the board connect to your home router like a phone (borrowing the network); AP (Soft-AP) mode makes the board open its own hotspot, and phones connect to it instead. The "event callback" on this page is like setting an alarm — when Wi-Fi connects, disconnects, or gets an IP, the system automatically "rings" and notifies your program to handle it.

This tutorial is based on the official Ai-Thinker SDK (Ai-Thinker-Open/Ai-Thinker-WB2, version release_bl_iot_sdk_1.6.40). Connection examples that follow are in the official applications/wifi directory (station / softAP / scan etc.).

🎯Page GoalLearn the Ai-WB2's Wi-Fi hardware capabilities, STA/AP mode concepts and the SDK's Wi-Fi event framework, building the foundation for each following network tutorial.

🧰Prerequisites① An Ai-WB2 development board ② A 2.4GHz router (needed for STA mode) ③ Environment set up per [SDK Installation](../../sdk/sdk_intro).

🔗RelatedConnecting to a router: [Connect Wi-Fi](./wifi_connect); hotspot mode: [Soft-AP Mode](./wifi_softap).

---

Wi-Fi Hardware Capabilities

First, the board's wireless "hardware specs" — beginners only need to remember: supports 2.4GHz, up to 72.2 Mbps:

Parameter	Description
Protocol standard	IEEE 802.11 b / g / n (2.4GHz)
Antenna	Onboard PCB antenna (included on the Ai-WB2 module)
Working modes	STA (station), AP (hotspot), also supports STA+AP coexistence
Security	WPA / WPA2 / WPA3 Personal
Max rate	72.2 Mbps (802.11n HT20)
Supported channels	1 ~ 13 (with country code CN)

STA and AP Modes

Remember one sentence: STA is "connecting to someone else" (be the phone), AP is "letting others connect" (open a hotspot):

Mode	Role	Typical Use
STA (Station)	Connects to a router as a client	Collect data and report to the cloud, receive commands
AP (Access Point)	Serves as a hotspot for other devices	Device provisioning, phone-direct configuration
STA + AP	Connects to a router while opening a hotspot	Relay, stay connected after provisioning

SDK Wireless Network Framework

The Ai-WB2's Wi-Fi stack layers (top to bottom like "front desk → supervisor → logistics"; you mostly touch the top two layers):

Layer	Component	Responsibility
Application	User main	Registers event callbacks, runs business logic
Event	aos/yloop.h	Event loop: aos_register_event_filter + aos_post_event
Management	wifi_mgmr_ext.h	Wi-Fi management: wifi_mgmr_sta_enable / wifi_mgmr_sta_connect etc.
Network	lwIP (lwip/tcpip.h)	TCP/IP stack: tcpip_init initializes it
Driver	hal_wifi.h	Firmware task: hal_wifi_start_firmware_task

Event-driven flow (common to all Wi-Fi tutorials):

Don't worry if you don't understand — just remember initialize first → then connect → internet once you get an IP. Every network tutorial in this series uses this skeleton:

main → tcpip_init() → create main_entry task
     → aos_register_event_filter(EV_WIFI, callback, NULL)  register event
     → hal_wifi_start_firmware_task()                      start firmware task
     → aos_post_event(EV_WIFI, CODE_WIFI_ON_INIT_DONE)     trigger initialization
     → callback receives INIT_DONE → wifi_mgmr_start_background()
     → callback receives MGMR_DONE → start connecting / open hotspot
     → callback receives GOT_IP → networked, start network applications

Key event codes (hal_wifi.h / wifi_mgmr_ext.h) — event codes are the "notification content" the system gives you; comparing event codes in the callback tells you how far Wi-Fi has gotten:

Event Code	Meaning
CODE_WIFI_ON_INIT_DONE	Wi-Fi firmware initialization complete
CODE_WIFI_ON_MGMR_DONE	Management module started (can start connecting)
CODE_WIFI_ON_CONNECTING	Connecting to the router
CODE_WIFI_ON_CONNECTED	Connected (no IP yet)
CODE_WIFI_ON_GOT_IP	Got the IP (the "house number" on the network), network ready
CODE_WIFI_ON_DISCONNECT	Disconnected
CODE_WIFI_ON_AP_STARTED	Hotspot started successfully
CODE_WIFI_ON_AP_STA_ADD	A device joined the hotspot

💡 All network applications (TCP/UDP/HTTP/MQTT) are built after CODE_WIFI_ON_GOT_IP; the main skeleton in every tutorial in this series is identical — only the business part is swapped.

---

API Summary for This Tutorial

tcpip_init(callback, arg)

Initializes the lwIP TCP/IP stack (socket, DNS, netif etc. depend on it); called first in main.

Parameters:

• callback: initialization-complete callback function pointer, usually NULL
• arg: callback argument, pass NULL

Return: none

aos_register_event_filter(evt, cb, arg)

Registers a filter callback for an event type (Wi-Fi events use EV_WIFI); called when the event occurs.

Parameters:

• evt: event type, values: EV_WIFI (Wi-Fi events)
• cb: callback function pointer, shaped void cb(uint32_t event, void *val, void *arg), required
• arg: pass-through argument, pass NULL if none

Return: 0 on success; negative error code on failure

aos_post_event(evt, code, value)

Posts an event to the event loop (e.g. the initialization-complete event, kicking off the following flow).

Parameters:

• evt: event type, values: EV_WIFI
• code: event code, values: CODE_WIFI_ON_INIT_DONE (init complete) etc. (defined in hal_wifi.h)
• value: event extra value (pointer/number), pass NULL if none

Return: 0 on success; negative error code on failure

hal_wifi_start_firmware_task

Starts the Wi-Fi firmware task, enabling the wireless hardware (driver layer; users generally don't call it directly).

Return: none

wifi_mgmr_start_background(conf)

Starts the Wi-Fi manager (the scheduling core of connecting/hotspot/scanning).

Parameters:

• conf: wifi_conf_t struct pointer, optional fields: country_code (country code, "CN" for China, affects channel range and transmit power)

Return: 0 on success; negative error code on failure

wifi_mgmr_sta_enable

Enables station (STA) mode, ready to connect to a router.

Return: interface handle (wifi_interface_t) on success; NULL on failure

wifi_mgmr_sta_connect(if, ssid, pwd, ...)

Connects to a router by SSID/password (asynchronous; success or failure is notified via event callback).

Parameters:

• if: STA interface handle (return of wifi_mgmr_sta_enable())
• ssid: router name string, required (e.g. "FAE@Seahi")
• pwd: Wi-Fi password string, required (e.g. "fae12345678")
• ...: optional args (BSSID, channel, security type etc.), pass NULL, NULL, 0, 0

Return: 0 on success; negative error code on failure

wifi_mgmr_ap_enable

Enables hotspot (AP) mode, ready for other devices to join.

Return: interface handle (wifi_interface_t) on success; NULL on failure

wifi_mgmr_ap_start(if, ssid, channel, pwd, enc)

Starts the hotspot (detailed params in Wi-Fi Hotspot).

Parameters:

• if: AP interface handle (return of wifi_mgmr_ap_enable())
• ssid: hotspot name (SSID), e.g. "ai-thinker"
• channel: channel (1~13)
• pwd: hotspot password; pass NULL or an empty string for an open network
• enc: encryption (6 = WPA2, 0 = open)

Return: 0 on success; negative error code on failure

xTaskCreate(fn, name, stack, arg, prio, handle)

Creates a task and adds it to the ready queue; the scheduler runs it according to priority.

Parameters:

• fn: pointer to the task entry function, shaped void task(void *arg), required
• name: task name string (for debugging), e.g. "main_entry"
• stack: task stack size (in words), values: any size within memory limits, e.g. 1024
• arg: pointer to the argument passed to the entry function; pass NULL if none
• prio: task priority, values: 0 (lowest)~19 (highest), e.g. 15
• handle: output pointer for the task handle; pass NULL if not needed

Return: pdPASS on success; pdFAIL on failure

---

FAQ & Troubleshooting

⚠️ Can't connect to a 5GHz router
Cause: the Ai-WB2 only supports the 2.4GHz band
Fix: enable the router's 2.4GHz band (or the dual-band-merge switch), or use a 2.4GHz-only SSID

⚠️ Event callback never fires
Cause: no aos_register_event_filter, or no aos_post_event to start the flow
Fix: follow the official skeleton: register the filter → start the firmware task → post the INIT_DONE event

⚠️ Insufficient memory breaks network applications
Cause: lwIP buffers and the firmware task take a lot of RAM, and the business task stack is too large
Fix: size the business task stack to need (official main_entry example is 1024); print xPortGetFreeHeapSize() in the CODE_WIFI_ON_GOT_IP callback to monitor remaining memory

Self-Check

Follow the Connect Wi-Fi tutorial that comes next; the serial shows INIT DONE → MGMR DONE → connected → GOT IP events in order — the framework is verified.