生活物联网平台提供多种Wi-Fi设备的配网技术方案,对于不具备人机交互能力的设备,可以通过借助其他设备来协助配网。为此,生活物联网平台提供了开放的配网能力,便于您在不同的设备硬件平台上快速适配和实现Wi-Fi配网功能。

下图为生活物联网平台SDK中Wi-Fi设备配网模块的分层框架。

fig1
  • HAL_AWSS实现接口和OS、硬件的适配对接,为上层SDK的配网服务提供基础的Wi-Fi通信能力。

    在生活物联网平台SDK中,HAL_AWSS的适配实现,主要提供了Wi-Fi配网需要适配的接口。

  • AWSS模块是SDK中提供的配网服务,可以提供多种配网方式,依赖于HAL层的HAL_AWSS部分,以及HAL层其他相关接口的正确适配。

    AWSS模块为上层的应用开发提供了配网相关的用户编程接口,Examples为调用这些接口的完整示例的实现。

    在生活物联网平台SDK中,AWSS用户编程接口,主要用来调用实现设备的Wi-Fi配网功能。

通用HAL说明

Wi-Fi配网模块中依赖生活物联网平台SDK的公共HAL接口(如下表所示)。请您参照生活物联网平台SDK中对应模块的说明完成对接。

序号 适配接口名 说明
1 HAL_MutexCreate 创建一个互斥量对象,返回指向所创建互斥量的指针,用于同步访问,对于仅支持单线程应用,可实现为空函数
2 HAL_MutexDestroy 销毁一个互斥量对象,释放资源
3 HAL_MutexLock 锁住一个互斥量
4 HAL_MutexUnlock 解锁一个互斥量
5 HAL_UptimeMs 获取设备从上电到当前时刻所经过的毫秒数
6 HAL_Malloc 申请一块堆内存
7 HAL_Free 释放参数ptr指向的一块堆内存,当传入的参数为NULL时不执行任何操作
8 HAL_SleepMs 睡眠函数,使当前执行线程睡眠指定的毫秒数
9 HAL_GetProductKey 获取设备的ProductKey,用于标识设备的品类,设备证书之一
10 HAL_GetProductSecret 获取设备的ProductSecret,用于标识设备的品类,设备证书之一
11 HAL_GetDeviceName 获取设备的DeviceName,用于标识设备单品的名字,设备证书之一
12 HAL_GetDeviceSecret 获取设备的DeviceSecret, 用于标识设备单品的密钥, 设备证书之一
13 HAL_Kv_Set Flash中写入键值对(Key-Value)
14 HAL_Kv_Get Flash中读取键值对的Value
15 HAL_Aes128_Init 初始化AES加密的结构体
16 HAL_Aes128_Destroy 销毁AES加密的结构体
17 HAL_Aes128_Cbc_Encrypt 以AES-CBC-128方式,根据HAL_Aes128_Init()时传入的密钥,加密指定的明文
18 HAL_Aes128_Cbc_Decrypt 以AES-CBC-128方式,根据HAL_Aes128_Init()时传入的密钥,解密指定的密文
19 HAL_Aes128_Cfb_Encrypt 以AES-CFB-128方式,根据HAL_Aes128_Init()时传入的密钥,加密指定的明文
20 HAL_Aes128_Cfb_Decrypt 以AES-CFB-128方式,根据HAL_Aes128_Init()时传入的密钥,解密指定的密文
21 HAL_Timer_Create 根据Name、TimerFunc和用户上下文创建Timer
22 HAL_Timer_Start Timer开始计时,Timer超时时调用回调函数TimerFunc
23 HAL_Timer_Stop 停止Timer计时
24 HAL_Timer_Delete 删除Timer,释放资源
说明 带AliOS Things的生活物联网平台SDK的HAL接口文件说明,请参见以下目录中的各个文件内容。
  • /Living_SDK/framework/protocol/linkkit/sdk/iotx-sdk-c_clone/include/imports/
  • /Living_SDK/framework/protocol/linkkit/sdk/iotx-sdk-c_clone/include/iot_import.h

HAL适配概述

Wi-Fi配网模块需要适配的HAL接口的详细说明如下表所示。

说明 表中分类为 配网通用的接口在适配时必须要实现,否则会影响Wi-Fi设备生活物联网平台SDK的正常运行。其他配网特定的分类,您可以根据自己硬件平台的情况以及产品的使用场景和需要进行选择支持,但是同一配网方式类别的所有接口需要适配完整,否则会影响此种配网方式的正常运行。
序号 适配接口名 说明 分类
1 HAL_Wifi_Get_Mac 获取设备的MAC地址, 格式应当是”XX:XX:XX:XX:XX:XX” 配网通用
2 HAL_Wifi_Get_IP 获取设备的IP地址,点分十进制格式保存在字符串数组出参,二进制格式则作为返回值,并以网络字节序(大端)表达,Station模式为连接AP时的IP地址,SoftAP模式为设备作为AP的Gateway IP地址 配网通用
3 HAL_Awss_Get_Channelscan_Interval_Ms 获取在每个信道(channel)上扫描的时间长度,单位是毫秒 配网通用
4 HAL_Awss_Get_Timeout_Interval_Ms 获取配网服务(AWSS)的超时时间长度,单位是毫秒 配网通用
5 HAL_Awss_Get_Encrypt_Type 获取一键配网服务的安全等级 一键配网
6 HAL_Awss_Get_Conn_Encrypt_Type 获取基于连接的配网服务(热点配网/零配)的安全等级
  • 零配配网
  • 设备热点配网
  • 蓝牙辅助配网
  • 手机热点配网
7 HAL_Awss_Open_Monitor 设备工作在监听(Monitor)模式,并在收到802.11帧的时候调用被传入的回调函数(包括管理帧和数据帧) 配网通用
8 HAL_Awss_Close_Monitor 关闭监听(Monitor)模式 配网通用
9 HAL_Wifi_Scan 启动一次Wi-Fi的空中扫描 配网通用
10 HAL_Awss_Switch_Channel 设置Wi-Fi设备切换到指定的信道(channel)上 配网通用
11 HAL_Awss_Connect_Ap 要求Wi-Fi网卡连接指定热点(Access Point)的函数,bssid指定特定AP,另外bssid也可能为空或无效值(全0或全0xff) 配网通用
12 HAL_Wifi_Send_80211_Raw_Frame 在当前信道(channel)上以基本数据速率(1Mbps)发送裸的802.11帧(raw 802.11 frame) 配网通用
13 HAL_Wifi_Enable_Mgmt_Frame_Filter 使能或禁用对管理帧的过滤 配网通用
14 HAL_Sys_Net_Is_Ready 检查Wi-Fi网卡、芯片或模组当前的IP地址是否有效 配网通用
15 HAL_Wifi_Get_Ap_Info 获取设备所连接的热点(Access Point)的信息(SSID、Password、BSSID等) 配网通用
16 HAL_Wifi_Get_Link_Stat 获取当前与AP连接链路状态的信息(channel、RSSI等) 配网通用
17 HAL_Awss_Open_Ap 开启设备热点(SoftAP模式) 设备热点配网
18 HAL_Awss_Close_Ap 关闭当前设备热点,并把设备由SoftAP模式切换到Station模式 设备热点配网

HAL_Wifi_Get_Mac

原型

char *HAL_Wifi_Get_Mac(_OU_ char mac_str[HAL_MAC_LEN]);

接口说明

获取Wi-Fi网口的MAC地址,格式为XX:XX:XX:XX:XX:XX

参数说明

参数 数据类型 方向 说明
mac_str char 输出 指向缓冲区数组起始位置的字符指针

返回值说明

指向缓冲区数组起始位置的字符指针。

HAL_Wifi_Get_IP

原型

uint32_t HAL_Wifi_Get_IP(_OU_ char ip_str[NETWORK_ADDR_LEN], _IN_ const char *ifname);

接口说明

获取Wi-Fi网口的IP地址,点分十进制格式保存在字符串数组出参,二进制格式则作为返回值,并以网络字节序(大端)表达。

参数说明

参数 数据类型 方向 说明
ip_str char[] 输出 存放点分十进制格式的IP地址字符串的数组
ifname const char* 输入 指定Wi-Fi网络接口的名字(如果只有一个网口,可以忽略此参数,该参数可能为NULL)

返回值说明

二进制形式的IP地址,以网络字节序(大端)组织。

HAL_Awss_Get_Channelscan_Interval_Ms

原型

int HAL_Awss_Get_Channelscan_Interval_Ms(void);

接口说明

获取在每个信道(channel)上扫描的时间长度,单位是毫秒,建议设置为200ms~400ms(默认250ms)。

参数说明

void

返回值说明

时间长度,单位为毫秒。

HAL_Awss_Get_Timeout_Interval_Ms

原型

int HAL_Awss_Get_Timeout_Interval_Ms(void);

接口说明

获取配网服务(AWSS)的超时时间长度,单位是毫秒,建议配置为60s或60000ms。

参数说明

void

返回值说明

超时时长,单位是毫秒。

HAL_Awss_Get_Encrypt_Type

原型

int HAL_Awss_Get_Encrypt_Type(void);

接口说明

获取一键配网服务的安全等级。

参数说明

void

返回值说明

说明
0 open (no encrypt)
1 aes256cfb with default aes-key and aes-iv
2 aes128cfb with default aes-key and aes-iv
3 aes128cfb with aes-key per product and aes-iv = 0
4 aes128cfb with aes-key per device and aes-iv = 0
5 aes128cfb with aes-key per manufacture and aes-iv = 0
others 无效

HAL_Awss_Get_Conn_Encrypt_Type

原型

int HAL_Awss_Get_Conn_Encrypt_Type(void);

接口说明

获取零配,热点配网的安全等级。

参数说明

void

返回值说明

说明
3 aes128cfb with aes-key per product and aes-iv = random
4 aes128cfb with aes-key per device and aes-iv = random
5 aes128cfb with aes-key per manufacture and aes-iv = random
others 无效

HAL_Awss_Open_Monitor

原型

void HAL_Awss_Open_Monitor(_IN_ awss_recv_80211_frame_cb_t cb);

接口说明

设置Wi-Fi网卡工作在监听(Monitor)模式,并在收到802.11帧的时候调用被传入的回调函数。

参数说明

参数 数据类型 方向 说明
cb awss_recv_80211_frame_cb_t 输入 回调函数指针,当Wi-Fi接收到帧时会调用此函数
/**
 * @brief   802.11帧的处理函数,可以将802.11 Frame传递给这个函数
 *
 * @param[in] buf @n 80211 frame buffer, or pointer to struct ht40_ctrl
 * @param[in] length @n 80211 frame buffer length
 * @param[in] link_type @n AWSS_LINK_TYPE_NONE for most rtos HAL,
 *              and for linux HAL, do the following step to check
 *              which header type the driver supported.
   @verbatim
               a) iwconfig wlan0 mode monitor    #open monitor mode
               b) iwconfig wlan0 channel 6    #switch channel 6
               c) tcpdump -i wlan0 -s0 -w file.pacp    #capture 80211 frame & save
               d) open file.pacp with wireshark or omnipeek
                   check the link header type and fcs included or not
   @endverbatim
 * @param[in] with_fcs @n 80211 frame buffer include fcs(4 byte) or not
 * @param[in] rssi @n rssi of packet, range of [-127, -1]
 */
typedef int (*awss_recv_80211_frame_cb_t)(char *buf, int length,
        enum AWSS_LINK_TYPE link_type, int with_fcs, signed char rssi);

返回值说明

void

HAL_Awss_Close_Monitor

原型

void HAL_Awss_Close_Monitor(void);

接口说明

设置Wi-Fi网卡离开监听(Monitor)模式,并开始以站点(Station)模式工作。

参数说明

void

返回值说明

void

HAL_Wifi_Scan

原型

int HAL_Wifi_Scan(awss_wifi_scan_result_cb_t cb);

接口说明

启动一次Wi-Fi的空中扫描,该API是一个阻塞操作,扫描没有完成不能结束。所有的AP列表收集完成后,一个一个通过回调函数告知AWSS,最好不要限制AP的数量,否则可能导致中文GBK编码的SSID热点配网失败。

参数说明

参数 数据类型 方向 说明
cb awss_wifi_scan_result_cb_t 输入 扫描通知回调函数

返回值说明

说明
0 扫描正常结束
-1 其他情况

HAL_Awss_Switch_Channel

原型

void HAL_Awss_Switch_Channel(
            _IN_ char primary_channel,
            _IN_OPT_ char secondary_channel,
            _IN_OPT_ uint8_t bssid[ETH_ALEN]);

接口说明

设置Wi-Fi网卡切换到指定的信道(channel)上。

参数说明

参数 数据类型 方向 说明
primary_channel char 输入 首选信道
secondary_channel char 输入 辅助信道,信道带宽为40MHz时才会使用,信道宽度为20MHz时忽略该参数
bssid uint8_t 输入 生活物联网平台SDK1.3.0及以上版本中,此参数已废弃,您若兼容1.3.0以前版本使用

返回值说明

void

HAL_Awss_Connect_Ap

原型

int HAL_Awss_Connect_Ap(
            _IN_ uint32_t connection_timeout_ms,
            _IN_ char ssid[HAL_MAX_SSID_LEN],
            _IN_ char passwd[HAL_MAX_PASSWD_LEN],
            _IN_OPT_ enum AWSS_AUTH_TYPE auth,
            _IN_OPT_ enum AWSS_ENC_TYPE encry,
            _IN_OPT_ uint8_t bssid[ETH_ALEN],
            _IN_OPT_ uint8_t channel);

接口说明

要求Wi-Fi网卡连接指定热点(Access Point)的函数,bssid指定特定AP,另外bssid也可能为空或无效值(全0或全0xff)。

参数说明

参数 数据类型 方向 说明
connection_timeout_ms uint32_t 输入 连接AP的超时时间
ssid char 输入 目的AP的SSID
passwd char 输入 目的AP的PASSWORD
auth enum 输入 目的AP的加密方式,HAL可以忽略
encry enum 输入 目的AP的认证方式,HAL可以忽略
bssid uint8_t 输入 目的AP的BSSID,该字段可能为NULL或设置为全0
channel uint8_t 输入 目的AP的信道,该字段可以忽略

返回值说明

说明
0 连接AP和DHCP成功
-1 连接AP或DHCP失败

HAL_Wifi_Send_80211_Raw_Frame

原型

int HAL_Wifi_Send_80211_Raw_Frame(_IN_ enum HAL_Awss_Frame_Type type,
        _IN_ uint8_t *buffer, _IN_ int len);

接口说明

在当前信道(channel)上以基本数据速率(1Mbps)发送裸的802.11帧(raw 802.11 frame)。

参数说明

参数 数据类型 方向 说明
type enum HAL_Awss_Frame_Type 输入 查看HAL_Awss_Frame_Type_t定义
buffer uint8_t * 输入 802.11裸数据帧,包括完整的MAC头和FCS域
len int 输入 802.11裸帧字节长度
/* 80211 frame type */
typedef enum HAL_Awss_Frame_Type {
    FRAME_ACTION,                 // 802.11中的Action帧
    FRAME_BEACON,                // 802.11中的Beacon帧
    FRAME_PROBE_REQ,           // 802.11中的Probe Request帧
    FRAME_PROBE_RESPONSE,       // 802.11中的Probe Response帧
    FRAME_DATA                 // 802.11中的数据帧
} HAL_Awss_Frame_Type_t;

返回值说明

说明
0 发送成功
-1 发送失败

HAL_Wifi_Enable_Mgmt_Frame_Filter

原型

int HAL_Wifi_Enable_Mgmt_Frame_Filter(
            _IN_ uint32_t filter_mask,
            _IN_OPT_ uint8_t vendor_oui[3],
            _IN_ awss_wifi_mgmt_frame_cb_t callback);

接口说明

使能或禁用对特定管理帧的过滤。

参数说明

参数 数据类型 方向 说明
filter_mask uint32_t 输入 帧过滤参数
vendor_oui uint8_t 输入 Wi-Fi联盟分配的厂商OUI,如果OUI为NULL,表示不对OUI过滤,反之要根据OUI过滤
callback awss_wifi_mgmt_frame_cb_t 输入 用于接收802.11帧或者信息元素(IE)的回调函数

返回值说明

说明
= 0 发送成功
= -1 发送失败
= -2 不支持

HAL_Sys_Net_Is_Ready

原型

int HAL_Sys_Net_Is_Ready();

接口说明

检查系统网络是否可用(设备是否已经成功获得IP地址并且当前IP地址可用)。

参数说明

void

返回值说明

说明
0 网络不可用
1 网络可用

HAL_Wifi_Get_Ap_Info

原型

int HAL_Wifi_Get_Ap_Info(
            _OU_ char ssid[HAL_MAX_SSID_LEN],
            _OU_ char passwd[HAL_MAX_PASSWD_LEN],
            _OU_ uint8_t bssid[ETH_ALEN]);

接口说明

获取所连接的热点(Access Point)的信息。

参数说明

参数 数据类型 方向 说明
ssid char 输出 AP的SSID,该参数可能为NULL
passwd char 输出 AP的Password,该参数为NULL
bssid uint8_t 输出 AP的BSSID,该参数可能为NULL,如果bssid不对将导致零配设备发现失败

返回值说明

说明
0 操作成功
-1 操作失败

HAL_Wifi_Get_Link_Stat

原型

int HAL_Wifi_Get_Link_Stat(_OU_ int *p_rssi,
                           _OU_ int *p_channel);

接口说明

获取当前与AP连接链路状态的信息(channel、RSSI等)。

参数说明

参数 数据类型 方向 说明
p_rssi char 输出 设备当前关联的AP的信号强度值
p_channel char 输出 设备当前关联的AP所在的信道

返回值说明

说明
0 操作成功
-1 操作失败

HAL_Awss_Open_Ap

原型

int HAL_Awss_Open_Ap(const char *ssid, 
                     const char *passwd, 
                     int beacon_interval, 
                     int hide);

接口说明

开启设备热点(SoftAP模式)。

参数说明

参数 数据类型 方向 说明
ssid const char * 输入 热点的ssid字符
passwd const char * 输入 热点的passwd字符
beacon_interval int 输入 热点的Beacon广播周期(广播间隔)
hide int 输入
  • 0:非隐藏
  • 非0(其它值):隐藏

返回值说明

说明
0 success
-1 unsupported
-2 failure with system error
-3 failure with no memory
-4 failure with invalid parameters

HAL_Awss_Close_Ap

原型

int HAL_Awss_Close_Ap(void);

接口说明

关闭设备热点。

参数说明

void

返回值说明

说明
0 success
-1 unsupported
-2 failure