WifiScan 开发指导_Rev1.1
修订记录
版本 |
日期 |
作者 |
修订内容 |
|---|---|---|---|
Rev1.0 |
2023-09-12 |
WTY |
创建文档 |
Rev1.1 |
2024-03-25 |
sxx |
更改文档名称 |
1 简介
本文档介绍 LTE-EC71X Wifi Scan 接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_wifiscan/liot_wifiscan.h 文件声明。
新增
2 API 函数概览
函数 |
说明 |
|---|---|
|
启用 Wi-Fi Scan |
|
禁用 Wi-Fi Scan |
|
配置 Wi-Fi Scan 扫描参数 |
|
进行 Wi-Fi Scan 同步模式扫描 |
|
开始 Wi-Fi Scan 异步模式扫描 |
|
注册回调函数 |
说明：
若无特别说明，本文档所述的 Wi-Fi Scan API 接口函数均不支持并发调用，并且不可在任何回调函数中调用所述函数，否则会对后续消息的处理造成影响。
不支持在 LTE 网络做数据业务时启用 Wi-Fi Scan。
3 类型说明
3.1 liot_wifiscan_errcode_e
Wi-Fi Scan 错误码定义枚举如下：
声明
typedef enum
{
LIOT_WIFISCAN_SUCCESS = 0,
LIOT_WIFISCAN_EXECUTE_ERR = 1 | LIOT_WIFISCAN_ERRCODE_BASE,
LIOT_WIFISCAN_MEM_ADDR_NULL_ERR,
LIOT_WIFISCAN_INVALID_PARAM_ERR,
LIOT_WIFISCAN_SEMAPHORE_WAIT_ERR,
LIOT_WIFISCAN_MUTEX_TIMEOUT_ERR,
LIOT_WIFISCAN_OPEN_FAIL,
LIOT_WIFISCAN_BUSY_ERR,
LIOT_WIFISCAN_ALREADY_OPEN_ERR,
LIOT_WIFISCAN_NOT_OPEN_ERR,
LIOT_WIFISCAN_HW_OCCUPIED_ERR,
LIOT_WIFISCAN_NO_SET_CB_ERR,
} liot_wifiscan_errcode_e;
参数
LIOT_WIFISCAN_SUCCESS：执行成功
LIOT_WIFISCAN_EXECUTE_ERR：执行失败
LIOT_WIFISCAN_MEM_ADDR_NULL_ERR：内存申请失败
LIOT_WIFISCAN_INVALID_PARAM_ERR：无效参数
LIOT_WIFISCAN_SEMAPHORE_WAIT_ERR：等待信号量异常
LIOT_WIFISCAN_MUTEX_TIMEOUT_ERR：获取 Mutex 异常
LIOT_WIFISCAN_OPEN_FAIL：Wi-Fi Scan 启用异常
LIOT_WIFISCAN_BUSY_ERR：Wi-Fi Scan 尝试重复启用错误
LIOT_WIFISCAN_ALREADY_OPEN_ERR：Wi-Fi Scan 未启用
LIOT_WIFISCAN_NOT_OPEN_ERR：Wi-Fi Scan 忙碌（如正在进行扫描）
LIOT_WIFISCAN_HW_OCCUPIED_ERR：硬件被占用
LIOT_WIFISCAN_NO_SET_CB_ERR：未设置回调函数
3.2 liot_wifi_ap_info_s
扫描的 Wi-Fi AP 具体信息结构体定义如下：
声明
typedef struct
{
UINT8 bssidNum; // rssi number
UINT8 rsvd;
UINT8 ssidHexLen[LIOT_WIFI_SCAN_MAX_AP_CNT]; // the length of Wifi SSID Name hex data
UINT8 ssidHex[LIOT_WIFI_SCAN_MAX_AP_CNT][32]; // the hex data of WiFi SSID Name
INT8 rssi[LIOT_WIFI_SCAN_MAX_AP_CNT]; // rssi value of scanned bssid
UINT8 channel[LIOT_WIFI_SCAN_MAX_AP_CNT]; // record channel index of bssid, 2412MHz ~ 2472MHz correspoding to 1 ~ 13
UINT8 bssid[LIOT_WIFI_SCAN_MAX_AP_CNT][6]; // mac address is fixed to 6 digits
} liot_wifi_ap_info_s;
参数
bssidNum：扫描到的 WIFI AP 数量
rsvd：保留参数
ssidHexLen：ssid 长度
ssidHex：ssid 数据
rssi：AP 的信号强度
channel：WIFI AP 的通道
bssid：WIFI AP 的 MAC 地址
3.3 liot_wifiscan_callback
Wi-Fi Scan 回调函数指针定义如下：
声明
typedef void (*liot_wifiscan_callback)(liot_wifiscan_ind_msg_s *msg_buf);
3.4 liot_wifiscan_ind_msg_s
内核通过回调函数通知 APP 侧的信息结构体定义如下：
声明
typedef struct
{
uint32_t msg_err_code;
void *msg_data;
} liot_wifiscan_ind_msg_s;
参数
msg_err_code：执行结果码，请参考 3.1 节说明。
msg_data ：通知的具体数据，可以通过转换成 liot_wifi_ap_info_s 类型结构体读取数据
4 API 函数详解
4.1 liot_wifiscan_open
该函数用于启用 Wi-Fi Scan。
声明
liot_wifiscan_errcode_e liot_wifiscan_open(void);
参数
无
返回值
liot_wifiscan_errcode_e：执行结果码，请参考3.1 节说明。
4.2 liot_wifiscan_close
该函数用于禁用 Wi-Fi Scan。
声明
liot_wifiscan_errcode_e liot_wifiscan_close(void);
参数
无
返回值
liot_wifiscan_errcode_e：执行结果码，请参考 3.1 节说明。
4.3 liot_wifiscan_option_set
该函数用于配置 Wi-Fi Scan 扫描参数。
声明
liot_wifiscan_errcode_e liot_wifiscan_option_set(int32 maxTimeOut,
uint8 round,
uint8 maxBssidNum,
uint8 scanTimeOut,
uint8 wifiPriority);
参数
maxTimeOut：[In] 如果超过时间没有扫描结果，则会报错，范围：4000 ~ 255000，默认值：12000，单位：毫秒；
round：[In] Wi-Fi Scan 的轮数，范围：1~3，默认值：1；
maxBssidNum：[In] 期望扫描到的 Wi-Fi 热点个数，范围：4~10，默认值：5；
scanTimeOut：[In] Wi-Fi Scan 的 RRC 轮询超时时间，范围：0~255，默认值：5，单位：秒；
wifiPriority：[In] Wi-Fi Scan 优先参数， 0：数据优先，1：Wi-Fi Scan 优先。（说明：数据优先模式下，只会在CFUN=0或UE处于IDLE状态下才会开始wifi扫描；Wi-Fi Scan 优先模式下，如果此时UE在连接态期间，不管是否有数据业务，都会打断当前连接态返回idle， 发起wifi搜网）
返回值
liot_wifiscan_errcode_e：执行结果码，请参考 3.1节说明。
4.4 liot_wifiscan_do
该函数用于进行 Wi-Fi Scan 同步模式扫描。
声明
liot_wifiscan_errcode_e liot_wifiscan_do(liot_wifi_ap_info_s *p_ap_infos);
参数
p_ap_infos：[Out] 扫描到的所有 AP 的信息。详见3.2 liot_wifi_ap_info_s。
返回值
liot_wifiscan_errcode_e：执行结果码，请参考 3.1 节说明。
4.5 liot_wifiscan_register_cb
该函数用于注册 Wifi-Scan 异步模式回调函数。
声明
liot_wifiscan_errcode_e liot_wifiscan_register_cb(liot_wifiscan_callback wifiscan_cb);
参数
wifiscan_cb：[In] 中断回调函数，在调用异步扫描函数后，扫描完成时会进入该回调函数。回调函数格式详见3.3 liot_wifiscan_callback
返回值
liot_wifiscan_errcode_e：执行结果码，请参考 3.1 节说明。
4.6 liot_wifiscan_async
该函数用于开始 Wi-Fi Scan 异步模式扫描。
声明
liot_wifiscan_errcode_e liot_wifiscan_async(void);
参数
无
返回值
liot_wifiscan_errcode_e：执行结果码，请参考3.1节说明。
5 代码示例
示例代码参考 examples/demo/src/demo_wifiscan.c 文件。
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "lierda_app_main.h"
#include "liot_os.h"
#include "liot_type.h"
#include "liot_wifiscan.h"
/*===========================================================================
* Functions
===========================================================================*/
void liot_wifiscan_ap_info_output(liot_wifi_ap_info_s *p_ap_infos)
{
if (NULL == p_ap_infos)
{
return;
liot_trace("result NULL");
}
for (uint16 i = 0; i < p_ap_infos->bssidNum; i++)
{
liot_trace("WIFISCAN:(-,-,%d,\"%02X:%02X:%02X:%02X:%02X:%02X\",%d",
p_ap_infos->rssi[i],
p_ap_infos->bssid[i][0],
p_ap_infos->bssid[i][1],
p_ap_infos->bssid[i][2],
p_ap_infos->bssid[i][3],
p_ap_infos->bssid[i][4],
p_ap_infos->bssid[i][5],
p_ap_infos->channel[i]);
}
}
// all memory of msg_buf and it's sub item will be released by core after the call of callback.
void liot_wifiscan_app_callback(liot_wifiscan_ind_msg_s *msg_buf)
{
liot_wifiscan_close();
if ((LIOT_WIFISCAN_SUCCESS == msg_buf->msg_err_code) && (NULL != msg_buf->msg_data))
{
liot_wifi_ap_info_s *scan_result = msg_buf->msg_data;
liot_trace("ap_cnt=%d", scan_result->bssidNum);
liot_wifiscan_ap_info_output(scan_result);
}
}
// to start a async scan
void liot_wifiscan_async_start(void)
{
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_option_set(LIOT_WIFI_SCAN_TIME_RevAL_DEF,
LIOT_WIFI_SCAN_DEFAULT_ROUND,
LIOT_WIFI_SCAN_DEFAULT_AP_CNT,
LIOT_WIFI_SCAN_SCANTIMEOUT_VAL_DEF,
LIOT_WIFI_SCAN_PRIORITY_VAL_DEF)
)
{
liot_trace("option set err");
return;
}
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_register_cb(liot_wifiscan_app_callback))
{
liot_trace("register cb err");
return;
}
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_open())
{
liot_trace("device open err");
return;
}
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_async())
{
liot_wifiscan_close();
liot_trace("to do a async scan err");
return;
}
}
// complete flow to do one time scan: option->open->scan->close->output
void liot_wifiscan_synchro_complete_flow(void)
{
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_option_set(LIOT_WIFI_SCAN_TIME_VAL_DEF,
LIOT_WIFI_SCAN_DEFAULT_ROUND,
LIOT_WIFI_SCAN_DEFAULT_AP_CNT,
LIOT_WIFI_SCAN_SCANTIMEOUT_VAL_DEF,
LIOT_WIFI_SCAN_PRIORITY_VAL_DEF))
{
liot_trace("option set err");
return;
}
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_open())
{
liot_trace("device open err");
return;
}
liot_wifi_ap_info_s ap_infos = {0};
if (LIOT_WIFISCAN_SUCCESS != liot_wifiscan_do(&ap_infos))
{
liot_wifiscan_close();
liot_trace("to do a scan err");
return;
}
liot_trace("ap_cnt=%d", ap_infos.bssidNum);
liot_wifiscan_close();
liot_wifiscan_ap_info_output(&ap_infos);
}
void liot_wifiscan_demo_thread(void *argv)
{
liot_trace("==========wifiscandemo start==========");
liot_rtos_task_sleep_ms(1000);
while (1)
{
liot_wifiscan_synchro_complete_flow();
liot_rtos_task_sleep_ms(5000);
liot_wifiscan_async_start();
liot_rtos_task_sleep_ms(15000);
}
}
运行结果：
