TXTAIXIN文档
V1.0 / 指南 / 中文

TXSDK_WiFi开发指南

下载 PDF

logo

责任与版权

责任限制

由于产品版本升级或者其他原因，本文档会不定期更新。除非另行约定，泰芯半导体有限公司对本文档所有内容不提供任何担保或授权。

客户应在遵守法律、法规和安全要求的前提下进行产品设计，并做充分验证。泰芯半导体有限公司对应用帮助或客户产品设计不承担任何义务。客户应对其使用泰芯半导体有限公司的产品和应用自行负责。

在适用法律允许的范围内，泰芯半导体有限公司在任何情况下，都不对因使用本文档相关内容及本文档描述的产品而产生的损失和损害进行超过购买支付价款的赔偿（除在涉及人身伤害的情况中根据适用的法律规定的损害赔偿外）。

版权申明

泰芯半导体有限公司保留随时修改本文档中任何信息的权利，无需提前通知且不承担任何责任。

未经泰芯半导体有限公司书面同意，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。除非获得相关权利人的许可，否则，任何人不能以任何形式对前述软件进行复制、分发、修改、摘录、反编译、反汇编、解密、反向工程、出租、转让、分许可等侵犯本文档描述的享有版权的软件版权的行为，但是适用法禁止此类限制的除外。

修订记录

日期

版本

描 述

修订人

2024-05-07

V1.0

TX

1. 概述

TXSDK是泰芯半导体发布的WiFi系列芯片开发SDK。本文档是TXSDK的WiFi功能开发指南，介绍了SDK的WiFi协议栈所支持的功能以及使用方法，适用于所有的泰芯WiFi芯片SDK。

SDK的WiFi协议栈同时支持标准WiFi协议和泰芯私有WiFi协议，支持标准协议和私有协议互通。可以根据产品实际需求，选择标准协议或私有协议。

SDK的WiFi协议栈的特性综述如下：

  1. 工作模式：AP,STA,P2P,APSTA,WNBAP,WNBSTA,TXMESH
  2. 安全模式：OPEN，WPA2-PSK，WPA3-PSK
  3. 协议标准：WiFi标准协议(11BGN，11AX，11AH) ， 泰芯私有WiFi协议
  4. 一键配对：支持AP，STA一键配对组网，简化组网参数设置。
  5. 快速漫游：支持STA在多个AP之间快速漫游。
  6. 休眠唤醒：支持STA进入低功耗状态，支持休眠唤醒。
  7. 无线桥接：支持WiFi接口与其他网络接口进行桥接，例如网口。
  8. 动态裁剪：未启用的功能代码，在程序链接时会自动移除，减少代码体积。
  9. 二次开发：SDK的WiFi协议栈设计了Event和Hook机制，支持应用代码参与控制协议栈的运行，以满足应用方案对WiFi功能进行管理控制的需求（详见第4，5章节）。

2. WiFi工作模式

SDK的WiFi协议栈支持多种工作模式，可以根据产品方案需求选择不同的工作模式。

2.1. AP模式

SDK支持WiFi AP模式，提供WiFi热点服务。支持4地址模式，支持多STA接入，支持STA进入低功耗状态和休眠唤醒。

该AP模式是指标准协议的AP功能，例如TXW81x芯片可支持常见的手机，无线网卡接入，TXW8301芯片可支持802.11ah STA设备接入。

2.2. STA模式

SDK支持WiFi STA模式，作为WiFi设备接入到其他WiFi AP。STA模式支持低功耗功能，支持4地址模式桥接和3地址模式桥接。

该STA模式是指标准协议的STA功能，例如TXW81x芯片可以连接常见的WiFi路由器，TXW8301芯片可以连接802.11ah路由器。

2.3. 中继模式

SDK支持WiFi中继模式，也就是APSTA模式。中继模式是AP功能和STA功能的组合体，可实现无线中继功能。

中继模式时WiFi协议栈同时启用AP接口和STA接口，STA用于连接上一级AP，AP接口则用于提供AP热点，接受其他STA接入。

中继模式支持自动中继功能，协议栈自动搜寻周围的AP热点，选择最优AP进行连接，可实现多设备自动组网，中继转发。

2.4. P2P模式

SDK支持WiFi p2p模式，也就是WiFi direct功能。可支持开发WiFi p2p类型的应用方案。

2.5. WNBAP模式

SDK支持WNBAP模式，该模式是泰芯私有WiFi协议的AP模式，可兼容v1.x SDK固件。泰芯私有协议可支持更快速的连接过程，最快20ms左右可以完成连接。支持wnbsta快速无缝漫游，最快50ms左右完成漫游，漫游过程中可实现不丢数据。

注：只支持WNBSTA连接。

2.6. WNBSTA模式

SDK支持WNBSTA模式，该模式是泰芯私有WiFi协议的STA模式，可以兼容v1.x SDK固件。可支持更快速的连接，支持快速漫游。

注：只能连接WNBAP。

2.7. TXMesh模式

SDK支持TXMesh模式，该模式是泰芯私有Mesh协议。支持跳频通信，多节点自动组网转发通信，转发层级无限制，支持IPv4和IPv6。

3. WiFi协议栈初始化

SDK WiFi协议栈初始化代码在main.c文件中的sys_wifi_init函数，包含了WiFi协议栈初始化和WiFi模式初始化。

WiFi协议栈所支持的各种工作模式，是以WiFi接口形式存在的。所有的API都需要接口索引参数，用于表示设置的是哪个WiFi接口。

WiFi协议栈初始化之前需要分配好TX，RX buffer，在sys_config.h文件中定义了WiFi TX/RX buffer，详细说明请阅读SDK入门指南的第4章节。

如上图所示：

  • skbpool_init 是WiFi协议栈的TX/RX buffer初始化。
  • sys_lmac_init是lmac协议栈初始化。
  • ieee80211_init是WiFi协议栈初始化，初始化参数说明如下：

struct ieee80211_initparam {

uint8 vif_maxcnt; //支持的接口数量

uint8 bss_maxcnt; //BSS列表缓存AP信息的最大数量，当数量超过该值的1/2时，AP信息的生存时间是5s，5s之后开始清除缓存信息

uint8 headroom, tailroom;

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

uint16 bss_lifetime; //BSS列表AP信息的生存时间，单位：秒

uint16 stack_size; //WiFi协议栈的堆栈大小，默认是2048

uint16 no_rxtask:1, //WiFi协议栈是否使用独立的RX Task

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

rev: 11;

ieee80211_evt_cb evt_cb; //WiFi协议栈的event callback

};

  • ieee80211_support_txw81x是开启WiFi协议栈支持TXW81x系列芯片。
  • ieee80211_deliver_init是开启WiFi协议栈的转发功能，并指定转发路由表的最大路由信息条数（128条）和路由信息生存时间（60秒）。

3.1. AP模式初始化

AP模式初始化主要是创建AP接口，设置AP接口参数，并启动AP接口，如下图所示：

如上图所示：

  • ieee80211_iface_create_ap API是创建AP接口，需要指定接口的索引ID和WiFi Band类型。
  • IEEE80211_BAND_2GHZ：2.4G类型WiFi
  • IEEE80211_BAND_S1GHZ：802.11ah WiFi
  • wificfg_flush函数是将系统参数刷写到WiFi协议栈，并指定接口索引WIFI_MODE_AP
  • ieee80211_iface_start函数是启动WiFi协议栈的功能接口。
  • 停止协议栈功能接口的API是ieee80211_iface_stop函数。

3.2. STA模式初始化

STA模式初始化主要是创建STA接口，设置STA接口参数，并启动STA接口，如下图所示：

如上图所示：

  • ieee80211_iface_create_sta API是创建STA接口，需要指定接口的索引ID和WiFi Band类型。
  • ieee80211_conf_set_use4addr 是设置支持sta接口的4地址模式，可用于4地址桥接功能。
  • ieee80211_conf_stabr_table设置开启sta接口的3地址桥接功能，并指定路由表信息最大数量和生存时间。桥接功能可根据实际产品需要选择关闭，或开启3地址桥接，或开启4地址桥接。
    • 3地址桥接和4地址桥接的功能区别：
  • 3地址桥接：
    • 优点：使用3地址桥接时，不需要对路由器做任何设置。
    • 缺点：有防火墙管控的网络，可能会造成桥接后的设备不能访问外部网络。
  • 4地址桥接：
    • 优点：使用4地址桥接时，可以不受防火墙的影响。
    • 缺点：需要设置路由器支持4地址。可能部分路由器不支持，或者需要修改参数才能支持。

SDK的无线网桥方案的demo代码针对3地址和4地址桥接功能做了自适应适配，自动检查当前网络环境是适用3地址模式，还是4地址模式。

3.3. 中继模式初始化

中继模式是AP功能和STA功能的组合体，所以中继模式的初始化需要同时初始化AP模式和STA模式。WIFI_MODE_APSTA宏定义值并不是协议栈的接口索引。创建接口的索引还是WIFI_MODE_AP和WIFI_MODE_STA。

开启中继功能时参数设置有所差别，其中ssid/psk 用于STA接口连接上一级AP，r_ssid/r_psk则用于AP接口，提供AP热点服务。如下图所示：

使用ieee80211_conf_set_relay_mode API开启自动中继功能。实际上不执行该API，开启中继功能的WiFi协议栈也会自动搜索连接周围的AP，实现自动中继的效果。但是在链路择优，避免链路回环方面可能会有问题。所以当需要多设备中继组网通信时请开启自动中继功能。

3.4. P2P模式初始化

WiFi P2P功能是2个WiFi设备通过协议协商选择一个做GO(AP)，另一个做GC(STA)，然后建立WiFi连接。所以P2P模式的初始化涉及到AP接口，STA接口，P2P接口的初始化。如下图所示：

开启p2p功能后，通过手机可搜索发现p2p设备，并进行连接。可以根据应用需要，控制WiFi设备是做GO，还是GC。

3.5. WNBAP模式初始化

WNBAP模式是泰芯私有协议的AP模式，初始化工作主要是创建WNBAP接口，并设置参数。如下图所示：

参数设置，使用方式 和AP模式一样。示例代码中的wnbap接口开启了一键配对功能。

私有协议的AP接口和STA接口，仅仅是初始化API不同，其他参数设置API和使用方式与标准协议接口没有区别。

3.6. WNBSTA模式初始化

WNBAP模式是泰芯私有协议的STA模式，初始化工作主要是创建WNBSTA接口，并设置参数。如下图所示：

参数设置和使用方式，与STA模式一样。示例代码的wnbsta接口开启了一键配对和快速漫游功能。

3.7. Mesh模式初始化

SDK的WiFi协议栈支持Mesh功能，并支持跳频通信。协议栈实现的Mesh功能是树状网络，支持多节点多跳通信，支持IPv4和IPv6。Mesh功能适用于多设备自组网通信，例如智能电表。

4. WiFi协议栈Event机制

SDK WiFi协议栈设计了event机制。协议栈运行过程中在不同的阶段会产生不同的event，通过这些event应用程序可以参与控制WiFi协议栈的运行。

协议栈的event 处理函数在初始化时通过evt_cb参数指定event callback函数。需要注意的是该callback是在协议栈的运行任务中执行的，所以不能在callback中执行复杂耗时的逻辑，以免影响协议栈的运行效率。

event callback定义如下：

  • 参数ifidx：产生事件的接口索引
  • 参数evt：事件id，见枚举：enum ieee80211_event
  • 参数param1：event参数1，具体含义需要查阅event列表说明
  • 参数param2：event参数2，具体含义需要查阅event列表说明
  • 返回值：不同的event，返回值具有不同的含义，具体需要查阅event列表说明。

4.1. WiFi协议栈Event列表

4.1.1. IEEE80211_EVENT_PAIR_START

启动配对事件。当协议栈启动一键配对时产生此事件。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.2. IEEE80211_EVENT_PAIR_SUCCESS

配对成功事件。在AP和STA配对成功时产生此事件。配对成功之后，在停止配对之前，协议栈会重复周期性产生此事件，直到停止配对。

    • param1：uint8* 类型，此次配对成功的另一端设备的MAC地址。
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.3. IEEE80211_EVENT_PAIR_DONE

停止配对事件。停止配对时产生此事件。

    • param1：uint8 * 类型，此次配对成功的另一端设备MAC地址。如果未配对成功，则存储的是全0数据。
    • param2：表示配对过程是否协商了角色
      • 0：未协商角色
      • -1：已协商角色，并且当前设备为从设备（STA模式）
      • 1：已协商角色，并且当前设备为主设备（AP模式）
    • 返回值：无含义，返回0即可

4.1.4. IEEE80211_EVENT_SCAN_START

启动扫描事件。协议栈进入扫描状态时产生此事件。协议栈进入扫描状态可能是因为调用ieee80211_scan API，也可能是因为协议栈自动扫描。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.5. IEEE80211_EVENT_SCAN_DONE

扫描完成事件。协议栈扫描完成时产生此事件。产生此事件可能是因为停止扫描，或者扫描结束。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.6. IEEE80211_EVENT_CONNECT_START

连接启动事件。协议栈开始连接AP时产生此事件，进入此事件表明协议栈已经发现AP，通常是STA接口产生此事件。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.7. IEEE80211_EVENT_CONNECTED

连接成功事件。协议栈连接AP成功后产生此事件。AP接口产生此事件表明有STA成功连接自己，STA接口产生此事件表明自己成功连接到AP。

    • param1：uint8* 类型。AP接口时表示是新连接的sta mac地址，STA接口时表示是连接的AP mac地址。
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.8. IEEE80211_EVENT_CONNECT_FAIL

连接失败事件。通常是STA接口在多次尝试连接AP失败时产生此事件。

    • param1：uint8* 类型。尝试连接的AP mac地址。
    • param2：uint16类型，连接失败时的status code
    • 返回值：无含义，返回0即可

4.1.9. IEEE80211_EVENT_DISCONNECTED

断开连接事件。AP接口产生此事件表示某个sta断开连接，STA接口产生此事件表示自己与AP断开连接。

    • param1：uint8* 类型。存储的断开连接的AP mac地址或STA mac地址。
    • param2：uint16类型，断开连接时的reason code。
    • 返回值：无含义，返回0即可

4.1.10. IEEE80211_EVENT_RX_FRAME

接收数据的事件。协议栈在成功接收数据时产生此事件。接收到每一个数据都会产生此事件。

    • param1：uint8* 类型，表示接收到的数据地址。注意：数据是WiFi帧格式。
    • param2：数据长度。
    • 返回值：
      • 0： 通知协议栈继续接收该数据
      • 非0：通知协议栈丢弃该数据

4.1.11. IEEE80211_EVENT_RSSI

RSSI信号变化事件。协议栈在检测到RSSI发生变化时产生此事件。协议栈会连续统计10个数据的接收信号，进行加权平均。如果信号波动超过阈值(默认是6db)时就产生此事件。AP接口产生此事件表示某个sta的接收信号发生波动，STA接口产生此事件表示接收AP的信号发生波动。

    • param1：int8类型，表示本次接收信号的rssi值。
    • param2：uint8* 类型，表示发生信号波动的AP或STA的 mac地址。
    • 返回值：无含义，返回0即可

使用ieee80211_conf_set_signal_threshold API可以修改信号波动阈值。

4.1.12. IEEE80211_EVENT_NEW_BSS

发现新AP的事件。协议栈找到1个新AP时产生此事件。AP和STA接口都可以产生此事件，都可以执行扫描动作。

    • param1：uint8* 类型，表示AP的bssid
    • param2：uint8* 类型，表示AP的ssid
    • 返回值：无含义，返回0即可

4.1.13. IEEE80211_EVENT_UPDATE_BSS

更新AP信息的事件。协议栈更新AP信息时产生此事件。AP和STA接口都可以产生此事件，都可以执行扫描动作。

    • param1：uint8* 类型，表示AP的bssid
    • param2：uint8* 类型，表示AP的ssid
    • 返回值：无含义，返回0即可

4.1.14. IEEE80211_EVENT_STA_PS_START

sta进入休眠的事件。AP接口产生此事件，当有sta进入休眠时协议栈就会产生此事件通知应用程序。

    • param1：uint8* 类型，表示进入休眠的sta mac地址
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.15. IEEE80211_EVENT_STA_PS_END

sta退出休眠的事件。AP接口产生此事件，当有sta退出休眠时协议栈就会产生此事件。

    • param1：uint8* 类型，表示退出休眠的sta mac地址
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.16. IEEE80211_EVENT_INTERFACE_ENABLE

协议栈接口打开事件。执行ieee80211_iface_start API时会产生此事件。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.17. IEEE80211_EVENT_INTERFACE_DISABLE

协议栈接口关闭事件。执行ieee80211_iface_stop API时会产生此事件。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.18. IEEE80211_EVENT_ADD_CUSTOMER_IE

通知添加自定义element的事件。协议栈在发送管理帧之前会产生此事件，应用程序可以在此事件向管理帧中添加自定义的element数据。

    • param1：uint8* 类型，本次发送的管理帧数据地址。可以通过此参数识别管理帧类型，判断是否需要添加自定义element数据。
    • param2：uint8** 类型，输出参数。通知协议栈需要添加的element数据的地址。协议栈会将该参数指定的数据添加到管理帧中发送出去。
    • 返回值：uint32类型
      • 0：没有element数据，
      • 非0：需要添加的element数据长度。

4.1.19. IEEE80211_EVENT_MAC_CHANGE

接口MAC地址更改事件。接口MAC地址被修改时产生此事件。

    • param1：uint8* 类型，修改后的mac地址
    • param2：0，无含义
    • 返回值：无含义，返回0即可。

4.1.20. IEEE80211_EVENT_EVM

接收信号的EVM发送波动事件。协议栈在检测到EVM发生变化时产生此事件。协议栈会连续统计10个数据的接收信号EVM，进行加权平均。如果信号EVM波动超过10时就产生此事件。AP接口产生此事件表示某个sta的接收信号EVM发生波动，STA接口产生此事件表示接收AP的信号EVM发生波动。

    • param1：int8类型，表示本次接收信号的evm值。
    • param2：uint8* 类型，表示发生EVM波动的AP或STA的mac地址。
    • 返回值：无含义，返回0即可

4.1.21. IEEE80211_EVENT_PRE_AUTH

STA请求auth认证事件。AP接口接收到sta auth请求时产生此事件。

    • param1：uint8* 类型，发起auth请求的sta mac地址
    • param2：0，无含义
    • 返回值：通知协议栈是否接受该sta的auth请求。
      • 0：允许sta继续连接，
      • 非0：拒绝该sta连接 ，并表示拒绝的原因。

4.1.22. IEEE80211_EVENT_PRE_ASSOC

STA请求连接事件。AP接口接收到sta assoc请求时产生此事件。

    • param1：uint8* 类型，发起assoc请求的sta mac地址
    • param2：0，无含义
    • 返回值：通知协议栈是否接受该sta的assoc请求。
      • 0：允许sta继续连接，
      • 非0：拒绝该sta连接，并表示拒绝的原因。

4.1.23. IEEE80211_EVENT_UNPAIR_SUCCESS

配对解绑事件。协议栈收到解绑请求时产生此事件。AP接口和STA接口都可以发起解绑请求，所以AP和STA接口都会产生此事件。

    • param1：uint8* 类型，发起解绑请求的sta mac地址
    • param2：0，无含义
    • 返回值：无含义，返回0即可。

4.1.24. IEEE80211_EVENT_TX_BITRATE

协议栈预估的传输速率。协议周期性产生此事件，通知应用程序当前链路预估的可最大传输速率，单位的Kbps。应用程序可以根据此事件调整自身的行为，例如对于视频传输，可以动态调整视频码率。

    • param1：uint32 类型，预估的最大传输速率，单位kbps。
    • param2：0，无含义
    • 返回值：无含义，返回0即可。

4.1.25. IEEE80211_EVENT_TX_FRAME

协议栈TX数据之前产生此事件，通知应用程序将要TX一笔数据。每次TX数据都会产生此事件，应用程序可以在此事件中根据数据内容执行一些特定的动作。

    • param1：uint8* 类型，表示将要TX的数据地址。数据是WiFi帧格式。
    • param2：无效
    • 返回值：
      • 0： 通知协议栈继续TX该数据
      • 非0：通知协议栈丢弃该数据

4.1.26. IEEE80211_EVENT_RX_CUSTMGMT

接收到自定义管理帧事件。当协议栈接收到泰芯自定义管理帧时产生此事件。发送方使用ieee80211_tx_custmgmt API发送自定义管理帧，接收方就会产生此事件。

    • param1：struct ieee80211_custmgmt_data * 类型。

struct ieee80211_custmgmt_data{

uint8 *from; //发送方的mac地址

uint8 *data; //接收到的数据

uint8 len; //数据长度

};

    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.27. IEEE80211_EVENT_WRONG_KEY

密码错误提示事件。当协议栈尝试连接AP失败时，会判断是否因为密码错误，产生此事件通知应用程序。

    • param1：0，无含义
    • param2：0，无含义
    • 返回值：无含义，返回0即可

4.1.28. IEEE80211_EVENT_CHANNEL_CHANGE

信道切换事件。当协议栈检测到信道发生切换时产生此事件。产生信道切换的原因可能是AP通知切换信道，或因检测到当前信道有干扰而切换信道。AP和STA都会产生此事件。

    • param1：uint8类型，切换信道之前的旧信道
    • param2：uint8类型，切换信道之后的新信道
    • 返回值：无含义，返回0即可

4.1.29. IEEE80211_EVENT_TX_STATUS

数据TX状态事件。当协议栈发送数据完成后产生此事件，通知应用程序该数据发送成功或失败。发送的每一笔数据都产生此事件。

    • param1：uint8* 类型，表示本次发送的数据地址，数据格式为WiFi帧格式。
    • param2：uint8类型，表示是否成功，0：发送失败，1：发送成功。
    • 返回值：无含义，返回0即可

4.1.30. IEEE80211_EVENT_PAIR_NGO

配对协商角色事件。在配对时如果2个设备的角色相同，则可以进行协商，决定谁做AP，谁做STA。默认的协商规则是：比较2个设备的MAC地址，转成64bit数字，大的做AP，小的做STA。

在此过程会产生IEEE80211_EVENT_PAIR_NGO事件，通知应用程序正在进行配对协商。应用程序可以通过此事件自定义协商规则，通过该事件的返回值控制协商结果。

    • param1：uint8* 类型，表示请求配对的设备MAC地址。
    • param2：0，无含义。
    • 返回值：
      • 1：本设备做AP
      • -1：本设备做STA
      • 其他值：应用程序未处理此事件

注：通过index参数可以知道对方的角色，因为只有2个设备的角色相同时才会产生此事件。

4.2. WiFi协议栈sysevt机制

如4.1章节所说，由于在协议栈的event callback函数中不能执行复杂耗时的逻辑，所以有些event需要配合sysevt模块来执行一些复杂耗时的逻辑，例如读写flash。sysevt机制的介绍在SDK入门指南第9章节。

sysevt.h定义了一些和WiFi有关的event，每个event都可以携带一个event data，event data的具体含义是随event id变化。

  • SYSEVT_WIFI_CONNECT_START

STA接口开始连接, event data: 0

  • SYSEVT_WIFI_CONNECTTED

STA接口连接成功, event data: 自己的AID.

  • SYSEVT_WIFI_CONNECT_FAIL

STA接口连接失败, event data: 连接失败的status code.

  • SYSEVT_WIFI_DISCONNECT

STA接口断开连接，event data: 断开连接的reason code

  • SYSEVT_WIFI_SCAN_START

开始扫描，event data: 0

  • SYSEVT_WIFI_SCAN_DONE

扫描完成, event data: 0

  • SYSEVT_WIFI_STA_DISCONNECT

AP接口检测到sta断开连接, event data: 断开连接的sta AID.

  • SYSEVT_WIFI_STA_CONNECTTED

AP接口检测到sta连接成功, event data: 连接成功的sta AID.

  • SYSEVT_WIFI_STA_PS_START

AP接口检测到sta进入休眠, event data: 进入休眠的sta AID.

  • SYSEVT_WIFI_STA_PS_END

AP接口检测到sta退出休眠, event data: 退出休眠的sta AID.

  • SYSEVT_WIFI_PAIR_DONE

一键配对完成，event data: 配对是否成功，1:success, 0:fail.

  • SYSEVT_WIFI_TX_SUCCESS

WiFi发送数据成功，event data: 数据标签，该标签是通过 ieee80211_conf_set_datatag API设置的。

  • SYSEVT_WIFI_TX_FAIL

WiFi发送数据失败，event data: 数据标签，该标签是通过 ieee80211_conf_set_datatag API设置的。

  • SYSEVT_WIFI_WRONG_KEY

WiFi连接发现密码错误，event data:0

5. WiFi协议栈Hook机制

SDK WiFi协议栈设计了hook机制，支持应用程序参与控制数据的发送和接收。

协议栈的IEEE80211_EVENT_TX_FRAME和IEEE80211_EVENT_RX_FRAME 这2个事件也可以用于处理发送和接收的数据，但是hook机制的不同之处是hook处理的数据是以太网帧格式，对应用程序开发更加友好。

应用程序使用ieee80211_register_pkthook API向协议栈注册一个hook，如下图所示：

上图的示例代码注册了一个hook：netAT，指定了hook需要处理的协议类型为0x800（IP包），设置了hook的 tx/rx 函数。

当WiFi协议栈发送或接收IP包时就会执行该hook的tx/rx函数，从而让该hook能够参与IP包的发送和接收过程。

通过hook机制，应用代码在数据收发过程中可以采取一些动作，例如：

  • 修改IP包的数据内容
  • 对IP包进行过滤：是丢弃还是继续发送
  • 识别IP包数据内容，执行一些特定的应用代码，或给数据打个标签

应用程序注册hook时需要填充的数据类型是struct ieee80211_pkthook_const，定义如下：

struct ieee80211_pkthook_const{

const char *name; //hook的名称

void *priv; //hook的私有数据，在执行tx/rx函数时会传递回给hook

uint16 protocol; //hook关注的以太网协议类型

uint16 mcast: 1, //hook是否关注所有的组播报

ucast:1, //hook是否关注所有的单播包

rev: 14;

ieee80211_pkthdl tx; //TX处理函数，协议栈TX数据时执行此函数

ieee80211_pkthdl rx; //RX处理函数，协议栈RX数据时执行此函数

};

typedef enum { //hook的tx/rx 函数返回值定义

IEEE80211_PKTHDL_CONTINUE = 0, //TX/RX继续执行

IEEE80211_PKTHDL_CONSUMED = 1, //该数据已被消耗，通知协议栈丢弃数据

} ieee80211_pkthdl_res;

struct ieee80211_hookdata{ //hook data

uint8 *data; //数据地址

uint16 len; //数据长度

uint16 ext: 1, recv: 15;

uint32 hdl; //数据句柄，ieee80211_conf_set_datatag API需要这个句柄

};

6. WiFi协议栈API

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

6.1. 初始化API

6.1.1. ieee80211_init

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

  • 参数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函数

};

    • ap信息生存时间：当AP列表的数量超过bss_macnt/2时，ap信息的生存时间自动调整为5s，直到清除后的ap数量小于bss_macnt/2，生存时间恢复为bss_lifetime值。
  • 返回值 ：表示是否成功，0：成功，非0：失败，errno

6.1.2. ieee80211_support_txw830x

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

  • 参数ops [in] ：LMAC协议栈的句柄
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.3. ieee80211_support_txw80x

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

  • 参数ops [in] ：LMAC协议栈的句柄
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.4. ieee80211_support_txw81x

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

  • 参数ops [in] ：LMAC协议栈的句柄
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.5. ieee80211_iface_create_ap

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

  • 参数ifidx [in] ：AP模式接口使用的接口索引
  • 参数band [in] ：WiFi频段类型
    • IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片
    • IEEE80211_BAND_5GHZ： 5G频段
    • IEEE80211_BAND_60GHZ：60G频段
    • IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.6. ieee80211_iface_create_sta

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

  • 参数ifidx [in] ：STA模式接口使用的接口索引
  • 参数band [in] ：WiFi频段类型
    • IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片
    • IEEE80211_BAND_5GHZ： 5G频段
    • IEEE80211_BAND_60GHZ：60G频段
    • IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.7. ieee80211_iface_create_wnbap

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

  • 参数ifidx [in] ：WNBAP模式接口使用的接口索引
  • 参数band [in] ：WiFi频段类型
    • IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片
    • IEEE80211_BAND_5GHZ： 5G频段
    • IEEE80211_BAND_60GHZ：60G频段
    • IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.8. ieee80211_iface_create_wnbsta

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

  • 参数ifidx [in] ：WNBSTA模式接口使用的接口索引
  • 参数band [in] ：WiFi频段类型
    • IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片
    • IEEE80211_BAND_5GHZ： 5G频段
    • IEEE80211_BAND_60GHZ：60G频段
    • IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.9. ieee80211_iface_create_p2pdev

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

  • 参数ifidx [in] ：p2p模式接口使用的接口索引
  • 参数band [in] ：WiFi频段类型
    • IEEE80211_BAND_2GHZ： 2.4G频段，适用TXW80x,TXW81x芯片
    • IEEE80211_BAND_5GHZ： 5G频段
    • IEEE80211_BAND_60GHZ：60G频段
    • IEEE80211_BAND_S1GHZ：低于1G频段，适用TXW8301芯片
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.10. ieee80211_iface_start

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

  • 参数ifidx [in] ：需要启动的接口索引
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.11. ieee80211_iface_stop

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

  • 参数ifidx [in] ：需要停止的接口索引
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.12. ieee80211_deliver_init

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

  • 参数max [in] ：路由表缓存信息的最大数量
  • 参数lifetime [in]：路由表缓存信息的生成时间，单位：秒
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.1.13. ieee80211_conf_stabr_table

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

  • 参数ifidx [in]：接口索引
  • 参数max [out]：路由表信息最大数量
  • 参数lifetime [in]：路由表信息的生存时间
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.1.14. wpa_passphrase

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

  • 参数ssid [in] ：WiFi ssid
  • 参数passwd [in]：WiFi password，明文密码
  • 参数psk [out] ：生成的密文密码psk
  • 返回值 ：表示是否成功，0：成功，-1：失败

6.2. 基础配置API

6.2.1. ieee80211_conf_set_channel

ieee80211_conf_set_channel API用于设置WiFi信道。

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

  • 参数ifidx [in]：接口索引
  • 参数channel [in]：设置新的channel
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.2.2. ieee80211_conf_set_ssid

ieee80211_conf_set_ssid API用于设置WiFi ssid参数。

  • 参数ifidx [in]：接口索引
  • 参数ssid [in]：WiFi SSID参数。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.2.3. ieee80211_conf_set_keymgmt

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

  • 参数ifidx [in]：接口索引
  • 参数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)

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

6.2.4. ieee80211_conf_set_psk

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

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

  • 参数ifidx [in]：接口索引
  • 参数psk [in]：密文密码
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.2.5. ieee80211_conf_set_passwd

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

  • 参数ifidx [in]：接口索引
  • 参数passwd [in]：明文密码
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.2.6. ieee80211_conf_set_beacon_int

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

  • 参数ifidx [in]：接口索引
  • 参数beacon_int [in]：新的beacon周期，单位：毫秒
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3. 高级配置API

6.3.1. ieee80211_conf_set_bssbw

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

  • 参数ifidx [in]：接口索引
  • 参数bssbw [in]：BSS带宽，设置前需要确认芯片是否支持此带宽。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.2. ieee80211_conf_set_dtim_int

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

  • 参数ifidx [in]：接口索引
  • 参数dtim_int [in]：新的DTMI周期，该值的含义是beacon周期的个数
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.3. ieee80211_conf_set_bss_max_idle

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

  • 参数ifidx [in]：接口索引
  • 参数max_idle_period [in]：max idle时间，单位：秒，默认是300 秒。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.4. ieee80211_conf_set_bssid

ieee80211_conf_set_bssid API用于设置WiFi连接的AP BSSID。当存在多个SSID相同的AP时，如果需要指定连接某个AP，需要使用此API进行设置，否则协议栈将根据SSID查找AP，随机选择其中1个AP进行连接。

  • 参数ifidx [in]：STA接口索引
  • 参数bssid [in]：AP的mac地址
  • 返回值 ：表示是否成功，0：成功，非0：失败。

注：使用此功能，需要先设置ssid，再设置bssid。

6.3.5. ieee80211_conf_set_mac

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

  • 参数ifidx [in]：接口索引
  • 参数mac [in]：设置新的MAC地址
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.6. ieee80211_conf_set_aphide

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

  • 参数ifidx [in]：接口索引
  • 参数hide [in]：0：关闭隐藏，1：开启隐藏。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.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

};

  • 参数ifidx [in]：接口索引
  • 参数mode [in]：WiFi协议模式：enum ieee80211_hwmode。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.8. ieee80211_expand_mlme_size

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

  • 参数ifidx [in]：接口索引
  • 参数 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。

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

6.3.9. ieee80211_conf_set_wpa_cipher

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

  • 参数ifidx [in]：接口索引。
  • 参数 wpa_proto [in]：WPA协议版本
  • 参数 pairwise_cipher [in]：获取的AP的加密信息。
  • 参数 group_cipher [in]：获取的AP的加密信息。
  • 返回值 ：表示是否成功，0：成功，非0：失败。
    • 参数wpa_proto取值如下：

#define WPA_PROTO_WPA BIT(0)

#define WPA_PROTO_RSN BIT(1)

  • 参数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)

6.3.10. ieee80211_conf_set_isolate

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

  • 参数ifidx [in]：接口索引
  • 参数 isolate [in]：0：关闭隔离，1：开启隔离
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.11. ieee80211_conf_set_chanlist

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

  • 参数ifidx [in]：接口索引
  • 参数chan_list [in]：信道列表，要求是uint16数组。
  • 参数count [in]：信道数量
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.12. ieee80211_conf_set_wpa_group_rekey

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

  • 参数ifidx [in]：接口索引
  • 参数wpa_group_rekey [in]：更新周期，单位：秒。设置0表示关闭组播key更新功能。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.13. ieee80211_conf_set_dupfilter

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

  • 参数ifidx [in]：接口索引
  • 参数 enable [in]：0：关闭重复包过滤，1：开启重复包过滤
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.14. ieee80211_conf_set_conn_timeout

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

  • 参数ifidx [in]：接口索引
  • 参数 auth_tmo [in]：auth阶段的timeout值，默认值是100ms。
  • 参数 assoc_tmo [in]：assoc阶段的timeout值，默认值是100ms。
  • 参数 handshake_tmo [in]：4次握手阶段的timeout值，默认是2000ms。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.15. ieee80211_conf_set_aplost_time

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

  • 参数ifidx [in]：接口索引
  • 参数time [in]：检测AP离线的时间。默认值30，表示30个beacon周期。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.16. ieee80211_conf_set_wmm_enable

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

  • 参数ifidx [in]：接口索引
  • 参数enable [in]：0：关闭QoS，1：开启QoS。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.17. ieee80211_conf_set_wmm_param

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

  • 参数 ifidx [in]：接口索引
  • 参数 ac [in]：EDCA AC队列，取值范围：0，1，2，3，对应：AC_VO,AC_VI,AC_BK,AC_BE
  • 参数 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种情况：

    • ac参数取值：[0xf0, 0xf1, 0xf2, 0xf3]，表示只修改自己的本地edca参数，不影响sta的edca参数。
    • ac参数取值：[0,1,2,3],表示修改sta的edca参数。执行此API会修改AP发送的beacon帧中的wmm参数，sta会依此更新自己的edca参数。

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

6.3.18. ieee80211_conf_set_use4addr

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

  • 参数ifidx [in]：接口索引
  • 参数enable [in]：0：关闭4地址模式，1：开启4地址模式。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.19. ieee80211_conf_set_psdata_cnt

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

  • 参数ifidx [in]：接口索引
  • 参数max_cnt [in]：允许缓存数据的最大数量。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.20. ieee80211_conf_set_datatag

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

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

  • 参数ifidx [in]：接口索引
  • 参数hdl [in]：数据handle，这个值来自struct ieee80211_hookdata。在执行hook的tx/rx 函数时可以获取这个值。
  • 参数 tag [in]：数据标签。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.3.21. ieee80211_conf_set_signal_threshold

ieee80211_conf_set_signal_threshold API用于修改RSSI/EVM波动阈值，会影响IEEE80211_EVENT_RSSI和IEEE80211_EVENT_EVM事件的上报。

WiFi协议栈会实时监测当前AP或STA的RSSI/EVM波动情况。当前后的RSSI/EVM波动差值大于设定的阈值后，就会产生IEEE80211_EVENT_RSSI/IEEE80211_EVENT_EVM事件。

RSSI波动阈值默认是6db，EVM波动阈值默认是6db，通过此API可以修改这2个阈值。

  • 参数ifidx [in] ：接口索引
  • 参数rssi_thres [in] ：rssi波动阈值。
  • 参数evm_thres [in] ：evm波动阈值
  • 返回值 ：表示设置是否成功，0：成功，非0：失败

6.4. 一键配对API

6.4.1. ieee80211_pair_enable

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

  • 参数ifidx [in] ：启用配对功能的接口索引
  • 参数pair_magic [in] ：配对功能的magic number，在配对时相同magic number的设备才能相互配对成功。
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.4.2. ieee80211_pairing

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

  • 参数ifidx [in] ：start/stop配对功能的接口索引
  • 参数pair_magic [in] ：0：停止配对，1：启动配对，大于1：启动配对，并修改magic number。
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.4.3. ieee80211_unpair

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

  • 参数ifidx [in] ：配对解绑的接口索引
  • 参数mac [in] ：需要解绑的设备MAC地址，AP和STA都可以执行此API发起解绑操作，mac参数是对方的MAC地址。
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.4.4. ieee80211_conf_set_pair_ngo

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

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

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

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

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

  • 参数ifidx [in] ：配对解绑的接口索引
  • 参数enable[in] ：是否启用配对协商功能。
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.5. 连接扫描API

6.5.1. ieee80211_scan

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

  • 参数ifidx [in] ：执行扫描动作的接口索引
  • 参数start [in] ：1： 启动扫描，0：停止扫描，在扫描完成时也会自动停止。
  • 参数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;

};

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

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

6.5.2. ieee80211_get_bsslist

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

  • 参数bsslist [out]：接收AP列表信息的buffer地址
  • 参数list_size [in]：buffer size
  • 参数ignore_dis [in]：指示是否忽略被disable的AP信息。
  • 返回值 ：获取到的AP信息数量。

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

6.5.3. ieee80211_cleanup_bsslist

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

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

6.5.4. ieee80211_conf_set_auto_assoc

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

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

  • 参数ifidx [in]：接口索引。
  • 参数 auto_assoc [in]：0：关闭自动连接，1：开启自动连接
  • 参数 auto_scan [in]：0：关闭自动扫描，1：开启自动扫描
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.5.5. ieee80211_start_connect

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

  • 参数ifidx [in]：接口索引。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.5.6. ieee80211_disassoc

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

  • 参数ifidx [in]：接口索引
  • 参数 addr [in]：需要断开的sta mac地址
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.5.7. ieee80211_disassoc_all

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.5.8. ieee80211_bss_add_manualAP

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

  • 参数ssid [in]：添加的AP ssid
  • 参数 bssid [in]：添加的AP的mac地址
  • 参数 channel [in]：AP所在的信道
  • 参数 band [in]：AP的频段信息
  • 参数 wpadata [in]：AP的加密信息，这个值保存时使用ieee80211_bss_get_wpadata API从协议栈中获取。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.5.9. ieee80211_conf_set_scan_max

WiFi协议栈在连接扫描AP过程中，如果连续扫描多次（所有信道扫描一遍为1次，默认是15次）都未发现AP，就会上报IEEE80211_EVENT_CONNECT_FAIL事件，status code是WLAN_REASON_AP_NOT_FOUND。

ieee80211_conf_set_scan_max API用于控制协议栈在扫描多少次后再上报IEEE80211_EVENT_CONNECT_FAIL事件。

  • 参数ifidx [in]：接口索引
  • 参数scan_max[in]：扫描次数
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.6. 数据收发API

6.6.1. ieee80211_scatter_tx

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

  • 参数ifidx [in] ：发送数据的接口索引
  • 参数data [in] ：scatter_data数组地址
  • 参数count [in] ：scatter_data数组的大小
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.6.2. ieee80211_tx

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

  • 参数ifidx [in] ：发送数据的接口索引
  • 参数data [in] ：数据地址。
  • 参数size [in] ：数据长度
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.6.3. ieee80211_input

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

  • 参数ifidx [in] ：接口索引
  • 参数data [in] ：数据地址，数据必须是以太网帧格式。
  • 参数 len [in] ：数据长度
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.6.4. ieee80211_tx_mgmt

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

  • 参数ifidx [in] ：发送管理帧的接口索引
  • 参数data [in] ：管理帧数据地址，数据必须是完整的WiFi帧格式。MAC header的seq number和duration 填0即可。
  • 参数 len [in] ：管理帧数据长度
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.6.5. ieee80211_tx_custmgmt

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

  • 参数ifidx [in] ：发送管理帧的接口索引
  • 参数 dest [in]： 发送此管理帧的目的地址，可以是广播地址。
  • 参数 data [in] ：管理帧数据地址。可以是任意格式的数据，将作为管理帧payload发送。
  • 参数 len [in] ：管理帧数据长度
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.7. Hook和Event API

6.7.1. ieee80211_register_pkthook

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

  • 参数hook [in]：需要注册的hook信息
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.7.2. ieee80211_event_cb

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

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

  • 参数cb [in]：新的event callback函数
  • 返回值 ：协议栈旧的event callback函数

6.8. 低功耗API

6.8.1. ieee80211_conf_wakeup_sta

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

  • 参数ifidx [in]：接口索引
  • 参数addr [in]：被唤醒的sta mac地址
  • 参数reason [in]：唤醒sta的原因
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.8.2. ieee80211_conf_get_wkreason

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：唤醒原因。0：正常开机或AP未告知唤醒原因，非0：AP告知的唤醒原因。

6.9. 信息获取API

6.9.1. ieee80211_status

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

  • 参数buff [in] ：接收调试信息的换成buffer
  • 参数size [in] ：buffer size
  • 返回值 ：表示是否成功，0：成功，非0：失败

6.9.2. ieee80211_conf_get_psk

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

  • 参数ifidx [in]：接口索引
  • 参数psk [out]：接收psk的buffer地址，该buffer的size不能小于32byte。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.9.3. ieee80211_conf_get_keymgmt

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：WiFi加密模式。

6.9.4. ieee80211_conf_get_ssid

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

  • 参数ifidx [in]：接口索引
  • 参数ssid [out]：接收SSID参数的buffer地址，该buffer的size不能小于32byte。

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

6.9.5. ieee80211_get_stalist

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

  • 参数ifidx [in]：接口索引
  • 参数stalist [out]：接收sta列表信息的buffer地址
  • 参数list_size [in]：buffer size
  • 返回值 ：获取到的sta信息数量。

6.9.6. ieee80211_conf_get_bssbw

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：WiFi协议栈当前使用的BSS带宽。

6.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。

  • 参数ifidx [in]：STA接口索引
  • 参数bssid [out]：bssid
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.9.8. ieee80211_conf_get_channel

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：返回当前的WiFi信道。

6.9.9. ieee80211_conf_get_mac

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

  • 参数ifidx [in]：接口索引
  • 参数mac [out]：获取的MAC地址
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.9.10. ieee80211_conf_get_connstate

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：当前连接状态，返回值定义如下：

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 连接完成状态

};

6.9.11. ieee80211_conf_get_stainfo

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

  • 参数ifidx [in]：接口索引
  • 参数aid [in]：需要获取的sta aid，aid非0时根据aid查找sta。
  • 参数mac [in]：需要获取的sta mac地址，当mac不是NULL值时，优先则根据mac地址查找sta。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.9.12. ieee80211_conf_get_stalist

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

  • 参数ifidx [in]：接口索引
  • 参数sta [out]：接收sta信息列表的buffer地址
  • 参数count [in]：buffer可存储sta信息的数量。
  • 返回值 ：实际获取的sta数量。

6.9.13. ieee80211_conf_get_stacnt

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：该接口连接的sta数量。

6.9.14. ieee80211_conf_get_reason_code

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：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, //上级中继链路断开

};

6.9.15. ieee80211_conf_get_status_code

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

  • 参数ifidx [in]：接口索引
  • 返回值 ：status code。

6.9.16. ieee80211_chan_center_freq

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

  • 参数ifidx [in]：接口索引
  • 参数 channel [in]：信道号
  • 返回值 ：指定信道的中心频点。

6.9.17. ieee80211_bss_get_wpadata

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

  • 参数bssid [in]：需要获取的AP mac地址，根据mac地址查找ap信息。
  • 参数 band [in]：AP的频段信息
  • 参数 wpadata [out]：获取的AP的加密信息。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

6.10. WiFi漫游API

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

  • 标准协议：
    • 优点：可以兼容标准协议802.11kvr协议
    • 缺点：协议栈的STA模式支持快速漫游，AP模式不支持。STA模式使用快速漫游时需要路由器支持802.11kvr协议才可以进行漫游。是否支持无缝漫游也取决于路由器。
  • 私有协议：
    • 优点：AP和STA模式均支持漫游，且AP支持STA进行无缝漫游。
    • 缺点：不能和标准协议兼容，只能是私有协议的AP和STA共同工作。

6.10.1. 标准协议漫游

TBD...

6.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. ieee80211_wnb_roam_enable

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

  • 参数ifidx [in]：接口索引。
  • 返回值 ：表示是否成功，0：成功，非0：失败。
        1. ieee80211_conf_set_roaming

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

  • 参数ifidx [in]：接口索引。
  • 参数 roaming [in]：0：关闭漫游，1：开启漫游
  • 返回值 ：表示是否成功，0：成功，非0：失败。
        1. ieee80211_conf_set_roam_config

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

  • 参数ifidx [in]：接口索引。
  • 参数 roam_rssi_th [in]：触发漫游的rssi门限
  • 参数 roam_rssi_diff [in]：设置新旧AP的rssi差值，大于此差值的新AP才能被选中，避免频繁反复漫游切换。
  • 参数 roam_rssi_int [in]：设置连续监测多少个beacon的rssi进行累加平均。
  • 返回值 ：表示是否成功，0：成功，非0：失败。

7. 示例代码

7.1. 开启AP热点

AP模式初始化后，启动AP模式通常只需要设置以下几个参数：

char psk[32];

//设置SSID参数

ieee80211_conf_set_ssid(WIFI_MODE_AP, “TEST_AP”);

//设置安全加密模式

ieee80211_conf_set_keymgmt(WIFI_MODE_AP, WPA_KEY_MGMT_PSK);

//根据密码和SSID计算psk.

//计算psk比较耗时，通常是计算后保存，避免下次开机再计算

wpa_passphrase(“TEST_AP”, “12345678”, psk);

//设置psk

ieee80211_conf_set_psk(WIFI_MODE_AP, “TEST_AP”);

//设置beacon周期，默认是100ms

ieee80211_conf_set_beacon_int(WIFI_MODE_AP, 100);

//设置AP的工作channel

ieee80211_conf_set_channel(WIFI_MODE_AP, 1);

//启动AP接口

ieee80211_iface_start(WIFI_MODE_AP);

//////////////////////////////////////////////////

//断开指定的sta

ieee80211_disassoc(WIFI_MODE_AP, sta_mac);

//断开所有的sta

ieee80211_disassoc_all(WIFI_MODE_AP);

7.2. 开启STA连接AP

STA模式初始化后，启动STA连接指定的AP通常只需要设置以下几个参数：

char psk[32];

//设置SSID参数

ieee80211_conf_set_ssid(WIFI_MODE_STA, “TEST_AP”);

//设置安全加密模式

ieee80211_conf_set_keymgmt(WIFI_MODE_STA, WPA_KEY_MGMT_PSK);

//根据密码和SSID计算psk.

//计算psk比较耗时，通常是计算后保存，避免下次开机再计算

wpa_passphrase(“TEST_AP”, “12345678”, psk);

//设置psk

ieee80211_conf_set_psk(WIFI_MODE_STA, psk);

//启动STA接口

ieee80211_iface_start(WIFI_MODE_STA);