TXSDK_主控交互指南

责任与版权

责任限制

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

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

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

版权申明

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

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

修订记录

1. 概述

TXSDK是泰芯半导体发布的WiFi/音视频系列芯片开发SDK。本文档介绍的是WiFi模组与主控之间的交互行为，主要是针对低功耗WiFi模组。

WiFi模组与主控之间交互的主要是网络数据，驱动命令，模组事件3类信息。这3类信息由WiFi驱动统一封装，主控端可以使用Linux驱动，RTOS驱动或NonOS驱动。

本文档只介绍了WiFi模组上的开发方法，主控端的开发请查看对应的驱动开发指南文档。

2. 系统初始化

WiFi模组SDK在初始化需要添加wifi_mgr模块的初始化，如下图所示。

wifi_mgr模块负责与主控进行交互，包括数据收发，命令处理，事件上报。当主控未开机时，wifi_mgr会缓存固件产生的事件和数据，待主控开机后再发送给主控。默认最多缓存16个事件和16个数据，超过最大值则丢弃旧的数据，缓存新的数据。

wifi_mgr_init API定义如下：

int32 wifi_mgr_init(enum mac_bus_type bus_type, int8 frm_type, uint16 drv_aggsize, void *ops, void *btops)

• 参数 bus_type [in]: 和主控通信的接口类型，通常是SDIO或USB
• 参数 frm_type [in]: 和主控通信的帧类型

enum wifimgr_frm_type {

WIFIMGR_FRM_TYPE_ETHER = 0, //以太网帧格式，只能交互以太网数据

WIFIMGR_FRM_TYPE_HGIC, //泰芯驱动帧格式，可以交互数据，命令，事件

WIFIMGR_FRM_TYPE_RAW, //裸数据格式，由固件完成以太网帧格式封装

};

• 参数 drv_aggsize [in]: 接口聚合包Size。0：关闭聚合，非0：聚合包的Size。
• 参数 ops [in]: lmac协议栈句柄
• 参数 btops [in]: bt协议栈句柄
• 返回值：表示是否成功，0：成功，非0：失败

根据方案低功耗需求，可以选择初始化其他几个低功耗相关的模块：

• 初始化psalive功能：wifi_mgr_enable_psalive
• 初始化psconnect功能：wifi_mgr_enable_psconnect
• 初始化dhcp client模块：wifi_mgr_enable_dhcpc

3. 数据接口

WiFi模组与主控可以使用多种接口进行交互，例如 sdio，usb，uart，spi等。为了方便支持多种接口，SDK设计了mac_bus模块，该模块定义了统一接口对接wifi_mgr模块。切换与主控通信接口时，只需要修改宏定义FMAC_MAC_BUS的值。

SDK所支持的接口代码在sdk/lib/bus/mac_bus目录下。

4. 双协议栈

低功耗WiFi模组SDK支持启用lwip协议栈。这种情况下WiFi模组和主控同时运行各自的tcpip协议栈，主控中的网络接口（假设是wlan0）和WiFi模组内的网络接口（假设是w0），具体相同的MAC地址，相同的IP地址。WiFi模组和主控各自运行独立的网络程序实现不同的功能。

wifi_mgr模块会记录来自内部lwip协议栈的数据流，默认最多支持记录16路数据流，当从网络中接收到数据时会识别出该数据是送给内部lwip协议栈，还是送给主控协议栈。如果SDK提示“NO FREE LOCALID”时，表示记录的数据流已经超过最大数量。

主控的开机速度通常是比WiFi模组慢，可以由WiFi模块提前申请IP地址，主控开机后直接使用WiFi模组申请的IP地址，这样可以节省DHCP申请IP地址的时间。

在低功耗WiFi模组上运行的网络程序通常是休眠保活代码。设备进低功耗时主控通常会断电，WiFi模组进入休眠状态。WiFi模组周期性醒来执行保活代码，与服务器保持连接。

在WiFi模组上开发保活代码，和普通的网络程序开发没有区别。SDK提供的lwip协议栈支持BSD socket API，使用方法与其他系统一样。可以选择tcp保活或udp保活，按照设备的保活协议开发代码即可。建议在条件允许的情况下尽可能选择udp保活，udp保活对功耗更加友好，保活代码逻辑控制也更加简单。

需要注意的是不同芯片的休眠行为有所不同，会影响休眠保活代码的开发方式。

• TXW8301芯片由于不支持XIP，代码在SRAM中运行。休眠时SRAM掉电，在唤醒时需要重新加载运行固件（相当于重新开机运行），这种情况不适合在WiFi模组上开发保活程序。
• TXW80x/TXW81x芯片支持XIP，代码在flash中运行。休眠唤醒时，系统可以恢复到休眠之前的状态继续运行，所有的状态信息都不会丢失。这种情况可以在WiFi模组上开发保活程序，模组周期性醒来执行保活程序。

5. WIFI_DHCPC功能

如果模组SDK不启用lwip协议栈，可以使用wifi_dhcpc模块来申请IP地址。需要在系统初始化时使用wifi_mgr_enable_dhcpc API初始化wifi_dhcpc模块。

wifi_dhcpc模块可以在没有tcpip协议栈的情况下完成dhcp请求IP地址。申请IP地址后会自动通知主控。

对于TXW8301芯片来说，要启用这个模块，因为TXW8301芯片的程序代码是在SRAM中运行，不适合开发低功耗保活代码，这种情况下禁用lwip，就可以节省memory资源。

6. PSALIVE功能

PSALIVE功能是SDK提供的泰芯自定义UDP保活机制。该功能简化了UDP保活功能开发，使用此功能进行低功耗保活时不需要开发保活代码，只需要设置一些参数即可。不过该功能使用上有限制条件：AP和STA都必须是泰芯的WiFi芯片。

如果选择使用PSALIVE功能，在系统初始化时需要使用wifi_mgr_enable_psalive API初始PSALIVE模块。然后由主控设置相应参数，具体请阅读驱动开发指南的低功耗章节，选择psmode 2。

7. PSCONNECT功能

PSCONNECT功能是为优化设备功耗而开发的一个模块。

该模块的工作原理：如果在休眠后出现断线情况，在不需要唤醒主控的情况下（由唤醒原因决定），WiFi模组自行醒来连接AP。如果未能连接AP，模组则进入psconnect状态。psconnect状态下WiFi模组开机后尝试连接一次AP，连接失败则进入离线休眠状态，休眠时间t后自动唤醒再次尝试连接AP，如果连接失败则休眠2t时间，依此规律逐渐加大休眠时间，直到达到设定最大值后再回到初始时间t，依此循环。

psconnect功能是为了避免在AP出现异常后，WiFi模块频繁连接AP而增加功耗。该功能的参数设置请查看驱动开发指南文档。

8. 自定义交互

wifi_mgr模块已经支持了驱动定义的命令和事件。但是应用开发时可能会需要添加一些自定义的命令或事件与主控进行交互。SDK提供了添加自定义命令和事件的方法。

8.1. 自定义命令

添加自定义命令时需要和主控协同开发。目前有2种方式添加自定义命令，分别对应主控驱动的2个API。

8.1.1. 自定义CMD ID

推荐使用自定义CMD ID的方式添加自定义命令，请查看驱动的头文件hgic.h（如下图所示）。

添加自定义命令时，可以直接在驱动的命令列表中新增ID。建议为驱动预留足够的空间，自定义ID从65000开始，可以添加535个命令，应该是足够应用程序使用了。

使用自定义CMD ID时，在主控端使用hgic_iwpriv_set_customer_dvrdata API发送命令。

int hgic_iwpriv_set_customer_dvrdata(char *ifname, unsigned short cmd_id, char *data, int len)

• 参数ifname: 接口名称
• 参数 cmd_id： 自定义的cmd id
• 参数 data： 命令数据
• 参数 len： 命令数据长度
• 返回值：表示是否成功。0：成功，非0：失败

使用自定义CMD ID时，在WiFi模组端需要使用 wifi_proc_drvcmd_cust 函数处理这些自定义命令。在main.c中已经提供了wifi_proc_drvcmd_cust函数，在该函数添加对应的处理代码即可。

wifi_mgr模块接收的所有来自主控的命令都会先执行wifi_proc_drvcmd_cust函数，如果某个命令被wifi_proc_drvcmd_cust函数处理过了（返回值为RET_OK），wifi_mgr则忽略该cmd的后续处理。返回-ENOTSUPP表示wifi_proc_drvcmd_cust函数未处理该cmd，wifi_mgr模块继续处理。

8.1.2. HGIC_CMD_SET_CUST_DRIVER_DATA

早期的驱动定义了一个特殊的CMD ID：HGIC_CMD_SET_CUST_DRIVER_DATA，用于传输自定义驱动数据。如果主控程序使用了hgic_iwpriv_set_cust_driverdata API，使用的就是这个ID。这种情况下，需要在wifi_proc_drvcmd_cust函数中添加对HGIC_CMD_SET_CUST_DRIVER_DATA的处理，解析处理自定义的数据。

8.2. 自定义事件

应用程序可以添加自定义事件通知主控。类似的在驱动event ID列表中添加自定义ID即可，如下图所示：

建议自定义事件ID从65000开始，为驱动预留足够的空间。

在WiFi模组中使用host_event_new API产生事件并通知主控。在主控端的demo代码hgicf.c文件中的hgicf_fwevent_parse函数添加自定义ID处理代码即可。如下图所示：

host_event_new API说明如下：

int32 host_event_new(uint32 evt_id, uint8 *data, uint32 data_len)

• 参数 evt_id ： 事件ID
• 参数 data ： 事件数据
• 参数 data_len：数据长度