注意

这是最新开发分支的文档，可能包含尚未在发布版本中提供的功能。如果您在寻找特定版本的文档，请使用左侧的下拉菜单选择。

WLAN Offload 控制示例

概述

WLAN offload 框架用于固件负责 802.11 MAC 的 Wi-Fi 设备。RT-Thread WLAN、 NetMgmt 和 lwIP 仍是普通应用接口；libwlan_offload 则提供版本化的用户态控制 接口，适用于能力诊断、事件监控和完整 supplicant 集成。

相关源码：

src/rtsmart/rtsmart/kernel/rt-thread/components/drivers/wlan/offload/
src/rtsmart/libs/wlan_offload/
src/rtsmart/examples/peripheral/wlan_offload/

支持该框架的驱动可注册：

• phyN-sta 和 phyN-ap：RT-Thread WLAN 管理设备；

• wlanN 和 wlanNap：lwIP 网络接口；

• /dev/wlanctlN：可选的用户态控制设备。

N 由射频注册顺序决定。应用应查询名称，不应假设目标设备始终是 /dev/wlanctl0。

配置和构建

支持 offload 的 vendor 驱动会选择所需的内核选项。手工集成时相关选项为：

配置项	作用
RT_WLAN_OFFLOAD	通用 radio、VIF、命令、事件和 transport 框架
RT_WLAN_OFFLOAD_CONTROL	注册 /dev/wlanctlN 控制设备
RT_WLAN_OFFLOAD_SUPPLICANT	启用外部 supplicant 契约
RT_WLAN_OFFLOAD_EMBEDDED_WPA2	内核 WPA/WPA2/WPA3 Personal 路径
RT_WLAN_OFFLOAD_EMBEDDED_HOSTAPD	开放/WPA2-Personal SoftAP authenticator

在用户态示例配置中启用：

RTSMART_ENABLE_PERIPHERAL_EXAMPLES=y
RTSMART_PERIPHERAL_ENABLE_WLAN_OFFLOAD=y

完整构建会生成 wlan_offload.elf。也可以单独构建库：

make -C src/rtsmart/libs/wlan_offload

应用只包含安装后的 wlan_offload_client.h。不要包含私有的 wlan_offload_wire.h 或内核 wlan_offload_control_protocol.h。

示例命令

先用 RT-Smart shell 查看实际设备：

wifi devices

再运行诊断程序：

wlan_offload.elf /dev/wlanctl0 names
wlan_offload.elf /dev/wlanctl0 info
wlan_offload.elf /dev/wlanctl0 probe
wlan_offload.elf /dev/wlanctl0 scan
wlan_offload.elf /dev/wlanctl0 monitor

只连接一块 radio 时也可省略设备参数，默认使用 /dev/wlanctl0：

wlan_offload.elf info

各命令作用如下：

命令	说明
names	查询 radio index、control、STA 和 AP 名称
info	读取当前接口能力和固件版本，不主动启动 STA
probe	先通过 WLAN 管理路径启用 STA，再读取能力
scan	发起扫描并打印 scan result/done 事件
monitor	启用 STA 后无限阻塞，打印启动命令之后收到的事件

开启自动 STA 的驱动中，probe 是幂等诊断操作。monitor 会持续运行，使用 Ctrl+C 结束。

备注

控制设备是独占打开的。同一时间只能由一个进程持有；运行 monitor 时，其他 诊断程序或用户态 supplicant 无法打开同一个 /dev/wlanctlN。

客户端 API

典型生命周期：

#include <wlan_offload_client.h>

struct wlan_offload_handle *handle;
struct wlan_offload_names names;
struct wlan_offload_info info;

if (wlan_offload_open(&handle, "/dev/wlanctl0") != 0)
    return -1;

wlan_offload_get_names(handle, WLAN_OFFLOAD_INTERFACE_STATION, &names);
wlan_offload_get_info(handle, WLAN_OFFLOAD_INTERFACE_STATION, &info);

wlan_offload_close(handle);

公共 API 分组如下：

分组	接口
打开和查询	wlan_offload_open()、close()、get_fd()、get_info()、get_names()
接口和扫描	set_interface()、scan()、abort_scan()
连接控制	authenticate()、associate()、disconnect()
密钥	set_key()、delete_key()、set_default_key()
数据帧	send_mgmt()、send_eapol()
外部认证	external_auth_response()
事件	receive_event()

wlan_offload_receive_event() 的 timeout_ms 为 -1 时无限等待，为 0 时 非阻塞，大于零时按毫秒超时。收到 external-auth 事件后，supplicant 处理指定 AKM 交换，并把同一个 request_id 传给 wlan_offload_external_auth_response()。

信道相关结构使用完整 wlan_offload_channel，包含频段、主信道、宽度和中心 频率，不能简化为单个信道号。扫描安全类型使用公共 WLAN_OFFLOAD_SECURITY_* 常量，不要依赖内核枚举头文件。

示例边界

wlan_offload.elf 是诊断程序，不实现 WPA supplicant，也不会代替普通应用中的 NetMgmt。日常联网仍使用 wifi join、rt_wlan_* 或 NetMgmt。需要完整企业认证、 SAE H2E 等功能时，应让成熟的用户态 supplicant 链接 libwlan_offload，而不是 在应用中自行编码私有 wire protocol。