Wi-Fi 监听模式#
WS53 通过混杂模式接收指定类型的 802.11 空口帧,用于现场诊断、帧统计和协议分析。
学习目标#
为已经使能的 WS53 Wi-Fi 接口配置混杂模式。
使用
wifi_ptype_filter_stru控制上报的报文类型。在高频接收回调中安全检查并解析 802.11 帧头。
正确关闭监听并释放应用侧资源。
案例说明#
WS53 当前没有 src/application/samples/wifi/ 下的独立监听模式案例工程。本页基于 Wi-Fi Device API 给出集成方法,代码需要加入产品的诊断任务或自定义 Sample。
开启混杂模式后,符合过滤条件的帧会通过接收回调上报。回调运行频率取决于当前信道的空口流量,不能在回调中逐帧打印、动态分配大块内存或执行阻塞操作。
sequenceDiagram
participant A as Diagnostic Task
participant W as WS53 Wi-Fi
participant Q as Packet Queue
A->>W: 使能 STA/SoftAP/P2P 接口
A->>W: wifi_set_promis_rx_pkt_cb()
A->>W: wifi_set_promis_mode(iftype, 1, &filter)
W-->>A: recv_buf / frame_len / rssi
A->>Q: 复制必要数据或更新统计
Q-->>A: 普通任务解析和输出
A->>W: wifi_set_promis_mode(iftype, 0, NULL)
关键配置#
调用前必须完成
wifi_init(),并使能与iftype对应的接口。非关联诊断场景可使用
wifi_set_channel()设置监听信道;STA 已关联时,实际工作信道由所连接 AP 决定。从最小过滤集合开始,确认业务需要后再增加报文类型,避免无关帧占用 CPU 和队列。
回调和消费任务之间需要有明确的缓冲上限、丢包计数和停止同步机制。
wifi_ptype_filter_stru 的 WS53 字段如下:
字段 |
置 1 后接收 |
|---|---|
|
组播或广播数据帧 |
|
单播数据帧 |
|
组播或广播管理帧 |
|
单播管理帧 |
|
Beacon、Probe 等定制上报帧 |
这些成员必须使用带 _en 后缀的 WS53 字段名。监听模式不会自动切换或轮询信道,也不能保证应用获得解密后的业务数据。
代码详解#
1. 准备目标接口#
混杂模式依附于已使能的 Wi-Fi 接口。以下示例使用 STA 接口:
#include "wifi_device.h"
if (wifi_is_wifi_inited() == 0) {
/* 等待系统 Wi-Fi 初始化完成。 */
return ERRCODE_FAIL;
}
if (wifi_sta_enable() != ERRCODE_SUCC) {
return ERRCODE_FAIL;
}
如果应用已经通过 STA 案例使能 wlan0,不要重复调用 wifi_sta_enable()。未关联情况下需要固定监听信道时,可在开启混杂模式前调用:
if (wifi_set_channel(IFTYPE_STA, 6) != ERRCODE_SUCC) {
return ERRCODE_FAIL;
}
信道必须符合当前国家码和区域法规。与 STA、SoftAP 或 P2P 并发时,应以实际业务接口的工作信道为准。
2. 注册混杂模式回调#
WS53 回调签名为 int32_t (*)(void *recv_buf, int32_t frame_len, int8_t rssi):
static volatile uint32_t g_mgmt_count;
static volatile uint32_t g_data_count;
static volatile uint32_t g_invalid_count;
static int32_t promis_rx_cb(void *recv_buf, int32_t frame_len, int8_t rssi)
{
const uint8_t *frame = (const uint8_t *)recv_buf;
uint16_t frame_control;
uint8_t type;
(void)rssi;
if (frame == NULL || frame_len < 2) {
g_invalid_count++;
return ERRCODE_FAIL;
}
/* 802.11 Frame Control 为小端字段,逐字节读取可避免非对齐访问。 */
frame_control = (uint16_t)frame[0] | ((uint16_t)frame[1] << 8);
type = (uint8_t)((frame_control >> 2) & 0x3);
if (type == 0) {
g_mgmt_count++;
} else if (type == 2) {
g_data_count++;
}
return ERRCODE_SUCC;
}
if (wifi_set_promis_rx_pkt_cb(promis_rx_cb) != ERRCODE_SUCC) {
return ERRCODE_FAIL;
}
示例只读取 Frame Control 的 type。如需解析 MAC 地址、SSID 或其他 Information Element,必须先按照帧类型和子类型检查最小长度,再逐字段验证边界。不要直接把 recv_buf 强制转换为带对齐要求的 C 结构体。
实际产品通常把有限长度的帧头复制到预分配队列,由普通任务完成解析和日志输出。队列已满时应丢弃并计数,不能在回调中等待消费者。
3. 配置过滤器并开启监听#
下面只接收管理类和定制上报帧:
wifi_ptype_filter_stru filter = {
.mdata_en = 0,
.udata_en = 0,
.mmngt_en = 1,
.umngt_en = 0,
.custom_en = 1,
};
if (wifi_set_promis_mode(IFTYPE_STA, 1, &filter) != ERRCODE_SUCC) {
wifi_set_promis_rx_pkt_cb(NULL);
return ERRCODE_FAIL;
}
IFTYPE_STA 必须与实际使能的接口一致。使用 SoftAP 或 P2P 接口时,应传入对应的 wifi_if_type_enum,并确认目标构建包含该接口能力。
4. 关闭监听#
停止时先阻止新帧上报,再注销回调,最后等待消费任务处理或丢弃队列中的剩余数据:
errcode_t ret = wifi_set_promis_mode(IFTYPE_STA, 0, NULL);
wifi_set_promis_rx_pkt_cb(NULL);
if (ret != ERRCODE_SUCC) {
/* 记录关闭失败,避免立即释放仍可能被访问的上下文。 */
return ret;
}
关闭混杂模式不会自动关闭 STA/SoftAP/P2P 接口。接口是否继续保留应由上层业务决定。
只需要特定管理帧时,也可评估 wifi_set_mgmt_frame_rx_cb(),避免同时开启两条重复的报文上报通道。
案例操作指导#
在自定义诊断工程中加入回调、过滤器和启停函数,构建并烧录 WS53。
使能目标接口并选择合法信道,确认回调注册和混杂模式开启均返回成功。
先只开启一种过滤类型,使用附近 AP 或终端产生 Beacon、Probe 或业务流量。
在普通任务中输出帧类型计数、RSSI 和队列丢包数,确认关闭后计数不再增长。
分别验证高流量、弱信号、队列满、切换信道、重复启停和业务接口并发场景。
监听模式会增加射频、CPU、内存和日志负载,并可能影响正常 Wi-Fi 业务。捕获内容还可能包含其他设备的信息,使用时应遵守当地法规、隐私和数据安全要求。构建与烧录方法参见快速入门。