概述

Ai-WB2 系列（BL602/BL702 芯片）内置 2.4GHz Wi-Fi（注意：连不了手机 5GHz 频段的 Wi-Fi），支持 IEEE 802.11 b/g/n 协议，可工作在 STA（连接路由器） 与 AP（热点） 两种模式。SDK（官方提供的开发工具包）基于 FreeRTOS + lwIP（负责网络收发的软件模块）提供完整的网络栈，通过 Wi-Fi 事件驱动框架管理连接状态。本页为无线网络系列的开篇，介绍基本概念与 SDK 网络框架。

用大白话讲：Wi-Fi 就是开发板的「无线电话」。STA 模式是让开发板像手机一样去连你家的路由器（蹭网）；AP（Soft-AP）模式是让开发板自己开一个热点，手机反过来连它。本页讲的「事件回调」就像设闹钟——Wi-Fi 连上、断开、拿到 IP 这些时刻一到，系统自动「响铃」通知你的程序去处理。

本教程基于安信可官方 SDK（Ai-Thinker-Open/Ai-Thinker-WB2，版本 release_bl_iot_sdk_1.6.40）。后续连接实例见官方 applications/wifi 目录（station / softAP / scan 等）。

🎯本页目标了解 Ai-WB2 的 Wi-Fi 硬件能力、STA/AP 模式概念与 SDK 的 Wi-Fi 事件框架，为后续各篇网络教程建立基础。

🧰前置条件① 一块 Ai-WB2 开发板 ② 一个 2.4GHz 路由器（STA 模式需要）③ 已按 [SDK 安装](../../sdk/sdk_intro) 完成环境搭建。

🔗相关章节连接路由器见 [连接 Wi-Fi](./wifi_connect)；热点模式见 [路由模式(Soft-AP)](./wifi_softap)。

---

Wi-Fi 硬件能力

先看开发板的无线「硬件参数」——小白只需要记住：支持 2.4GHz、最高 72.2 Mbps 就够了：

参数	说明
协议标准	IEEE 802.11 b / g / n（2.4GHz）
天线	板载 PCB 天线（Ai-WB2 模组自带）
工作模式	STA（站点）、AP（热点）、同时支持 STA+AP 共存
安全方式	WPA / WPA2 / WPA3 个人版
最大速率	72.2 Mbps（802.11n HT20）
支持信道	1 ~ 13（国家码 CN 时）

STA 与 AP 模式

记住一句话：STA 是「去连别人」（当手机），AP 是「让别人连」（开热点）：

模式	角色	典型应用
STA（Station）	作为客户端连接路由器	采集数据上报云平台、接收指令
AP（Access Point）	作为热点供其他设备接入	设备配网、手机直连配置
STA + AP	同时连接路由器并开热点	中继、配网后保持连接

SDK 无线网络框架

Ai-WB2 的 Wi-Fi 栈分层（从上到下像「前台 → 主管 → 后勤」，平时你主要接触最上面两层）：

层	组件	职责
应用层	用户 main	注册事件回调、执行业务
事件层	aos/yloop.h	事件循环：aos_register_event_filter + aos_post_event
管理层	wifi_mgmr_ext.h	Wi-Fi 管理：wifi_mgmr_sta_enable / wifi_mgmr_sta_connect 等
网络层	lwIP（lwip/tcpip.h）	TCP/IP 协议栈：tcpip_init 初始化
驱动层	hal_wifi.h	固件任务：hal_wifi_start_firmware_task

事件驱动流程（所有 Wi-Fi 教程通用）：

看不懂没关系，只要记住先初始化 → 再连接 → 拿到 IP 就能上网，本系列每篇网络教程都是这套骨架：

main → tcpip_init() → 创建 main_entry 任务
     → aos_register_event_filter(EV_WIFI, 回调, NULL)  注册事件
     → hal_wifi_start_firmware_task()                  启动固件任务
     → aos_post_event(EV_WIFI, CODE_WIFI_ON_INIT_DONE) 触发初始化
     → 回调收到 INIT_DONE → wifi_mgmr_start_background()
     → 回调收到 MGMR_DONE → 发起连接/开启热点
     → 回调收到 GOT_IP → 联网成功，开始网络应用

关键事件码（hal_wifi.h / wifi_mgmr_ext.h）——事件码就是系统给你的「通知内容」，在回调里比对事件码，就知道 Wi-Fi 走到哪一步了：

事件码	含义
CODE_WIFI_ON_INIT_DONE	Wi-Fi 固件初始化完成
CODE_WIFI_ON_MGMR_DONE	管理模块启动完成（可开始连接）
CODE_WIFI_ON_CONNECTING	正在连接路由器
CODE_WIFI_ON_CONNECTED	已连接（尚未获取 IP）
CODE_WIFI_ON_GOT_IP	获取到 IP（网络里的「门牌号」），网络就绪
CODE_WIFI_ON_DISCONNECT	断开连接
CODE_WIFI_ON_AP_STARTED	热点启动成功
CODE_WIFI_ON_AP_STA_ADD	有设备接入热点

💡 所有网络应用（TCP/UDP/HTTP/MQTT）都建立在 CODE_WIFI_ON_GOT_IP 之后，本系列各篇的 main 骨架完全相同，只替换业务部分。

---

本文 API 汇总

tcpip_init(callback, arg)

初始化 lwIP TCP/IP 协议栈（socket、DNS、netif 等依赖它），main 函数最先调用。

参数：

• callback：初始化完成回调函数指针，一般传 NULL
• arg：回调参数，传 NULL

返回值：无

aos_register_event_filter(evt, cb, arg)

注册某个事件类型的过滤器回调（Wi-Fi 事件为 EV_WIFI），事件发生时被调用。

参数：

• evt：事件类型，可选值：EV_WIFI（Wi-Fi 事件）
• cb：回调函数指针，形如 void cb(uint32_t event, void *val, void *arg)，必填
• arg：透传参数，无参传 NULL

返回值：成功返回 0；失败返回负值错误码

aos_post_event(evt, code, value)

向事件循环投递一个事件（如初始化完成事件，触发后续流程）。

参数：

• evt：事件类型，可选值：EV_WIFI
• code：事件码，可选值：CODE_WIFI_ON_INIT_DONE（初始化完成）等（定义于 hal_wifi.h）
• value：事件附加值（指针/数值），无需传 NULL

返回值：成功返回 0；失败返回负值错误码

hal_wifi_start_firmware_task

启动 Wi-Fi 固件任务，开启无线硬件（驱动层，用户一般不直接使用）。

返回值：无

wifi_mgmr_start_background(conf)

启动 Wi-Fi 管理器（连接/热点/扫描的调度核心）。

参数：

• conf：wifi_conf_t 结构体指针，可选字段：country_code（国家码，中国用 "CN"，影响信道范围与发射功率）

返回值：成功返回 0；失败返回负值错误码

wifi_mgmr_sta_enable

启用站点（Station）模式，可连接路由器。

返回值：成功返回接口句柄（wifi_interface_t）；失败返回 NULL

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

按 SSID/密码连接路由器（异步，成功与否通过事件回调通知）。

参数：

• if：STA 接口句柄（wifi_mgmr_sta_enable() 返回值）
• ssid：路由器名称字符串，必填（如 "FAE@Seahi"）
• pwd：Wi-Fi 密码字符串，必填（如 "fae12345678"）
• ...：可选参数（BSSID、信道、安全类型等），传 NULL, NULL, 0, 0

返回值：成功返回 0；失败返回负值错误码

wifi_mgmr_ap_enable

启用热点（AP）模式，可让其他设备接入。

返回值：成功返回接口句柄（wifi_interface_t）；失败返回 NULL

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

启动热点（详细参数见 Wi-Fi 热点）。

参数：

• if：AP 接口句柄（wifi_mgmr_ap_enable() 返回值）
• ssid：热点名称（SSID），如 "ai-thinker"
• channel：信道（1~13）
• pwd：热点密码，开放网络传 NULL 或空字符串
• enc：加密方式（6 = WPA2，0 = 开放）

返回值：成功返回 0；失败返回负值错误码

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

创建任务并加入就绪队列，由调度器按优先级调度执行。

参数：

• fn：任务入口函数指针，形如 void task(void *arg)，必填
• name：任务名称字符串（调试用），如 "main_entry"
• stack：任务栈大小（单位：字），可选值：内存允许范围内任意值，如 1024
• arg：入口函数参数指针，无参传 NULL
• prio：任务优先级，可选值：0（最低）~19（最高），如 15
• handle：任务句柄输出指针，不需要可传 NULL

返回值：成功返回 pdPASS；失败返回 pdFAIL

---

常见问题与踩坑提示

⚠️ 5GHz 路由器连不上
原因：Ai-WB2 仅支持 2.4GHz 频段
解决：路由器开启 2.4GHz 频段（或双频合一开关），或改用 2.4GHz 专属 SSID

⚠️ 事件回调不触发
原因：未 aos_register_event_filter 或未 aos_post_event 启动流程
解决：确认按官方骨架执行：注册过滤 → 启动固件任务 → 发送 INIT_DONE 事件

⚠️ 内存不足导致网络应用失败
原因：lwIP 缓冲区与固件任务占用大量 RAM，业务任务栈开太大
解决：业务任务栈按需设置（官方示例 main_entry 为 1024）；CODE_WIFI_ON_GOT_IP 回调可打印 xPortGetFreeHeapSize() 监控剩余内存

运行自检

按后续 连接 Wi-Fi 教程执行，串口依次出现 INIT DONE → MGMR DONE → connected → GOT IP 事件，即框架验证通过。

遇到问题？

如有其他问题，请到统一的提问与讨论区：Ai-Thinker Discussions