K230 SDK IoT WiFi AiW4211LV10使用指南
1. 功能介绍
AiW4211LV10是一款低功耗IoT WiFi芯片，我司采用该芯片平台设计了一款AiW4211LV10开发板，该开发板可通过TF卡插槽接入K230 EVB板。K230 EVB加载AiW4211LV10驱动之后，可以生成wlan0无线网卡，实现网络数据通信。
图1-1 AiW4211LV10开发板
WiFi主要功能如图1-1所示：
图1-1 WiFi功能框图
WiFi主要功能简介：
- 消息通信：WiFi接收并解析Host端发送的消息指令及指令参数，触发相应事件执行
- 网络通信：网络数据透传
- 参数配置：建立SoftAP，接收配置参数，并触发配置事件
- 配置存取：管理配置数据形成的配置文件，存储在flash上
- AP接入：接入指定AP，监控接入状态并进行相应处理
- 保活链路：建立维护与远程服务器之间的保活链路
- 休眠：设置软硬件环境，给Host下电（依据平台特性，K230自下电），WiFi进入休眠模式
- IO唤醒：处理button或PIR唤醒信号，恢复软硬件环境，给Host上电
- 网络唤醒：处理来自保活链路的唤醒数据包，恢复软硬件环境，给Host上电
2. 模块依赖
硬件上依赖AiW4211LV10开发板，依赖K230 EVB开发板。软件上依赖于K230 SDK。
2.1 软件环境
K230 SDK V0.5.1及后 续版本。 AiW4211LV10 SDK。
2.2 硬件环境
K230 EVB开发板设置emmc启动，空出TF卡插槽用于AiW4211LV10开发板接入。 开发板硬件版本及跳线见表2-1：
表2-1开发板版本
| 开发板 | 硬件版本 | 设置 |
|---|---|---|
| K230 EVB | V1.1 | POWER BY BUTTON启动模式，跳线关系： 1.JUMPER J1 1—-2 2.JUMPER J1 13–14 |
| AiW4211LV10 | V1.1 |
K230 EVB开发板飞线到AiW4211LV10开发板排针，连接关系见表2-2：
表2-2 飞线关系
| Link1 | Link2 | Link3 | Link4 | Link5 | Link6 | Link7 | |
|---|---|---|---|---|---|---|---|
| K230 排针 | TP21 (5V) | J8.PIN9 (GPIO34) | J1.PIN9 (RTC_INT4) | J1.PIN14 (PW_EN) | |||
| WiFi 排针 | J6.PIN1 (5V) | J2.PIN3 (SDIO_INT_OUT) | J6.PIN3 (WH) | J2.PIN2 (GPIO2) | J2.PIN4 (TX) | J2.PIN5 (RX) | J2.PIN6 (GND) |
| TTL-USB | RX | TX | GND | ||||
| 说明 | 5V供电线 | WiFi数据中断线 | WiFi唤醒K230中断线 | WiFi监控K230电平 | com口收发 | com口收发 | com口GND |
连接说明：
- TP21是5V电压测试点，需要焊接一个插针，如果K230 EVB版本为V1.0则需要连接到J5 PIN16
- 如果使用不涉及WiFi唤醒K230 EVB则无需建立Link3
- 如果WiFi配置成通过监控K230 core的电源状态进入休眠则建立Link4，否则不需要。
- TTL-USB与WiFi的连线主要是为了观察WiFi的固件输出，无需要可以不连接
- AiW4211LV10开发板排针说明见表2-3
表2-3 WiFi开发板排针说明
| WIFI子板 接口 | 信号定义 | 描述 | 电平 | 必要性 | K230 USIP LP3 EVB 接口 | |
|---|---|---|---|---|---|---|
| J4 | 金手指 | SDIO_CLK/CMD/DATA | SDIO信号及GND | 3.3V | 必连 | TF卡槽 |
| J6 | PIN1 | VDD_5V_WIFI | 供电输入_5V | POWER | 必连 | TP21(V1.1) 或J5.PIN16(V1.0) |
| PIN2 | GND | GND | GND | 预留 | ||
| PIN3 | WIFI_WAKE_HOST | WIFI唤醒K230 | 1.8V | 功能信号 | J1.PIN9 | |
| PIN4 | WIFI_UART0_TX | 串口TX，可连接K230 | 1.8V | 预留 | J8.PIN15，目前无连接需求 | |
| PIN5 | WIFI_UART0_RX | 串口RX，可连接K230 | 1.8V | 预留 | J8.PIN13，目前无连接需求 | |
| PIN6 | HOST_WAKE_WIFI | K230唤醒WIFI | 1.8V | 功能信号 | J8.PIN11, 目前无连接需求 | |
| J2 | PIN1 | WIFI_POWER_EN | WIFI使能，预留 | 3.3V | 预留 | |
| PIN2 | GPIO2 | 监控K230电平 | 3.3V | 功能信号 | J1.PIN14 | |
| PIN3 | SDIO_INT_OUT | SDIO中断 | 1.8V | 功能信号 | J8.PIN9 | |
| PIN4 | UART0_TXD | 调试串口TXD | 3.3V | 调试串口 | 连PC | |
| PIN5 | UART0_RXD | 调试串口RXD | 3.3V | 调试串口 | 连PC | |
| PIN6 | GND | GND | GND | 调试串口 | 连PC | |
| J3 | PIN1 | PIR_WAKE_HOST | PIR唤醒K230 | 1.8V | 可选 | J1.PIN待定 |
| PIN2 | GND | PIR供电，接PIR黑色线 | GND | \ | \ | |
| PIN3 | PIR_WAKE_WiFi | PIR信号，接PIR棕色线 | 3.3V | \ | \ | |
| PIN4 | VDD_3V3 | PIR供电，接PIR红色线 | POWER | \ | \ |
3. 模块配置
3.1 SDK目录结构
WiFi SDK的目录结构如下：
├── README.txt //简要编译及使用说明文档
├── support //存放固件烧写工具BurnTool.exe，编译环境搭建说明文档及支持包
├── toolchain //固件交叉编译工具链
├── Makefile //编译入口Makefile，可实现一键编译
├── SocChannel //WiFi驱动及配置工具源码
├── AiW4211LV10 //WiFi固件源码
编译驱动的工具链因与平台相关，故未放入SDK之中，如有需要请联系我们。
3.2 定制化修改
在WiFi SDK之中，为了便于固件的定制化，与硬件设计关联比较紧密的代码，需要公布且可由用户定制的SoftAP相关参数，以及自定义的被多个文件使用的全局变量等，被放置在canaan_private.h及canaan_private.c文件之中。重点项目说明见表3-1：
表3-1 定制化重点项说明
| 项目 | 说明 |
|---|---|
| CONFIG_WIFI_MONITOR_HOSTLEVEL | 使能该宏之后WiFi通过监控K230的电源状态引脚触发休眠，将忽略休眠指令 |
| HOST_LLEVEL_TIME | 配合CONFIG_WIFI_MONITOR_HOSTLEVEL使用，电源状态引脚拉低持续HOST_LLEVEL_TIME时间将触发休眠，设置该时间是为了防抖及过滤冷启动的不稳定状态 |
| LONG_PRESS_TIME | 长按WiFi开发板上的K4按键持续LONG_PRESS_TIME时间WiFi将建立SoftAP模式，用于配置AP接入。参考5.3.1。 |
| TCP_SERVER_PORT | SoftAP建立之后，WiFi启动一个tcp socket server用于接收网络配置信息，TCP_SERVER_PORT是指定监听端口 |
| g_softap_ipaddr | SoftAP的网关、掩码及ip |
| g_softapcfg | SoftAP的热点名称及密码等 |
| gpios_config[] g_gpios_config | WiFi GPIO配置表，与硬件设计相关，描述各功能GPIO的编号、功能名、方向、中断类型及触发方式和中断回调函数 |
| kd_gpios_hoststanby | WiFi给Host下电接口，可根据平台特性实现，因K230自下电，此接口未操作任何IO |
| kd_gpios_wakehost | WiFi给Host上电接口，可根据平台特性实现，针对K230平台，WiFi给K230 PMU发送了一个IO信号 |
4. 固件编译
4.1 编译环境
固件编译环境搭建请参考文档《AiW4211V10／AiW4211LV10 SDK开发环境搭建 用户指南.pdf》，该文档存储于WiFi SDK的support目录。 使用者也可以联系 成都爱旗科技有限公司(http://www.aichtech.com/) 索取相关资料。
4.2 编译方法
进入WiFi SDK源码目录执行指令make all和make install，编译得到WiFi固件、驱动、配置工具及通信接口共享库文件存储在顶层的out目录下：
out/
├── bin
│ ├── aiw4211l_demo_allinone.bin
│ ├── aiw4211lv10.ko
│ ├── wifi.conf
│ ├── iotwifi_link
│ ├── iotwifi_cli
│ └── k230_pwrdown
├── inc
│ ├── soc_msg.h
│ └── hal_iotwifi_cli.h
└── lib
└── libhal_iotwifi.so
也可以各部分独立编译： make firmware：编译WiFi固件aiw4211l_demo_allinone.bin make driver：编译WiFi驱动aiw4211lv10.ko make tools：编译配置工具和通信接口共享库，iotwifi_link、iotwifi_cli、libhal_iotwifi.so、k230_pwrdown
备注：K230 SDK已经集成了WiFi驱动、配置工具和通信接口库，因此这些可以不编译
5. 模块启动
5.1 固件烧写
使用WiFi SDK support目录 下的烧写工具BurnTool.exe，通过串口将固件aiw4211l_demo_allinone.bin烧写到AiW4211LV10开发板。
烧写方法请参考文档《AiW4211V10／AiW4211LV10 BurnTool工具 使用指南.pdf》，该文档存储于WiFi SDK的support目录。
使用者也可以联系 成都爱旗科技有限公司(http://www.aichtech.com/) 索取相关资料。
图5-1展示的是单板快速烧写的示意图：
图5-1 单板快速烧写
step 1: 选择烧写COM口 step 2: 通过“Setting”菜单项配置COM口参数 step 3: 选择WiFi固件 step 4: 点击“Connect”控件向WiFi开发板发起连接，WiFi开发板上电，工具log窗口可以看到ready to load …，表示连接已经建立，可以开始烧写了 step 5: 点击“Send file”控件开始烧写
5.2 驱动加载
参考2.2节内容配置硬件环境，长按K230 EVB板上K1按键上电启动，加载驱动：
modprobe aiw4211lv10 或者 modprobe aiw4211lv10 mmc=1 gpio=34
启动配置工具server端并置于后台运行：iotwifi_link &
当前驱动支持传入mmc主控编号及用于中断检测的gpio编号，可以实现较为灵活的硬件配置，如果不传参则分别使用代码中规定的默认值1和34。iotwifi_link的功能角色类似于wpa_supplicant，它首先会将wlan0 up起来，然后从WiFi设备 侧同步mac地址及ip地址到Host端。
图 5-2 驱动加载及iotwifi_link启动
5.3 参数配置
AiW4211LV10的接入AP、休眠等级、休眠周期、唤醒IO、tcp keepalive的目标server、保活参数等直接影响WiFi运行，且需要根据实际场景进行动态调整的参数，可以通过5.3.1和5.3.2节提供的方式方法进行传参配置。
除非用户想要改变配置，否则每次启动之后无需重配。
5.3.1 通过网络配置AP接入
AiW4211LV10开发板支持通过网络配置目标AP的名称、密码和加密方式这三个参数。配置AP接入的步骤如下：
step 1: 准备一个路由器，并记录其热点名称、密码和加密方式信息 step 2: AiW4211LV10开发板在固件烧写之后初次启动运行时，或者在已经完成配置的情况下长按板上K4按键3s，WiFi将启动SoftAP模式生成一个热点并建立一个基于TCP协议的socket server step 3: 将PC连入该热点，然后启动NetAssist step 4: 配置NetAssist作为 tcp socket client连接到WiFi step 5: server解析配置数据后连接到指定AP，退出SoftAP模式
使用者如有能力可以开发一个手机APP进行网络配置，这里为简单起见只是使用了PC+NetAssist方案。SoftAP参数及配置数据格式见表5-1，NetAssist配置运行见图5-1：
表 5-1 SoftAP 参数及配置数据格式
| 项目 | 参数 |
|---|---|
| AP name | k230 |
| AP password | 12345678 |
| server ip | 192.168.43.1 |
| server port | 35556 |
| config data | cfg=<targer ap name>,<targer ap auth>,<targer ap password> 例如：cfg=xuyuxuan,2,Xuyuxuan123 |
图 5-3 NetAssist配置运行
5.3.2 通过消息配置AP接入
AiW4211LV10开发板支持通过消息通道配置目标AP参数（与5.3.1功能相同），除此之外还可以通过消息通道配置WiFi休眠参数和tcp keepalive参数。消息通道是K230与AiW4211LV10之间通过SDIO总线建立起来的软件通道。
5.3.2.1 通过配置工具配置
配置步骤如下：
step 1: 准备一个路由器并启动热点 step 2: 将PC接入该热点，然后启动NetAssist，这里为简单起见使用PC+NetAssist作为远端保活服务器 step 3: 配置NetAssist作为 tcp socket server等待WiFi保活链路的接入 step 4: K230端根据热点信息和NetAssist启动的server信息编辑配置文件/etc/wifi.conf step 5: 运行配置工具client端，解析配置文件，发送配置消息：iotwifi_cli –config /etc/wifi.conf step 6: AiW4211LV10接收到配置参数之后，首先存储休眠参数，然后接入指定AP，最后建立tcp socket client连入NetAssist建立的 tcp socket server
/etc/wifi.conf是WiFi工作参数配置文件，以json格式编写，基本上是对wifi_config_t结构体的映射，具体可参考6.1.2章节。文件内容如下：
{
"sleep": {
"level": 2,
"period": 3000,
"wake_gpios": [5]
},
"conn": {
"ssid": "xuyuxuan",
"auth": 2,
"key": "Xuyuxuan123",
"bssid": "",
"pairwise": 0
},
"keepalive": {
"svrip": "192.168.50.197",
"svrport": 5001,
"time": 10,
"intvl": 2,
"probes": 5,
"hrintvl": 60,
"hrprobes": 5
}
}
备注： “wake_gpios”: [5] 是一个数组项，当前数组只有一个元素5，表示WiFi可以被自身的gpio5唤醒，该IO对应按键K4，如果新添加唤醒源可以以逗号分隔追加。这取决于具体的硬件设计。
图 5-4 （A）WiFi接入路由器并被分配IP （B）tcp keepalive server
5.3.2.2 通过调用API配置
在实际的业务程序中，可以通过调用通信接口共享库libhal_iotwifi.so提供的API接口kd_wifi_config进行参数配置，API说明请参考6.1.1章节，配置步骤与5.3.2.1相同。
5.3.2.1节当中介绍的工具iotwifi_cli也是通过调用该接口实现WiFi参数配置的。
5.4 系统休眠
5.4.1 通过工具配置休眠
运行配置工具client端发送休眠指令触发WiFi休眠：iotwifi_cli –dirsleep
图 5-5 WiFi进入休眠log
5.4.2 通过调用API休眠
在实际的业务程序中，可以通过调用通信接口共享库libhal_iotwifi.so提供的API接口kd_wifi_sleep触发WiFi休眠，具体请参考6.2章节。
工具iotwifi_cli也是通过调用该接口触发WiFi休眠的。
5.4.3 通过监控电平休眠
K230 EVB可以实现自下电，下电之后K230 EVB开发板J1 PIN14（PW_EN）引脚的电平将会被拉低，WiFi也可以通过监控该引脚的电平触发休眠。该功能使用的前提是K230功耗管理功能正常，并在编译WiFi固件时使能宏 CONFIG_WIFI_MONITOR_HOSTLEVEL（默认不使能），使能该宏之后WiFi将忽略K230发送的sleep指令，仅依据引脚电平状态进行休眠。
工具k230_pwrdown可以实现较为简单的K230 EVB双核自下电，它未做任何文件存储、状态检测等业务逻辑上的安全处理，因此只可以用于电平触发WiFi休眠的场景验证。该工具未集成到K230 SDK当中，因此需要拷贝到K230 EVB上执行：
./k230_pwrdown
5.5 系统唤醒
5.5.1 按键唤醒
如果WiFi已进入休眠状态，短按AiW4211LV10开发板上的K4按键可唤醒WiFi，WiFi将给K230 EVB的PMU发送唤醒信号，如果此时K230 EVB处于5.4.3节配置的下电状态（非冷启动），其将被上电。
图5-6 按键唤醒log
5.5.2 网络唤醒
如果WiFi已进入休眠状态，NetAssist发送wakeup可唤醒WiFi，WiFi将给K230 EVB的PMU发送唤醒信号，如果此时K230 EVB处于5.4.3节配置的下电状态（非冷启动），其将被上电。
图5-7 网络唤醒log
6. API参考
AiW4211LV10驱动加载后生成的无线网卡与一般WiFi网卡无异，因此网络通信功能无特殊API需要说明。 除基本的网络通信外，K230与WiFi还存在两个消息通信接口，需要重点说明。
6.1 config接口
6.1.1 API
int kd_wifi_config(wifi_config_t *config) 配置WiFi工作参数：
- 配置目标AP的名称、密码、认证及加密方式
- 配置WiFi休眠等级，苏醒周期以及可唤醒的gpio
- 配置tcp keepalive时间参数等
6.1.2 数据结构
6.1.2.1 wifi_config_t
typedef struct {
unsigned int config_mask;
#define CFG_MASK_SLEEP (1 << 0)
#define CFG_MASK_CONNECT (1 << 1)
#define CFG_MASK_KEEPALIVE (1 << 2)
wifi_sleep_t sleep;
wifi_connect_t conn;
wifi_keepalive_t keepalive;
} wifi_config_t;
表6-1 wifi_config_t结构体成员
| config_mask | 配置目标项掩码，使能或屏蔽目标项，例如全部配置则：config_mask = CFG_MASK_SLEEP|CFG_MASK_CONNECT|CFG_MASK_KEEPALIVE CFG_MASK_SLEEP：配置休眠参数 CFG_MASK_CONNECT：配置AP连接参数 CFG_MASK_KEEPALIVE：配置tcp keepalive参数 |
|---|---|
| sleep | 休眠参数 |
| conn | AP连接参数 |
| keepalive | tcp keepalive参数 |
6.1.2.2 wifi_sleep_t
typedef struct
{
unsigned int level;
#define WIFI_SLEEP_LIGHT 1
#define WIFI_SLEEP_DEEP 2
#define WIFI_SLEEP_ULTRA 3
unsigned int period;
union
{
/*
* gpioX_wake: 0---disable, 1---enable
*/
struct {
unsigned int gpio0_wake:1;
unsigned int gpio1_wake:1;
unsigned int gpio2_wake:1;
unsigned int gpio3_wake:1;
unsigned int gpio4_wake:1;
unsigned int gpio5_wake:1;
unsigned int gpio6_wake:1;
unsigned int gpio7_wake:1;
unsigned int gpio8_wake:1;
unsigned int gpio9_wake:1;
unsigned int gpio10_wake:1;
unsigned int gpio11_wake:1;
unsigned int gpio12_wake:1;
unsigned int gpio13_wake:1;
unsigned int gpio14_wake:1;
};
unsigned int wake_gpios;
};
} wifi_sleep_t;
表6-2 wifi_sleep_t结构体成员
| level | 休眠等级 WIFI_SLEEP_LIGHT：浅睡 WIFI_SLEEP_DEEP：深睡，主要休眠模式 WIFI_SLEEP_ULTRA：超深睡，只有3/5/7/14号gpio可唤醒，目前不使用 |
|---|---|
| period | 苏醒周期，有效数值33~~4000ms。WiFi周期性从休眠态醒来，检测AP是否有发给自己的数据缓存 |
| wake_gpios | enable或disable可唤醒WiFi的gpio（WiFi侧gpio） |
6.1.2.3 wifi_connect_t
typedef struct
{
char ssid[EXT_WIFI_MAX_SSID_LEN + 1];
ext_wifi_auth_mode auth;
char key[EXT_WIFI_MAX_KEY_LEN + 1];
unsigned char bssid[EXT_WIFI_MAC_LEN];
ext_wifi_pairwise pairwise;
} wifi_connect_t;
表6-3 wifi_connect_t结构体成员
| ssid | AP名称 |
|---|---|
| auth | 认证类型 EXT_WIFI_SECURITY_OPEN EXT_WIFI_SECURITY_WEP EXT_WIFI_SECURITY_WPA2PSK EXT_WIFI_SECURITY_WPAPSK_WPA2PSK_MIX EXT_WIFI_SECURITY_WPAPSK EXT_WIFI_SECURITY_WPA EXT_WIFI_SECURITY_WPA2 EXT_WIFI_SECURITY_SAE EXT_WIFI_SECURITY_WPA3_WPA2_PSK_MIX EXT_WIFI_SECURITY_UNKNOWN |
| Key | AP密码 |
| bssid | AP bssid，一般为AP mac地址 |
| pairwise | 加密类型 EXT_WIFI_PARIWISE_UNKNOWN EXT_WIFI_PAIRWISE_AES EXT_WIFI_PAIRWISE_TKIP EXT_WIFI_PAIRWISE_TKIP_AES_MIX |
6.1.2.4 wifi_keepalive_t
typedef struct
{
unsigned char svrip[16];
unsigned short svrport;
unsigned short tcp_keepalive_time;
unsigned short tcp_keepalive_intvl;
unsigned short tcp_keepalive_probes;
unsigned short heartbeat_intvl;
unsigned short heartbeat_probes;
} wifi_keepalive_t;
表6-4 wifi_keepalive_t结构体成员
| svrip | server端ip地址 |
|---|---|
| svrport | server端端口号 |
| tcp_keepalive_time | TCP层keepalive心跳包常规发送周期，秒 |
| tcp_keepalive_intvl | TCP层keepalive心跳包无回应之后新的发送周期，秒 |
| tcp_keepalive_probes | TCP层keepalive心跳包无回应计数超过该阈值之后，判断TCP连接异常，断开重连 |
| heartbeat_intvl | 应用层心跳包发送周期，秒 |
| heartbeat_probes | 应用层心跳包无回应计数超过该阈值之后，判断socket连接异常，断开重连 |
6.2 sleep接口
int kd_wifi_sleep(void) 控制WiFi进入休眠，休眠相关参数在config API当中设置。
7.wifi功能限制
AiW4211LV10芯片为单频wifi芯片,不支持ap和sta同时共存，当ap启动时固定在某一信道，再起sta的话sta会在不同的信道上扫描，此时ap就会断连。 当通过sdio传入conf为错误配置时，AiW4211LV10会显示sta连接ap失败 串口打印 please reset conf，此时可通过iotwifi_cli传入新的正确的conf。 当通过client传入sta错误配置时，wifi从ap会切换到sta模式，AiW4211LV10会显示sta连接ap失败 串口同样打印please reset conf，由于sta与ap不能同时共存，这时wifi芯片会从sta切换到ap模式重新起tcp server ，sta需要重新连接ap,作为client重新接入。