Wi-Fi 扫描#
本文介绍 WS53 STA 的基础扫描、定向扫描、异步事件处理和结果读取。当前 SDK 没有独立的扫描示例,完整流程可参考
src/application/samples/wifi/sta_sample/sta_sample.c。
学习目标#
使用 WS53 STA 接口扫描周围无线接入点。
在扫描完成事件后安全地读取、筛选和释放扫描结果。
根据 SSID、SSID 前缀、BSSID 或信道执行定向扫描。
案例说明#
扫描是异步操作。wifi_sta_scan() 或 wifi_sta_scan_advance() 返回成功,只表示扫描请求已被接受;应用必须等待 wifi_event_scan_state_changed 回调,再在任务上下文调用 wifi_sta_get_scan_info()。
sequenceDiagram
participant Task as 业务任务
participant WiFi as WS53 Wi-Fi
participant CB as 事件回调
Task->>WiFi: wifi_sta_enable()
Task->>WiFi: wifi_sta_scan()
WiFi-->>CB: wifi_event_scan_state_changed(state, size)
CB-->>Task: 更新状态/投递消息
Task->>WiFi: wifi_sta_get_scan_info(result, &num)
WiFi-->>Task: SSID/BSSID/RSSI/信道/安全类型
Task->>WiFi: wifi_sta_scan_result_clear()
关键接口#
接口 |
用途 |
|---|---|
|
发起全信道基础扫描 |
|
按指定 SSID、前缀、BSSID 或单一信道扫描 |
|
强制停止正在进行的 STA 扫描 |
|
读取服务保存的扫描结果 |
|
清空服务保存的扫描结果 |
|
注册扫描状态变化回调 |
接口和结构体定义参见 Wi-Fi Device API。
代码详解#
1. 注册扫描事件#
#include "wifi_device.h"
#include "wifi_event.h"
static volatile int g_scan_done;
static volatile int32_t g_scan_state;
static volatile int32_t g_scan_result_hint;
static void scan_state_changed(int32_t state, int32_t size)
{
g_scan_state = state;
g_scan_result_hint = size;
g_scan_done = 1;
}
static errcode_t scan_register_event(void)
{
wifi_event_stru event = {0};
event.wifi_event_scan_state_changed = scan_state_changed;
return wifi_register_event_cb(&event);
}
size 可用于日志或预估结果数量,但读取结果时仍要给 wifi_sta_get_scan_info() 传入实际数组容量。回调中不要分配大块内存、打印全部 AP 或直接发起连接。
2. 发起基础扫描#
static errcode_t scan_start(void)
{
if (wifi_is_wifi_inited() == 0) {
return ERRCODE_FAIL;
}
if (wifi_sta_enable() != ERRCODE_SUCC) {
return ERRCODE_FAIL;
}
g_scan_done = 0;
g_scan_result_hint = 0;
return wifi_sta_scan();
}
如果 STA 已经使能,无需重复调用 wifi_sta_enable()。扫描请求失败时不要等待完成标志,应立即进入错误处理或稍后重试。
3. 在任务中读取并筛选结果#
WS53 服务接口一次最多接收 64 项结果容量。下面沿用 sta_sample 的做法,在任务中申请结果数组。
#include <string.h>
#include "securec.h"
#include "soc_osal.h"
#define SCAN_RESULT_MAX 64
static int scan_read_result(const char *target_ssid)
{
uint32_t capacity = SCAN_RESULT_MAX;
uint32_t bytes = sizeof(wifi_scan_info_stru) * capacity;
wifi_scan_info_stru *result = osal_kmalloc(bytes, OSAL_GFP_ATOMIC);
int found = 0;
if (result == NULL) {
return 0;
}
(void)memset_s(result, bytes, 0, bytes);
if (wifi_sta_get_scan_info(result, &capacity) == ERRCODE_SUCC) {
for (uint32_t i = 0; i < capacity; i++) {
if (strcmp(result[i].ssid, target_ssid) == 0) {
found = 1;
/* 复制 BSSID、安全类型、信道等需要保留的字段。 */
break;
}
}
}
osal_kfree(result);
return found;
}
capacity 输入时表示数组可容纳的条目数,输出时表示实际返回数量,有效范围为 1~64。若结果超过数组容量,接口只返回容量范围内的数据。
不要只根据 SSID 判断唯一 AP。多个 AP 可能使用相同 SSID,漫游或选网时还应结合 BSSID、RSSI、安全类型和产品策略。SSID 数组最大长度固定,但业务代码仍应以合法字符串边界或显式长度处理外部数据。
4. 发起定向扫描#
wifi_sta_scan_advance() 支持以下扫描类型。
|
必填字段 |
说明 |
|---|---|---|
|
|
扫描指定的单一信道 |
|
|
精确匹配 SSID |
|
|
匹配指定 SSID 前缀 |
|
|
匹配指定 AP 的 BSSID |
WIFI_BASIC_SCAN 应调用 wifi_sta_scan(),不能作为 wifi_sta_scan_advance() 的参数。
按 SSID 扫描示例如下。
static errcode_t scan_by_ssid(const char *ssid)
{
wifi_scan_params_stru param = {0};
size_t ssid_len = strlen(ssid);
if ((ssid_len == 0) || (ssid_len >= sizeof(param.ssid))) {
return ERRCODE_FAIL;
}
if (memcpy_s(param.ssid, sizeof(param.ssid),
ssid, ssid_len + 1) != EOK) {
return ERRCODE_FAIL;
}
param.ssid_len = (int8_t)ssid_len;
param.scan_type = WIFI_SSID_SCAN;
g_scan_done = 0;
return wifi_sta_scan_advance(¶m);
}
按信道扫描只需设置 scan_type = WIFI_CHANNEL_SCAN 和 channel_num。接口实现接受 1~14,但实际可用信道必须同时符合当前国家码、射频法规和产品配置。
5. 停止扫描和清理缓存#
static void scan_request_stop(void)
{
if (g_scan_done == 0) {
(void)wifi_sta_scan_stop();
}
}
static void scan_clear_result(void)
{
/* 等待完成/停止事件并结束本轮结果处理后再调用。 */
(void)wifi_sta_scan_result_clear();
}
强制停止扫描后仍应正确处理扫描状态事件,避免业务状态机永久停留在“扫描中”。读取完成后,如果不再需要旧结果,可调用 wifi_sta_scan_result_clear() 释放服务侧缓存;下一次扫描前也可按产品策略清理,避免误用上一轮结果。
扫描结果字段#
wifi_scan_info_stru 的常用字段如下。
字段 |
含义 |
|---|---|
|
接入点名称 |
|
接入点 MAC 地址 |
|
安全类型;构造连接参数时应使用与目标 AP 匹配的值 |
|
接收信号强度,数值越接近 0 通常表示信号越强 |
|
频带信息 |
|
AP 工作信道 |
运行与验证#
使能并运行
sta_sample,确认日志出现Scan start和Scan done。在
example_get_match_network()中检查wifi_sta_get_scan_info()返回数量和目标 SSID。分别验证基础扫描、指定信道、精确 SSID、SSID 前缀和 BSSID 扫描。
准备重名 SSID,确认业务能通过 BSSID、RSSI 和安全类型选择正确 AP。
验证无 AP、隐藏 SSID、大量 AP、扫描请求失败和扫描中止场景。
扫描期间会占用射频资源。STA 已连接或与 SoftAP/P2P 并发时,应根据时延和信道策略限制扫描频率。
连续执行多轮扫描并清理结果,检查任务内存和服务侧结果缓存没有持续增长。
构建、烧录和串口日志查看方法参见快速入门。