版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_wifiscan/

一、概述

xt_wifiscan 是 xtiny 平台的 Wi-Fi 扫描模块，提供设置回调、启动扫描、停止扫描三个接口。用户通过 set_cb 注册回调，调用 start 发起扫描，扫描结果异步推送到回调中。

设计理念： 回调驱动 + 消息通道绑定 。不同平台通过各自的消息总线或 AT 命令通道实现扫描，模块统一封装为"注册监听 → 发请求 → 等回调"的异步模式。

1.1 设计原则

先设回调，再启动 ：扫描结果通过回调异步返回，启动前必须先注册回调
通道独立 ：每个平台可绑定不同的消息通道，上层接口不变
一次一回调 ：启动一次扫描产生一次回调，回调后结果数据生命周期仅在此次回调内有效
线程安全 ：回调指针的读写由临界区（ XT_CRIT_* ）保护

1.2 依赖

依赖	用途
xt_error.h	错误码类型（ xt_err_t ）
xt_safe.h	临界区宏（ XT_CRIT_* ）
平台消息通道	具体实现依赖

二、核心概念

2.1 异步扫描流程

用户代码                xt_wifiscan                平台消息通道
  |                        |                            |
  |-- set_cb(my_cb) ----->| 注册回调 + 绑定 IND 监听    |
  |                        |                            |
  |-- start(mask, n, t) ->| 校验参数                    |
  |                        |-- REQ 消息 ---------------->|
  |                        |<-- CNF 消息 ----------------|  扫描启动完成
  |<----- XT_EOK ---------|                            |
  |                        |                            |
  |                        |<-- IND 消息 ----------------|  扫描结果到达
  |                        |-- 解析 + 组装 ------------>|  
  |<-- my_cb(info) --------|                            |  回调用户

注意： start 返回 XT_EOK 只表示扫描请求已发出，不代表扫描完成。结果通过回调异步送达。

2.2 回调生命周期

回调函数中传入的 xt_wifiscan_info_t *info 指针在 回调返回后立即释放 。如果需要在回调外使用结果数据，必须在回调内深拷贝。

2.3 扫描参数语义

参数	含义	典型值
channel_mask = 0 或 0xFFFFFFFF	扫描全部信道	—
channel_mask = 0x0006	仅扫描信道 1、2	bit1\|bit2
scannum	所有信道总共上报的 AP 最大个数	1 ~ 20
timeout_ms	一次扫描所有信道的总超时	>= 1000ms

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_wifiscan（Wi-Fi 扫描）。

3.1 回调管理

函数签名	说明
xt_err_t xt_wifiscan_set_cb(xt_wifiscan_cb_t cb)	设置扫描完成回调。传 NULL 取消注册

3.2 扫描控制

函数签名	说明
xt_err_t xt_wifiscan_start(uint32_t channel_mask, uint32_t scannum, uint32_t timeout_ms)	启动 Wi-Fi 扫描
xt_err_t xt_wifiscan_stop(void)	停止正在进行的扫描

3.3 回调类型

类型签名	说明
typedef void (xt_wifiscan_cb_t)(xt_wifiscan_info_t info)	扫描完成回调函数类型

3.4 数据结构

结构体	说明
xt_wifiscan_cell_info_t	单个 AP 信息： bssid / ssid / rssi / channel_num
xt_wifiscan_info_t	扫描结果： bssid_num + list[] 数组

四、编译配置

宏	默认值	说明
XT_WIFISCAN_AP_NUM_MAX	20	扫描结果中 AP 的最大数量
XT_WIFISCAN_SSID_SIZE	32	SSID 名称缓冲区长度
XT_WIFISCAN_MAC_SIZE	6	MAC 地址长度（固定值）

五、常见模式

5.1 基本扫描流程

static void my_scan_cb(xt_wifiscan_info_t *info)
{
    xt_printf("found %d APs:\n", info->bssid_num);
    for (int i = 0; i < info->bssid_num; i++) {
        xt_printf("  ch=%ld rssi=%ld ssid=%s\n",
                  info->list[i].channel_num,
                  info->list[i].rssi,
                  info->list[i].ssid);
    }
}
 
void do_wifi_scan(void)
{
    xt_wifiscan_set_cb(my_scan_cb);
    xt_wifiscan_start(0, 10, 5000);  // 全信道，最多10个AP，超时5秒
}

5.2 停止扫描并取消回调

xt_wifiscan_stop();

xt_wifiscan_set_cb(NULL); // 同时注销监听

xt_wifiscan_stop

xt_err_t xt_wifiscan_stop(void)

停止 Wi-Fi 扫描

5.3 保存回调结果（深拷贝）

static xt_wifiscan_info_t s_cached_info;
 
static void save_and_process(xt_wifiscan_info_t *info)
{
    memcpy(&s_cached_info, info, sizeof(xt_wifiscan_info_t));
    // 回调返回后 info 会被释放，但 s_cached_info 仍有效
}
 
void later_process(void)
{
    for (int i = 0; i < s_cached_info.bssid_num; i++) {
        /* 使用 s_cached_info.list[i] */
    }
}

六、反模式

反模式	问题	正确做法
未设回调就调 start	扫描结果被丢弃，无法获取	先 set_cb 再 start
回调内长时间阻塞	阻塞消息通道，后续扫描结果丢失	回调内仅记录数据，设置标志后快速返回
保存回调传来的指针	回调返回后指针被释放，成为野指针	回调内深拷贝到自己的 buffer
start 后立即 stop	结果不确定，可能 CNF 未到就发 STOP	至少等一次回调后再 stop

七、已知行为与限制

行为	说明
扫描结果列表不排序	AP 按上报顺序排列，不按信号强度排序
scannum = 0 立即返回 XT_EINVAL	必须至少请求 1 个 AP
timeout_ms < 1000 返回 XT_EINVAL	平台有最小超时限制
scannum > 20 返回 XT_EINVAL	超过 XT_WIFISCAN_AP_NUM_MAX 默认值
回调在消息通道线程上下文执行	不可调用阻塞型 API

八、示例

示例代码位于 examples/platform_specific/lm620/wifiscan/。

cd examples/platform_specific/lm620/wifiscan
xt --target lm620/r4f4 fullclean build
xt --target lm620/r4f4 run