WIOTA AP API
AP应用接口文档
前言说明:
1)AP_8288只提供镜像文件。
库接口说明
以下接口全声明在“uc_wiota_api.h”文件中。
1. 初始化WIoTa
-
目的
WIoTa协议栈初始化。 -
语法
void uc_wiota_init(void);
-
描述
初始化WIoTa协议栈资源,比如:线程,内存等。 -
返回值
无。 -
参数
无。
2. 启动WIoTa
-
目的
启动WIoTa协议栈。 -
语法
void uc_wiota_run(void);
-
描述
启动WIoTa协议栈,并启动基带。 -
返回值
无。 -
参数
无。
3. 关闭WIoTa
-
目的
关闭WIoTa协议栈,基带也将停止。 -
语法
void uc_wiota_exit(void);
-
描述
关闭WIoTa协议栈,回收所有WIoTa协议栈资源。 -
返回值
无。 -
参数
无。
4. 获取WIoTa库版本信息
-
目的
获取当前WIoTa版本信息和构建时间。 -
语法
void uc_wiota_get_version(unsigned char *wiota_version_8088,
unsigned char *git_info_8088,
unsigned char *make_time_8088
unsigned char *wiota_version_8288,
unsigned char *git_info_8288,
unsigned char *make_time_8288
unsigned int *cce_version);
-
描述
获取WIoTa版本信息和构建时间,包括AP和基带的版本信息,需自行开辟空间或使用数组接收出参,wiota_version大于等于15个字节,git_info大于等于36个字节,make_time大于等于36个字节, cce_version 4个字节。
注意:如果未启动WIoTa协议栈(2. 启动WIoTa)调用该接口只能得到UC8088的版本信息,要得到UC8288和CCE的版本信息必须先启动WIoTa协议栈。 -
返回值
无。 -
参数
wiota_version_8088 //当前UC8088 WIoTa库版本号
git_info_8088 //当前UC8088 WIoTa库版本git信息
make_time_8088 //当前UC8088 WIoTa库版本构建时间
wiota_version_8288 //当前UC8288 WIoTa库版本号
git_info_8288 //当前UC8288 WIoTa库版本git信息
make_time_8288 //当前UC8288 WIoTa库版本构建时间
cce_version //当前CCE版本号
5. 配置系统参数
5.1 获取系统配置
-
目的
获取系统配置 。 -
语法
void uc_wiota_get_system_config(sub_system_config_t *config);
-
描述
获取系统配置。 -
返回值
无。 -
参数
config //结构体指针
- 参数类型
typedef struct
{
unsigned char ap_max_pow;
unsigned char id_len;
unsigned char pp;
unsigned char symbol_length;
unsigned char dlul_ratio;
unsigned char bt_value;
unsigned char group_number;
unsigned char spectrum_idx;
unsigned char old_subsys_v;
unsigned char bitscb;
unsigned char freq_idx; // v2.7版本将频点加入系统配置中
unsigned char reserved;
unsigned int system_id; // v2.5版本之后无改参数
unsigned int subsystem_id; // v2.9版本之后,子系统id的高12bit将固定为mask,用户设置之后也将被强行替换
}sub_system_config_t;
参数类型描述:
- ap_max_pow:AP最大发射功率,默认22dbm. 范围 0 - 29 dbm。
- 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。
- dlul_ratio:帧配置,该值代表一帧里面上下行的比例,取值0,1代表1:1和1:2。
- bt_value:该值和调制信号的滤波器带宽对应,BT越大,信号带宽越大,取值0,1代表BT配置为1.2和BT配置为0.3,bt_value为0时,代表使用的是低阶mcs组,即低码率传输组。bt_value为1时,代表使用的是高mcs组,即高码率传输组。
- group_number:帧配置,取值0,1,2,3代表一帧里包含1,2,4,8个上行group数量。
- spectrum_idx:频谱序列号,默认为3,即470-510M(具体见下图)。
- old_subsys_v:匹配老版本iote(v2.3及之前的版本)标志位,默认值为0,表示不匹配老版本,如果需要匹配老版本,将该值设为1。
- freq_idx:频点配置,默认值160,v2.7版本将频点加入系统配置。
- bitscb:比特加扰标志位,默认值为1,表示开启比特加扰,为0表示关闭比特加扰。
- system_id:系统id,预留值,必须设置,但是不起作用。(注意:v2.5版本之后无该参数)
- subsystem_id:子系统id(子系统的识别码,终端IOTE如果要连接该子系统(AP),需要将config配置里的子系统ID参数配置成该ID)。
- na:48个字节预留位。
频谱idx | 低频MHz | 高频MHz | 中心频率MHz | 带宽MHz | 频点stepMHz | 频点idx | 频点个数 |
---|---|---|---|---|---|---|---|
0(other1) | 223 | 235 | 229 | 12 | 0.2 | 0-60 | 61 |
1(other2) | 430 | 432 | 431 | 2 | 0.2 | 0-10 | 11 |
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 |
5.2 设置系统配置
-
目的
设置系统配置。 -
语法
void uc_wiota_set_system_config(sub_system_config_t *config);
-
描述
设置系统配置时,注意参数个数,强烈建议先获取系统配置,再更改相关参数,最后设置系统配置。v2.3版本后子系统id支持热配置,在wiota run之后也可以设置 -
返回值
无 。 -
参数
同5.1 获取系统配置。 -
注意
终端的系统配置需要跟AP的系统配置保持一致才能与AP同步。
6. AP端上下行状态信息(状态信息相关接口在v2.4及之后的版本将不再支持)
6.1 查询单个终端的单个状态信息
-
目的
查询单个终端的单个状态信息。 -
语法
unsigned int uc_wiota_get_single_state_info_of_iote(unsigned int user_id,
uc_state_type_e state_type);
-
描述
查询单个终端的单个状态信息。 -
返回值
查询到的单个状态值。 -
参数
user_id //要查询的终端id。
state_type //状态类型
- 参数类型
typedef enum
{
TYPE_UL_RECV_LEN = 1,
TYPE_UL_RECV_SUC = 2,
TYPE_DL_SEND_LEN = 3,
TYPE_DL_SEND_SUC = 4,
TYPE_DL_SEND_FAIL = 5,
UC_STATE_TYPE_MAX
} uc_state_type_e;
- 参数类型描述
- TYPE_UL_RECV_LEN:上行接受成功的数据长度状态。
- TYPE_UL_RECV_SUC:上行接受成功的次数状态。
- TYPE_DL_SEND_LEN:下行发送成功的数据长度状态。
- TYPE_DL_SEND_SUC:下行发送成功次数的状态。
- TYPE_DL_SEND_FAIL:下行发送失败次数的状态。
- UC_STATE_TYPE_MAX:无效状态。
6.2 查询单个终端的所有状态信息
- 目的
查询单个终端的所有状态信息。
注意:返回的结构体指针禁止释放。
- 语法
uc_state_info_t *uc_wiota_get_all_state_info_of_iote(unsigned int user_id);
-
描述
查询单个终端的所有状态信息。 -
返回值
uc_state_info_t //结构体指针
- 返回值类型
typedef struct uc_state_info
{
slist_t node;
unsigned int user_id;
unsigned int ul_recv_len;
unsigned int ul_recv_suc;
unsigned int dl_send_len;
unsigned int dl_send_suc;
unsigned int dl_send_fail;
}uc_state_info_t;
//单链表(下同)
typedef struct slist
{
struct slist *next;
}slist_t
- 返回值类型描述
- user_id:终端的user id。
- ul_recv_len:单个终端上行成功接受数据的总长度,单位:byte。
- ul_recv_suc:单个终端上行成功接受数据的次数,接受完一次完整数据后加1。
- dl_send_len:单个终端下行成功发送数据的总长度,单位:byte。
- dl_send_suc:单个终端下行成功发送数据的次数,发送完一次完整数据后加1。
- dl_send_fail:单个终端下行发送数据失败的次数,一次下行数据发送失败后加1。
- node:单链表节点。
- 参数
user_id //要查询的终端id。
6.3 查询所有终端的所有状态信息
- 目的
查询所有终端的所有状态信息。
注意:返回的结构体指针禁止释放。 - 语法
uc_state_info_t *uc_wiota_get_all_state_info(void);
-
描述
查询所有终端的全部状态信息。此函数返回该信息链表结构的首节点,如果节点的next不为空,则代表有相应终端的状态信息。 -
返回值
uc_state_info_t //结构体指针
-
返回值类型
同6.2 查询单个终端的所有状态信息。 -
参数
无。
6.4 重置单个终端的单个状态信息
-
目的
重置单个终端的单个状态信息。 -
语法
void uc_wiota_reset_single_state_info_of_iote(unsigned int user_id,
uc_state_type_e state_type);
-
描述
重置单个终端的单个状态信息,即单个状态变量归零。 -
返回值
无。 -
参数
user_id //要重置的终端id。
state_type //状态类型,同6.1
6.5 重置单个终端的所有状态信息
-
目的
重置单个终端的所有状态信息。 -
语法
void uc_wiota_reset_all_state_info_of_iote(unsigned int user_id);
-
描述
重置单个终端的所有状态信息,即所有状态变量都归零。 -
返回值
无。 - 参数
user_id //要重置的终端id。
6.6 重置所有终端的所有状态信息
-
目的
重置所有终端的所有状态信息。 -
语法
void uc_wiota_reset_all_state_info(void);
-
描述
重置所有终端的所有状态信息,即所有终端的所有状态变量都归零。 -
返回值
无。 -
参数
无。
7. 频点相关
7.1 扫描频点集合
-
目的
扫描频点集合。 -
语法
uc_result_e uc_wiota_scan_freq(unsigned char *freq,
unsigned char freq_num,
unsigned char scan_type,
signed int timeout,
uc_scan_callback callback,
uc_scan_recv_t *scan_result);
- 描述
扫描频点集合,返回各频点的详细结果,包括snr、rssi、is_synced(详细解释看本小节末尾)。
*freq以及freq_num的意思如下:
unsigned char freq[freq_num] = {100,101,102……}; //freq 代表数组名,freq_num代表有效的数据个数,不一定是数组的大小。
如果freq为NULL , freq_num 为 0 , timeout 为 -1时,为全扫(0-200共201个频点),全扫大约需要4分钟,注意把控超时时间 。
-
返回值
uc_result_e
-
说明
在代码中有一个扫描频点集合的例子:test_handle_scan_freq()。该函数声明在“test_wiota_api.c”文件中,搜索名字即可定位到该函数。 -
返回值类型
typedef enum
{
UC_OP_SUC = 0,
UC_OP_TIMEOUT = 1,
UC_OP_FAIL = 2,
}uc_result_e;
- 返回值类型描述
- UC_OP_SUC:函数执行结果成功。
- UC_OP_TIMEOUT:函数执行超时。
-
UC_OP_FAIL:函数执行失败。
注:下面用到uc_result_e的地方都表示相同含义。 -
参数
freq //频点集合
freq_num //频点数量
scan_type //扫频类型,0表示正常扫频,1表示快速扫频(只扫rssi)
timeout //超时时间
callback //执行结果回调函数指针
scan_result //扫频结果
- 参数类型
typedef void (*uc_scan_callback)(uc_scan_recv_t *result)
typedef struct
{
unsigned short data_len;
unsigned char *data;
unsigned char result;
} uc_scan_recv_t;
//频点的信息
typedef struct
{
unsigned char freq_idx;
signed char snr;
signed char rssi;
unsigned char is_synced;
} uc_scan_freq_info_t;
- 参数类型描述
- uc_scan_recv_t:扫频结果信息结构体。
- data_len:扫频结果数据的总长度。
- data:扫频结果数据,将类型转换为uc_scan_freq_info_t即可得到各频点的详细信息,在使用完成后,该指针需要调用者手动释放。
- result:uc_result_e
- uc_scan_freq_info_t:频点信息结构体。
- freq_idx:频点。
- snr:该频点的信噪比。
- rssi:该频点的接收信号强度指示。
- is_synced:该频点是否能同步上,能同步上该值为1,不能同步上该值为0。
7.2 设置默认频点
-
目的
设置默认频点,支持热配置。 -
语法
void uc_wiota_set_freq_info(unsigned char freq_idx);
-
描述
设置默认频点,频点范围470M-510M,每200K一个频点,v2.3版本后频点支持热配置,在wiota run之后也可以设置。 -
参数
freq_idx //范围0 ~ 200,代表频点(470 + 0.2 * freq_idx)
7.3 查询默认频点
-
目的
获取当前设置的默认频点。 -
语法
unsigned char uc_wiota_get_freq_info(void);
-
描述
获取设置的默认频点。 -
返回值
freq_idx // 频点,范围0 ~ 200
- 参数
无。
7.4 设置跳频频点
-
目的
设置跳频频点,支持的配置。 -
语法
void uc_wiota_set_hopping_freq(unsigned char hopping_freq);
-
描述
设置跳频频点,频点范围470M-510M,每200K一个频点。 v2.3版本后频点支持热配置,在wiota run之后也可以设置。 -
返回值
无。 -
参数
hopping_freq //范围0 ~ 200,代表频点(470 + 0.2 * hopping_freq)
7.5 设置跳频模式
-
目的
设置跳频模式。 -
语法
void uc_wiota_set_hopping_mode(unsigned char ori_freq_frame, unsigned char hopping_freq_frame);
-
描述
设置跳频模式,默认不跳频。 例如:ori_freq_frame为10, hopping_freq_frame为20则表示,在原频点工作10帧后在跳频频点工作20帧,如此循环。 -
返回值
无。 -
参数
ori_freq_frame //在原频点工作的帧数
hopping_freq_frame //在跳频频点工作的帧数
8. 连接态相关
8.1 设置连接态保持时间
-
目的
设置连接态的保持时间。 -
语法
void uc_wiota_set_active_time(unsigned int active_s);
-
描述
设置连接态的保持时间(需要与终端保持一致)。
终端在接入后,即进入连接态,当无数据发送或者接收时,会保持一段时间的连接态状态,在此期间AP和终端双方如果有数据需要发送则不需要再进行接入操 作,一旦传输数据就会重置连接时间,而在时间到期后,终端自动退出连接态,AP同时删除该终端连接态信息。正常流程是终端接入后发完上行数据,AP再开始发送下行数据,显然,这段时间不能太短,否则底层会自动丢掉终端的信息,导致下行无法发送成功。默认连接时间是3秒,也就是说AP侧应用层在收到终端接入后,需要在3秒内下发下行数据,超过3秒AP端将走寻呼流程,当然,重走寻呼过程再下发数据,这全是协议栈完成,应用层不可见。 -
返回值
无。 -
参数
active_s //单位:秒,根据symbol length的不同默认值稍有不同:对应关系为symbol length为128,256,512,1024分别对应的连接态时间为2,3,4,8
8.2 查询连接态保持时间
-
目的
查询连接态的连接态保持时间。 -
语法
unsigned int uc_wiota_get_active_time(void);
-
描述
查询连接态的保持时间,单位:秒。 -
返回值
unsigned int //连接态保持的时间
- 参数
无。
8.3 设置连接态终端数量
-
目的
设置最大的连接态终端的数量。 -
语法
void uc_wiota_set_max_num_of_active_iote(unsigned short max_iote_num);
-
描述
用于设置最大的连接态终端数量,默认1:1配置为72个,1:2配置为144个,一般不建议用户设置,如果有特殊需求才设置。 -
返回值
无。 -
参数
max_iote_num //默认1:1配置为72个,1:2配置为144个
8.4 获取终端信息(获取终端信息接口在v2.4及之后的版本将不再支持)
-
目的
查询当前在线或离线的终端信息。 -
语法
iote_info_t *uc_wiota_get_iote_info(unsigned short *connected_iote_num,
unsigned short *disconnected_iote_num);
-
描述
查询当前终端的信息,返回信息链表头和在线总个数、离线总个数(这两个数据以参数方式返回)。 -
返回值
iote_info_t //结构体指针,使用完成后不需要手动释放
- 返回值类型
//终端信息
typedef struct iote_info
{
slist_t node;
unsigned int user_id;
unsigned char iote_status;
unsigned char group_idx;
unsigned char subframe_idx;
}iote_info_t;
//终端状态
typedef enum
{
STATUS_DISCONNECTED = 0,
STATUS_CONNECTED = 1,
STATUS_MAX
}iote_status_e;
- 返回值描述
- iote_info_t:终端信息。
- user_id:终端id。
- iote_status:终端状态,iote_status_e。
- group_idx:终端所在的group位置信息。
- subframe_idx:终端所在的子帧位置信息。
- node:单链表节点。
-
iote_status_e:终端状态。
- STATUS_DISCONNECTED:表示终端处于离线状态。
- STATUS_DISCONNECTED:表示终端处于在线状态。
- STATUS_MAX:无效状态。
-
参数
connected_iote_num //传出当前在线终端的总个数
disconnected_iote_num //传出当前离线终端的总个数
8.5 打印获取的终端信息(打印获取的终端信息接口在v2.4及之后的版本将不再支持)
-
目的
串口打印连接态的终端信息或离线的终端信息。 -
语法
void uc_wiota_print_iote_info(iote_info_t *head_node,
unsigned short connected_iote_num,
unsigned short disconnected_iote_num);
-
描述
根据查询到的结果,串口打印终端信息。 -
返回值
无。 -
参数
head_node //获取到的信息链表头,类型同8.4
connected_iote_num //传出当前在线终端的总个数
disconnected_iote_num //传出当前离线终端的总个数
9. 黑名单
9.1 添加终端到黑名单
-
目的
添加一个或多个终端到黑名单(可用于删除指定id的终端,将该终端的id添加到黑名单即可)。 -
语法
void uc_wiota_add_iote_to_blacklist(unsigned int *user_id, unsigned short user_id_num);
-
描述
根据传入的user_id和数量,将该组user_id添加到黑名单,黑名单中的user_id将不再处理。 -
返回值
无。 -
参数
user_id //user id数组首地址
user_id_num //数组有效id数量
9.2 从黑名单中移除终端
-
目的
将一个或多个终端从黑名单中移除。 -
语法
void uc_wiota_remove_iote_from_blacklist(unsigned int *user_id, unsigned short user_id_num);
-
描述
根据传入的user_id和数量,将该组user_id从黑名单中移除,如果某个user_id本来就不在黑名单里,就跳过这个user_id,不做任何处理,执行下一个user_id。 -
返回值
无。 -
参数
user_id //user id数组首地址
user_id_num //数组有效id数量
9.3 获取黑名单
-
目的
获取已设置的黑名单信息。 -
语法
blacklist_t *uc_wiota_get_blacklist(unsigned short *blacklist_num);
-
描述
获取已设置的黑名单链表头。 -
返回值
blacklist_t //黑名单链表头,使用完后不需要手动释放
- 返回值类型
typedef struct blacklist
{
slist_t node;
unsigned int user_id;
}blacklist_t
- 返回值描述
- user_id:已添加的终端id。
-
node:单链表节点。
-
参数
blacklist_num //返回已添加的黑名单数量
9.4 打印黑名单
-
目的
打印已获取到的黑名单内容。 -
语法
void uc_wiota_print_blacklist(blacklist_t *head_node, unsigned short blacklist_num);
-
描述
根据获取到的黑名单链表头,通过串口输出打印所有节点信息。 -
返回值
无。 -
参数
head_node //获取到的黑名单链表头,类型见9.3
blacklist_num //获取到的黑名单总个数
10. 回调注册 (禁止在回调函数中加延迟或者大量操作)
10.2 终端掉线提示
-
目的
终端掉线提示回调注册。 -
语法
void uc_wiota_register_iote_dropped_callback(uc_iote_drop callback);
-
描述
当有终端掉线时主动上报哪一个user_id的终端掉线,可在1. 初始化WIoTa 之后或者2. 启动WIoTa之后注册。 -
返回值
无。 -
参数
typedef void (*uc_iota_drop)(unsigned int user_id);
callback //回调函数函数指针(参数可增加,目前只有user_id)
10.3 接收数据主动上报
-
目的
数据被动上报回调注册, v2.3版本后将接入提示回调注册接口取消,合并到数据接收回调中,通过上报的数据类型区分是接入短消息还是连接态短消息(便于上层业务做终端位置管理),并在数据上报的同时上报该终端在帧结构的位置信息 。 -
语法
void uc_wiota_register_recv_data_callback(uc_recv callback);
-
描述
当上行数据接受完成后上报给应用层,可在1. 初始化WIoTa 之后或者2. 启动WIoTa之后注册。 -
返回值
无。 -
参数
callback //回调函数函数指针
- 参数类型
typedef void (*uc_recv)(unsigned int user_id, uc_dev_pos_t dev_pos, unsigned char *data, unsigned int data_len, uc_recv_data_type_e type);
typedef struct
{
unsigned char group_idx;
unsigned char burst_idx;
unsigned char slot_idx;
unsigned char reserved;
} uc_dev_pos_t;
typedef enum
{
DATA_TYPE_ACCESS = 0,
DATA_TYPE_ACTIVE = 1,
DATA_TYPE_SUBF_DATA = 2, // v3.0新增,上行为子帧数据
} uc_recv_data_type_e;
- 参数类型描述
uc_recv:回调函数指针。 - user_id:终端id。
- dev_pos:终端在帧结构上的位置信息,包括终端所在的group_idx, burst_idx, slot_idx。
- data:接收到的数据指针,不需要调用者释放。
- data_len:接收到的数据长度。
- type:接收到的数据类型,DATA_TYPE_ACCESS表示接入短消息,DATA_TYPE_ACTIVE表示连接态短消息,DATA_TYPE_SUBF_DATA为上行子帧数据,开启上行子帧接收模式后才能收到。
11. 数据发送
11.1 设置和查询广播的传输速率
- 目的
设置和查询广播的mcs(包括普通广播和OTA)。 - 语法
void uc_wiota_set_broadcast_mcs(uc_mcs_level_e mcs);
uc_mcs_level_e uc_wiota_get_broadcast_mcs(void);
- 描述
设置广播的传输速率,分为7个等级,OTA默认等级2,等级越高,速率越高。 - 返回值
无。 - 参数
mcs //mcs等级
- 参数类型
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_LEVEL_AUTO = 8,
UC_MCS_LEVEL_INVALID = 9,
}uc_mcs_level_e;
- 参数描述
BT=0.3(即bt_value = 1时,5.1 获取系统配置) 时在不同symbol length和不同MCS下,对应每帧传输的应用数据量(byte)会有差别,NA表示不支持,见下表:
(备注:下表中为单播数据包的数据量,如果是普通广播包,下表每项减2,如果是OTA包,下表每项减1)
symbol length | mcs0 | mcs1 | mcs2 | mcs3 | mcs4 | mcs5 | mcs6 | mcs7 |
---|---|---|---|---|---|---|---|---|
128 | 6 | 8 | 51 | 65 | 79 | NA | NA | NA |
256 | 6 | 14 | 21 | 51 | 107 | 156 | 191 | NA |
512 | 6 | 14 | 30 | 41 | 72 | 135 | 254 | 296 |
1024 | 6 | 14 | 30 | 62 | 107 | 219 | 450 | 618 |
Note1:由于协议限制,广播和单波在不同symbol_length下支持的最大MCS不同,但设置超过最大MCS时,默认设置为最大MCS,见下表:
symbol length | 广播最大MCS | 单波最大MCS |
---|---|---|
128 | 4 | 4 |
256 | 6 | 6 |
512 | 6 | 7 |
1024 | 5 | 7 |
Note2:当OTA的MCS为高阶MCS且一直发送时,此时发送上行会失败,在此种场景下要发上行,请采用低阶MCS发送OTA。128配置MCS大于等于MCS2为高阶小于MCS2为低阶;256配置MCS大于等于MCS3为高阶小于MCS3为低阶;512和1024配置MCS大于等于MCS4为高阶小于MCS4为低阶。
11.2 广播数据发送
- 目的
发送广播数据给所有終端,现在发送广播(OTA或普通广播)时可同时进行上下行业务。 - 语法
uc_result_e uc_wiota_send_broadcast_data(unsigned char *send_data,
unsigned short send_data_len,
broadcast_mode_e mode,
signed int timeout,
uc_send_callback callback,
void *para);
- 描述
发送广播数据给所有終端,有两种模式,设置mode的值决定为哪种模式。
如果callback为NULL,为阻塞调用,需要等到函数返回值为UC_SUCCESS才能发送下一个包。
如果callback不NULL,为非阻塞调用。
详见:uc_wiota_interface_test.c中test_send_broadcast_data()这个例子。
备注:(禁止在回调函数中加延迟或者大量操作)
- 返回值
uc_result_e //函数执行结果
//当callack!=NULL时直接返回成功,真正的结果由callback返回
- 参数
send_data //要发送的数据,该指针如果是调用者malloc的空间,需要调用者自己释放,且调用完该接口后即可释放
send_data_len //要发送的数据长度,最大为1024byte
mode //发送的模式广播或OTA,见下说明
timeout //超时时间,发送1k数据的时间大约为4s,若要发送大量数据请将数据分段并控制发送频率
callback //执行结果回调,为NULL时为阻塞调用,非NULL时为非阻塞调用,结构见下
para //用于非阻塞发送,使应用成感知每段数据的发送情况,一般传入发送数据的地址,在数据发送成功后返回该地址,表示某段数据发送结束,不需要该功能时填NULL
- 参数类型
typedef enum
{
NORMAL_BROADCAST = 0,
OTA_BROADCAST = 1,
INVALID_BROADCAST,
}broadcast_mode_e;
typedef void (*uc_send_callback)(uc_send_recv_t *result)
typedef struct
{
unsigned int user_id; // 发送广播时,该id无意义
unsigned int data_id;
unsigned char result;
}uc_send_recv_t;
- 参数类型描述
- broadcast_mode_e: 广播类型。
- NORMAL_BROADCAST:普通广播模式,数据量小,速率相对较低。
- OTA_BROADCAST:OTA模式,数据量大,速率相对较高。
11.3 设置组播ID
-
目的
设置用于发送组播的组播ID,需要跟终端约定,最多设置8个组播ID。 -
语法
void uc_wiota_set_multicast_id(unsigned int *multicast_id, unsigned int id_num);
-
描述
设置一组组播ID用于发送组播。最多设置8个,可多次设置,只有设置了组播ID才能向该ID发送组播。 故发送组播前必须先设置组播ID,否则会提示发送失败。 -
返回值
无。 -
参数
multicast_id //组播id数组首地址
id_num //组播id个数
11.4 删除组播ID
-
目的
用于删除组播ID,对于设置错误或不再需要的组播ID,可进行删除。 -
语法
void uc_wiota_del_multicast_id(unsigned int *multicast_id, unsigned int id_num);
-
描述
删除一组组播ID,删除后不可再用该组ID发送组播。 -
返回值
无。 -
参数
multicast_id //组播id数组首地址
id_num //组播id个数
11.5 发送组播数据
-
目的
设置好组播id后可发送组播消息。设置了相同组播id的终端可接收到消息 -
语法
uc_result_e uc_wiota_send_multicast_data(unsigned char *send_data,
unsigned short send_data_len,
unsigned int multicast_id,
signed int timeout,
uc_send_callback callback
void *para);
- 描述
可向一组终端发送数据。
如果回调函数不为NULL,则非阻塞模式,成功发送数据或者超时后会调用callback返回结果。
如果回调函数为NULL,则为阻塞模式,成功发送数据或者超时该函数才会返回结果。
备注:(禁止在回调函数中加延迟或者大量操作)
- 返回值
uc_result_e //函数执行结果
//当callack!=NULL时直接返回成功,真正的结果由callback返回
- 参数
send_data //要发送的数据,该指针如果是调用者malloc的空间,需要调用者自己释放,且调用完该接口后即可释放
send_data_len //要发送的数据长度,最大为300byte
user_id //要发送数据的终端的组播ID
timeout //超时时间
callback //执行结果回调,为NULL时为阻塞调用,非NULL时为非阻塞调用
para //用于非阻塞发送,使应用成感知每段数据的发送情况,一般传入发送数据的地址,在数据发送成功后返回该地址,表示某段数据发送结束,不需要该功能时填NULL
- 参数类型
typedef void (*uc_send_callback)(uc_send_recv_t *result)
typedef struct
{
unsigned int user_id; // 发送组播时,该id表示组播id
unsigned int data_id;
unsigned char result;
}uc_send_recv_t;
11.6 指定終端发送数据
-
目的
指定终端发送数据,只要终端同步上该AP,在任何情况下都可发送。 -
语法
uc_result_e uc_wiota_send_data(unsigned char *send_data,
unsigned short send_data_len,
unsigned int user_id,
signed int timeout,
uc_send_callback callback
void *para);
- 描述
可向一个终端发送数据。
如果回调函数不为NULL,则非阻塞模式,成功发送数据或者超时后会调用callback返回结果。
如果回调函数为NULL,则为阻塞模式,成功发送数据或者超时该函数才会返回结果。
备注:(禁止在回调函数中加延迟或者大量操作)
- 返回值
uc_result_e //函数执行结果
//当callack!=NULL时直接返回成功,真正的结果由callback返回
- 参数
send_data //要发送的数据,该指针如果是调用者malloc的空间,需要调用者自己释放,且调用完该接口后即可释放
send_data_len //要发送的数据长度,最大为300byte
user_id //要发送数据的终端的user_id
timeout //超时时间
callback //执行结果回调,为NULL时为阻塞调用,非NULL时为非阻塞调用
para //用于非阻塞发送,使应用成感知每段数据的发送情况,一般传入发送数据的地址,在数据发送成功后返回该地址,表示某段数据发送结束,不需要该功能时填NULL
- 参数类型
typedef void (*uc_send_callback)(uc_send_recv_t *result)
typedef struct
{
unsigned int user_id; //发送单播时该id表示user_id
unsigned int data_id;
unsigned char result;
}uc_send_recv_t;
12. 授时相关接口
12.1 开启帧边界对齐功能
-
目的
利用授时校准同步帧边界的功能是否开启。 -
语法
void uc_wiota_set_frame_boundary_align_func(unsigned char is_open);
-
描述
开启GPS、1588或同步助手授时功能后开启帧边界对齐功能可周期性校准帧边界 。 -
返回值
无。 -
参数
is_open //是否开启帧边界对齐功能,0:关闭,1:打开
12.2 开启同步授时功能
-
目的
支持GPS功能的版本固件或有带1588协议的网关版本可开启此功能,开启后会周期性进行授时并校准帧边界。 -
语法
void uc_wiota_set_time_service_func(time_service_type_e type, unsigned char is_open);
-
描述
开启授时功能后开启帧边界对齐功能可周期性校准帧边界。只能同时设置一种授时类型。 -
返回值
无。 -
参数
type //授时类型,GPS、1588协议或同步助手
is_open //是否开启帧边界对齐功能,0:关闭,1:打开
- 参数类型
typedef enum
{
TIME_SERVICE_GNSS = 0, //设置授时类型为GPS
TIME_SERVICE_1588_PROTOCOL = 1, //设置授时类型为1588协议
TIME_SERVICE_SYNC_ASSISTANT = 2, //设置授时类型为同步助手
} time_service_type_e;
12.3 查询授时功能开启状态
-
目的
查询授时功能开启状态,是GPS还是1588。 -
语法
unsigned char uc_wiota_get_time_service_func(time_service_type_e type);
-
描述
查询开启授时的类型是GPS还是1588。 -
返回值
开启状态。 -
参数
type //为0表示查询GPS授时是否开启,为1表示查询1588授时是否开启
12.4 查询授时过程状态
-
目的
查询授时过程状态。 -
语法
time_service_state_e uc_wiota_get_time_service_state(void);
-
描述
查询授时过程的状态。 -
返回值
time_service_state_e。 -
返回值类型
typedef enum
{
TIME_SERVICE_NULL = 0, //授时线程创建,未开启gps或1588授时的状态
TIME_SERVICE_START = 1, //授时开始的状态
TIME_SERVICE_SUC = 2, //一次授时成功的状态
TIME_SERVICE_FAIL = 3, //授时结果偏差过大无法完成对齐校验的状态
GTIME_SERVICE_INIT_END = 4, //初次开机经过授时完成帧头计算成功后的状态,在该状态时需要立即将协议栈run起来
TIME_SERVICE_ALIGN_END = 5, //非初次开机,每隔固定时间进行帧头对齐校准成功的状态
TIME_SERVICE_STOP = 6, //一次授时停止的状态
} time_service_state_e;
12.5 设置1588时间到协议栈
-
目的
将1588授时时间传入协议栈。 -
语法
void uc_wiota_set_1588_protocol_rtc(unsigned int timestamp, unsigned int usec);
-
描述
开启1588授时后,将外部1588获取的世界时钟源传入协议栈。 -
返回值
无。 -
参数
timestamp //1588授时时钟源的整秒部分
usec //1588授时时钟源的微秒部分
12.6 查询GNSS授时时的位置信息
-
目的
当GPS授时成功后可通过该接口查询授时时的位置信息。 -
语法
void uc_wiota_gnss_query_fix_pos(int pos_x, int pos_y, int pos_z);
-
描述
开启GPS授时功能并成功授时后flash中会保存授时时的位置信息,此接口可查询该位置信息。 -
返回值
无。 -
参数
pos_x //位置信息x
pos_y //位置信息y
pos_z //位置信息z
12.7 设置GNSS重新定位
- 目的
一般来说AP只会在第一次启动后定位一次,后续只会授时,但如果AP移动了位置或者连续发生GNSS授时失败时,需要上层决策是否重新定位。
- 语法
void uc_wiota_gnss_relocation(unsigned char is_relocation);
-
描述
开启功能可让GPS在下次授时时重新定位后再授时。 -
返回值
无。 -
参数
is_relocation //是否重新定位,0:关闭重新定位,1:打开重新定位
12.8 注册授时状态回调函数
- 目的
在wiota init之前注册,可监测授时过程状态。 - 语法
void uc_wiota_register_time_service_state_callback(
uc_time_service_callback callback);
-
描述
开启授时功能后,上报授时过程状态,应用可根据状态进行一些处理。 -
返回值
无。 -
参数
uc_time_service_callback //授时状态回调函数
- 参数类型
typedef void (*uc_time_service_callback)(time_service_state_e state);
12.6 授时开始
-
目的
开始授时。 -
语法
void uc_wiota_time_service_start(void);
-
描述
当设置授时类型为GPS、1588或同步助手后,调用该接口授时开始运行,周期校准定时器开始工作,校准周期为15分钟。 -
返回值
无。
12.7 授时停止
-
目的
停止授时 -
语法
void uc_wiota_time_service_stop(void);
-
描述
停止授时,周期校准定时器也将停止。 -
返回值
无。
13. 其他接口说明
13.1 查询ap8288芯片温度
-
目的
可实时获取到ap8288芯片的温度。 -
语法
uc_result_e uc_wiota_read_temperature(uc_temp_callback callback,
uc_temp_recv_t *read_temp,
signed int timeout)
-
描述
调用该接口可读取基带芯片内部的实时温度,读取温度需要两帧左右,需要在没有任务的时候读取,有任务时会直接返回读取失败。
如果回调函数不为NULL,则为非阻塞模式,成功执行或者超时后会调用callback返回结果。
如果回调函数为NULL,则为阻塞模式,成功执行或者超时该函数才会返回结果。 -
返回值
uc_result_e //函数执行结果
//当callack!=NULL时直接返回成功,真正的结果由callback返回
- 参数
callback //函数执行结果回调,为NULL时为阻塞调用,非NULL时为非阻塞调用
read_temp //出参,返回读取的温度和执行结果
timeout //函数执行超时时间
- 参数类型
typedef void (*uc_temp_callback)(uc_temp_recv_t *result)
typedef struct
{
signed char temp;
unsigned char result;
}uc_temp_recv_t;
- 参数类型描述
- uc_temp_callback:函数指针。
- uc_temp_recv_t:查询结果结构体。
- temp:查询到的温度值。
- result:查询到的结果,uc_result_e。
13.2 设置WIoTa log开关
-
目的
设置协议层的log开关。 -
语法
void uc_wiota_log_switch(uc_log_type_e log_type, unsigned char is_open);
-
描述
开关协议层的log,包括uart和spi两种,可开启其中一种log,也可以同时开启(该函数不同参数设置两次)。 -
返回值
无。 -
参数
log_type //uart和spi两种
is_open //是否开启该log
- 参数类型
typedef enum
{
UC_LOG_UART = 0,
UC_LOG_SPI = 1
}uc_log_type_e;
- 参数类型说明
- UC_LOG_UART:串口log。
- UC_LOG_SPI:spi log。
13.3 设置AP CRC开关
-
目的
设置AP CRC开关。 -
语法
void uc_wiota_set_crc(unsigned short crc_limit);
-
描述
开关协议层的CRC校验和设置检验长度。大于等于设定值则自动添加CRC,否则不添加,默认为100,即当发送的数据大于等于100字节时,协议层自动加CRC,小于100时不加CRC。 -
返回值
无。 -
参数
crc_limit //开启CRC的检验长度
//0:关闭CRC校验,不管数据长度多长都不加CRC
//大于0:表示加CRC的数据长度,如:crc_limit为50,则表示大于等于50个字节的数据开启CRC校验
13.4 设置和查询AP数据传输模式和速率
-
目的
根据应用需求设置、查询数据传输模式和速率 。 -
语法
uc_result_e uc_wiota_set_data_rate(uc_data_rate_mode_e rate_mode, unsigned int rate_value);
unsigned int uc_wiota_get_data_rate(uc_data_rate_mode_e rate_mode);
- 描述
四种模式:
第一种基本模式,是基本速率设置。
在第一种模式的基础上,在系统配置中dlul_ratio为1:2时,才能打开第二种模式,打开该模式能够提高该帧结构情况下两倍速率,默认第二种模式开启状态。
在第一种模式的基础上,打开第三种模式,能够提升(8*(1 << group_number))倍单终端的速率,但是会影响网络中其他终端的上行,建议在大数据量快速传输需求时使用。
备注:group_number为系统配置中的参数。
第四种为减少基带CRC为1字节,提高上层单帧数据量3字节。
- 返回值
uc_result_e //函数执行结果
- 参数
rate_mode //传输模式
rate_value //当rate_mode为UC_RATE_NORMAL时,rate_value为UC_MCS_LEVEL
//当rate_mode为UC_RATE_MID时,rate_value为0或1,表示关闭或打开,必须和终端的状态保持一致
//当rate_mode为UC_RATE_HIGH时,rate_value为0,表示关闭rate_value为其他值,表示当实际发送数据量(byte)大于等于该值时才会真正开启该模式,常用建议设置rate_value为100,可单独开启,建议最好和终端状态保持一致
- 参数类型
typedef enum
{
UC_RATE_MORMAL = 0, //普通模式
UC_RATE_MID = 1, //dlul_ratio为1:2时可开启
UC_RATE_HIGH = 2, //连续数据包模式
UC_RATE_CRC_TYPE = 3, //基带CRC类型,默认为0,表示四字节CRC校验,为1表示1字节CRC校验,也就是说开启该模式后,上层单帧可多携带3字节数据
}uc_data_rate_mode_e;
- 参数类型描述
- UC_RATE_MORMAL:普通模式。
- UC_RATE_MID:dlul_ratio为1:2时可开启。
- UC_RATE_HIGH:连续数据包模式。
- UC_RATE_CRC_TYPE:基带CRC类型
13.5 查询id在帧结构上的位置
-
目的
根据user_id查询对应的位置信息。 -
语法
uc_dev_pos_t *uc_wiota_query_dev_pos_by_userid(unsigned int *user_id, unsigned int user_id_num);
-
描述
根据user id返回该id在帧结构上的位置。 -
返回值
uc_dev_pos_t //函数执行结果
typedef struct
{
unsigned char group_idx;
unsigned char burst_idx;
unsigned char slot_idx;
unsigned char reserved;
} uc_dev_pos_t;
- 参数
user_id //要查询的id数组首地址
user_id_num //要查询的id个数
13.6 查询AP8288运行状态(AP主线程运行状态)
-
目的
查询AP8288运行是否正常,该接口可大致判断AP整体的运行是否异常。 -
语法
ap8288_state_e uc_wiota_get_ap8288_state(void);
-
描述
AP主线程依赖AP8288产生的中断驱动,如果AP8288发生异常,则AP主线程会停止运行,整个AP也就发生异常,该状态只能大概判断AP8288是否异常,如发生异常并不能准确反馈造成异常的原因。 -
返回值
ap8288_state_e //AP8288运行状态,正常或异常
-
返回值类型
typedef enum
{
STATE_ABNORMAL = 0, //AP8288运行状态异常
STATE_NORMAL = 1, //AP8288运行状态正常
} ap8288_state_e;
13.7 获取当前配置帧长
-
目的
获取当期配置下的帧长。 -
语法
unsigned int uc_wiota_get_frame_len(void);
-
描述
调用接口,返回当前配置的帧长,单位:微妙。 -
返回值
帧长。
13.8 设置广播帧发送周期
-
目的
设置广播帧发送周期 -
语法
void uc_wiota_set_broadcast_fn_cycle(unsigned char bc_fn_cycle);
-
描述
广播帧主要用于发送帧号给IOTE,当使用同步DTU的低功耗时设为1,其他情况不建议设置,默认值11,最小值1,最大值11。 -
参数
bc_fn_cycle //发送周期,最小1,最大11
13.9 获取广播帧发送周期
-
目的
获取广播帧发送周期。 -
语法
unsigned char uc_wiota_get_broadcast_fn_cycle(void);
- 描述
用于获取当前的广播帧发送周期。 - 返回值
广播帧发送周期。
13.10 设置广播发送轮数
-
目的
设置普通广播、OTA或下行子帧数据的发送轮数。 -
语法
void uc_wiota_set_broadcast_send_round(unsigned char round);
-
描述
由于广播没有ACK,一次广播数据会默认会发3轮,保证IOTE接收成功率,当信号好时用户可设置发送轮数,缩短发送时间 。 -
返回值
无。 -
参数
round //广播发送轮数
13.11 获取广播发送轮数
-
目的
获取普通广播或OTA的发送轮数。 -
语法
unsigned int uc_wiota_get_broadcast_send_round(void);
-
描述
调用接口,返回当前广播发送轮数。 -
返回值
广播发送轮数。
13.12 开启或关闭单音发送
-
目的
AP控制发送单音。 -
语法
void uc_wiota_set_single_tone(unsigned char is_open);
-
描述
通过AP控制AP8288发送单音,或结束发送单音。 -
返回值
无。 -
参数
is_open //1:打开,0:关闭
13.13 获取当前帧号
-
目的
获取AP当前的帧号。 -
语法
unsigned int uc_wiota_get_frame_num(void);
-
描述
获取AP当前的帧号。 -
返回值
帧号。 -
参数
无。
13.14 IOTE主动离开连接态
-
目的
控制IOTE主动离开连接态。 -
语法
void uc_wiota_iote_leaving_active_state(unsigned int *user_id, unsigned int id_num);
-
描述
调用此接口终端如果在连接态将在下一帧离开连接态,不管连接态时间是否超时,如果此时该终端有上下行业务,都将失败,慎用。 -
返回值
无。 -
参数
user_id //要主动离开连接态终端的id数组首地址
id_num //要主动离开连接态终端的id个数
13.14 获取模组ID
-
目的
获取模组ID。 -
语法
void uc_wiota_get_module_id(unsigned int *module_id);
-
描述
查询AP模组的模组ID。 -
返回值
无。 -
参数
module_id //AP模组ID
14. 空中唤醒相关接口
14.1 设置paging tx配置
-
目的
设置空中唤醒终端的寻呼配置。 -
语法
void uc_wiota_set_paging_tx_cfg(uc_lpm_tx_cfg_t *config);
-
描述
设置空中唤醒终端的配置,开始寻呼前必须设置配置。 -
返回值
无。 -
参数
config //寻呼配置信息
- 参数类型
typedef struct
{
unsigned char freq;
unsigned char spectrum_idx;
unsigned char bandwidth;
unsigned char symbol_length;
unsigned short awaken_id;
unsigned short reserved;
unsigned int send_time;
}uc_lpm_tx_cfg_t;
- 参数类型说明
- freq:频点。
- spectrum_idx:频谱。
- bandwidth:带宽。
- symbol_length:symbol length。
- awaken_id:指示需要唤醒的ID。
- reserved:对齐预留位
- send_time: 最小值为接收端检测周期
14.2 获取paging tx配置
-
目的
获取寻呼配置。 -
语法
void uc_wiota_get_paging_tx_cfg(uc_lpm_tx_cfg_t *config);
-
描述
获取空中唤醒终端的配置。 -
返回值
无。 -
参数
config //寻呼配置信息
14.3 开始paging tx
-
目的
开始寻呼。 -
语法
void uc_wiota_start_paging_tx(void);
-
描述
设置好寻呼配置后,可调用该接口进行空中唤醒对应配置的终端设备。 -
返回值
无。 -
参数
无。
14.4 发送同步paging
-
目的
发送周期性唤醒信号,在接收到终端发送的paging ctrl消息后,调用该接口唤醒进入同步paging低功耗的终端。 -
语法
void uc_wiota_register_sync_paging_callback(uc_paging_ctrl_callback callback);
void uc_wiota_sync_paging(uc_paging_info_t *paging_info, uc_paging_callback callback);
- 描述
该接口为发送周期唤醒信号,需要提前知道终端睡眠时的帧号,并在需要唤醒时将该帧号传入。
上层如何知道终端睡眠时的帧号,通过uc_wiota_register_sync_paging_callback该接口注册回调,当终端进入sync paging低功耗前会发送一个ctrl消息通知AP,AP收到该消息后会将当前帧号通过该回调函数告知上层,当需要唤醒时,上层再将该帧号传入paging_info中通过uc_wiota_sync_paging下发周期唤醒信号,从而唤醒该终端。
-
返回值
无。 -
参数
paging_info // 同步paging信息结构体指针
callback //用于返回多帧寻呼是否完成,当该参数为NULL时,表示阻塞等待寻呼完成结果;当该参数不为NULL时,表示非阻塞调用,寻呼完成后会调用callback返回结果
- 参数类型
typedef void (*uc_paging_callback)(uc_paging_recv_t *result);
typedef void (*uc_paging_ctrl_callback)(unsigned int user_id, //发送paging ctrl消息的终端id
unsigned char burst_idx, // 该id在帧结构的burst位置
unsigned int fn_index); // 该终端实际睡眠的帧号,上层需要记录该值
typedef struct
{
unsigned int user_id; //同步寻呼的设备id
unsigned int result; //多帧寻呼是否完成
} uc_paging_recv_t;
typedef struct
{
unsigned int user_id; //同步寻呼的设备id
unsigned int fn_index; //终端睡眠时的帧号,由callback传出,paging时传入
unsigned int detection_period; //检测周期,与终端检测paging信号周期一致
unsigned int send_round; //发送唤醒信号的轮数,一般为1,表示发送一轮
unsigned int continue_fn; //单轮发送唤醒信号的帧数,一般为1,表示只在周期点发送,如果为2,则表示在周期点再前后各发送一帧唤醒信号,为3则表示前后各发两帧,以此类推,当超过detection_period的一半时,将变为每帧都发送唤醒信号
} uc_paging_info_t;
14.5 查询当前同步paging任务的个数
-
目的
查询帧结构某位置上当前有多少个同步paging的任务,便于上层安排寻呼任务 -
语法
unsigned char uc_wiota_get_syncpaging_num(unsigned char group_idx, unsigned char subframe_idx);
-
描述
传入位置信息group_idx和subframe_idx,返回该位置上正在进行同步paging的终端个数。 -
返回值
同步paging的个数。 -
参数
group_idx //帧结构group位置,范围0到7
subframe_idx //帧结构子帧位置,范围0~
15. 子帧模式相关接口(目前只用于传输语音数据)
15.1 设置子帧模式配置
-
目的
设置子帧模式配置,协议栈根据该配置接受上行子帧数据或发送下行子帧数据,一般情况下无需设置,使用默认值即可。 -
语法
void uc_wiota_set_subframe_mode_cfg(uc_subf_cfg_t *subf_cfg);
-
描述
设置子帧模式配置,目前只设置语音数据单帧大小和子帧数据发送轮数,协议栈根据大小组包上报或组包发送。 -
返回值
无。 -
参数
subf_cfg //子帧模式配置
- 参数类型
typedef struct
{
unsigned char block_size;
unsigned char send_round;
unsigned char na[2];
}uc_subf_cfg_t;
- 参数类型说明
- block_size:语音数据单帧数据大小,协议栈编码使用。
- send_round:下行子帧数据发送轮数,默认为1,表示发送一轮,最多三轮。
15.2 获取子帧模式配置
-
目的
获取子帧模式配置。 -
语法
void uc_wiota_get_subframe_mode_cfg(uc_subf_cfg_t *subf_cfg);
-
描述
获取子帧模式配置。 -
返回值
无。 -
参数
subf_cfg //子帧模式配
15.3 设置上行子帧模式
-
目的
设置上行子帧接收模式。 -
语法
void uc_wiota_set_ul_subframe_mode(unsigned char subf_mode, unsigned int user_id);
-
描述
对单个终端开启或关闭上行子帧接收模式,对应的终端也需要相同配置,设置该模式后该终端将一直处于连接态,目前主要用于语音数据的接收。 -
返回值
无。 -
参数
subf_mode //上行子帧模式,0表示关闭,1表示一帧只接收一包数据,2表示一帧接收两包数据,为2时只有在dlul_radio为1时有效
user_id //要设置上行子帧模式的终端ID
15.4 添加下行子帧数据
-
目的
添加下行子帧数据,即发送下行子帧数据。 -
语法
void uc_wiota_add_dl_subframe_data(unsigned char *data, unsigned char data_len, unsigned char fn);
-
描述
非阻塞添加下行子帧数据,协议栈根据子帧模式配置发送数据,目前主要用于语音数据的发送。 -
返回值
无。 -
参数
data //下行子帧数据
data_len //下行子帧数据长度
fn //上行子帧数据接收时的帧号,发送下行时回填
15.5 子帧模式测试(测试用)
-
目的
开启或关闭子帧模式测试,需要和终端配合使用。 -
语法
void uc_wiota_set_subframe_test(unsigned char mode);
-
描述
开启或关闭子帧模式测试。 -
返回值
无。 -
参数
mode //子帧数据测试模式,取值0~2,分别表示关闭测试,开启测试,清除测试结果
15.6 获取子帧模式测试结果(测试用)
-
目的
查询子帧模式测试结果。 -
语法
uc_subf_test_t *uc_wiota_get_subframe_test(void);
- 描述
获取子帧模式测试结果,包括有几个终端收到几次上行子帧数据和下行子帧数据发送次数。 - 返回值
测试结果。 - 返回值类型
typedef struct
{
unsigned int user_id;
unsigned int recv_cnt;
} uc_subf_node_t
typedef struct
{
uc_subf_node_t *subf_node; // ul
unsigned int subf_node_num; // ul
unsigned int send_cnt; // dl
} uc_subf_test_t
- 返回值描述
- user_id:接收上行子帧数据的ID。
- recv_cnt:接收次数。
- subf_node_num:ID个数
-
send_cnt:下行发送次数
-
参数
无。