1. WiFi协议栈API

SDK WiFi协议栈的API定义在sdk/include/umac/ieee80211.h文件中。

1.1. 初始化API

1.1.1. ieee80211_init

ieee80211_init API用于初始化WiFi协议栈。

l 参数param [in] ：WiFi协议栈初始化参数

struct ieee80211_initparam {

uint8 vif_maxcnt; //支持创建接口的最大个数

uint8 bss_maxcnt; //支持缓存的AP信息最大个数

uint8 headroom, tailroom;

uint16 sta_maxcnt; //支持连接的sta的最大个数

uint16 bss_lifetime; //缓存的AP信息生存时间

uint16 stack_size; //协议栈的task堆栈大小，默认是2K

uint16 no_rxtask:1,//协议栈是否使用独立的rx task

ssid_fuzzy_match:4,//协议栈是否开启ssid模糊匹配

rev: 11;

ieee80211_evt_cb evt_cb; //协议栈的event callback函数

};

n ap信息生存时间：当AP列表的数量超过bss_macnt/2时，ap信息的生存时间自动调整为5s，直到清除后的ap数量小于bss_macnt/2，生存时间恢复为bss_lifetime值。

l 返回值 ：表示是否成功，0：成功，非0：失败，errno

1.1.2. ieee80211_support_txw830x

ieee80211_support_txw830x API用于初始化协议栈支持TXW8301芯片。

l 参数ops [in] ：LMAC协议栈的句柄

l 返回值：表示是否成功，0：成功，非0：失败

1.1.3. ieee80211_support_txw80x

ieee80211_support_txw80x API用于初始化协议栈支持TXW80x芯片。

l 参数ops [in] ：LMAC协议栈的句柄

l 返回值：表示是否成功，0：成功，非0：失败

1.1.4. ieee80211_support_txw81x

ieee80211_support_txw81x API用于初始化协议栈支持TXW81x芯片。

l 参数ops [in] ：LMAC协议栈的句柄

l 返回值：表示是否成功，0：成功，非0：失败

1.1.5. ieee80211_iface_create_ap

ieee80211_iface_create_ap API用于创建标准协议AP模式接口。

l 参数ifidx [in] ：AP模式接口使用的接口索引

l 参数band [in] ：WiFi频段类型

n IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片

n IEEE80211_BAND_5GHZ： 5G频段

n IEEE80211_BAND_60GHZ：60G频段

n IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片

l 返回值：表示是否成功，0：成功，非0：失败

1.1.6. ieee80211_iface_create_sta

ieee80211_iface_create_sta API用于创建标准协议STA模式接口。

l 参数ifidx [in] ：STA模式接口使用的接口索引

l 参数band [in] ：WiFi频段类型

n IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片

n IEEE80211_BAND_5GHZ： 5G频段

n IEEE80211_BAND_60GHZ：60G频段

n IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片

l 返回值：表示是否成功，0：成功，非0：失败

1.1.7. ieee80211_iface_create_wnbap

ieee80211_iface_create_wnbap API用于创建泰芯私有协议WNBAP模式接口。

l 参数ifidx [in] ：WNBAP模式接口使用的接口索引

l 参数band [in] ：WiFi频段类型

n IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片

n IEEE80211_BAND_5GHZ： 5G频段

n IEEE80211_BAND_60GHZ：60G频段

n IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片

l 返回值：表示是否成功，0：成功，非0：失败

1.1.8. ieee80211_iface_create_wnbsta

ieee80211_iface_create_wnbsta 用于创建泰芯私有协议WNBSTA模式接口。

l 参数ifidx [in] ：WNBSTA模式接口使用的接口索引

l 参数band [in] ：WiFi频段类型

n IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片

n IEEE80211_BAND_5GHZ： 5G频段

n IEEE80211_BAND_60GHZ：60G频段

n IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片

l 返回值：表示是否成功，0：成功，非0：失败

1.1.9. ieee80211_iface_create_p2pdev

ieee80211_iface_create_p2pdev API用于创建标准协议p2p模式接口。

l 参数ifidx [in] ：p2p模式接口使用的接口索引

l 参数band [in] ：WiFi频段类型

n IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片

n IEEE80211_BAND_5GHZ： 5G频段

n IEEE80211_BAND_60GHZ：60G频段

n IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片

l 返回值：表示是否成功，0：成功，非0：失败

1.1.10. ieee80211_iface_start

ieee80211_iface_start API用于启动已创建的接口。

l 参数ifidx [in] ：需要启动的接口索引

l 返回值：表示是否成功，0：成功，非0：失败

1.1.11. ieee80211_iface_stop

ieee80211_iface_stop API用于停止已启动的接口。

l 参数ifidx [in] ：需要停止的接口索引

l 返回值：表示是否成功，0：成功，非0：失败

1.1.12. ieee80211_deliver_init

ieee80211_deliver_init API用于初始化协议栈的转发路由表。

l 参数max [in] ：路由表缓存信息的最大数量

l 参数lifetime [in]：路由表缓存信息的生成时间，单位：秒

l 返回值：表示是否成功，0：成功，非0：失败

1.1.13. ieee80211_conf_stabr_table

ieee80211_conf_stabr_table API用于初始化WiFi协议栈的STA接口桥接路由表，该API仅对STA接口有效。

l 参数ifidx [in]：接口索引

l 参数max [out]：路由表信息最大数量

l 参数lifetime [in]：路由表信息的生存时间

l 返回值：表示是否成功，0：成功，非0：失败。

1.1.14. wpa_passphrase

wpa_passphrase API用于根据ssid和明文密码password，计算密文密码psk。

l 参数ssid [in] ：WiFi ssid

l 参数passwd [in]：WiFi password，明文密码

l 参数psk [out] ：生成的密文密码psk

l 返回值：表示是否成功，0：成功，-1：失败

1.2. 基础配置API

1.2.1. ieee80211_conf_set_channel

ieee80211_conf_set_channel API用于设置WiFi信道。

该API对sta模式无效，因为sta需要扫描连接AP，跟随AP的channel。

l 参数ifidx [in]：接口索引

l 参数channel [in]：设置新的channel

l 返回值：表示是否成功，0：成功，非0：失败。

1.2.2. ieee80211_conf_set_ssid

ieee80211_conf_set_ssid API用于设置WiFi ssid参数。

l 参数ifidx [in]：接口索引

l 参数ssid [in]：WiFi SSID参数。

l 返回值：表示是否成功，0：成功，非0：失败。

1.2.3. ieee80211_conf_set_keymgmt

ieee80211_conf_set_keymgmt API用于设置WiFi加密模式。

l 参数ifidx [in]：接口索引

l 参数keymgmt [in]：WiFi 加密模式，有效值如下：

#define WPA_KEY_MGMT_PSK BIT(1)

#define WPA_KEY_MGMT_NONE BIT(2)

#define WPA_KEY_MGMT_SAE BIT(10)

#define WPA_KEY_MGMT_OWE BIT(22)

l 返回值：表示是否成功，0：成功，非0：失败。

1.2.4. ieee80211_conf_set_psk

ieee80211_conf_set_psk API用于设置WiFi加密使用的密文密码。

密文密码通常是使用wpa_passphrase API计算得到的，但是也可以完全自定义，例如使用随机数。

l 参数ifidx [in]：接口索引

l 参数psk [in]：密文密码

l 返回值：表示是否成功，0：成功，非0：失败。

1.2.5. ieee80211_conf_set_passwd

ieee80211_conf_set_passwd API用于设置WiFi加密的明文密码，在开启wpa3时需要使用此API。

l 参数ifidx [in]：接口索引

l 参数passwd [in]：明文密码

l 返回值：表示是否成功，0：成功，非0：失败。

1.2.6. ieee80211_conf_set_beacon_int

ieee80211_conf_set_beacon_int API用于修改AP接口的beacon周期。默认beacon周期为100ms。

l 参数ifidx [in]：接口索引

l 参数beacon_int [in]：新的beacon周期，单位：毫秒

l 返回值：表示是否成功，0：成功，非0：失败。

1.3. 高级配置API

1.3.1. ieee80211_conf_set_bssbw

ieee80211_conf_set_bssbw API用于设置WiFi协议栈的BSS带宽。

l 参数ifidx [in]：接口索引

l 参数bssbw [in]：BSS带宽，设置前需要确认芯片是否支持此带宽。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.2. ieee80211_conf_set_dtim_int

ieee80211_conf_set_dtim_int API用于设置AP接口的DTIM周期。默认DTIM周期是10，也就是dtim10，表示STA在休眠时每10个beacon时刻醒来一次。

l 参数ifidx [in]：接口索引

l 参数dtim_int [in]：新的DTMI周期，该值的含义是beacon周期的个数

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.3. ieee80211_conf_set_bss_max_idle

ieee80211_conf_set_bss_max_idle API用于设置AP接口的max idle参数。该参数要求sta在max idle时间内至少通信一次，让AP判断sta是否在线。

l 参数ifidx [in]：接口索引

l 参数max_idle_period [in]：max idle时间，单位：秒，默认是300 秒。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.4. ieee80211_conf_set_bssid

ieee80211_conf_set_bssid API用于设置WiFi连接的BSSID。只有在要绑定固定的AP设备时才需要使用此API。

l 参数ifidx [in]：STA接口索引

l 参数bssid [in]：AP的mac地址

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.5. ieee80211_conf_set_mac

ieee80211_conf_set_mac API用于修改接口的MAC地址。

l 参数ifidx [in]：接口索引

l 参数mac [in]：设置新的MAC地址

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.6. ieee80211_conf_set_aphide

ieee80211_conf_set_aphide API用于设置AP接口隐藏 SSID。隐藏SSID的AP不会被设备扫描到，除非设备在扫描时指定了ssid参数。

l 参数ifidx [in]：接口索引

l 参数hide [in]：0：关闭隐藏，1：开启隐藏。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.7. ieee80211_conf_set_hwmode

ieee80211_conf_set_hwmode 用于设置WiFi协议模式。

enum ieee80211_hwmode {

IEEE80211_HWMODE_NONE,

IEEE80211_HWMODE_11B, // b only

IEEE80211_HWMODE_11G, // bg mix

IEEE80211_HWMODE_11N, // bgn mix

IEEE80211_HWMODE_11AH, // ah only

};

l 参数ifidx [in]：接口索引

l 参数mode [in]：WiFi协议模式：enum ieee80211_hwmode。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.8. ieee80211_expand_mlme_size

ieee80211_expand_mlme_size API用于扩展WiFi协议栈的管理帧长度。当需要在管理帧中添加自定义element时，可能会遇到管理帧buffer长度不够的情况，可以通过此API通知协议栈扩展管理帧长度，便于添加自定义的element信息。

l 参数ifidx [in]：接口索引

l 参数 size [in]：需要扩展size的管理帧信息。

/*MLME frame expand size*/

struct ieee80211_mlme_size{

uint16 probe_req, probe_resp;

uint16 beacon, vendor_spec_action;

uint16 assoc_req, assoc_resp;

uint8 auth, deauth, disassoc, addba_resp;

uint16 p2p_neg;

};

每个字段对应一种管理帧的扩展size，表示需要协议栈在创建此管理帧时扩大指定的size。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.9. ieee80211_conf_set_wpa_cipher

ieee80211_conf_set_wpa_cipher API用于修改协议栈的WiFi加密参数。

l 参数ifidx [in]：接口索引。

l 参数 wpa_proto [in]：WPA协议版本

l 参数 pairwise_cipher [in]：获取的AP的加密信息。

l 参数 group_cipher [in]：获取的AP的加密信息。

l 返回值：表示是否成功，0：成功，非0：失败。

n 参数wpa_proto取值如下：

#define WPA_PROTO_WPA BIT(0)

#define WPA_PROTO_RSN BIT(1)

l 参数pairwise_cipher和 group_cipher取值如下：

#define WPA_CIPHER_NONE BIT(0)

#define WPA_CIPHER_TKIP BIT(3)

#define WPA_CIPHER_CCMP BIT(4)

#define WPA_CIPHER_CCMP_256 BIT(9)

1.3.10. ieee80211_conf_set_isolate

ieee80211_conf_set_isolate API用于设置接口隔离。WiFi协议栈默认允许所有接口之间相互转发通信。该API可以设置接口处于隔离状态，不能和其他接口转发通信。

l 参数ifidx [in]：接口索引

l 参数 isolate [in]：0：关闭隔离，1：开启隔离

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.11. ieee80211_conf_set_chanlist

ieee80211_conf_set_chanlist API用于设置自定义信道列表。执行此API将会修改WiFi的信道列表，可以完全自定义信道列表。

l 参数ifidx [in]：接口索引

l 参数chan_list [in]：信道列表，要求是uint16数组。

l 参数count [in]：信道数量

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.12. ieee80211_conf_set_wpa_group_rekey

ieee80211_conf_set_wpa_group_rekey API用于设置AP接口的组播key更新周期。

l 参数ifidx [in]：接口索引

l 参数wpa_group_rekey [in]：更新周期，单位：秒。设置0表示关闭组播key更新功能。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.13. ieee80211_conf_set_dupfilter

ieee80211_conf_set_dupfilter API用于设置WiFi协议栈是否开启重复包过滤功能。

l 参数ifidx [in]：接口索引

l 参数 enable [in]：0：关闭重复包过滤，1：开启重复包过滤

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.14. ieee80211_conf_set_conn_timeout

ieee80211_conf_set_conn_timeout API用于修改WiFi协议栈的连接超时时间。

l 参数ifidx [in]：接口索引

l 参数 auth_tmo [in]：auth阶段的timeout值，默认值是100ms。

l 参数 assoc_tmo [in]：assoc阶段的timeout值，默认值是100ms。

l 参数 handshake_tmo [in]：4次握手阶段的timeout值，默认是2000ms。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.15. ieee80211_conf_set_aplost_time

ieee80211_conf_set_aplost_time API用于设置STA接口检测AP离线的时间。超过设置的时间未收到AP的任何数据，则认为AP已离线。

l 参数ifidx [in]：接口索引

l 参数time [in]：检测AP离线的时间。默认值30，表示30个beacon周期。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.16. ieee80211_conf_set_wmm_enable

ieee80211_conf_set_wmm_enable API用于设置WiFi协议栈是否开启QoS功能，该功能默认是开启状态。

l 参数ifidx [in]：接口索引

l 参数enable [in]：0：关闭QoS，1：开启QoS。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.17. ieee80211_conf_set_wmm_param

ieee80211_conf_set_wmm_param API用于修改WMM EDCA参数。修改EDCA参数通常是4个AC一起修改，所以该API需要执行4次。

l 参数 ifidx [in]：接口索引

l 参数 ac [in]：EDCA AC队列，取值范围：0，1，2，3，对应：AC_VO,AC_VI,AC_BK,AC_BE

l 参数 param [in]：指定某个AC的EDCA参数，参数定义如下：

struct ieee80211_wmm_param {

uint16 txop; //连续发送的时间上限，0：只发送一帧，单位:us

uint16 cw_min; //竞争窗口指数的最小值

uint16 cw_max; //竞争窗口指数的最大值

uint8 aifsn; //仲裁帧间隙数

uint8 acm; //暂未使用

};

对AP接口来说，参数ac有2种情况：

n ac参数取值：[0xf0, 0xf1, 0xf2, 0xf3]，表示只修改自己的本地edca参数，不影响sta的edca参数。

n ac参数取值：[0,1,2,3],表示修改sta的edca参数。执行此API会修改AP发送的beacon帧中的wmm参数，sta会依此更新自己的edca参数。

对于STA接口来说，执行此API只修改本地EDCA参数，同时会拒绝更新AP发送的EDCA参数。

1.3.18. ieee80211_conf_set_use4addr

ieee80211_conf_set_use4addr API用于设置接口是否开启4地址模式。AP接口可以自动兼容4地址sta和非4地址sta。

l 参数ifidx [in]：接口索引

l 参数enable [in]：0：关闭4地址模式，1：开启4地址模式。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.19. ieee80211_conf_set_psdata_cnt

ieee80211_conf_set_psdata_cnt API用于设置AP为休眠sta缓存数据的最大数量。缓存数据超过最大数量时，丢弃旧的数据，缓存新的数据。

l 参数ifidx [in]：接口索引

l 参数max_cnt [in]：允许缓存数据的最大数量。

l 返回值：表示是否成功，0：成功，非0：失败。

1.3.20.

ieee80211_conf_set_datatag API用于给特定的数据设置标签，标签可以是uint32类型的任意值，只要应用程序自己能识别即可。

该API通常是结合hook机制使用，在hook中识别特定数据后，给该数据打上标签。WiFi协议栈在发送该数据后会根据发送成功或失败，产生SYSEVT_WIFI_TX_SUCCESS或SYSEVT_WIFI_TX_SUCCESS事件。这2个事件的event data就是该数据的标签值。

l 参数ifidx [in]：接口索引

l 参数hdl [in]：数据handle，这个值来自struct ieee80211_hookdata。在执行hook的tx/rx 函数时可以获取这个值。

l 参数 tag [in]：数据标签。

l 返回值：表示是否成功，0：成功，非0：失败。

1.4. 一键配对API

1.4.1. ieee80211_pair_enable

ieee80211_pair_enable API用于初始化协议栈的一键配对功能。

l 参数ifidx [in] ：启用配对功能的接口索引

l 参数pair_magic [in] ：配对功能的magic number，在配对时相同magic number的设备才能相互配对成功。

l 返回值：表示是否成功，0：成功，非0：失败

1.4.2. ieee80211_pairing

ieee80211_pair_enable API用于控制一键配对功能的开/关。

l 参数ifidx [in] ：start/stop配对功能的接口索引

l 参数pair_magic [in] ：0：停止配对，1：启动配对，大于1：启动配对，并修改magic number。

l 返回值：表示是否成功，0：成功，非0：失败

1.4.3. ieee80211_unpair

ieee80211_unpair API用于执行配对信息解绑。

l 参数ifidx [in] ：配对解绑的接口索引

l 参数mac [in] ：需要解绑的设备MAC地址，AP和STA都可以执行此API发起解绑操作，mac参数是对方的MAC地址。

l 返回值：表示是否成功，0：成功，非0：失败

1.4.4. ieee80211_conf_set_pair_ngo

ieee80211_conf_set_pair_ngo API用于开启配对角色协商功能。

配对协商功能是指2个相同角色的设备配对时，协商谁做AP，谁做STA。

默认的协商规则是通过比较MAC地址大小：大的做AP，小的做STA。

触发此功能时会产生IEEE80211_EVENT_PAIR_NGO事件，通过此事件可以自定义协商规则。

此功能默认是开启的，可以通过该API关闭此功能。

l 参数ifidx [in] ：配对解绑的接口索引

l 参数enable[in] ：是否启用配对协商功能。

l 返回值：表示是否成功，0：成功，非0：失败

1.5. 连接扫描API

1.5.1. ieee80211_scan

ieee80211_scan API用于控制协议栈进行扫描。

l 参数ifidx [in] ：执行扫描动作的接口索引

l 参数start [in] ：1：启动扫描，0：停止扫描，在扫描完成时也会自动停止。

l 参数scan_param [in]: 扫描控制参数：

struct ieee80211_scandata {

uint32 chan_bitmap; //需要扫描的channel bitmap，每个bit位对应一个channel，bit位为1，表示需要扫描该channel。channel_bitmap=0，则扫描所有的channel

uint8 ssid[SSID_MAX_LEN+1]; //指定扫描特定的ssid

uint8 scan_time, //每个channel的扫描时间，单位：毫秒，默认是20ms

scan_cnt; //每个channel扫描时发送probe request的次数，默认发送2次。

uint8 passive_scan: 1, //是否执行被动扫描，不发送probe request

flush: 1, //启动扫描时是否清空AP列表

rev: 6;

};

l 返回值：表示是否成功，0：成功，非0：失败

注意：该API仅启动协议栈开始扫描，该API返回不代表协议栈已经完成扫描。扫描完成时会产生SYSEVT_WIFI_SCAN_DONE 事件。接收SYSEVT_WIFI_SCAN_DONE 事件后才能获取AP信息列表。

1.5.2. ieee80211_get_bsslist

ieee80211_get_bsslist API用于从WiFi协议栈获取AP列表。

l 参数bsslist [out]：接收AP列表信息的buffer地址

l 参数list_size [in]：buffer size

l 参数ignore_dis [in]：指示是否忽略被disable的AP信息。

l 返回值：获取到的AP信息数量。

注意：AP信息列表存在老化时间。当AP列表个数大于bss_maxcnt的二分之一时老化时间自动调整为5s,否则老化时间为bss_lifetime。老化时间到达后会清除部分超时的AP信息。bss_maxcnt 和 bss_lifetime是WiFi初始化时设置的参数。

1.5.3. ieee80211_cleanup_bsslist

ieee80211_cleanup_bsslist API用于清空WiFi协议栈缓存的AP列表信息。

l 返回值：表示是否成功，0：成功，非0：失败

1.5.4. ieee80211_conf_set_auto_assoc

ieee80211_conf_set_auto_assoc API用于设置WiFi协议栈是否进行自动连接和自动扫描。协议栈默认是自动连接，自动扫描。使用此API可以关闭此行为，由应用程序控制协议栈的连接和扫描行为。

执行连接使用ieee80211_start_connect API，执行扫描使用ieee80211_scan API。

l 参数ifidx [in]：接口索引。

l 参数 auto_assoc [in]：0：关闭自动连接，1：开启自动连接

l 参数 auto_scan [in]：0：关闭自动扫描，1：开启自动扫描

l 返回值：表示是否成功，0：成功，非0：失败。

1.5.5. ieee80211_start_connect

ieee80211_start_connect API用于控制WiFi协议栈发起连接。通常是在关闭自动连接的情况下使用此API。关闭自动连接后，此API执行一次，WiFi协议栈就执行一次连接。不管是否连接成功，WiFi协议栈就会停下来，不会再次自动发起连接。

l 参数ifidx [in]：接口索引。

l 返回值：表示是否成功，0：成功，非0：失败。

1.5.6. ieee80211_disassoc

ieee80211_disassoc API用于控制WiFi协议栈断开连接。执行此API可以断开连接，但是sta可能会又再次发起连接，只要ssid/密码是正确的，sta依然可以再次连接成功。

l 参数ifidx [in]：接口索引

l 参数 addr [in]：需要断开的sta mac地址

l 返回值：表示是否成功，0：成功，非0：失败

1.5.7. ieee80211_disassoc_all

ieee80211_disassoc_all API用于控制WiFi协议栈断开所有sta连接。

l 参数ifidx [in]：接口索引

l 返回值：表示是否成功，0：成功，非0：失败

1.5.8. ieee80211_bss_add_manualAP

ieee80211_bss_add_manualAP API用于向协议栈注册AP信息，通常是用于快速连接。应用代码将上次连接的AP信息保存到flash，开机时使用flash存储的AP信息向协议栈注册AP信息，可以让协议栈跳过扫描的过程，直接发起连接，减少连接过程的时间。

l 参数ssid [in]：添加的AP ssid

l 参数 bssid [in]：添加的AP的mac地址

l 参数 channel [in]：AP所在的信道

l 参数 band [in]：AP的频段信息

l 参数 wpadata [in]：AP的加密信息，这个值保存时使用ieee80211_bss_get_wpadata API从协议栈中获取。

l 返回值：表示是否成功，0：成功，非0：失败。

1.6. 数据收发API

1.6.1. ieee80211_scatter_tx

ieee80211_scatter_tx API用于发送非连续的片段数据，主要是对接LWIP时使用。数据必须是以太网帧格式。

l 参数ifidx [in] ：发送数据的接口索引

l 参数data [in] ：scatter_data数组地址

l 参数count [in] ：scatter_data数组的大小

l 返回值：表示是否成功，0：成功，非0：失败

1.6.2. ieee80211_tx

ieee80211_tx API用于发送连续的数据，数据必须是以太网帧格式。

l 参数ifidx [in] ：发送数据的接口索引

l 参数data [in] ：数据地址。

l 参数size [in] ：数据长度

l 返回值：表示是否成功，0：成功，非0：失败

1.6.3. ieee80211_input

ieee80211_input API用于向WiFi协议栈输入一笔RX数据，借助WiFi协议栈的RX通道，向上输入到lwip或主控。

l 参数ifidx [in] ：接口索引

l 参数data [in] ：数据地址，数据必须是以太网帧格式。

l 参数 len [in] ：数据长度

l 返回值：表示是否成功，0：成功，非0：失败

1.6.4. ieee80211_tx_mgmt

ieee80211_tx_mgmt API用于发送自定义管理帧。应用程序需要自行组装完整的WiFi管理帧再调用此API进行发送。

l 参数ifidx [in] ：发送管理帧的接口索引

l 参数data [in] ：管理帧数据地址，数据必须是完整的WiFi帧格式。MAC header的seq number和duration 填0即可。

l 参数 len [in] ：管理帧数据长度

l 返回值：表示是否成功，0：成功，非0：失败

1.6.5. ieee80211_tx_custmgmt

ieee80211_tx_custmgmt API用于发送自定义管理帧。为了简化自定义管理帧的发送，WiFi协议栈提供了这个API，使用此API可以不用关心WiFi帧格式如何组装。对WiFi帧格式不熟悉的情况下，也可以发送自定义管理帧。该API只要求提供任意格式的payload数据即可，协议栈会完成WiFi帧格式的封装。使用此API发送的管理帧，需要配合 IEEE80211_EVENT_RX_CUSTMGMT 来接收。

l 参数ifidx [in] ：发送管理帧的接口索引

l 参数 dest [in]：发送此管理帧的目的地址，可以是广播地址。

l 参数 data [in] ：管理帧数据地址。可以是任意格式的数据，将作为管理帧payload发送。

l 参数 len [in] ：管理帧数据长度

l 返回值：表示是否成功，0：成功，非0：失败

1.7. Hook和Event API

1.7.1.

ieee80211_register_pkthook API用于向WiFi协议栈注册hook，hook机制的介绍请阅读第5章节。

l 参数hook [in]：需要注册的hook信息

l 返回值：表示是否成功，0：成功，非0：失败

1.7.2. ieee80211_event_cb

ieee80211_event_cb API用于修改WiFi协议栈的event callback函数。执行此API将更新协议栈的event callback函数，同时该函数将返回旧的event callback函数。

应用程序在修改event callback时，应当将旧的callback函数保存下来，当执行完自己的callback函数应继续执行旧的callback函数，避免丢失旧的callback，造成其他模块无法正常工作。

l 参数cb [in]：新的event callback函数

l 返回值：协议栈旧的event callback函数

1.8. 低功耗API

1.8.1. ieee80211_conf_wakeup_sta

ieee80211_conf_wakeup_sta API用于AP接口唤醒休眠的STA，并通知STA被唤醒的原因。

l 参数ifidx [in]：接口索引

l 参数addr [in]：被唤醒的sta mac地址

l 参数reason [in]：唤醒sta的原因

l 返回值：表示是否成功，0：成功，非0：失败。

1.8.2. ieee80211_conf_get_wkreason

ieee80211_conf_get_wkreason API用于获取协议栈接收到的唤醒原因。该唤醒原因通常是AP唤醒sta时，由AP告知sta是什么原因唤醒它。该功能是泰芯自定义低功耗功能，可以实现由AP在唤醒STA时通知STA唤醒原因。

l 参数ifidx [in]：接口索引

l 返回值：唤醒原因。0：正常开机或AP未告知唤醒原因，非0：AP告知的唤醒原因。

1.9. 信息获取API

1.9.1. ieee80211_status

ieee80211_status API用于打印协议栈的调试信息。

l 参数buff [in] ：接收调试信息的换成buffer

l 参数size [in] ：buffer size

l 返回值：表示是否成功，0：成功，非0：失败

1.9.2. ieee80211_conf_get_psk

ieee80211_conf_get_psk API用于获取WiFi协议栈使用的密文密码。

l 参数ifidx [in]：接口索引

l 参数psk [out]：接收psk的buffer地址，该buffer的size不能小于32byte。

l 返回值：表示是否成功，0：成功，非0：失败。

1.9.3. ieee80211_conf_get_keymgmt

ieee80211_conf_get_keymgmt API用于获取WiFi协议栈当前使用的加密模式。

l 参数ifidx [in]：接口索引

l 返回值：WiFi加密模式。

1.9.4. ieee80211_conf_get_ssid

ieee80211_conf_get_ssid API用于获取WiFi协议栈当前使用的ssid参数。

l 参数ifidx [in]：接口索引

l 参数ssid [out]：接收SSID参数的buffer地址，该buffer的size不能小于32byte。

返回值：表示是否成功，0：成功，非0：失败。

1.9.5. ieee80211_get_stalist

ieee80211_get_stalist API用于从WiFi协议栈获取sta信息列表。

l 参数ifidx [in]：接口索引

l 参数stalist [out]：接收sta列表信息的buffer地址

l 参数list_size [in]：buffer size

l 返回值：获取到的sta信息数量。

1.9.6. ieee80211_conf_get_bssbw

ieee80211_conf_get_bssbw API用于获取WiFi协议栈当前使用的BSS带宽。

l 参数ifidx [in]：接口索引

l 返回值：WiFi协议栈当前使用的BSS带宽。

1.9.7. ieee80211_conf_get_bssid

ieee80211_conf_get_bssid API用于获取WiFi当前连接的AP MAC地址。AP接口执行此API返回是AP接口的MAC地址。STA接口执行此API返回的是sta连接的ap mac地址，或者sta断开连接时返回是ieee80211_conf_set_bssid API设置的bssid。

l 参数ifidx [in]：STA接口索引

l 参数bssid [out]：bssid

l 返回值：表示是否成功，0：成功，非0：失败。

1.9.8. ieee80211_conf_get_channel

ieee80211_conf_get_channel API用于获取当前的WiFi信道。

l 参数ifidx [in]：接口索引

l 返回值：返回当前的WiFi信道。

1.9.9. ieee80211_conf_get_mac

ieee80211_conf_get_mac API用于获取接口的MAC地址。

l 参数ifidx [in]：接口索引

l 参数mac [out]：获取的MAC地址

l 返回值：表示是否成功，0：成功，非0：失败。

1.9.10. ieee80211_conf_get_connstate

ieee80211_conf_get_connstate API用于获取当前的连接状态。

l 参数ifidx [in]：接口索引

l 返回值：当前连接状态，返回值定义如下：

enum wpa_states {

WPA_DISCONNECTED, //0 断开连接

WPA_INTERFACE_DISABLED, //1 接口已关闭

WPA_INACTIVE, //2 关闭状态

WPA_SCANNING, //3 扫描状态

WPA_AUTHENTICATING, //4 发起认证状态

WPA_ASSOCIATING, //5 发起连接状态

WPA_ASSOCIATED, //6 已连接状态

WPA_4WAY_HANDSHAKE, //7 4次握手状态

WPA_GROUP_HANDSHAKE, //8 组播key握手状态

WPA_COMPLETED, //9 连接完成状态

};

l

1.9.11. ieee80211_conf_get_stainfo

ieee80211_conf_get_stainfo API用于从WiFi协议栈获取单个sta信息。可以根据AID，或MAC地址来获取sta信息。

l 参数ifidx [in]：接口索引

l 参数aid [in]：需要获取的sta aid，aid非0时根据aid查找sta。

l 参数mac [in]：需要获取的sta mac地址，当mac不是NULL值时，优先则根据mac地址查找sta。

l 返回值：表示是否成功，0：成功，非0：失败。

1.9.12. ieee80211_conf_get_stalist

ieee80211_conf_get_stalist API用于从WiFi协议栈获取sta信息列表。

l 参数ifidx [in]：接口索引

l 参数sta [out]：接收sta信息列表的buffer地址

l 参数count [in]：buffer可存储sta信息的数量。

l 返回值：实际获取的sta数量。

1.9.13. ieee80211_conf_get_stacnt

ieee80211_conf_get_stacnt API用于获取指定接口所连接的sta数量。

l 参数ifidx [in]：接口索引

l 返回值：该接口连接的sta数量。

1.9.14. ieee80211_conf_get_reason_code

ieee80211_conf_get_reason_code API获取连接失败的reason code。在连接失败时该API返回的reason code才是有效值。

l 参数ifidx [in]：接口索引

l 返回值：reason code。

SDK添加了部分自定义reason code，在sdk/include/lib/umac/ieee80211.h文件中，说明如下：

/* txsemi custom reason code */

enum IEEE80211_TXREASON{

WLAN_REASON_AP_NOT_FOUND = 60000, //未发现AP

WLAN_REASON_PAIR_START, //启动配对断开连接

WLAN_REASON_UNPAIR, //解除配对绑定

WLAN_REASON_RELAY_DISCONNECT, //上级中继链路断开

};

1.9.15. ieee80211_conf_get_status_code

ieee80211_conf_get_status_code API获取连接失败的status code。在连接失败时该API返回的status code才是有效值。

l 参数ifidx [in]：接口索引

l 返回值：status code。

1.9.16. ieee80211_chan_center_freq

ieee80211_chan_center_freq 用于获取指定channel的中心频点信息。

l 参数ifidx [in]：接口索引

l 参数 channel [in]：信道号

l 返回值：指定信道的中心频点。

1.9.17. ieee80211_bss_get_wpadata

ieee80211_bss_get_wpadata API用于获取当前连接的AP的加密信息，主要是用于将AP信息保存到flash，加速开机连接过程。

l 参数bssid [in]：需要获取的AP mac地址，根据mac地址查找ap信息。

l 参数 band [in]：AP的频段信息

l 参数 wpadata [out]：获取的AP的加密信息。

l 返回值：表示是否成功，0：成功，非0：失败。

1.10. WiFi漫游API

SDK WiFi协议栈的标准协议和泰芯私有协议都可以支持快速漫游功能，2者之间的区别如下：

l 标准协议：

n 优点：可以兼容标准协议802.11kvr协议

n 缺点：协议栈的STA模式支持快速漫游，AP模式不支持。STA模式使用快速漫游时需要路由器支持802.11kvr协议才可以进行漫游。是否支持无缝漫游也取决于路由器。

l 私有协议：

n 优点：AP和STA模式均支持漫游，且AP支持STA进行无缝漫游。

n 缺点：不能和标准协议兼容，只能是私有协议的AP和STA共同工作。

1.10.1. 标准协议漫游

TBD...

1.10.2. 私有协议漫游

开启漫游功能后，协议栈在运行过程中会实时监测当前的rssi。连续统计n个beacon帧的rssi进行累加平均，降低因信号抖动产生的影响。当检测rssi低于设定的漫游门限时，开始检查AP列表中是否存在更合适的AP。

如果找到更合适的AP则向当前AP发起漫游请求，当前AP接收漫游请求后记录STA进入漫游状态，开始为sta的缓存数据，并回复response给STA。

STA接收到response后开始向新的AP发起连接请求，如果连接失败，则会回连到旧AP，继续和旧AP通信。如果连接成功，旧AP则会将缓存的数据发送给新AP，由新AP发送给sta，避免因漫游产生数据丢失。

1.10.2.1. ieee80211_wnb_roam_enable

ieee80211_wnb_roam_enable API用于初始化协议栈漫游功能。

l 参数ifidx [in]：接口索引。

l 返回值：表示是否成功，0：成功，非0：失败。

1.10.2.2. ieee80211_conf_set_roaming

ieee80211_conf_set_roaming API用于设置漫游功能开关。

l 参数ifidx [in]：接口索引。

l 参数 roaming [in]：0：关闭漫游，1：开启漫游

l 返回值：表示是否成功，0：成功，非0：失败。

1.10.2.3. ieee80211_conf_set_roam_config

ieee80211_conf_set_roam_config API用于设置漫游功能参数。

l 参数ifidx [in]：接口索引。

l 参数 roam_rssi_th [in]：触发漫游的rssi门限

l 参数 roam_rssi_diff [in]：设置新旧AP的rssi差值，大于此差值的新AP才能被选中，避免频繁反复漫游切换。

l 参数 roam_rssi_int [in]：设置连续监测多少个beacon的rssi进行累加平均。

l 返回值：表示是否成功，0：成功，非0：失败。

📄️ {{item.documents.name}}

🗃️ {{item.documents.name}}