WLAN设备用户开发

基础BSP配置--以STM32为例

建立工程文件

如果在提供的 oneos 源码中已经有适合的工程 DEMO 工程，则可以直接使用；如果没有请参照快速上手中的操作指南，新建一个适合的工程。

使用STM32CUBEMX配置硬件

1. 打开 oneos\projects\xxxxx(project文件夹)\board\CubeMX_Config 下 的 CUBE 工程文件；
2. 在 CUBE 工程中进行SDIO 配置，如下图所示，选中SDMMC、配置SDIO工作模式、分配引脚；
3. 点击 GENARATE CODE 生成代码；

使用 Menuconfig 配置工程选项

1. 在对应的 oneos\projects\xxxxx(project文件夹) 目录下打开 OneOS-Cube 工具，在命令行输入 menuconfig 打开可视化配置界面；

2. 如下图示，通过空格或向右方向键选择 Drivers->WLAN 下的 Using Wi-Fi framework选项；

(Top) → Drivers→ WLAN
[*] Using Wi-Fi framework  --->
[ ] Enable Wi-Fi AP6181

1. 进入该选项，对WLAN各项参数进行配置;

(Top) → Drivers→ WLAN→ Using Wi-Fi framework
                                             OneOS Configuration
(wlan0) The device name for station
(wlan1) The device name for ap
(32) SSID maximum length
(32) Password maximum length
(2) Driver events maxcount
[*] Connection management Enable
(10000) Set scan timeout time(ms)
(10000) Set connect timeout time(ms)
[*]     Automatic sorting of scan results
[*]     MSH command Enable
[*]     Auto connect Enable
(2000)      Auto connect period(ms)
-*- WiFi information automatically saved Enable
(3)     Maximum number of WiFi information automatically saved
[*] Transport protocol manage Enable
(8)     Transport protocol name length
(2)     Transport protocol maxcount
(lwip)  Default transport protocol
[*]     LWIP transport protocol Enable
(lwip)      LWIP transport protocol name
[*]         Forced use of PBUF transmission
-*- WLAN work queue task Enable
(wlan)  WLAN work queue task name
(2048)  WLAN work queue task size
(15)    WLAN work queue task priority
[ ] Enable WLAN Debugging Options  ----

1. 进入 Drivers->WLAN，使能 Enable WiFi (AP6181)

(Top) → Drivers→ WLAN
-*- Using Wi-Fi framework  --->
[*] Enable Wi-Fi AP6181
(49)    AP6181 wifi reg on pin
(37)    AP6181 interrupt pin

5.Esc键退出menuconfig，注意保存所修改的设置。

使用 Scons 构建工程

在上一步打开的 OneOS-Cube 工具命令行输入 scons --ide=mdk5 构建工程；

工程编译及实现

1. 打开对应的 oneos\projects\xxxxx(project文件夹) 目录下的 project.uvprojx 工程文件；
2. 编译并下载工程，运行程序；
3. 打开串口工具如 xshell 等，通信成功后，即可通过输入 wifi scan，wifi join 等命令进行WLAN测试。

WLAN设备

API列表

WLAN 初始化

os_wlan_init

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

int os_wlan_init(void);

os_wlan_set_mode

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

os_err_t os_wlan_set_mode(const char *dev_name, os_wlan_mode_t mode);

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);

WLAN 连接

os_wlan_connect

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

os_err_t os_wlan_connect(const char *ssid, const char *password);

os_wlan_connect_adv

该函数用于连接热点，函数原型如下：

os_err_t os_wlan_connect_adv(struct os_wlan_info *info, const char *password);

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

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

连接信息必须配置的项有security、ssid。完整配置如下：

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_wlan_is_connected

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

os_bool_t os_wlan_is_connected(void);

os_wlan_is_ready

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

os_bool_t os_wlan_is_ready(void);

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

os_wlan_get_info

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

os_err_t os_wlan_get_info(struct os_wlan_info *info);

os_wlan_get_rssi

该函数用于获得信号强度，函数原型如下：

int os_wlan_get_rssi(void);

os_wlan_config_autoreconnect

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

void os_wlan_config_autoreconnect(os_bool_t enable);

os_wlan_get_autoreconnect_mode

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

os_bool_t os_wlan_get_autoreconnect_mode(void);

os_wlan_set_mac

该函数用于设置mac地址，函数原型如下：

os_err_t  os_wlan_set_mac(os_uint8_t mac[6]);

os_wlan_get_mac

该函数用于获取mac地址，函数原型如下：

os_err_t  os_wlan_get_mac(os_uint8_t mac[6]);

WLAN 扫描

os_wlan_scan

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

os_err_t os_wlan_scan(void);

os_wlan_scan_sync

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

struct os_wlan_scan_result *os_wlan_scan_sync(void);

os_wlan_scan_with_info

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

struct os_wlan_scan_result *os_wlan_scan_with_info(struct os_wlan_info *info);

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);

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);

WLAN 热点

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);

os_wlan_ap_is_active

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

os_bool_t os_wlan_ap_is_active(void);

os_wlan_ap_stop

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

os_err_t os_wlan_ap_stop(void);

os_wlan_ap_get_info

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

os_err_t os_wlan_ap_get_info(struct os_wlan_info *info);

os_wlan_ap_get_sta_num

该函数用于获取station个数，函数原型如下：

int os_wlan_ap_get_sta_num(void);

os_wlan_ap_get_sta_info

该函数用于获取station的信息，函数原型如下：

int  os_wlan_ap_get_sta_info(struct os_wlan_info *info, int num);

os_wlan_ap_deauth_sta

该函数用于踢特定mac地址station下线，函数原型如下：

os_err_t  os_wlan_ap_deauth_sta(os_uint8_t *mac);

os_wlan_ap_set_country

该函数用于设置区域国家码，函数原型如下：

os_err_t  os_wlan_ap_set_country(os_country_code_t country_code);

os_wlan_ap_get_country

该函数用于获取国家码，函数原型如下：

os_country_code_t os_wlan_ap_get_country(void);

WLAN 事件回调

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);

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_unregister_event_handler

该函数用于注销事件回调函数，函数原型如下：

os_err_t os_wlan_unregister_event_handler(os_wlan_event_t event);

WLAN 功耗管理

os_wlan_set_powersave

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

os_err_t os_wlan_set_powersave(int level);

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]