OneNETStudio设备接入SDK使用说明.docx

OneNETStudio设备接入SDK使用说明.docx

《OneNETStudio设备接入SDK使用说明.docx》由会员分享，可在线阅读，更多相关《OneNETStudio设备接入SDK使用说明.docx（26页珍藏版）》请在冰豆网上搜索。

OneNETStudio设备接入SDK使用说明

OneNETStudio设备接入SDK使用说明

版本号：

1.1.0

日期

版本

作者

更新记录

备注

2020/06/24

v1.0.0

吴优、陈龙宇

初版发布。

2020/07/22

v1.0.1

吴优

添加数组上传的说明

2020/09/27

v1.0.2

宋伟

新增读属性、服务调用接口

2020/10/22

v1.1.0

宋伟

新增网关子设备接口

目　　录

一．前言

本文用于说明OneNETStudio物模型设备接入SDK的使用，适用于“MCU+标准通信模组”或单板SOC的方案。

SDK由固定代码包和平台生成的配置文件构成，用户根据使用的硬件平台集成SDK，通过配置宏选择不同的接入协议，并调用相应API接口即可实现OneNETStudio的快速接入。

二．SDK文件说明

表2-1SDK文件说明

说明

config.h

宏配置文件

onenet

thing_model

core

用户API接口，物模型数据封装与解析，OneNET相关数据模型

user

用户配置文件，根据平台定义的物模型生成，包含数据上传、读写接口

protocols

mqtt

paho-mqtt库

coap

er-coap-13库

security

wolfssl

wolfssl加密库

platforms

linux

Linux系统适配接口，包括内存接口，网络接口，时间接口等

三．SDK使用说明

3.1宏定义

用户需通过配置宏来决定使用的接入协议，心跳周期，数据缓冲区大小，以及是否加密等。

宏

含义

FEATURE_TM_PROTOCOL_MQTT

MQTT协议

FEATURE_TM_MQTT_TLS_NONE

非加密（MQTT）

FEATURE_TM_MQTT_TLS_WOLFSSL

TLS加密（MQTT）

FEATURE_TM_PROTOCOL_COAP

CoAP协议

FEATURE_TM_VERSION

物模型版本（默认1.0）

FEATURE_TM_LIFE_TIME

心跳周期（秒）

FEATURE_TM_REPLY_TIMEOUT

设备响应超时时间（毫秒）

FEATURE_TM_SEND_BUF_LEN

发送缓冲区长度

FEATURE_TM_RECV_BUF_LEN

接收缓冲区长度

FEATURE_TM_PAYLOAD_BUF_LEN

数据最大封包长度

3.2设备通用接口

用户通过调用物模型相关API接口，可实现设备初始化，登录、注销平台，以及数据解析等功能，可用于直连设备和网关设备。

3.2.1设备初始化

功能

设备初始化，需传入配置文件中生成的属性功能点数组及其长度

函数定义

int32_ttm_init（structtm_downlink_tbl_t*downlink_tbl）

参数

downlink_tbl：

下行数据处理回调定义表，包含属性和服务表，详细定义参考tm_api.h

返回值

0：

初始化成功；-1：

初始化失败

说明

需在设备登录之前调用

3.2.2设备登录

功能

发起设备登录请求，需传入产品与设备相关信息

函数定义

int32_ttm_login（

constint8_t*product_id,

constint8_t*dev_name,

constint8_t*access_key,

uint32_ttimeout_ms

）

参数

product_id：

产品id

dev_name：

设备名称

access_key：

产品key

timeout_ms：

超时时间（毫秒）

返回值

0：

登录成功；-1：

登录失败

3.2.3设备注销

功能

发起设备注销请求，释放内存，断开平台连接

函数定义

int32_ttm_logout（uint32_ttimeout_ms）

参数

timeout_ms：

超时时间（毫秒）

返回值

0：

注销成功

3.2.4数据解析

功能

解析平台下发的数据

函数定义

int32_ttm_step（uint32_ttimeout_ms）

参数

timeout_ms：

超时时间（毫秒）

返回值

0：

解析正常；-1：

解析错误

说明

需在设备登录成功之后反复调用，若数据解析错误（由网络异常等原因引起），则需注销设备，然后重新登录；超时时间推荐设置200ms

3.2.5获取期望属性

功能

获取平台为设备设置的期望属性值

函数定义

int32_ttm_get_desired_props（uint32_ttimeout_ms）

参数

timeout_ms：

超时时间（毫秒）

返回值

0：

获取成功

说明

调用接口后，SDK内部解析平台下发的期望属性值，将自动调用对应的写属性接口。

3.2.6清除期望属性

功能

清除平台为设备设置的期望属性值

函数定义

int32_ttm_delete_desired_props（uint32_ttimeout_ms）

参数

timeout_ms：

超时时间（毫秒）

返回值

0：

清除成功

说明

默认清除平台侧配置的所有期望属性值。

3.2.6打包设备数据

功能

打包设备的属性和事件数据，可用于子设备。

函数定义

void*tm_pack_device_data（void*data,constint8_t*product_id,constint8_t*dev_name,void*prop,void*event,int8_tas_raw）

参数

data：

需要打包的目标指针地址，用于后续调用上报接口。

设置为空时由接口内部分配空间，并通过返回值返回地址

product_id：

需要打包数据的产品id

dev_name：

需要打包数据的设备名称

prop：

传入属性数据。

支持json格式（as_raw为1），也可以仿照tm_user文件的数据上传接口使用tm_data接口构造数据（as_raw为0）

event：

定义同prop，用于传入事件数据

返回值

打包后的数据指针地址

3.2.6上报批量数据

功能

向平台批量上报若干设备的属性、事件

函数定义

int32_ttm_post_pack_data（void*pack_data,uint32_ttimeout_ms）

参数

pack_data：

调用tm_pack_device_data打包的返回数据指针

timeout_ms：

超时时间（毫秒）

返回值

0：

上报成功

调用tm_pack_device_data时，传入的属性和事件的json格式如下：

{“prop1”:

{“value”:

1,“time”:

00},

“prop2”:

{“value”:

“test”,“time”:

00}}

当使用tm_data接口进行打包时可参考以下方式：

void*data=tm_data_create（）;

tm_data_set_int32（data,“prop1”,1,00）;

tm_data_set_string（data,“prop2”,“test”,00）;

//对于每个属性功能点都可以调用相应的tm_data_set_xxx接口来向data中打包数据，然后调用tm_pack_device_data将data及其对应的产品信息进行打包，再进行发送

3.2.6上报历史数据

功能

向平台批量上报若干设备的历史属性、事件

函数定义

int32_ttm_post_history_data（void*history_data,uint32_ttimeout_ms）

参数

history_data：

调用tm_pack_device_data打包的返回数据指针

timeout_ms：

超时时间（毫秒）

返回值

0：

上报成功

调用tm_pack_device_data时，传入的属性和事件的json格式如下：

{“prop1”:

[{“value”:

1,“time”:

00},{“value”:

2,“time”:

00}],

“prop2”:

[{“value”:

“test”,“time”:

00}]}

3.3子设备接口

3.3.1子设备功能初始化

功能

为设备初始化子设备通道。

（目前仅MQTT协议可用）

函数定义

int32_ttm_subdev_init（structtm_subdev_cbscallbacks）

参数

callbacks：

子设备数据下发处理回调，定义参考移植说明。

返回值

0：

初始化成功

说明

需要在调用tm_init后使用

其中，struct_subdev_cbs定义如下：

功能

子设备属性获取

函数定义

int（*subdev_props_get）（constint8_t*product_id,constint8_t*dev_name,constint8_t*props_list,int8_t**props_data）

参数

product_id：

需要获取的子设备产品ID

dev_name：

需要获取的子设备名称

props_list：

需要获取的属性列表，json格式，例如“[“prop1”,“prop2”]”

props_data：

返回的属性数据，json格式，例如“{“prop1”:

1,“prop2”:

3}”

返回值

0：

获取成功，其它：

获取失败

说明

返回参数props_data指向的地址空间不得使用静态地址。

功能

子设备属性设置

函数定义

int（*subdev_props_set）（constint8_t*product_id,constint8_t*dev_name,int8_t*props_data）

参数

product_id：

需要获取的子设备产品ID

dev_name：

需要获取的子设备名称

props_data：

需要设置的属性数据，json格式，例如“{“prop1”:

1,“prop2”:

3}”

返回值

0：

设置成功，其它：

设置失败

功能

子设备服务调用

函数定义

int（*subdev_service_invoke）（constint8_t*product_id,constint8_t*dev_name,constint8_t*svc_id,int8_t*in_data,int8_t**out_data）

参数

product_id：

需要调用的子设备产品ID

dev_name：

需要调用的子设备名称

svc_id：

需要调用的子设备服务标识符

in_data：

服务输入参数，json格式，例如“{“in1”:

1,“in2”:

3}”

out_data：

服务输出参数，json格式，例如“{“out”:

4}”

返回值

0：

服务调用成功

说明

返回参数out_data指向的地址空间不得使用静态地址。

功能

拓扑关系同步

函数定义

int（*subdev_topo）（int8_t*topo_data）

参数

topo_data：

平台下发的拓扑关系，包含当前网关设备已绑定的子设备信息，json格式，例如

“[{“productID”:

“pid1”,“deviceName”:

“dev1”},{“productID”:

“pid2”,“deviceName”:

“dev2”}]”

返回值

0：

同步成功

3.3.2添加子设备

功能

将指定子设备绑定到当前网关设备。

函数定义

int32_ttm_subdev_add（constint8_t*product_id,constint8_t*dev_name,constint8_t*access_key,uint32_ttimeout_ms）

参数

product_id：

子设备产品ID

dev_name：

子设备名称

access_key：

子设备产品key

timout_ms：

超时时间（毫秒）

返回值

0：

添加成功

说明

3.3.3删除子设备

功能

将指定子设备解除与当前网关设备的绑定关系。

函数定义

int32_ttm_subdev_delete（constint8_t*product_id,constint8_t*dev_name,constint8_t*access_key,uint32_ttimeout_ms）

参数

product_id：

子设备产品ID

dev_name：

子设备名称

access_key：

子设备产品key

timout_ms：

超时时间（毫秒）

返回值

0：

添加成功

说明

3.3.3获取子设备拓扑关系

功能

从平台获取当前网关绑定的子设备信息

函数定义

int32_ttm_subdev_topo_get（uint32_ttimeout_ms）

参数

timout_ms：

超时时间（毫秒）

返回值

0：

获取成功

说明

获取的子设备拓扑关系将通过tm_subdev_init注册的subdev_topo回调返回

3.3.4子设备登录

功能

子设备登录平台

函数定义

int32_ttm_subdev_login（constint8_t*product_id,constint8_t*dev_name,uint32_ttimeout_ms）

参数

product_id：

需要登录的子设备产品ID

dev_name；需要登录的子设备名称

timout_ms：

超时时间（毫秒）

返回值

0：

登录成功

说明

子设备登录前需确保已绑定到当前网关

3.3.5子设备登出

功能

子设备登出平台

函数定义

int32_ttm_subdev_logout（constint8_t*product_id,constint8_t*dev_name,uint32_ttimeout_ms）

参数

product_id：

需要登出的子设备产品ID

dev_name；需要登出的子设备名称

timout_ms：

超时时间（毫秒）

返回值

0：

登出成功

3.3.5子设备上报数据

功能

子设备上报数据到平台

函数定义

int32_ttm_subdev_post_data（constint8_t*product_id,constint8_t*dev_name,int8_t*prop_json,int8_t*event_json,uint32_ttimeout_ms）

参数

product_id：

需要登出的子设备产品ID

dev_name；需要登出的子设备名称

prop_json：

需要上报的属性数据，json格式，例如：

“{“prop1”:

{“value”:

1,“time”:

00}}

event_json：

需要上报的事件数据，json格式，例如：

“{“event1”:

{“value”:

{“a”:

1,“b”:

2},“time”:

00}}

timout_ms：

超时时间（毫秒）

返回值

0：

上报成功

3.4配置文件接口

配置文件由平台定义好物模型之后生成，根据功能点的功能、读写和数据类型，会在配置文件中生成相应的接口函数，不同的功能点对应不同的接口。

3.4.1功能点数组

配置文件中会生成属性和事件功能点结构体数组，数组中会列出定义的功能点的读写类型和标识符信息，在调用3.2.1接口时，用户需将功能点数组及其长度作为参数传入。

功能点类型

数组名

数组长度

属性

tm_prop_list

tm_prop_list_size

服务

tm_svc_list

tm_svc_list_size

3.4.2数据下发（写属性点）

功能

用于接收平台下发的功能点数据，生成条件为功能点具备写操作

函数定义

int32_ttm_prop_yyy_wr_cb（void*data）

参数

data：

数据资源

返回值

0：

下发操作成功；其他：

下发操作失败

说明

yyy为功能点标识符，只有属性功能点具备写操作

3.4.3数据下发（读属性点）

功能

用于接收平台下发的功能点数据，生成条件为功能点具备读操作

函数定义

int32_ttm_prop_yyy_rd_cb（void*data）

参数

data：

数据资源

返回值

0：

下发操作成功；其他：

下发操作失败

说明

yyy为功能点标识符，只有属性功能点具备写操作

3.4.4数据下发（服务调用）

功能

用于接收平台下发的功能点数据，生成条件为功能点具备读操作

函数定义

int32_ttm_svc_yyy_cb（void*in_data,void*out_data）

参数

in_data：

由平台下发的服务执行输入数据

out_data：

需要返回平台的的服务执行输出数据

返回值

0：

下发操作成功；其他：

下发操作失败

说明

yyy为功能点标识符，只有属性功能点具备写操作

3.4.5数据上传

功能

以阻塞方式上传功能点数据，生成条件为功能点具备读操作

函数定义

int32_ttm_xxx_yyy_notify（

void*data,

zzzval,

uint64_ttimestamp,

uint32_ttimeout_ms

）

参数

data：

数据资源

val：

上传数据

timestamp：

时间戳（没有则为0）

timeout_ms：

上传超时时间（毫秒）

返回值

0：

上传成功；其他：

上传失败

说明

xxx为prop或event（由功能类型决定），yyy为功能点标识符，zzz为数据类型

3.5系统适配接口

3.5.1内存接口

3.5.1.1内存分配

功能

内存分配

函数定义

void*osl_malloc（size_tsize）

参数

size：

申请内存长度

返回值

若分配成功，则返回指向被分配内存区域的指针；若分配失败，则返回NULL

3.5.1.2内存释放

功能

内存释放

函数定义

voidosl_free（void*ptr）

参数

ptr：

待释放内存区域地址

返回值

无

3.5.1.3内存拷贝

功能

将源内存中的值拷贝到目标内存中

函数定义

void*osl_memcpy（void*dst,constvoid*src,size_tn）

参数

dst：

目标内存地址

src：

源内存地址

n：

拷贝字节数

返回值

无

3.5.1.4内存初始化

功能

内存区域初始化，将指定内存区域设置为某个值

函数定义

void*osl_memset（void*dst,int32_tval,size_tn）

参数

dst：

待初始化内存区域地址

val：

待初始化值

n：

待初始化内存区域长度

返回值

无

3.5.2网络接口

3.5.2.1TCP接口

3.5.2.1.1创建网络连接

功能

创建TCP连接

函数定义

handle_ttcp_connect（

constchar*host,

uint16_tport,

uint32_ttimeout_ms

）

参数

host：

目标地址，支持点分十进制IP和域名形式

port：

目标端口

timeout_ms：

执行连接的超时时间（毫秒）

返回值

-1：

失败；其他：

网络操作句柄

3.5.2.1.2数据发送

功能

发送TCP数据

函数定义

int32_ttcp_send（

handle_thandle,

void*buf,

uint32_tlen,

uint32_ttimeout_ms

）

参数

handle：

网络操作句柄

buf：

需要发送的数据缓冲区地址

len：

需要发送的数据长度

timeout_ms：

执行发送的超时时间（毫秒）

返回值

-1：

失败；0：

超时；其他：

成功发送的数据长度

3.5.2.1.3数据接收

功能

接收TCP数据

函数定义

int32_ttcp_recv（

handle_thandle,

void*buf,

uint32_tlen,

uint32_ttimeout_ms

）

参数

handle：

网络操作句柄

buf：

用于接收数据的缓冲区地址

len：

需要接收的数据长度

timeout_ms：

执行接收的超时时间（毫秒）

返回值

-1：

失败；0：

超时；其他：

成功接收的数据长度

3.5.2.1.4断开网络连接

功能

断开TCP连接

函数定义

int32_ttcp_disconnect（handle_thandle）

参数

handle：

需要断开的网络操作句柄

返回值

0：

成功

3.5.2.2UDP接口

3.5.2.2.1创建网络连接

功能

创建UDP连接

函数定义

handle_tudp_connect（constchar*host,uint16_tport）

参数

host：

目标地址，支持点分十进制IP和域名形式

port：

目标端口

返回值

-1：

失败；其他：

网络操作句柄

3.5.2.2.2数据发送

功能

发送UDP数据

函数定义

int32_tudp_send（

handle_thandle,

void*buf,

uint32_tlen,

uint32_ttimeout_ms

）

参数

handle：

网络操作句柄

buf：

需要发送的数据缓冲区地址

len：

需要发送的数据长度

timeout_ms：

执行发送的超时时间（毫秒）

返回值

-1：

失败；0：

超时；其他：

成功发送的数据长度

3.5.2.2.3数据接收

功能

接收UDP数据

函数定义

int32_tudp_recv（

handle_thandle,

void*buf,

uint32_tlen,

uint32_ttimeout_ms

）

参数

handle：

网络操作句柄

buf：

用于接收数据的缓冲区地址

len：

需要接收的数据长度

timeout_ms：

执行接收的超时时间（毫秒）

返回值

-1：

失败；0：

超时；其他：

成功接收的数据长度

3.5.2.2.4断开网络连接

功能

断开UDP连接

函数定义

int32_tudp_disconnect（handle_thandle）

参数

handle：

需要断开的网络操作句柄

返回值

0：

成功

3.5.3时间接口

3.5.3.1获取系统时间

功能

获取毫秒级时间计数

函数定义

uint64_ttime_count_ms（void）

参数

无

返回值

当前毫秒级计数值