全部文档
OneOS简介 硬件支持 编译构造工具 API参考文档 高级语言 用户编程手册 应用笔记 FAQ

WLAN设备


API列表

WLAN 初始化

接口 说明
os_wlan_init() 初始化连接管理器
os_wlan_set_mode() 设置工作模式
os_wlan_get_mode() 获取设备工作模式

os_wlan_init

该函数对连接管理器进行初始化,函数原型如下:

int os_wlan_init(void);
参数 说明
返回 说明
0 执行成功

os_wlan_set_mode

该函数用于设置 WLAN 设备的工作模式,函数原型如下:

os_err_t os_wlan_set_mode(const char *dev_name, os_wlan_mode_t mode);
参数 说明
dev_name 设备名字
mode 工作模式
返回 说明
OS_EOK 设置成功
OS_ERROR 设置失败

WLAN 设备工作模式如下:

typedef enum
{
    OS_WLAN_NONE,
    OS_WLAN_STATION,
    OS_WLAN_AP,
    OS_WLAN_MODE_MAX
} os_wlan_mode_t;

os_wlan_get_mode

该函数用于查询 WLAN 设备的工作模式,函数原型如下:

os_wlan_mode_t os_wlan_get_mode(const char *dev_name);
参数 说明
dev_name 设备名字
返回 说明
OS_WLAN_NONE 设备停止工作
OS_WLAN_STATION 无线终端模式
OS_WLAN_AP 无线接入服务模式

WLAN 连接

接口 说明
os_wlan_connect() 连接热点
os_wlan_connect_adv() 无阻塞连接热点
os_wlan_disconnect() 断开热点
os_wlan_is_connected() 获取连接标志
os_wlan_is_ready() 获取就绪标志
os_wlan_get_info() 获取连接信息
os_wlan_get_rssi() 获取信号强度
os_wlan_config_autoreconnect() 启动/停止自动重连
os_wlan_get_autoreconnect_mode() 获取自动重连模式

os_wlan_connect

该函数用于连接热点,连接成功或失败后才会返回,期间会阻塞调用者,函数原型如下:

os_err_t os_wlan_connect(const char *ssid, const char *password);
参数 说明
ssid 热点的名字
password 热点密码,无密码传空
返回 说明
OS_EOK 连接成功
OS_ERROR 连接失败

os_wlan_connect_adv

该函数用于连接热点,函数原型如下:

os_err_t os_wlan_connect_adv(struct os_wlan_info *info, const char *password);
参数 说明
info 连接信息
password 热点密码,无密码传空
返回 说明
OS_EOK 执行成功
OS_ERROR 执行失败

连接参数可通过扫描获得或手动指定,返回值表示连接动作是否开始执行。

连接成功与否需要主动查询或设置回调通知。

连接信息必须配置的项有securityssid。完整配置如下:

struct os_wlan_info
{
    /* security type */
    os_wlan_security_t security;
    /* 2.4G/5G */
    os_802_11_band_t band;
    /* maximal data rate */
    os_uint32_t datarate;
    /* radio channel */
    os_int16_t channel;
    /* signal strength */
    os_int16_t  rssi;
    /* ssid */
    os_wlan_ssid_t ssid;
    /* hwaddr */
    os_uint8_t bssid[OS_WLAN_BSSID_MAX_LENGTH];
    os_uint8_t hidden;
};

安全模式如下所示:

typedef enum
{
    SECURITY_OPEN           = 0,                                                /* Open security                           */
    SECURITY_WEP_PSK        = WEP_ENABLED,                                      /* WEP Security with open authentication   */
    SECURITY_WEP_SHARED     = (WEP_ENABLED | SHARED_ENABLED),                   /* WEP Security with shared authentication */
    SECURITY_WPA_TKIP_PSK   = (WPA_SECURITY  | TKIP_ENABLED),                   /* WPA Security with TKIP                  */
    SECURITY_WPA_AES_PSK    = (WPA_SECURITY  | AES_ENABLED),                    /* WPA Security with AES                   */
    SECURITY_WPA2_AES_PSK   = (WPA2_SECURITY | AES_ENABLED),                    /* WPA2 Security with AES                  */
    SECURITY_WPA2_TKIP_PSK  = (WPA2_SECURITY | TKIP_ENABLED),                   /* WPA2 Security with TKIP                 */
    SECURITY_WPA2_MIXED_PSK = (WPA2_SECURITY | AES_ENABLED | TKIP_ENABLED),     /* WPA2 Security with AES & TKIP           */
    SECURITY_WPS_OPEN       = WPS_ENABLED,                                      /* WPS with open security                  */
    SECURITY_WPS_SECURE     = (WPS_ENABLED | AES_ENABLED),                      /* WPS with AES security                   */
    SECURITY_UNKNOWN        = -1,                                               /* May be returned by scan function if security is unknown.
                                                                                    Do not pass this to the join function! */
} os_wlan_security_t;

os_wlan_disconnect

该函数用于断开 WLAN 连接,返回值表示是否成功断开,函数原型如下:

os_err_t os_wlan_disconnect(void);
参数 说明
返回 说明
OS_EOK 断开成功
OS_ERROR 断开失败

os_wlan_is_connected

该函数用于查询 WLAN 是否建立连接,函数原型如下:

os_bool_t os_wlan_is_connected(void);
参数 说明
返回 说明
OS_TRUE 已经连接
OS_FALSE 没有连接

os_wlan_is_ready

该函数用于查询连接是否就绪,函数原型如下:

os_bool_t os_wlan_is_ready(void);
参数 说明
返回 说明
OS_TRUE 已经就绪
OS_FALSE 没有就绪

一般的,获取到 IP 表示已经准备就绪,可以传输数据。

os_wlan_get_info

该函数用于获取详细的连接信息,可获取热点名字、通道、信号强度、安全类型等,函数原型如下:

os_err_t os_wlan_get_info(struct os_wlan_info *info);
参数 说明
info info 对象
返回 说明
OS_EOK 获取成功
OS_ERROR 获取失败

os_wlan_get_rssi

该函数用于获得信号强度,函数原型如下:

int os_wlan_get_rssi(void);
参数 说明
返回 说明
负数 信号强度,值越大信号越强
0 未连接

os_wlan_config_autoreconnect

该函数用于开启或关闭自动重连模式,函数原型如下:

void os_wlan_config_autoreconnect(os_bool_t enable);
参数 说明
enable 开关:OS_TRUE-开启; OS_FALSE-关闭
返回 说明
执行成功

os_wlan_get_autoreconnect_mode

该函数用于查询自动重连是否启动,函数原型如下:

os_bool_t os_wlan_get_autoreconnect_mode(void);
参数 说明
返回 说明
OS_TRUE 启动
OS_FALSE 未启动

WLAN 扫描

接口 说明
os_wlan_scan() 异步扫描
os_wlan_scan_sync() 同步扫描
os_wlan_scan_with_info() 条件扫描
os_wlan_scan_get_info_num() 获取热点个数
os_wlan_scan_get_info() 拷贝热点信息
os_wlan_scan_get_result() 获取扫描缓存
os_wlan_scan_result_clean() 清理扫描缓存
os_wlan_find_best_by_cache() 查找最佳热点

os_wlan_scan

该函数用于启动无线热点扫描,扫描完成需要程序进程查询,或者通过回调进行通知,函数原型如下:

os_err_t os_wlan_scan(void);
参数 说明
返回 说明
OS_EOK 启动扫描成功
OS_ERROR 启动扫描失败

os_wlan_scan_sync

该函数用于同步扫描热点,完成之后直接返回扫描结果,函数原型如下:

struct os_wlan_scan_result *os_wlan_scan_sync(void);
参数 说明
返回 说明
扫描结果 热点信息和数量
OS_NULL 扫描失败

os_wlan_scan_with_info

该函数用于同步条件扫描。根据传入的参数进行过滤,可用于扫描指定的 SSID,函数原型如下:

struct os_wlan_scan_result *os_wlan_scan_with_info(struct os_wlan_info *info);
参数 说明
info 通过 info 指定限定条件
返回 说明
扫描结果 热点信息和数量
OS_NULL 扫描失败

os_wlan_scan_get_info_num

该函数返回扫描到的热点数量,函数原型如下:

int os_wlan_scan_get_info_num(void);
参数 说明
返回 说明
数量 热点数量

os_wlan_scan_get_info

该函数用于拷贝获取扫描结果,函数原型如下:

int os_wlan_scan_get_info(struct os_wlan_info *info, int num);
参数 说明
info info 缓存,用于保存拷贝结果
num info 个数
返回 说明
数量 实际拷贝的个数

os_wlan_scan_get_result

该函数用于获取扫描结果临时缓存指针,函数原型如下:

struct os_wlan_scan_result *os_wlan_scan_get_result(void);
参数 说明
返回 说明
扫描缓存指针 该指针不安全,仅作临时访问

os_wlan_scan_result_clean

该函数用于清空扫描缓存,函数原型如下:

void os_wlan_scan_result_clean(void);
参数 说明
返回 说明

os_wlan_find_best_by_cache

该函数用于指定 SSID ,在扫描缓存中查找信号最好的热点信息,函数原型如下:

os_bool_t os_wlan_find_best_by_cache(const char *ssid, struct os_wlan_info *info);
参数 说明
ssid 指定需要查询的 ssid
info 保存查询到的热点信息
返回 说明
OS_FALSE 没有查到
OS_TRUE 查到

WLAN 热点

接口 说明
os_wlan_start_ap() 启动热点
os_wlan_ap_is_active() 获取启动标志
os_wlan_ap_stop() 停止热点
os_wlan_ap_get_info() 获取热点信息

os_wlan_dev_ap_start

该函数用于阻塞式启动热点,返回值表示是否启动成功,函数原型如下:

os_err_t os_wlan_dev_ap_start(struct os_wlan_device *device, struct os_wlan_info *info, const char *password, int password_len);
参数 说明
device 设备名字
info 热点信息
password 热点密码
password_len 热点密码长度
返回 说明
OS_EOK 启动成功
OS_ERROR 启动失败

os_wlan_ap_is_active

该函数用于查询热点是否处于活动状态,函数原型如下:

os_bool_t os_wlan_ap_is_active(void);
参数 说明
返回 说明
OS_TRUE 热点已启动
OS_FALSE 热点未启动

os_wlan_ap_stop

该函数用于阻塞式停止热点,返回值表示停止成功与否,函数原型如下:

os_err_t os_wlan_ap_stop(void);
参数 说明
返回 说明
OS_EOK 停止成功
OS_ERROR 停止失败

os_wlan_ap_get_info

该函数用于获取热点相关信息,如热点 SSID 等,函数原型如下:

os_err_t os_wlan_ap_get_info(struct os_wlan_info *info);
参数 说明
info 热点信息
返回 说明
OS_EOK 获取成功
OS_ERROR 获取失败

WLAN 事件回调

接口 说明
os_wlan_register_event_handler() 事件注册
os_wlan_unregister_event_handler() 解除注册

os_wlan_register_event_handler

该函数用于注册事件回调函数,函数原型如下:

os_err_t os_wlan_register_event_handler(os_wlan_event_t event, os_wlan_event_handler handler, void *parameter);
参数 说明
event 事件类型
handler 事件处理函数
parameter 用户参数
返回 说明
OS_EOK 注册成功
OS_ERROR 注册失败

WLAN 产生如下事件时,触发回调:

typedef enum
{
    OS_WLAN_EVT_READY = 0,              /* connect and prot is ok, You can send data*/
    OS_WLAN_EVT_SCAN_DONE,              /* Scan a info */
    OS_WLAN_EVT_SCAN_REPORT,            /* Scan end */
    OS_WLAN_EVT_STA_CONNECTED,          /* connect success */
    OS_WLAN_EVT_STA_CONNECTED_FAIL,     /* connection failed */
    OS_WLAN_EVT_STA_DISCONNECTED,       /* disconnect */
    OS_WLAN_EVT_AP_START,               /* AP start */
    OS_WLAN_EVT_AP_STOP,                /* AP stop */
    OS_WLAN_EVT_AP_ASSOCIATED,          /* sta associated */
    OS_WLAN_EVT_AP_DISASSOCIATED,       /* sta disassociated */
    OS_WLAN_EVT_MAX
} os_wlan_event_t;

WLAN 回调函数定义为:

typedef void (*os_wlan_event_handler)(int event, struct os_wlan_buff *buff, void *parameter);

其中 buff 根据事件的不同有不同的涵义。详细信息参考下表。

事件 类型 说明
OS_WLAN_EVT_READY ip_addr_t * IP 地址
OS_WLAN_EVT_SCAN_DONE struct os_wlan_scan_result * 扫描的结果
OS_WLAN_EVT_SCAN_REPORT struct os_wlan_info * 扫描到的热点信息
OS_WLAN_EVT_STA_CONNECTED struct os_wlan_info * 连接成功的 Station 信息
OS_WLAN_EVT_STA_CONNECTED_FAIL struct os_wlan_info * 连接失败的 Station 信息
OS_WLAN_EVT_STA_DISCONNECTED struct os_wlan_info * 断开连接的 Station 信息
OS_WLAN_EVT_AP_START struct os_wlan_info * 启动成功的 AP 信息
OS_WLAN_EVT_AP_STOP struct os_wlan_info * 启动失败的 AP 信息
OS_WLAN_EVT_AP_ASSOCIATED struct os_wlan_info * 连入的 Station 信息
OS_WLAN_EVT_AP_DISASSOCIATED struct os_wlan_info * 断开的 Station 信息

os_wlan_unregister_event_handler

该函数用于注销事件回调函数,函数原型如下:

os_err_t os_wlan_unregister_event_handler(os_wlan_event_t event);
参数 说明
event 事件类型
返回 说明
OS_EOK 注销成功

WLAN 功耗管理

接口 说明
os_wlan_set_powersave() 设置功耗等级
os_wlan_get_powersave() 获取功耗等级

os_wlan_set_powersave

该函数用于设置 station 模式的功耗等级,函数原型如下:

os_err_t os_wlan_set_powersave(int level);
参数 说明
level 功耗等级
返回 说明
OS_EOK 设置成功
OS_ERROR 设置失败

os_wlan_get_powersave

该函数用于获取当前功耗等级,函数原型如下:

int os_wlan_get_powersave(void);
参数 说明
返回 说明
功耗等级 功耗等级

WLAN 调试命令

使用 shell 命令,可以帮助我们快速调试 WiFi 相关功能。wifi 相关的 shell 命令如下:

wifi                           /* 查看帮助 */
wifi help                      /* 查看帮助 */
wifi join SSID [PASSWORD]      /* 连接 wifi */
wifi ap   SSID [PASSWORD]      /* 建立热点 */
wifi scan                      /* 扫描全部热点 */
wifi disc                      /* 断开连接 */
wifi ap_stop                   /* 停止热点 */
wifi status                    /* 查看 wifi 状态 */
wifi smartconfig               /* 启动配网功能 */

WiFi 扫描

wifi 扫描命令为 wifi scan,执行 wifi 扫描命令后,会将周围的热点信息打印在终端上。通过打印的热点信息,可以看到 SSID,MAC 地址等多项属性。

在 shell 中输入该命令,扫描结果如下所示:

sh />wifi scan
             SSID                      MAC            security    rssi chn Mbps
------------------------------- -----------------  -------------- ---- --- ----
CMCC-IOT-TEST                   fe:53:9e:8d:6a:3b  WPA2_AES_PSK   -30    6  150
CMCC-IOT                        0e:74:9c:76:b5:c6  OPEN           -44   11  144
CMCC-IPv6                       06:74:9c:76:b5:c6  OPEN           -45   11  144
CMCC-GUEST                      0a:74:9c:76:b5:c6  OPEN           -45   11  144
Tenda_586808                    c8:3a:35:58:68:09  WPA2_AES_PSK   -51    1  144
CMCC-Monitoring                 d0:76:e7:dd:e0:e1  WPA2_AES_PSK   -64    1  300

WiFi 连接

wifi 扫描命令为 wifi join,命令后面需要跟热点名称和热点密码,没有密码可不输入这一项。执行 WiFi 连接命令后,如果热点存在,且密码正确,开发板会连接上热点,并获得 IP 地址。网络连接成功后,可使用 socket 套接字进行网络通讯。

wifi 连接命令使用示例如下所示,连接成功后,将在终端上打印获得的 IP 地址,如下所示:

sh />wifi join CMCC-IOT-TEST 12345678
[62215] I/wlan.mgnt tshell: disconnect success! [os_wlan_disconnect][1251]
[62456] I/wlan.mgnt tshell: wifi connect success ssid:CMCC-IOT-TEST [os_wlan_event_dispatch][590]
sh />[62857] I/wlan.lwip wlan: Got IP address : 192.168.43.28 [netif_is_ready][108]

WiFi 断开

wifi 断开的命令为 wifi disc,执行 WiFi 断开命令后,开发板将断开与热点的连接。

WiFi 断开命令使用示例如下所示,断开成功后,将在终端上打印如下信息,如下所示

sh />wifi disc
[76863] I/wlan.mgnt tshell: disconnect success! [os_wlan_disconnect][1251]

使用示例

扫描 Wi-Fi 热点

#include <drv_cfg.h>
#include <wlan_mgnt.h>
#include <wlan_prot.h>
#include <wlan_cfg.h>
#include <shell.h>
#include <string.h>

static int wifi_scan(int argc, char **argv)
{
    struct os_wlan_scan_result *scan_result = OS_NULL;
    struct os_wlan_info *info = OS_NULL;
    struct os_wlan_info filter;

    if (argc > 3)
        return -1;

    if (argc == 3)
    {
        INVALID_INFO(&filter);
        SSID_SET(&filter, argv[2]);
        info = &filter;
    }

    /* clean scan result */
    os_wlan_scan_result_clean();
    /* scan ap info */
    scan_result = os_wlan_scan_with_info(info);
    if (scan_result)
    {
        int index, num;
        char *security;

        num = scan_result->num;
        os_kprintf("             SSID                      MAC            security    rssi chn Mbps\n");
        os_kprintf("------------------------------- -----------------  -------------- ---- --- ----\n");
        for (index = 0; index < num; index ++)
        {
            os_kprintf("%-32.32s", &scan_result->info[index].ssid.val[0]);
            os_kprintf("%02x:%02x:%02x:%02x:%02x:%02x  ",
                       scan_result->info[index].bssid[0],
                       scan_result->info[index].bssid[1],
                       scan_result->info[index].bssid[2],
                       scan_result->info[index].bssid[3],
                       scan_result->info[index].bssid[4],
                       scan_result->info[index].bssid[5]
                      );
            switch (scan_result->info[index].security)
            {
            case SECURITY_OPEN:
                security = "OPEN";
                break;
            case SECURITY_WEP_PSK:
                security = "WEP_PSK";
                break;
            case SECURITY_WEP_SHARED:
                security = "WEP_SHARED";
                break;
            case SECURITY_WPA_TKIP_PSK:
                security = "WPA_TKIP_PSK";
                break;
            case SECURITY_WPA_AES_PSK:
                security = "WPA_AES_PSK";
                break;
            case SECURITY_WPA2_AES_PSK:
                security = "WPA2_AES_PSK";
                break;
            case SECURITY_WPA2_TKIP_PSK:
                security = "WPA2_TKIP_PSK";
                break;
            case SECURITY_WPA2_MIXED_PSK:
                security = "WPA2_MIXED_PSK";
                break;
            case SECURITY_WPS_OPEN:
                security = "WPS_OPEN";
                break;
            case SECURITY_WPS_SECURE:
                security = "WPS_SECURE";
                break;
            default:
                security = "UNKNOWN";
                break;
            }
            os_kprintf("%-14.14s ", security);
            os_kprintf("%-4d ", scan_result->info[index].rssi);
            os_kprintf("%3d ", scan_result->info[index].channel);
            os_kprintf("%4d\n", scan_result->info[index].datarate / 1000000);
        }
        os_wlan_scan_result_clean();
    }
    else
    {
        os_kprintf("wifi scan result is null\n");
    }

    return 0;
}

SH_CMD_EXPORT(wifi_scan, wifi_scan, "wifi_scan");

运行结果如下:

sh />wifi_scan
             SSID                      MAC            security    rssi chn Mbps
------------------------------- -----------------  -------------- ---- --- ----
CMCC-GUEST                      0a:74:9c:76:b5:c6  OPEN           -40   11  144
CMCC-IOT                        0e:74:9c:76:b5:c6  OPEN           -40   11  144
CMCC-IPv6                       06:74:9c:76:b5:c6  OPEN           -41   11  144
Tenda_586808                    c8:3a:35:58:68:09  WPA2_AES_PSK   -51    1  144
huawei_hsj                      f8:9a:78:94:ba:d8  WPA2_MIXED_PSK -51    6  300
Tenda_56D088                    c8:3a:35:56:d0:89  WPA2_AES_PSK   -54    8  144
CMCC-GUEST                      0a:74:9c:76:c3:5a  OPEN           -57    6  144
WiFi_4C36                       20:76:93:45:4c:36  WPA2_AES_PSK   -59    5  144
TP-LINK_3C0E                    78:44:fd:75:3c:0e  WPA2_AES_PSK   -61   11  300
CMCC-Monitoring                 d0:76:e7:dd:e0:e1  WPA2_AES_PSK   -64    1  300
CMCC-IOT                        0e:74:9c:76:c4:56  OPEN           -66    1  144
CMCC-GUEST                      0a:74:9c:76:c4:56  OPEN           -67    1  144
MERCURY_6E21                    c0:a5:dd:33:6e:21  WPA2_AES_PSK   -67   13  300
Magellan                        4a:0e:ec:d4:7b:33  WPA2_AES_PSK   -68   11  300
Xiaomi_E11A                     28:6c:07:53:e1:1b  WPA2_MIXED_PSK -69    4  144
Skymoon                         68:a0:3e:f6:b2:18  WPA2_AES_PSK   -71    6  300
StarCommunity                   58:ef:68:5d:a4:3d  WPA2_MIXED_PSK -72    5  144
                                68:a0:3e:f6:b2:1d  WPA2_AES_PSK   -73    6  300
                                78:bc:1a:2a:22:85  WPA2_AES_PSK   -74    1  216
YLKJ                            f4:74:88:0d:36:30  WPA2_MIXED_PSK -79    1  144
Tencent-GuestWiFi               78:bc:1a:3f:fc:83  OPEN           -83    6  216

连接 Wi-Fi

#include <drv_cfg.h>
#include <wlan_mgnt.h>
#include <wlan_prot.h>
#include <wlan_cfg.h>
#include <shell.h>
#include <string.h>

static int wifi_join(int argc, char **argv)
{
    const char *ssid = OS_NULL;
    const char *key = OS_NULL;
    struct os_wlan_cfg_info cfg_info;

    memset(&cfg_info, 0, sizeof(cfg_info));

    if (argc >= 3)
    {
        /* ssid */
        ssid = argv[2];
    }

    if (argc >= 4)
    {
        /* password */
        key = argv[3];
    }

    os_wlan_connect(ssid, key);

    return 0;
}
SH_CMD_EXPORT(wifi_join, wifi_join, "wifi_join");

运行结果如下:

sh />wifi_join CMCC-IOT-TEST 12345678
[25063] I/wlan.mgnt tshell: wifi connect success ssid:CMCC-IOT-TEST [os_wlan_event_dispatch][590]
sh />[25164] I/wlan.lwip wlan: Got IP address : 192.168.43.28 [netif_is_ready][108]

断开 Wi-Fi

#include <drv_cfg.h>
#include <wlan_mgnt.h>
#include <wlan_prot.h>
#include <wlan_cfg.h>
#include <shell.h>
#include <string.h>

static int wifi_disconnect(int argc, char *argv[])
{
    os_wlan_disconnect();
    return 0;
}
SH_CMD_EXPORT(wifi_disconnect, wifi_disconnect, "wifi_disconnect");

运行结果如下:

sh />wifi_disconnect
[2091] I/wlan.mgnt tshell: disconnect success! [os_wlan_disconnect][1251]

results matching ""

    No results matching ""

    返回顶部