异步应用接口文档

本文档基本数据类型说明：

PS：v3.02版本之后，类型均修改为标准类型，即unsigned char，unsigned int等。以下定义已在.h中移除。

u64_t表示数据类型unsigned long long
s64_t表示数据类型signed long long
ul32_t表示数据类型unsigned long
sl32_t表示数据类型signed long
u32_t表示数据类型unsigned int
s32_t表示数据类型signed int
u16_t表示数据类型unsigned short
s16_t表示数据类型signed short
u8_t表示数据类型unsigned char
s8_t表示数据类型signed char
n8_t表示数据类型char
boolean表示数据类型unsigned char

库接口说明

1. WIoTa系统资源

1.1 初始化WIoTa

初始化WIoTa

目的
WIoTa协议栈的初始化。
语法

void uc_wiota_init(void);

描述
初始化WIoTa协议栈的资源，比如：线程，内存等。
返回值
无。
参数
无。

1.2 启动WIoTa

目的
启动WIoTa协议栈。
语法

void uc_wiota_run(void);

描述
启动WIoTa协议栈，进入空闲状态，即UC_STATUS_NULL。
返回值
无。
参数
无。

1.3 关闭WIoTa

目的
关闭WIoTa协议栈。
语法

void uc_wiota_exit(void);

描述
关闭WIoTa协议栈，回收所有WIoTa协议栈资源。
返回值
无。
参数
无。

1.4 获取WIoTa库版本信息

目的 WIoTa库的版本号、git信息以及编译时间。
语法

void uc_wiota_get_version(unsigned char *wiota_version, unsigned char *git_info, unsigned char *time, unsigned int *cce_version);

描述
WIoTa库的版本号、git信息以及编译时间。
返回值
无。
参数
wiota_version: wiota 库的版本信息。字符串，最大字符长度16字节。
git_info：wiota库对应git信息。字符串，最大字符长度36字节。
time： wiota库编译时间。字符串，最大字符长度36字节。
cce_version: CCE版本号。无符号int型，长度4字节。

示例

unsigned char version[16] = {0};
unsigned char git_info[36] = {0};
unsigned char time[36] = {0};
unsigned int cce_version = 0;
uc_wiota_get_version(version, git_info, time, &cce_version);

1.5 暂停/恢复WIoTa

v3.01新增接口

目的
暂停/恢复WIoTa协议栈。
语法

unsigned char uc_wiota_suspend(void);  
unsigned char uc_wiota_recover(void);

描述
暂停wiota系统，进入空闲状态。用于避免wiota运行和读写flash的冲突。
恢复wiota系统，进入默认接收状态。
返回值
是否切换成功。
参数
无。

2. 配置系统参数

2.1 获取系统配置

目的
获取系统配置。
语法

void uc_wiota_get_system_config(sub_system_config_t *config);

描述
获取系统配置。
返回值
无。
参数
无。
结构体

typedef struct {  
  unsigned char  reserved0;       // 预留位，待改
  unsigned char  id_len;        // id长度，取值0,1,2,3代表2,4,6,8字节  
  unsigned char  pp;            // 固定为1，暂时不提供修改  
  unsigned char  symbol_length; // 帧配置，取值0,1,2,3代表128,256,512,1024  
  unsigned char  pz;                 // 帧头相关配置，默认值为8   
  unsigned char  btvalue;       // 和调制信号的滤波器带宽对应，BT越大，信号带宽越大，取值0,1代表BT_1.2和BT_0.3，BT_1.2的数据速率比BT_0.3的高  
  unsigned char  bandwidth;       // 带宽，默认为1，即200KHz 
  unsigned char  spectrum_idx;  // 频谱序列号，默认为3，即470-510M(具体见频谱idx表)
  unsigned int   systemid;      // 系统id  
  unsigned int   subsystemid;   // 子系统id  
  unsigned char freq_list[16];
  unsigned char  na[32];  
} sub_system_config_t;

v2.9版本更新如下：增加freq_idx，freq_list增大。

typedef struct {  
  unsigned char  reserved0;       // 预留位，待改
  unsigned char  id_len;        // id长度，取值0,1,2,3代表2,4,6,8字节  
  unsigned char  pp;            // 固定为1，暂时不提供修改  
  unsigned char  symbol_length; // 帧配置，取值0,1,2,3代表128,256,512,1024  
  unsigned char  pz;                 // 帧头相关配置，默认值为8   
  unsigned char  btvalue;       // 和调制信号的滤波器带宽对应，BT越大，信号带宽越大，取值0,1代表BT_1.2和BT_0.3，BT_1.2的数据速率比BT_0.3的高  
  unsigned char  bandwidth;       // 带宽，默认为1，即200KHz 
  unsigned char  spectrum_idx;  // 频谱序列号，默认为3，即470-510M(具体见频谱idx表)
  unsigned short freq_idx;      // freq idx
  unsigned char reserved1[2];
  unsigned int   subsystemid;   // 子系统id  
  unsigned short freq_list[16];
  unsigned char  na[16];  
} sub_system_config_t;

参数类型描述：

id_len：user_id长度，取值0,1,2,3代表2,4,6,8字节，默认四字节，IOTE该变量需要与AP保持一致，现在只支持设置为1，即四字节。
pp：固定为1，此值涉及同步灵敏度、传输效率等系统性能，暂时不提供修改。
symbol_length：帧配置，取值0,1,2,3代表128,256,512,1024
pz：帧头相关配置，默认值为8，低功耗需要修改
bt_value：该值和调制信号的滤波器带宽对应，BT越大，信号带宽越大，取值0,1代表BT配置为1.2和BT配置为0.3，bt_value为0时，代表使用的是低阶mcs组，即低码率传输组。bt_value为1时，代表使用的是高mcs组，即高码率传输组。
bandwidth：带宽，带宽会影响物理时间，帧长和子帧长等。
spectrum_idx：频谱序列号，默认为3，即470-510M(具体见下图)。
system_id：系统id，预留值，必须设置，但是不起作用。（v2.9版本删除了该参数）
freq_idx：频点。（v2.9版本新增参数）
subsystem_id：子系统id（子系统的识别码，终端IOTE如果要连接该子系统（AP），需要将config配置里的子系统ID参数配置成该ID）。
freq_list：频点列表，用于自动管理功能等，v2.9版本一个频点长度从1个字节改为2个字节。
na：预留位。

bandwidth
0: 400K    // 暂不支持
1: 200K // 默认带宽
2: 100K 
3: 50K 
4: 25K 
5: 12.5K // 暂不支持

以下表格为带宽为200K的频点idx情况，其他带宽可推算。

v2.9 将频段1的范围从430~432M改为了400~470M

频谱idx	低频MHz	高频MHz	中心频率MHz	频带宽度MHz	频点step MHz	频点idx	频点个数
0（other1）	223	235	229	12	0.2	0~60	61
1（other2）	400	470	435	70	0.2	0~350	351
2（EU433）	433.05	434.79	433.92	1.74	0.2	0~8	9
3（CN470-510）	470	510	490	40	0.2	0~200	201
4（CN779-787）	779	787	783	8	0.2	0~40	41
5（other3）	840	845	842.5	5	0.2	0~25	26
6（EU863-870）	863	870	866.5	7	0.2	0~35	36
7（US902-928）	902	928	915	26	0.2	0~130	131

注意
(1) 子系统配置表需要一样才能相互通信。
(2) 暂不支持BT_1.2，即btvalue=0。

2.2 设置系统配置

目的
设置系统配置。
语法

void uc_wiota_set_system_config(sub_system_config_t *config);

描述
设置系统配置时，注意参数个数，强烈建议先获取系统配置，再更改需要更新的相关参数，保持其他参数不变，最后设置系统配置。
返回值
无。
参数
子系统配置结构表。
结构体
同前一个接口。
注意
(1) 同一个系统内的所有终端的系统配置需要保持一致才能相互通信。
(2) 在协议栈初始化后，在启动之前配置。

2.3 设置子系统ID

目的
设置子系统ID。
获取子系统ID。
语法

void uc_wiota_set_subsystem_id(unsigned int subsystemid);  
unsigned int uc_wiota_get_subsystem_id(void);

描述
在协议栈初始化后，在启动之后均可配置。
在启动之后配置时，内部会停止当前收发，再切换子系统ID。
返回值
无。
参数
subsystemid：子系统ID
结构体
同前一个接口。
注意
(1) 同一个系统内的所有终端的子系统ID需要保持一致才能相互通信。
(2) 在协议栈初始化后，在启动之后均可配置，不建议在发送数据期间切换子系统ID。

3. 功率设置

3.1 设置当前功率

目的
设置固定功率或者自动功率(自动/手动切换)。
语法

void uc_wiota_set_cur_power(signed char power);

描述
设置功率值，如果功率值为正常范围值，则设置成该功率，如果超出范围，则设置为对应的最大或最小功率，并且关闭自动功率模式。
如果功率值为107，则代表恢复自动功率模式。
返回值
无。
参数
power，范围-16 ~ 21dbm。 (V2.9版本更新为 -18 ~ 22 dbm)
注意
暂不支持自动功率。
在协议栈初始化之后，或者在启动之后配置均可。

3.2 设置最大功率

目的
设置最大功率。
语法

void uc_wiota_set_max_power(signed char power);

描述
设置最大功率值，在自动功率模式情况下会用到最大功率值。
返回值
无。
参数
输入power，范围-16 ~ 21dbm。(V2.9版本更新为 -18 ~ 22 dbm)
注意
在协议栈初始化之后，或者在启动之后配置均可。

3.3 设置功率发送模式

目的
设置功率模式。
语法

void uc_wiota_set_tx_mode(unsigned char mode);   
unsigned char uc_wiota_get_tx_mode(void); // v3.00新增获取接口

描述
默认值为3，协议栈低功耗或者使用LE硬件模组时，需要设置mode为0
返回值
无。
参数
mode：默认值为3，一般不需要修改，LE模组在出厂配置里会默认配置为0。
注意
在协议栈初始化后，在启动之前配置。

3.4 设置ack自动功率模式

v3.01新增接口

目的
关闭/开启ack自动功率模式。
语法

void uc_wiota_set_auto_ack_pow(unsigned char is_open);   
unsigned char uc_wiota_get_auto_ack_pow(void);

描述
默认打开时，ack功率比发送端功率高0~5dbm，关闭时，使用本地配置的功率
返回值
查询接口返回：是否开启。
参数
is_open：0，关闭； 1，开启。
注意
在协议栈初始化后配置。

4. 频点相关

4.1 设置频点

4.1.1 v2.9以及之后版本的频点配置

目的
设置频点，各节点需要设置相同频点才能相互通信。
语法

void uc_wiota_set_freq_info(unsigned short freq_idx);

描述
设置频点，目前的默认频带是470M-510M，每间隔带宽为一个频点。当默认为200K带宽时，频点1代表 470.02 MHz；
当带宽为25K时，频点1代表 470.0025 MHz。
带宽即为系统参数配置中的bandwidth。
返回值
无。
参数
频点idx：范围根据频带和带宽不同而不同
注意
在协议栈初始化之后，或者在启动之后配置均可（不支持在发送数据过程中更改）。

4.1.2 v2.9之前版本的频点配置

目的
设置频点，各节点需要设置相同频点才能相互通信。
语法

void uc_wiota_set_freq_info(unsigned char freq_idx);

描述
设置频点，目前的默认频带是470M-510M，每200K一个频点。
返回值
无。
参数
频点idx，范围0~200，代表频点（470+0.2*idx）。
注意
在协议栈初始化之后，或者在启动之后配置均可（不支持在发送数据过程中更改）。

4.2 查询频点

4.2.1 v2.9以及之后版本的频点查询

目的
获取频点idx。
语法

unsigned short uc_wiota_get_freq_info(void);

描述
查询频点，目前频点范围470M-510M，每间隔带宽为一个频点。
当默认为200K带宽时，频点1代表 470.02 MHz；
当带宽为25K时，频点1代表 470.0025 MHz。
带宽即为系统参数配置中的bandwidth。
返回值
频点idx
参数
无。
注意
无。

4.2.2 v2.9之前版本的频点查询

目的
获取频点idx。
语法

unsigned char uc_wiota_get_freq_info(void);

描述
查询频点，目前频点范围470M-510M，每200K一个频点。
返回值
频点idx，范围0~200，代表频点（470+0.2*idx）。
参数
无。
注意
无。

4.3 快速扫频

目的
扫频，获取频点的RSSI，用于判断频点干扰情况。
语法

void uc_wiota_scan_freq(unsigned char* data, unsigned short len, unsigned char scan_round, unsigned int timeout, uc_recv callback, uc_recv_back_p recv_result);

描述
发送扫频频点数据，等待返回结果，提供两种模式。
如果回调函数不为NULL，则非阻塞模式，扫频结束或者超时后会调用callback返回结果。
如果回调函数为NULL，则为阻塞模式，扫频结束或者超时该函数才会返回结果。
返回值
recv_result。结构体参考10.3被动接收数据接口注册。
参数
data：需要传输的数据的头指针，在收到返回结果之前不能释放，数据内容为uc_freq_scan_req_t的结构体数组。
len：数据长度，如果len为0并且data为空，则代表需要全频带扫频，此刻的timeout建议设置为60000ms。注意：v2.9版本，频点从8bit变成16bit单位，uc_freq_scan_req_t变化，len不再等同于频点个数。
scan_round：扫频轮数，理论上来说，扫频轮数越多，越可能扫出潜在的信号，同时扫频时间也会更长。如果scan_round设为0，则使用默认值5。
callback：回调函数，非阻塞时处理返回结果。
timeout：超时时间，单位ms。
uc_recv_back_p：返回的结果结构体指针，详见10.3节数据接收回调注册，在扫频结果返回时，其中的type为UC_RECV_SCAN_FREQ，其中的data存放的是扫频结果，即uc_freq_scan_result_t结构体数组头指针。注意，data需要释放内存。
结构体

typedef struct {  
    unsigned char  freq_idx;  
}uc_freq_scan_req_t,*uc_freq_scan_req_p;  

typedef struct {    
    unsigned char  freq_idx;      
    signed char    rssi;  
}uc_freq_scan_result_t,*uc_freq_scan_result_p;

v2.9版本更新，频点更新为2个字节单位：

typedef struct
{
    unsigned short freq_idx;
} uc_freq_scan_req_t, *uc_freq_scan_req_p;

typedef struct
{
    unsigned short freq_idx;
    signed char rssi;
    unsigned char reserved;
} uc_freq_scan_result_t, *uc_freq_scan_result_p;

参数介绍
freq_idx：频点。
rssi：该频点的接收信号强度指示，该信号可能是本系统的，也可能是干扰信号。
注意
需要先初始化协议栈，并且配置系统参数，特别是其中的频带信息，再启动协议栈后才能扫频操作，每次扫频只能扫一个频带的频点。
上报结果会根据RSSI从大到小排序。
API的使用可以参考AT扫频接口。

5. 用户ID相关

5.1 设置用户id

目的
设置用户id。
语法

int uc_wiota_set_userid(unsigned int* id, unsigned char id_len);

描述
设置用户id，此id为终端唯一标识。
返回值
0：正常。
1：参数异常。
参数
id: 用户id的地址指针。例：

unsigned int uid_list[1] = {0x12345678};
uc_wiota_set_userid(uid_list,4);

id_len: id长度，取值范围1~4字节。

注意
目前支持最大4字节长度的user id。请勿使用0值。
在协议栈初始化后，在启动之前配置。

5.2 获取用户id

目的
获取用户id。
语法

void uc_wiota_get_userid(unsigned int* id, unsigned char* id_len);

描述
获取用户id，此id为终端唯一标识。
返回值
id: user_id
id_len: id长度，取值2,4,6,8字节。
参数
无。
注意
目前只支持4字节长度的user id。

6 状态信息

6.1 查询WIoTa当前状态

目的
查询WIoTa协议栈的状态，为下一步操作做准备。
语法

uc_wiota_status_e uc_wiota_get_state(void);

描述
查询wiota当前状态。
返回值
状态枚举值。

typedef enum {  
  UC_STATUS_NULL = 0,  
  UC_STATUS_RECV_TRY,  
  UC_STATUS_RECVING,  
  UC_STATUS_SENDING,
  UC_STATUS_SLEEP,  
  UC_STATUS_ERROR,   
}uc_wiota_status_e;

UC_STATUS_NULL：启动协议栈之前或者关闭协议栈后，或者启动协议栈后未开始自动检测接收时，处于该状态。
UC_STATUS_RECV_TRY：启动协议栈后，自动开始检测帧头，处于该状态。
UC_STATUS_RECVING：协议栈检测到其他节点的数据后，开始接收，处于该状态。
UC_STATUS_SENDING：协议栈收到应用数据开始发送数据，处于该状态。
UC_STATUS_SLEEP：协议栈休眠时，处于SLEEP状态，该状态暂未支持。
UC_STATUS_ERROR：其他错误状态。

参数
无。
注意
无。

6.2 获取无线信道状态

目的
获取信道参数。
语法

void uc_wiota_get_radio_info(radio_info_t *radio);

描述
设置系统配置。
参数
无线信道参数表：
rssi: 信号强度，范围0~150，实际表示0 ~ -150dbm，暂不支持。
ber: 误码率，暂不支持。
snr: 信噪比，范围 -25dB ~ 30dB，暂不支持。
cur_pow: 当前发射功率，范围 -16~21dBm。(V2.9版本更新为 -18 ~ 22 dbm)
min_pow: 最小发射功率，范围 -16~21dBm。(V2.9版本更新为 -18 ~ 22 dbm)
max_pow: 最大发射功率，范围 -16~21dBm。(V2.9版本更新为 -18 ~ 22 dbm)
cur_mcs: 当前数据发送速率级别，范围 0~7，越大速率越高。
max_mcs: 截止目前最大数据发送速率级别，范围 0~7。
frac_offset: 基带同步频偏，仅供参考，可判断此时同步是否正常，-1500 ~ 1500都属于正常。

6.3 查询WIoTa物理层的当前状态

目的
查询WIoTa物理层的状态，为下一步操作做准备。
语法

unsigned char uc_wiota_get_pyhsical_status(void); // UC_RF_STATUS_E

v2.9版本修改名字如下：

unsigned char uc_wiota_get_physical_status(void); // UC_RF_STATUS_E

描述
查询WIoTa物理层当前状态。
返回值
状态枚举值。

typedef enum
{
  RF_STATUS_IDLE = 0,
  RF_STATUS_TX,
  RF_STATUS_RX,
  INVALD_RF_STATUS
} uc_rf_status_e;

RF_STATUS_IDLE：基带空闲时处于该状态。
RF_STATUS_TX：基带发送时，处于该状态。
RF_STATUS_RX：基带接收时，处于该状态。
INVALD_RF_STATUS：其他错误状态。

参数
无。
注意
无。
结构体

typedef struct {  
  unsigned char   rssi;  // absolute value, 0~150 means 0 ~ -150
  unsigned char   ber;  
  signed char     snr;    
  signed char     cur_pow;
  signed char     min_pow;
  signed char     max_pow;
  unsigned char   cur_mcs;
  unsigned char   max_mcs;
  signed int      frac_offset;
}radio_info_t;

注意
rssi,snr,frac_offset只有在接收数据期间才有效，仅供参考

6.4 查询WIoTa系统当前运行状态

目的
查询WIoTa系统运行状态，为下一步操作做准备。
语法

unsigned char uc_wiota_execute_state(void);  // 返回值为uc_task_state_e

描述
查询wiota task的运行状态，不是协议栈的工作状态。
返回值
状态枚举值。

typedef enum
{
  MODULE_STATE_NULL = 0,
  MODULE_STATE_INIT,
  MODULE_STATE_RUN,
  MODULE_STATE_SWITCHING,
  MODULE_STATE_INVALID
} uc_task_state_e;

MODULE_STATE_NULL：初始化wiota之前或者关闭协议栈后，处于该状态。
MODULE_STATE_INIT：初始化wiota后，处于该状态。
MODULE_STATE_RUN：启动wiota run后，处于该状态。
MODULE_STATE_SWITCHING：在init/run/exit接口调用期间，处于该状态。
MODULE_STATE_INVALID：其他错误状态。

参数
无。
注意
无。

7. 频偏及dcxo

7.1 设置DCXO

目的
设置频偏，无源晶体才需要设置dcxo。
语法

void uc_wiota_set_dcxo(unsigned int dcxo);  
unsigned int uc_wiota_get_dcxo(void);  // v3.00 新增获取接口

描述
每块芯片的频偏不同，在协议栈启动之前需要单独配置，测试模式使用，之后量产时会测好后固定写在系统静态变量中，不需要应用管理。
返回值
无。
参数
dcxo：频偏。
注意
在协议栈初始化之后，启动之前调用，否则无法生效。

7.2 设置有源晶体

目的
设置有源晶体，查询有源晶体。
语法

void uc_wiota_set_is_osc(unsigned char is_osc);   
unsigned char uc_wiota_get_is_osc(void);

描述
硬件如果是有源晶体，需要设置为有源晶体。此项设置与DCXO设置互斥，如果设置了有源晶体，就不能再设置DCXO。第二个函数获取第一个函数设置下去的值。
返回值
无。
参数
is_osc：是否有源晶体。0: 设置非有源晶体， 1: 设置有源晶体。如果设置大于1，内部也处理成有源晶体。
注意
在协议栈初始化之后，启动之前调用，否则无法生效。

7.3 频偏校准

目的
设置校准模式，在一对一或者一对多（多个接收端）的多终端场景下校准dcxo，有源晶振不需要校准。
语法

void uc_wiota_set_agjust_mode(uc_adjust_mode_e adjust_mode);

描述
接收方的频偏需要跟发送方对齐，所以在通信之前需要校准，具体流程如下：
发送方初始化，设置ADJUST_MODE_SEND，启动协议栈，使用默认配置可不需要系统配置；
接收方初始化，设置ADJUST_MODE_RECV，启动协议栈，使用默认配置可不需要系统配置，启动后，等待10帧时间查询协议栈状态，如果是UC_STATUS_RECVING，则校准成功，此时关闭协议栈。
所有接收方均校准完成后，关闭发送方的协议栈。（正常通信时，不再需要修改收发双方的dcxo，内部会有校准好的dcxo数据，请勿破坏）
返回值
无。
参数
adjust_mode：校准模式。

typedef enum {
  ADJUST_MODE_SEND = 0,  // 发送方，开启后会一直发送信号
  ADJUST_MODE_RECV = 1,  // 接收者，根据接收信号与发送方校准频偏
} uc_adjust_mode_e;

注意
在协议栈初始化之后，启动之前调用，否则无法生效。校准完成后，是双向生效的，比如b/c都与a校准过，则b和c之间也能正常通信。

7.4 设置外部32K晶振

目的
设置外部32K晶振，需要硬件支持，外部32K晶振比内部的误差更小。
语法

void uc_wiota_set_outer_32K(unsigned char is_open);

描述
当硬件版上有此晶振才可以使用该接口开启。
返回值
无。
参数
is_open：是否使用外部32K晶振。
注意
建议在main开头使用，如需要则尽早开启。

8. 低功耗相关

8.1 设置降压模式

目的
降压模式设置
语法

void uc_wiota_set_vol_mode(unsigned char vol_mode);

描述
设置是否降压。
返回值
无。
参数
div_mode：0，默认电压（1.82v）；1，降压（1.56v）。

typedef enum {
  VOL_MODE_CLOSE = 0,  // 1.82v
  VOL_MODE_OPEN = 1,   // 1.56v
  VOL_MODE_TEMP_MAX,
} uc_vol_mode_e;

注意
该接口在不启动协议栈时使用。

8.2 设置降频

目的
降频分频比设置
语法

void uc_wiota_set_freq_div(unsigned char div_mode);

描述
设置降频分频比
返回值
无。
参数

typedef enum {  
  FREQ_DIV_MODE_1 = 0,  // default: 96M
  FREQ_DIV_MODE_2 = 1,  // 48M
  FREQ_DIV_MODE_4 = 2,  // 24M
  FREQ_DIV_MODE_6 = 3,  // 16M
  FREQ_DIV_MODE_8 = 4,  // 12M
  FREQ_DIV_MODE_10 = 5, // 9.6M
  FREQ_DIV_MODE_12 = 6, // 8M
  FREQ_DIV_MODE_14 = 7, // 48/7 M
  FREQ_DIV_MODE_16 = 8, // 6M
  FREQ_DIV_MODE_MAX,
} uc_freq_div_mode_e;

注意
该接口在不启动协议栈时使用，降频后系统运行速率会变慢。

8.3 设置WIoTa低功耗模式

目的
设置协议栈的低功耗运行。
语法

void uc_wiota_set_lpm_mode(unsigned char lpm_mode);

描述
设置协议栈的低功耗运行。
返回值
无。
参数
lpm_mode：0，关闭低功耗；1，打开低功耗。
注意
协议栈内部低功耗也会自动降压降频。目前如需协议栈低功耗，需要将pz设为4（系统配置时设置），需要将tx_mode设为0 ！

8.4 设置闹钟

目的
设置闹钟定时，定时触发RTC中断。
语法

void uc_wiota_set_alarm_time(unsigned int sec);

描述
设置闹钟定时，例如定时20秒后，会触发RTC中断，在sleep之前设置，可在sleep之后唤醒系统。
返回值
无。
参数
sec：定时时间，秒
注意

8.5 进入sleep模式

目的
进入sleep模式
语法

void uc_wiota_sleep_enter(unsigned char is_need_ex_wk, unsigned char is_need_32k_div);

描述
系统进入sleep
返回值
无。
参数
is_need_ex_wk：0，不需要外部唤醒源；1，需要外部唤醒源。外部唤醒源一般是指串口，当前硬件，串口悬空是不定态，必须关闭外部唤醒源，即is_need_ex_wk设为0，否则可能无法真正进入sleep
is_need_32k_div：0，不需要降低32K时钟频率；1，需要降低32K时钟频率。
降低32K时钟频率会导致32K定时不准。
注意
不需要关闭协议栈再sleep，可以直接sleep

8.6 开关gating省电模式

目的
开关gating省电模式。（gating暂未支持）
语法

void uc_wiota_set_is_gating(unsigned char is_gating);

描述
设置gating开关标志。
返回值
无。
参数
is_gating：0，关闭gating功能；1，打开gating功能。
注意
该功能在协议栈开启时才有效，需初始化协议栈之后再打开该功能，关闭协议栈则自动关闭gating功能。

8.7 设置中断唤醒源

目的
设置gating省电模式下的中断唤醒源。（gating暂未支持）
语法

void uc_wiota_set_gating_event(unsigned char action, unsigned char event_id);

描述
设置唤醒源。
返回值
无。
参数
action：0，清除该event_id唤醒源；1，设置该event_id唤醒源。
event_id：对应于中断向量表，将某一个中断作为唤醒源，参考代码interrupt_handle.c。
注意
(1) 该接口在协议栈开启时才有效，需初始化协议栈之后再设置。
(2) 不支持修改和配置event_id为0/1/23/24/29的唤醒源，分别为RTC/CCE/UART0/UART1/SYSTIMER。

8.8 paging发送唤醒

目的
唤醒处于paging检测模式下的终端。
发送一段时间的唤醒信号后，发送端会回到正常收发模式中。
语法

void uc_wiota_set_paging_tx_cfg(uc_lpm_tx_cfg_t *config);  
void uc_wiota_get_paging_tx_cfg(uc_lpm_tx_cfg_t *config);
void uc_wiota_paging_tx_start(void);  
void uc_wiota_get_awaken_id_limit(unsigned char symbol_length);

v2.9版本更新，增加tx配置是否成功返回值：

unsigned char uc_wiota_set_paging_tx_cfg(uc_lpm_tx_cfg_t *config);

描述
设置并发送唤醒信号。
返回值
v2.9版本更新，增加tx配置是否成功返回值。
参数
config：配置结构体指针
symbol_length：取值0,1,2,3代表128,256,512,1024
awaken_id：唤醒ID，根据symbol length不同，最大值不同，最大值限制为[41,82,168,339]（可等于，最小值为0，实际可能变化，以代码接口为准），可根据接口获取
send_time：最小值为接收端检测周期（单位ms），如果小于周期，可能无法唤醒
结构体

typedef struct {  
  unsigned char   freq;  // 频点  
  unsigned char   spectrum_idx;  // 频带  
  unsigned char   bandwidth; // 带宽
  unsigned char   symbol_length; 
  unsigned short  awaken_id;  // 指示需要唤醒的ID
  unsigned short  reserved;
  unsigned int    send_time;  // 最小值为接收端检测周期
}uc_lpm_tx_cfg_t;

v2.9版本更新，频点改为2个字节单位：

typedef struct {  
  unsigned char   reserved;
  unsigned char   spectrum_idx;  // 频带  
  unsigned char   bandwidth; // 带宽
  unsigned char   symbol_length; 
  unsigned short  awaken_id;  // 指示需要唤醒的ID
  unsigned short  freq;  // 频点  
  unsigned int    send_time;  // 最小值为接收端检测周期
}uc_lpm_tx_cfg_t;

注意
（1）初始化协议栈之后，如果不设置，则为内部缺省值。
（2）与系统配置类似，如果不想改变默认值，则先get，再修改，最后set。

8.9 paging接收检测

目的
进入paging接收检测模式，降低终端功耗。
语法

void uc_wiota_set_paging_rx_cfg(uc_lpm_rx_cfg_t *config);  
void uc_wiota_get_paging_rx_cfg(uc_lpm_rx_cfg_t *config);  
void uc_wiota_paging_rx_enter(unsigned char is_need_32k_div);

v2.8版本更新，增加rx配置是否成功返回值：

unsigned char uc_wiota_set_paging_rx_cfg(uc_lpm_rx_cfg_t *config);

v2.9版本更新，增加最大次数后强制醒来配置：

void uc_wiota_paging_rx_enter(unsigned char is_need_32k_div, unsigned int timeout_max);

描述
设置唤醒源。
返回值
v2.8版本更新，增加rx配置是否成功返回值。
参数
config：配置结构体指针
is_need_32k_div：0，不需要降低32K时钟频率；1，需要降低32K时钟频率。
降低32K时钟频率会导致32K定时不准。
timeout_max：如果在检测最大次数后仍未检测到信号，也强制醒来，防止时偏过大醒不过来的情况，如果配置为0，则不会强制醒来。（v2.9版本更新）
bandwidth：带宽，暂时只支持200K带宽。
symbol_length：取值0,1,2,3代表128,256,512,1024
threshold：检测门限，3~15，默认值10。增大该值，漏检率增大，虚警率减小。（虚警率即对噪声的敏感程度，漏检率即对唤醒信号的敏感程度）
awaken_id：唤醒ID，根据symbol length不同，最大值不同，当symbol length为[0,1,2,3]时，唤醒ID最大值限制分别为[41,82,168,339]（可等于，最小值为0，实际可能变化，以代码接口为准），可根据接口获取。
detect_period：接收端检测周期（单位ms，最大值44000），每隔该时间，基带会自动单独起来检测一次信号，如果检测到信号，则唤醒整个系统，如果没有则继续sleep，该时间越长，整体功耗越低，相应的发送端想要唤醒接收端时则需要发送更长的时间。
extra_flag：物理层检测到唤醒信号后，自动继续休眠的功能flag配置，设为1则开启该功能。
extra_period：物理层检测到唤醒信号后，自动继续休眠的时长配置，单位ms，如果extra_period 小于等于（detect_period + 10）ms，则继续休眠 detect_period 时长，否则继续休眠 extra_period 时长。(PS: 当前最新版本v3.01及之前版本，extra_period均不能小于等于（detect_period + 10）ms，后续版本会修复)
period_multiple：第二个唤醒的id的检测周期除detect_period的倍数，倍数为0时，不检测第二个唤醒id，倍数为1时，两个id的检测周期一样，以此类推。 v3.02版本新增
awaken_id_another：第二个检测的唤醒id（范围与第一个相同，值不能相同），当period_multiple为非0时有效。 v3.02版本新增
结构体

typedef struct {  
  unsigned char   freq;  // 频点  
  unsigned char   spectrum_idx;  // 频带  
  unsigned char   bandwidth; // 带宽
  unsigned char   symbol_length; 
  unsigned char   lpm_nlen;   // 检测头配置，1,2,3,4，默认值4
  unsigned char   lpm_utimes; // 检测头配置，1,2,3，默认值2
  unsigned char   threshold;  // 3~15, 默认值10
  unsigned char   extra_flag;  // v2.5更新参数，defalut 0, if set 1, last period will use extra_period, then wake up 
  unsigned short  awaken_id;  // 指示需要唤醒的ID
  unsigned short  reserved;
  unsigned int    detect_period;  // 接收端检测周期
  unsigned int    extra_period; // v2.5新增参数，ms, extra new period before wake up 
}uc_lpm_rx_cfg_t;

v2.9版本更新，频点改为2个字节单位：

typedef struct {  
  unsigned char   reserved;
  unsigned char   spectrum_idx;  // 频带  
  unsigned char   bandwidth; // 带宽
  unsigned char   symbol_length; 
  unsigned char   lpm_nlen;   // 检测头配置，1,2,3,4，默认值4
  unsigned char   lpm_utimes; // 检测头配置，1,2,3，默认值2
  unsigned char   threshold;  // 3~15, 默认值10
  unsigned char   extra_flag;  // v2.5更新参数，defalut 0, if set 1, last period will use extra_period, then wake up 
  unsigned short  awaken_id;  // 指示需要唤醒的ID
  unsigned short  freq;  // 频点  
  unsigned int    detect_period;  // 接收端检测周期
  unsigned int    extra_period; // v2.5新增参数，ms, extra new period before wake up 
  // 以下参数为v3.02版本新增  
  unsigned char reserved1;
  unsigned char period_multiple;    // the multiples of detect_period using awaken_id_ano, if 0, no need
  unsigned short awaken_id_another; // another awaken_id
}uc_lpm_rx_cfg_t;

注意
（1）初始化协议栈之后，如果不设置，则为内部缺省值。
（2）与系统配置类似，如果不想改变默认值，则先get，再修改，最后set。
（3）进入paging rx模式前，也可以设置闹钟进行定时唤醒，与进sleep前配置类似。
（4）不能打开外部唤醒寄存器，只能通过拉低spi cs引脚来强制唤醒！

8.10 获取被唤醒原因

目的
获取唤醒前状态和唤醒原因。
语法

unsigned char uc_wiota_get_awakened_cause(unsigned char *is_cs_awakened); // UC_AWAKENED_CAUSE

描述
获取唤醒前状态和唤醒原因。
在系统启动后，main函数里可调用该接口，获取当前系统启动是从什么情况下启动的，可能是之前还在paging或者在sleep，或者是硬件复位，watchdog复位，或者spi cs拉低复位，特别的，如果是spi cs拉低复位，还有is_cs_awakened标志位。
该接口无法判断出在paging下是被rtc时钟唤醒，还是被paging tx信号唤醒，统一为AWAKENED_CAUSE_PAGING。
同样，该接口无法判断出在sleep下是被rtc时钟唤醒，还是被外部唤醒源唤醒，统一为AWAKENED_CAUSE_SLEEP。
返回值

typedef enum
{
  AWAKENED_CAUSE_HARD_RESET = 0,      // also watchdog reset, spi cs reset
  AWAKENED_CAUSE_SLEEP = 1,
  AWAKENED_CAUSE_PAGING = 2,
  AWAKENED_CAUSE_GATING = 3,          // no need care
  AWAKENED_CAUSE_FORCED_INTERNAL = 4, // not use
  AWAKENED_CAUSE_OTHERS,
} uc_awakened_cause_e;

参数
is_cs_awakened：出参（返回值），是否被spi cs唤醒。
注意无。

8.11 获取paging唤醒原因

v2.9版本新增接口。

目的
当使用接口uc_wiota_get_awakened_cause获取原因为AWAKENED_CAUSE_PAGING时，可使用本接口进一步获取paging的唤醒原因。
语法

unsigned char uc_wiota_get_paging_awaken_cause(void); // UC_LPM_PAGING_WAKEN_CAUSE_E  
unsigned char uc_wiota_get_paging_awaken_cause(unsigned int *detected_times); // v3.01版本新增出参，检测次数
unsigned char uc_wiota_get_paging_awaken_cause(unsigned int *detected_times, unsigned char *detect_idx); // v4.0版本新增出参，唤醒id的idx

描述
获取paging的唤醒原因。
在系统启动后，当使用接口uc_wiota_get_awakened_cause获取原因为AWAKENED_CAUSE_PAGING时，可使用本接口进一步获取paging的唤醒原因，
如果为PAGING_WAKEN_CAUSE_NULL：则表示系统之前在paging下，可能是rtc或者spi cs唤醒；
如果为PAGING_WAKEN_CAUSE_PAGING_TIMEOUT，则表示系统之前在paging下，并且没有检测到信号，在达到最大次数后被基带强制唤醒；
如果为PAGING_WAKEN_CAUSE_PAGING_SIGNAL，则表示系统之前在paging下，并且基带检测到唤醒信号后唤醒系统。
其他唤醒类型暂未使用。
返回值

typedef enum
{
    PAGING_WAKEN_CAUSE_NULL = 0,            // not from paging  
    PAGING_WAKEN_CAUSE_PAGING_TIMEOUT = 1,  // from lpm timeout  
    PAGING_WAKEN_CAUSE_PAGING_SIGNAL = 2,   // from lpm signal  
    PAGING_WAKEN_CAUSE_SYNC_PG_TIMEOUT = 3, // not use in async, from sync paging timeout  
    PAGING_WAKEN_CAUSE_SYNC_PG_SIGNAL = 4,  // not use in async, from sync paging signal  
    PAGING_WAKEN_CAUSE_SYNC_PG_TIMING = 5,  // not use in async, from sync paging timing set   
    PAGING_WAKEN_CAUSE_MAX,  
} uc_lpm_paging_waken_cause_e;

参数
detected_times：v3.01版本新增返回参数，出参（返回值），用于获取当前被唤醒时的检测次数。
detect_idx：v4.0版本新增出参，唤醒id的idx，0或者1。
注意
无

8.12 设置外部唤醒

v3.00新增接口。

目的
在进入sleep或者paging rx之前，设置外部唤醒。
外部唤醒源一般是指串口，当前硬件，串口悬空是不定态，必须关闭外部唤醒源，否则可能无法真正进入sleep
语法

void uc_wiota_set_is_ex_wk(unsigned char is_need_ex_wk);

描述
单独配置是否支持外部唤醒源。
返回值
无。
参数
is_need_ex_wk：0，不需要外部唤醒源；1，需要外部唤醒源。
注意 paging rx模式下不能打开外部唤醒寄存器，只能通过拉低spi cs引脚来强制唤醒！

9. 帧结构相关

9.1 设置发送时的子帧数

目的
设置发送时的每帧的子帧数。
语法

void uc_wiota_set_subframe_num(unsigned char subframe_num);

v2.9版本更新，增加是否配置成功结果：

unsigned char uc_wiota_set_subframe_num(unsigned char subframe_num);

描述
设置每帧的子帧数，可根据数据量适当选择，目前默认为8。
返回值
无。
参数
subframe_num：子帧数，范围3~10，目前不支持1~2，推荐设置为4~8
注意
不同终端可不相同，接收方会根据接收到的首包数据获取到发送方的帧结构，进行后续接收流程，应用可暂不关注接收方的接收过程。
协议栈初始化之后就可以设置，如果需要变化，在每次发送数据前均可以再设置。

9.2 获取发送时的子帧数

目的
获取发送时的子帧数
语法

unsigned char uc_wiota_get_subframe_num(void);

描述
子帧数
返回值
子帧数，范围3~9
参数
无
注意
无

9.3 获取子帧长度

目的
获取子帧长度
语法

unsigned int uc_wiota_get_subframe_len(void);

描述
子帧长度在200K带宽下的表如下：

bandwidth	symbol_length	subframe length (ms)
200K	0	4
200K	1	8
200K	2	16
200K	3	32

100K带宽时，子帧长度为200K时的2倍，50K，25K，依次类推，继续翻倍。例如25K，symbol length 1024时，子帧长度为32*8=256ms

返回值
子帧长度，ms
参数
无
注意
100K带宽时，子帧长度为200K时的2倍，50K，25K，依次类推，继续翻倍。
当前系统配置下的子帧长度。

9.4 获取帧长

目的
获取当前配置下的帧长
语法

unsigned int uc_wiota_get_frame_len(unsigned char type);
unsigned int uc_wiota_get_frame_len_us(unsigned char type); // v4.0版本新增，返回值单位为us

描述 200K带宽时的对应部分帧长表格如下（由于内部基带参数变化，下图不一定准确，以实际代码返回值为准！）

subframe_num	symbol_length	uni_frameLen(ms)	bc_frameLen(ms)
3	0	28	22
4	0	32	27
5	0	36	31
3	1	56	45
4	1	64	53
5	1	72	61
3	2	112	90
4	2	129	106
5	2	145	123
3	3	225	180
4	3	258	213
5	3	291	246

100K带宽时，帧长为200K时的2倍，50K，25K，依次类推，继续翻倍。

返回值
帧长，ms
参数
type：0，广播帧长，1，单播帧长
注意
100K带宽时，帧长为200K时的2倍，50K，25K，依次类推，继续翻倍！
当前系统配置下的帧长。

9.5 根据配置获取帧长

v2.9版本新增接口。

目的
获取帧长
语法

unsigned int uc_wiota_get_frame_len_with_params(unsigned char symbol_len, unsigned char symbol_mode, unsigned char subf_num, unsigned char band_width, unsigned char suf_mode);

描述无
返回值
帧长，ms
参数
symbol_len：symbol length，详见系统配置参数
symbol_mode：symbol模式，默认填0即可，仅在小带宽模式支持
subf_num：子帧数量
band_width：带宽
suf_mode：是否按子帧发送模式，默认填0即可
注意
100K带宽时，帧长为200K时的2倍，50K，25K，依次类推，继续翻倍！
当前传入配置参数下的帧长。

9.6 获取单个子帧承载数据长度

目的
获取单个子帧承载数据长度
语法

unsigned short uc_wiota_get_subframe_data_len(unsigned char mcs, unsigned char is_bc, unsigned char is_first);   
// v4.0版本更新接口如下：
unsigned short uc_wiota_get_subframe_data_len(unsigned char mcs, unsigned char is_bc, unsigned char is_first_sub, unsigned char is_first_fn);

描述
BT_0.3时在不同symbol length和不同MCS时，对应每包(即每个数据子帧)传输的广播应用数据量（byte），单播时的每个包比下表少1个字节（V4.0版本单播每个数据子帧跟广播一样）。

symbol length	mcs0	mcs1	mcs2	mcs3	mcs4	mcs5	mcs6	mcs7
128	7	9	52	66	80	不支持	不支持	不支持
256	7	15	22	52	108	157	192	不支持
512	7	15	31	42	73	136	255	297
1024	7	15	31	63	108	220	451	619

返回值
单个子帧承载数据长度，byte（字节），返回0表示不支持。
参数
mcs：范围0~7
is_bc：0，单播，1，广播
is_first（is_first_sub，v4.0更换名字）：是否第一个子帧，第一个子帧有协议栈的控制信息，能够承载的应用数据量与其他子帧不同。
is_first_fn：是否第一帧，单播第一帧的第一个子帧，和后续帧的第一个子帧，所能承载的应用数据不同。（V4.0版本新增参数）

typedef enum {  
  UC_MCS_LEVEL_0 = 0,   
  UC_MCS_LEVEL_1,   
  UC_MCS_LEVEL_2,   
  UC_MCS_LEVEL_3,
  UC_MCS_LEVEL_4,
  UC_MCS_LEVEL_5,
  UC_MCS_LEVEL_6,
  UC_MCS_LEVEL_7,
  UC_MCS_AUTO = 8,
}UC_MCS_LEVEL;

注意
当前系统配置下的子帧承载能力。

9.7 计算匹配的子帧数

v3.02新增接口。

目的
根据当前数据量和mcs计算匹配的子帧数的接口。
WIoTa异步针对发送不同数据长度设置不同子帧数，可以有效提高发送效率，减少发送占用时间，降低工作功耗。
语法

unsigned char uc_wiota_calc_suitable_subframe_num(unsigned char type, unsigned short data_len);

描述
子帧数越多，一帧的数据量越多，子帧数限制为3~10个子帧，正常的传输建议是尽量满帧传输，使得传输效率最高。该接口可计算出合适的子帧数，使得最后一帧的子帧都尽量能够都传输数据。
异步WIoTa帧结构体中，1帧有3-10个子帧，除第一个子帧后面每个子帧发送数据长度一致。但是每帧的第一个子帧被WIoTa协议占用了部分负载数据，而且广播和单播第一个子帧应用可用负载长度不一样。同时WIoTa子帧的负载能力还跟MCS配置有一定关系，MCS越大单个子帧的负载能力越强。

根据上述理论步骤如下：
根据广播或者单播调用协议栈接口获取每个子帧负载和第一个子帧负载；
通过发送数据长度，匹配需要发送的帧数，在根据每帧的负载数据长度计算出最优子帧配置。

返回值
匹配的子帧数。从该接口获取计算出来的子帧数后，需要调用 uc_wiota_set_subframe_num 配置子帧数。
参数
type： 0：单播，1：广播
data_len：应用数据总长。（不需要包含CRC，接口中会根据数据量自动判断是否需要CRC）
注意
当前系统配置下的子帧承载能力。

10. 数据收发

10.1 设置数据传输速率

目的
根据应用需求设置数据传输速率。
语法

void uc_wiota_set_data_rate(unsigned char rate_mode, unsigned short rate_value);  
uc_uni_ack_mode_e uc_wiota_get_uni_ack_mode(void); // v4.0版本新增

描述
设置最大速率模式和级别，与枚举UC_DATA_RATE_MODE里对应。
除了基本模式，其余均为V4.0版本新增模式。
(1) 第一种基本模式 UC_RATE_NORMAL，是基本速率设置，有9档mcs速率级别（包括自动mcs），详见UC_MCS_LEVEL，默认为UC_MCS_LEVEL_0，设置非自动mcs时同时关闭自动速率匹配功能。暂未支持自动MCS功能!
(2) 第二种CRC模式 UC_RATE_CRC_TYPE，可增加高阶mcs的子帧数据量（增加3 bytes），
128/0/1（该形式表示symbollength 128下的mcs0和mcs1）,
256/0/1/2,
512/0/1/2/3,
1024/0/1/2/3，均为低阶mcs，以下为高阶mcs： 128/2/3/4,
256/3/4/5/6,
512/4/5/6/7,
1024/4/5/6/7,

默认低阶mcs的基带crc为1字节，高阶mcs的基带crc为4字节，打开CRC模式后，高阶mcs的基带crc也配置为1字节，所以此配置下可以额外提供给应用3字节的数据空间。

(3) 第三种单播ACK模式 UC_RATE_UNI_ACK_MODE，其枚举值为uc_uni_ack_mode_e，0、1、2分别代表单播无ack，单播每帧有ack，单播只有最后一帧有ack（这种情况暂未支持）。可使用接口uc_wiota_get_uni_ack_mode获取当前单播ACK模式。
(4) 第四种控制子帧MCS模式 UC_RATE_FIRST_MCS_MODE，其枚举值为uc_first_mcs_mode_e，默认为0，表示控制子帧固定使用mcs0，设为1时，使用根据配置的基本MCS计算的mcs作为控制子帧的mcs，通常是数字子帧的mcs减1。
(5) 第五种GAP模式 UC_RATE_PRM_GAP_MODE，其枚举值为uc_prm_gap_mode_e，v4.0新版本默认为0，表示帧头和子帧之间没有gap，整体缩短了帧长，提高了传输效率，但是新的帧结构不能与老版本通信，如果需要与V4.0之前版本通信，需要将gap模式设置为1。
(6) 第六种旧版本单播模式 UC_RATE_OLD_UNI_MODE，默认为0，表示v4.0新版本对于单播组包做了优化，相同mcs配置能够容纳更多应用数据，但是不能与老版本通信，如果需要与V4.0之前版本通信，需要将旧版本单播模式设为1。
返回值
无。
参数
rate_mode：枚举UC_DATA_RATE_MODE。
rate_value：对应不同模式有不同的意义，详见上面的描述部分。

typedef enum
{
  UC_RATE_NORMAL = 0,
  UC_RATE_CRC_TYPE = 1,       // 0, normal mode, 1, only one byte crc
  UC_RATE_UNI_ACK_MODE = 2,   // uc_uni_ack_mode_e
  UC_RATE_FIRST_MCS_MODE = 3, // default 0, first bc mcs is 0, 1: calc access mcs
  UC_RATE_PRM_GAP_MODE = 4,   // uc_prm_gap_mode_e
  UC_RATE_OLD_UNI_MODE = 5,   // 1: old mode, default 0: new mode
  UC_RATE_OTHER,
} uc_data_rate_mode_e;  

typedef enum
{
  FIRST_MCS_FIX0 = 0, // fix to 0
  FIRST_MCS_FLEX = 1, // calc by mcs set
  FIRST_MCS_UNVALID,
} uc_first_mcs_mode_e;  

typedef enum
{
  UNI_ACK_NONE = 0,  // every uni frame has no ack
  UNI_ACK_EVERY = 1, // every uni frame has ack
  UNI_ACK_LAST = 2,  // only last frame has ack
  UNI_ACK_UNVALID,
} uc_uni_ack_mode_e;  

typedef enum
{
  PRM_GAP_NONE = 0,
  PRM_GAP_HAS = 1,
  PRM_GAP_UNVALID,
} uc_prm_gap_mode_e;

初始化协议栈时默认位MCS0，调用该接口入参为0~7时，设置最大速率级别，同时关闭自动速率匹配功能，再次调用该接口入参为UC_MCS_AUTO（或者不是0~7）时，会打开自动速率匹配功能（暂不支持自动速率功能！）。
目前每帧第一个子帧有特殊用途，固定为MCS0，并且会占用相应的控制包长度，广播数据不会放在该子帧，单播数据会有2~3个字节的应用数据空间，建议计算每帧数据量时，以实际接口返回值为准。

举例：系统配置中symbol_length为1，默认下行子帧数为8，则 frameLen为 97 ms

在此帧结构配置情况下，如果选择MCS2，则应用数据速率为 7*20/0.099616 = 1,405 bps
(计算数据速率时，一般可以不考虑第一个包)。

注意
（1）一味提高速率，可能导致传输始终无法成功。
（2）发送单播和发送广播时的帧长不同，接收侧会根据接收到的数据自动调整对应的帧结构。
（3）协议栈初始化之后就可以设置，如果需要变化，在每次发送数据前均可以再设置。
（4） V4.0版本需要与之前版本通信时，必须将UC_RATE_PRM_GAP_MODE设为1，将UC_RATE_OLD_UNI_MODE设为1！

10.2 发送数据

目的
发送数据给其他节点
语法

c uc_op_result_e uc_wiota_send_data(unsigned int user_id, unsigned char* data, unsigned short len, unsigned char* bcHead, unsigned char headLen, unsigned int timeout, uc_send callback); unsigned char uc_wiota_set_data_limit(unsigned char mode, unsigned short limit); // v4.0版本新增接口 unsigned short uc_wiota_get_data_limit(unsigned char mode); // v4.0版本新增接口

描述
发送数据，等待返回结果，提供两种模式。
如果回调函数不为NULL，则非阻塞模式，成功发送数据或者超时后会调用callback返回结果。
如果回调函数为NULL，则为阻塞模式，成功发送数据或者超时该函数才会返回结果。
返回值
阻塞模式时该返回值有效。

typedef enum {  
  UC_OP_SUCC = 0,  
  UC_OP_TIMEOUT,  
  UC_OP_FAIL,  
  UC_OP_PART_SUCC,    // 目前仅用于接收结果
  UC_OP_CRC_FAIL,        // 目前仅用于接收结果
  UC_OP_QUEUE_FULL,   // 发送缓存队列目前为2，如果超出会直接返回队列满的结果
}uc_op_result_e;

参数
user_id: 目标用户ID，如果是0，则为广播数据发送
data：需要传输的数据的头指针。
len：数据长度，单播数据最长默认为310字节，广播数据最长默认为1021字节，均为不算CRC的长度，可是用接口uc_wiota_set_data_limit进行修改。
bcHead：额外的控制广播头信息的指针。
headLen：目前最大为2，如果不需要则填0，并且bcHead为NULL。
callback：回调函数，非阻塞时处理返回结果。
timeout：超时时间，单位ms，v2.0版本是unsigned short，之后版本是unsigned int，范围不一样了。
uc_wiota_set_data_limit 的参数：
mode： 0，广播，1，单播。
limit：数据最大长度，可分别设置广播数据最大长度和单播数据最大长度。广播最大1021，单播最大1021。
结构体

typedef struct {  
  unsigned int    result;  
  unsigned char*  oriPtr; 
}uc_send_back_t,*uc_send_back_p;  

typedef void (*uc_send)(uc_send_back_p send_result);

result：返回结果，UC_OP_RESULT。
oriPtr：返回原数据的地址，方便应用确认对应数据。

注意（1）在收到返回结果之前不能释放data内存，并且需要预留2字节的空间给底层CRC使用，比如数据len为101，则申请data_buffer大小为103，可参考at_wiotasend_setup的代码实现。
（2）不能在callback函数里释放内存。
（3）数据长度超过限制将直接返回失败。如果应用层需要传超过限制的数据量，建议自己先分包。
（4）由于底层空间限制，只能存两条应用数据，所以该函数不支持连续调用3次，否则会直接返回UC_OP_QUEUE_FULL
（5） bcHead，接收端是否需要处理广播控制头的数据，需要应用自己判断，即使发送方send接口未填，底层也会上报随机数。
（6）返回结果并不代表基带已经传输完成，需要使用接口uc_wiota_get_state查询协议栈状态，如果是SENDING状态则需要继续等待3个子帧长度的时间，才能关闭协议栈或者系统sleep。

10.3 被动接收数据接口注册

目的
被动接收数据。
语法

void uc_wiota_register_recv_data_callback(uc_recv callback,uc_callback_data_type_e type);

描述
注册一个接收数据的被动回调函数，只需要系统启动后注册一次即可，每当iote收到数据结果（包括广播、单播、扫频结果、加速数据结果）时，会调用该回调函数上报数据。
注册一个接收协议栈状态信息的回调函数，只需要系统启动后注册一次即可，每当iote收到状态结果（包括物理层重启、同步状态）时，会调用该回调函数上报数据。
返回值
无。
参数
回调函数用于接收数据结果。

结构体

#define PARTIAL_FAIL_NUM 8
#define UC_USER_HEAD_SIZE 2

typedef struct {
  unsigned char result; // UC_OP_RESULT
  unsigned char type; // UC_RECV_DATA_TYPE
  unsigned short data_len;
  unsigned char rssi; // absolute value, 1~150, means -1 ~ -150
  char snr;
  char sender_pow; // the power of sender, only effective when UC_RECV_MSG
  unsigned char headRight; // indicate if head is right
  unsigned char headData[UC_USER_HEAD_SIZE]; // if sender do not send head info,  rv will also report random data.
  unsigned char *data; // if result is UC_OP_SUCC or UC_OP_PART_SUCC, data is not null, need free
  unsigned short packet_size; // indicate packet size
  unsigned char fail_idx[PARTIAL_FAIL_NUM]; // packet number 1 ~ 255, if 0, means no packet fail, like 1,2,0,0... means only packet 1 and 2 is fail.
  unsigned int cur_rf_cnt; // （V2.8新增参数）algined by subframe struct
} uc_recv_back_t, *uc_recv_back_p;

typedef enum {  
  UC_RECV_MSG = 0,   // UC_CALLBACK_NORAMAL_MSG, unicast
  UC_RECV_BC,        // UC_CALLBACK_NORAMAL_MSG, broadcast
  UC_RECV_SCAN_FREQ, // UC_CALLBACK_NORAMAL_MSG, result of scan freq
  UC_RECV_PHY_RESET, // UC_CALLBACK_STATE_INFO, if physical level reset, report to app
  UC_RECV_SYNC_STATE,// UC_CALLBACK_STATE_INFO, （V2.8新增参数）when subf recv mode, if sync succ, report UC_OP_SUCC, if track fail, report UC_OP_FAIL  
  UC_RECV_ACC_DATA,  // UC_CALLBACK_NORAMAL_MSG, （V2.8新增参数）acc voice data   
  UC_RECV_SAVE_STATIC_DONE, // UC_CALLBACK_STATE_INFO, （V4.0新增参数）save static done when run
  UC_RECV_MAX_TYPE,  
}uc_recv_data_type_e;  

typedef enum {  
  UC_OP_SUCC = 0,  
  UC_OP_TIMEOUT,  
  UC_OP_FAIL,  
  UC_OP_PART_SUCC,
  UC_OP_CRC_FAIL,
  UC_OP_QUEUE_FULL,
}uc_op_result_e;  

typedef enum {  
  UC_CALLBACK_NORMAL_MSG = 0,   
  UC_CALLBACK_STATE_INFO,    // state info, only report UC_RECV_PHY_RESET
}uc_callback_data_type_e;  // use in uc_wiota_register_recv_data_callback's para

typedef void (*uc_recv)(uc_recv_back_p recv_data);

结构体解释

result：返回结果
type：返回类型，单播或者广播
data_len：数据总长度
rssi：信号质量，范围 -1 ~ -130，目前还不太准
snr：信噪比，范围-13 ~ 27，目前还不太准
sender_pow：发送方的功率，范围-16 ~ 21dbm(V2.9版本更新为 -18 ~ 22 dbm)，可强转为char类型后使用
headRight：指示headData是否正确，如果不正确，上报的是上次正确的内存
headData[UC_USER_HEAD_SIZE]：应用需要自己明确发送方是否有该数据，即使没有数据，底层也会上报随机数
data：数据指针，如果是有效数据则需要应用释放内存
packet_size：非全接收时的每个广播包的数据长度
fail_idx[PARTIAL_FAIL_NUM]：非全接收时，错误包的序号，范围1~255，如果是0则表示结束
cur_rf_cnt：收到数据时的rf counter值，该值与接收帧结构的子帧边界对齐，应用可使用其来对齐所有终端时刻（V2.8新增参数）

注意
在协议栈启动之后调用。

10.4 设置CRC校验开关

目的
设置CRC校验开关。
语法

void uc_wiota_set_crc(unsigned short crc_limit);

描述
开关协议层的CRC，并设置校验长度的标准。
如果crc_limit为0，表示关闭CRC校验功能。
如果crc_limit大于0，表示数据长度大于等于crc_limit时，才打开CRC校验功能，所以crc_limit设置为1，则可表示任意长度的数据均加CRC。
返回值
无。
参数
crc_limit：校验长度限制。
注意
各节点的crc_limit设置需要一致！默认值为100。
在初始化之后均可配置。

10.5 设置发送广播的轮数

目的
设置发送广播的轮数。
语法

void uc_wiota_set_bc_round(unsigned char bc_round);

描述
设置广播数据在物理层重复发送的轮数，因为广播没有反馈机制，目前默认重复发3轮数据，因为需要比较数据，所以广播也不支持自动调整MCS策略。
返回值
无。
参数
bc_round：广播重复轮数，大于1，小于8，默认3，尽量不要太大，建议2~4
注意
协议栈初始化之后，每次发送数据之前均可修改

10.6 设置发送前检测等待时间

目的
设置发送前检测等待时间。
语法

void uc_wiota_set_detect_time(unsigned int detect_time);

描述
为了避免冲突，发送数据前，物理层会先检测一段时间帧头，在没有收到其他终端数据的情况下，再发送数据。
返回值
无。
参数
detect_time：检测时间，单位ms，默认时间为两倍当前配置下最大的单播帧长。
注意
协议栈初始化之后均可修改

10.7 设置连续发送模式

目的
设置连续发送，维持帧结构不断
语法

void uc_wiota_set_continue_send(unsigned char c_send_flag);

描述
为语音或者其他需要连续传输很多个应用数据包设计，打开连续传输模式时，发送帧结构会一直维持，直到关闭该模式。该模式时，只能发送一种数据，广播或者单播，不能混发广播和单播。该模式时，也不会去接收数据。
返回值
无。
参数
c_send_flag：0，关闭，1，打开
注意
默认关闭
协议栈初始化之后，不需要每次发送数据之前设置，在大量数据发送前设置打开，在所有数据发送完之后关闭即可。

10.8 设置非全接收广播数据模式

目的
将底层错误包也整合上报给应用，让应用来判断是否需要
语法

void uc_wiota_set_incomplete_recv(unsigned char recv_flag);

描述
为语音或者其他需要错误包的应用设计，底层会把应用数据继续拆包进行发送，如果个别包错误，也会进行解析并整合成完整的应用数据包发给应用。
此时接收数据的结构体 uc_recv_back_t 中会填写具体的错误包序号，返回类型为UC_OP_PART_SUCC或者UC_OP_CRC_FAIL
返回值
无。
参数
recv_flag：0，关闭，1，打开
注意
默认关闭，由接收端设置！

10.9 设置自动接收检测控制

目的
设置自动接收检测控制
语法

void uc_wiota_set_recv_mode(uc_auto_recv_mode_e mode);

描述
协议栈启动后，默认会自动检测接收，如果设置该接口关闭，则进入空闲态。
返回值
无。
参数

typedef enum
{
  UC_AUTO_RECV_START = 0, // default
  UC_AUTO_RECV_STOP = 1,
  UC_AUTO_RECV_ERROR,
} uc_auto_recv_mode_e;

注意
默认值是0，即开启自动检测接收
协议栈初始化之后可以设置。

10.10 指定帧头时刻发送数据

目的
指定帧头时刻发送数据，以达到精确控制发送时刻的目的。
语法

uc_op_result_e uc_wiota_send_data_with_start_time(unsigned int userId, unsigned char *data, unsigned short len, unsigned char *bcHead, unsigned char headLen, unsigned int timeout, uc_send callback, unsigned int start_time);
unsigned int uc_wiota_get_curr_rf_cnt(void);

描述
发送数据部分与uc_wiota_send_data几乎一致，可参考该接口，区别在于增加了指定帧头的配置，即由应用配置发送时间点（start_time），该时间点必须比当前时间点提前量范围在3个子帧时长到1秒，如超过1秒，可使用定时器定时到临近时间点再开始调用接口发送数据，当前时间点可使用接口uc_wiota_get_curr_rf_cnt获取，获取的32bit的无符号值为射频计数器的计数值，单位是微妙（us），在初始化协议栈或者关闭协议栈时，该计数器会重置。
此接口的应用示例（1）：当终端要求严格间隔1秒发送一次数据，可使用该接口保证，每次发送的数据的起始帧头间隔1秒。
此接口的应用示例（2）：与接收数据上报的cur_rf_cnt配合使用，2个终端（终端A和B）接收同一个发送方（终端C）发送的广播时，收到该广播数据的cur_rf_cnt在物理时间上是相同时刻（并不是cur_rf_cnt的值相同），终端A以此时间间隔1秒发送广播给终端C，终端B以此间隔2秒发送相同广播内容（帧配置也相同），则终端C收到两条广播的间隔也精确为1秒（误差在3us左右）。
返回值
无。
参数
start_time：发送
注意
协议栈初始化之后可以设置。

10.11 设置单播连续失败次数限制

目的
设置单播连续失败次数限制，也可以理解为一帧数据的传输总次数，最小值为1，默认值为2。
语法

void uc_wiota_set_unisend_fail_cnt(unsigned char cnt);

描述
设置单播数据传输尝试总次数，终端发送单播数据在每帧结尾会接收ack，默认连续两次没收到ack，就会认为发送失败。
返回值
无。
参数
cnt：连续失败次数限制
注意
默认值是2
协议栈初始化之后可以设置。注意是传输总次数，最小值为1

10.12 单播ack信息bit传输功能配置

v3.02新增接口

目的
设置单播ack信息bit，ack中有1bit可用于立即回传通知发送方，但是接收方需要预配置。
语法

typedef struct
{
  unsigned char is_ack_info;  // if 1, use ack 1bit to trans info, need set same value both sides
  unsigned char is_same_info; // if 1, all recv id use same ack info, if 0, use ack_list
  unsigned char same_info;    // 0 or 1, if use this, below are not used
  unsigned char list_num;     // list num of id_list and ack_list
  unsigned short start_byte;  // protocol will get id from app data, need to know which byte to get from
  unsigned char id_len;       // id len in app data
  unsigned char reserved;     // 4 bytes align
  unsigned int *id_list;      // ptr malloc/free by app, if null, set same_info, defaul int, may not use full 4bytes
  unsigned char *ack_list;    // ptr malloc/free by app, if null, set same_info
} uc_uni_ack_info_t, *uc_uni_ack_info_p;  

void uc_wiota_get_uni_ack_info(uc_uni_ack_info_p uni_ack_info_ptr);  
void uc_wiota_set_uni_ack_info(uc_uni_ack_info_p uni_ack_info_ptr);

描述
设置单播ack信息bit，ack中有1bit可用于立即回传通知发送方，但是接收方需要预配置。
返回值
无。
参数
is_ack_info：是否开启该功能，两端需要对应配置，不能一边不开启一边开启
is_same_info：接收侧是否使用相同信息（sam_info）去填充ack信息bit
same_info：相同信息bit，0或者1
list_num：列表长度，如果为0，则使用same_info
start_byte：从接收数据中去取得id的起始字节
id_len：从接收数据中去取得id的长度
reserved：对齐位
id_list：id列表，每个id需为4字节长度（即最大长度），可不用满4字节，范围1~4字节。该列表可为全局变量或者malloc出来的指针，由应用自行管理，注意不可越界。当id_list为NULL时，使用same_info
ack_list：ack信息列表，与id_list一一对应，列表也由应用自行管理，当ack_list为NULL时，使用same_info
注意
任意时间可以设置，运行时配置会停止当前收发过程。
两端需要对应配置是否开启该功能。

10.13 主动接收数据

目的
主动接收数据，超时返回失败。

语法

void uc_wiota_recv_data(uc_recv_back_p recv_result, unsigned short timeout, unsigned int userId, uc_recv callback);

描述
如果回调函数不为NULL，则非阻塞模式，成功收到数据或者超时后会调用callback返回数据和结果。
如果回调函数为NULL，则为阻塞模式，成功收到数据或者超时该函数才会返回数据结果。
该回调函数与被动接收的回调注册函数不冲突，应用可根据自身需求设置。
返回值
recv_result:阻塞模式时，返回的结果。
参数
timeout：超时时间，单位ms。
callback：回调函数，非阻塞时处理返回结果。
userId：向目的userid主要请求数据，v4.0新增，但暂未支持。
结构体
参见上述接口。
注意该接口相当于提供了一个定时器来在限定时间内接收数据。

11. 调试相关

11.1 设置WIoTa log开关

目的
设置协议层的log开关。
语法

void uc_wiota_log_switch(unsigned char log_type, unsigned char is_open);   
typedef enum {  
  UC_LOG_UART = 0,  
  UC_LOG_SPI,  
}uc_log_type_e;

描述
开关协议层的log，包括uart和spi两种。
返回值
无。
参数
log_type：uart和spi两种。
is_open：是否开启该log。
结构体
参见上述接口。

11.2 WIoTa统计信息获取

目的
获取WIoTa的统计信息。
语法

unsigned int uc_wiota_get_stats(unsigned char type);   
void uc_wiota_get_all_stats(uc_stats_info_p stats_info_ptr);  
void uc_wiota_reset_stats(unsigned char type);   
void uc_wiota_reset_throughput(unsigned char type);
void uc_wiota_get_throughput(uc_throughput_info_t *throughput_info);

描述
获取/重置/增加某个/所有统计信息的计数。
返回值
uc_wiota_get_stats：返回对应type的统计计数。
stats_info_ptr：本地统计信息表，用来获取所有统计信息。
参数
type：uc_stats_type_e，与uc_stats_info_t的参数一一对应。
注意，在uc_wiota_get_stats中type为0，则返回无效值0。
结构体

typedef enum
{
    UC_STATS_TYPE_ALL = 0,
    UC_STATS_UNI_SEND_TOTAL,
    UC_STATS_UNI_SEND_SUCC,
    UC_STATS_BC_SEND_TOTAL,
    UC_STATS_BC_SEND_SUCC,
    UC_STATS_UNI_RECV_FAIL,
    UC_STATS_UNI_RECV_SUCC,
    UC_STATS_BC_RECV_FAIL,
    UC_STATS_BC_RECV_SUCC,
    UC_STATS_TYPE_MAX,
} uc_stats_type_e; 

typedef struct
{
  unsigned int uni_send_total;
  unsigned int uni_send_succ;
  unsigned int bc_send_total; // not use, is same as bc_send_succ
  unsigned int bc_send_succ;
  unsigned int uni_recv_fail;
  unsigned int uni_recv_succ;
  unsigned int bc_recv_fail;
  unsigned int bc_recv_succ;
} uc_stats_info_t, *uc_stats_info_p; 

typedef enum {  
  UC_STATS_READ = 0,  
  UC_STATS_WRITE,     
}uc_stats_mode_e;    

typedef struct
{
  unsigned int uni_send_succ_data_len;
  unsigned int bc_send_succ_data_len;
  unsigned int uni_recv_succ_data_len;
  unsigned int bc_recv_succ_data_len;
} uc_throughput_info_t, *uc_throughput_info_p;

注意
无

11.3 设置指示灯开关

目的
开关指示灯，在二次开发版本中，可关闭指示灯，即停止协议栈对相应GPIO（2/3/7/16/17）的操作，避免冲突。
语法

void uc_wiota_light_func_enable(unsigned char func_enable);

描述
开启或关闭协议栈运行状态及上下行数据的指示灯，默认关闭。
返回值
无。
参数
func_enable：开关指示灯功能。
注意

subframe_num	symbol_length	uni_frameLen(ms)	bc_frameLen(ms)
3	0	28	22
4	0	32	27
5	0	36	31
3	1	56	45
4	1	64	53
5	1	72	61
3	2	112	90
4	2	129	106
5	2	145	123
3	3	225	180
4	3	258	213
5	3	291	246

subframe_num	symbol_length	uni_frameLen(ms)	bc_frameLen(ms)
3	0	28	22
4	0	32	27
5	0	36	31
3	1	56	45
4	1	64	53
5	1	72	61
3	2	112	90
4	2	129	106
5	2	145	123
3	3	225	180
4	3	258	213
5	3	291	246

subframe_num	symbol_length	uni_frameLen(ms)	bc_frameLen(ms)
3	0	28	22
4	0	32	27
5	0	36	31
3	1	56	45
4	1	64	53
5	1	72	61
3	2	112	90
4	2	129	106
5	2	145	123
3	3	225	180
4	3	258	213
5	3	291	246