onenet studio sdk使用说明

Overview

在进行介绍 one studio sdk使用之前需要厘清几个概念的东西。
（1）子设备、直连设备、网关设备：子设备是没有ip地址的，所以它需要依托于网关设备进行预云平台的通信；直连设备是有IP地址的，所以它既可以依托于网关设备进行与云平台的通信，也可以通过自身与云平台进行连接；最后，网关设备也可以说是直连设备，但是它不仅仅可以上传自身的数据，还可以作为子设备的数据的中转站，所以他还需要有各种能和子设备进行通信的模块。到此三种设备之间的关系应该就清楚了吧。
（2）说明：在本文中仅仅介绍使用sdk的部分api来进行设备的登录和数据流转。

如果你是喜欢从头看到尾的的顺序，希望你可以看看特殊接口函数，它们起到了维持登录状态、数据解析等功能。需要在流程中间进行适当的调用。

管方的参考文档见参考链接;

宏定义

在onenet 的sdk中有许多的宏定义，通过指定这些宏定义来指定不同的传输协议、传输缓冲区、最大传输数据长度等，还能通过指定宏定义开启一些额外的服务和功能。如下图，【但是下图的并不完全，有一些宏定义在sdk文件中的CMakeLists.txt中可以看到一部分】

设备登录、登出云平台

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

直连设备登录、登出云平台

登录流程：

（1）设备初始化
功能 —— 设备初始化，需传入配置文件中生成的属性功能点数组及其长度，【但是如果你不想用配置文件中的函数接口就可以只传入空的数组，其长度定义为0】

函数定义 —— int32_t tm_init(struct tm_downlink_tbl_t *downlink_tbl)

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

返回值 —— 0：初始化成功；-1：初始化失败
说明 —— 这个是在调用设备登录函数之前使用的

（2）设备登录
功能 —— 发起设备登录请求，需传入产品与设备相关信息（产品id、设备id（其实就是设备名）、密钥【可以是产品界面的accesskey，也可以是设备界面的设备密钥】）

函数定义 —— int32_t tm_login(const int8_t *product_id,const int8_t *dev_name,const int8_t *access_key,uint32_t timeout_ms)

参数值 —— product_id：产品 id
dev_name：设备名称
access_key：产品 key
timeout_ms：超时时间（毫秒）【超过时间就会返回执行结果，所以是非阻塞的】

返回值 —— 0：登录成功；-1：登录失败

（3）到此，如果没有报错就是登陆成功了，可以在onenet云平台上看到设备登录状态。

登出流程

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

函数定义 —— int32_t tm_logout(uint32_t timeout_ms)

参数 —— timeout_ms：超时时间（毫秒）

返回值 —— 0：注销成功

注意：需要设备初始化成功才可以调用，不然很有可能会发生段错误。

子设备登录、登出云平台

登录流程

功能 子设备登录平台
函数定义 int32_t tm_subdev_login(const int8_t *product_id, const int8_t
*dev_name, uint32_t timeout_ms)
参数
product_id：需要登录的子设备产品 ID
dev_name；需要登录的子设备名称
timout_ms：超时时间（毫秒）
返回值 0：登录成功
说明 子设备登录前需确保已绑定到当前网关

登出流程

功能 子设备登出平台
函数定义 int32_t tm_subdev_logout(const int8_t *product_id, const int8_t
*dev_name, uint32_t timeout_ms)
参数
product_id：需要登出的子设备产品 ID
dev_name；需要登出的子设备名称
timout_ms：超时时间（毫秒）
返回值 0：登出成功

到目前还是十分顺利和简单的。

设备数据传输

直连设备数据传输

上行

直连设备上传数据的api是和批量上传子设备的数据的api是不同的。
直连设备需要用到：
（1）void *data = tm_data_create();

（2） 对于每个属性功能点都可以调用相应的 tm_data_set_xxx 接口来向 data 中打包数据，
tm_data_set_int32(data, “prop1”, 1, 1603329629000);
tm_data_set_string(data, “prop2”, “test”, 1603329629000);
具体的有哪些tm_data_set_xxx接口可以参考tm_data.h
（3）然后上传网关的数据需要用这个： uint32_t tm_post_property(resource, timeout);
网关的数据不需要进行打包。

（1）（2）同样适用于子设备，然后调用 tm_pack_device_data 将 data 及其对应的产品信息进行打包，再进行发送。

下行

获取期望属性
功能 获取平台为设备设置的期望属性值
函数定义 int32_t tm_get_desired_props(uint32_t timeout_ms)
参数 timeout_ms：超时时间（毫秒）
返回值 0：获取成功
说明 调用接口后，SDK 内部解析平台下发的期望属性值，将自动调用
对应的写属性接口。

子设备数据传输

上行

通过网关设备上传多个字设备数据流程：

（1）打包设备数据
功能 打包设备的属性和事件数据，可用于子设备。
函数定义 void* tm_pack_device_data(void *data, const int8_t *product_id,
const int8_t *dev_name, void *prop, void *event, int8_t as_raw)
参数
data：需要打包的目标指针地址，用于后续调用上报接口。设置
为空时由接口内部分配空间，并通过返回值返回地址
product_id：需要打包数据的产品 id
dev_name：需要打包数据的设备名称
prop：传入属性数据。支持 json 格式(as_raw 为 1)，也可以仿照
tm_user 文件的数据上传接口使用 tm_data 接口构造数据（as_raw
为 0）
event：定义同 prop，用于传入事件数据
返回值 打包后的数据指针地址
（2）上报批量数据
功能 向平台批量上报若干设备的属性、事件
函数定义 int32_t tm_post_pack_data(void *pack_data, uint32_t timeout_ms)
参数 pack_data：调用 tm_pack_device_data 打包的返回数据指针
timeout_ms：超时时间（毫秒）
返回值 0：上报成功
调用 tm_pack_device_data 时，传入的属性和事件的 json 格式如下：
{“prop1”:{ “value”:1, “time”:1603329629000},
“prop2”:{ “value”: “test”, “time”:1603329629000}}

子设备除了上面提到的这个流程之外，还可以参考直连设备设置属性的方式进行打包上传子设备数据

上传单个子设备数据到平台

子设备上报数据
功能 子设备上报数据到平台
函数定义
int32_t tm_subdev_post_data(const int8_t *product_id, const int8_t
*dev_name, int8_t *prop_json, int8_t *event_json, uint32_t
timeout_ms)
参数
product_id：需要登出的子设备产品 ID
dev_name；需要登出的子设备名称
prop_json：需要上报的属性数据，json 格式，例如：
“{“prop1”:{ “value”:1, “time”:1603329629000}}
event_json：需要上报的事件数据，json 格式，例如：
“{“event1”:{ “value”:{ “a”:1, “b”:2}, “time”:1603329629000}}
timout_ms：超时时间（毫秒）
返回值 0：上报成功

下行

子设备属性设置和子设备属性获取等可以参考子设备功能函数。

特殊接口函数

功能 解析平台下发的数据
函数定义 int32_t tm_step(uint32_t timeout_ms)
参数 timeout_ms：超时时间（毫秒）
返回值 0：解析正常；-1：解析错误
说明
需在设备登录成功之后反复调用，若数据解析错误（由网络异常
等原因引起），则需注销设备，然后重新登录；超时时间推荐设置
200ms

期望属性相关

清除期望属性
功能 清除平台为设备设置的期望属性值
函数定义 int32_t tm_delete_desired_props(uint32_t timeout_ms)
参数 timeout_ms：超时时间（毫秒）
返回值 0：清除成功
说明 默认清除平台侧配置的所有期望属性值。

当使用 tm_data 接口进行打包时可参考以下方式：
void *data = tm_data_create();
tm_data_set_int32(data, “prop1”, 1, 1603329629000);
tm_data_set_string(data, “prop2”, “test”, 1603329629000);
// 对于每个属性功能点都可以调用相应的 tm_data_set_xxx 接口来向 data 中打包数据，
然后调用 tm_pack_device_data 将 data 及其对应的产品信息进行打包，再进行发送

注意这两个期望相关的接口都是要根据设备端初始化的属性点列表进行获取和清除属性期望值的。需要重点关注的是这两个接口针对的是属性的期望值，而不是属性点的值，这两者是有区别的，首先，属性的值可以在平台的产品开发属性点界面看到，但是属性期望值就是需要再应用调试的属性期望设置看到了，如下两张图：
（1）属性值

（2）属性期望值

上报历史数据
功能 向平台批量上报若干设备的历史属性、事件
函数定义 int32_t tm_post_history_data(void *history_data, uint32_t
timeout_ms)
参数 history_data：调用 tm_pack_device_data 打包的返回数据指针
timeout_ms：超时时间（毫秒）
返回值 0：上报成功
调用 tm_pack_device_data 时，传入的属性和事件的 json 格式如下：
{“prop1”:[{ “value”:1, “time”:1603329629000},{ “value”:2, “time”:1603329630000}],
“prop2”:[{ “value”: “test”, “time”:1603329629000}]}

子设备功能函数【属于回调函数】

关系到子设备的拓扑关系获取等【这些功能都是通过回调函数的方式进行返回获取到的结果的，就是这些函数指针就是获取到的结果，你可以定义一个函数来赋值给结构体的函数指针来操作这些结果】

子设备功能初始化

功能 为设备初始化子设备通道。(目前仅 MQTT 协议可用)
函数定义 int32_t tm_subdev_init(struct tm_subdev_cbs callbacks)
参数 callbacks：子设备数据下发处理回调，定义参考移植说明。
返回值 0：初始化成功
说明 需要在调用 tm_init 后使用
其中，struct tm_subdev_cbs 定义如下：

子设备属性获取

功能 子设备属性获取
函数定义 int (*subdev_props_get)(const int8_t *product_id, const int8_t
*dev_name, const int8_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)(const int8_t *product_id, const int8_t
*dev_name, int8_t *props_data)
参数
product_id：需要获取的子设备产品 ID
dev_name：需要获取的子设备名称
props_data：需要设置的属性数据，json 格式，例如
“{“prop1”:1,“prop2”:3}”
返回值 0：设置成功，其它：设置失败

子设备服务调用

功能 子设备服务调用
函数定义 int (*subdev_service_invoke)(const int8_t *product_id, const int8_t
*dev_name, const int8_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：同步成功
应用场景：1、获取平台的拓扑关系；2、根据平台的拓扑关系添加或删除设备；

操作子设备接口

添加子设备

功能 将指定子设备绑定到当前网关设备。
函数定义 int32_t tm_subdev_add(const int8_t *product_id, const int8_t
*dev_name, const int8_t *access_key, uint32_t timeout_ms)
参数
product_id：子设备产品 ID
dev_name：子设备名称
access_key：子设备产品 key
timout_ms：超时时间（毫秒）
返回值 0：添加成功
说明

删除子设备

功能 将指定子设备解除与当前网关设备的绑定关系。
函数定义 int32_t tm_subdev_delete(const int8_t *product_id, const int8_t
*dev_name, const int8_t *access_key, uint32_t timeout_ms)
参数
product_id：子设备产品 ID
dev_name：子设备名称
access_key：子设备产品 key
timout_ms：超时时间（毫秒）
返回值 0：添加成功
说明

获取子设备拓扑关系

功能 从平台获取当前网关绑定的子设备信息
函数定义 int32_t tm_subdev_topo_get(uint32_t timeout_ms)
参数 timout_ms：超时时间（毫秒）
返回值 0：获取成功
说明 获取的子设备拓扑关系将通过 tm_subdev_init 注册的 subdev_topo回调返回

配置文件接口函数

数据下发（写属性点）
功能 用于接收平台下发的功能点数据，生成条件为功能点具备写操作
函数定义 int32_t tm_prop_yyy_wr_cb(void *data)
参数 data：数据资源
返回值 0：下发操作成功；其他：下发操作失败
说明 yyy 为功能点标识符，只有属性功能点具备写操作
注意：这个函数是用来接收平台下发的数据的，应用场景：就是当在平台使用api或者调试工具中的应用调试选择某个属性点进行属性设置的时候，在设备端会自动调用这个接口函数，并根据你在这个接口函数中定义好的函数体进行操作【可以获取到平台设置的值，或者根据获取到的值进行添加相应的操作代码，具体这个值是通过什么传递过来的，可以参考默认的接口函数体】

数据下发（读属性点）
功能 用于接收平台下发的功能点数据，生成条件为功能点具备读操作
函数定义 int32_t tm_prop_yyy_rd_cb(void *data)
参数 data：数据资源
返回值 0：下发操作成功；其他：下发操作失败
说明 yyy 为功能点标识符，只有属性功能点具备写操作
注意：这个函数是用来接收平台下发的数据的，应用场景：就是当在平台使用api或者调试工具中的应用调试选择某个属性点进行属性获取的时候，在设备端会自动调用这个接口函数【可以获取到设备端设置的值，或者添加相应的操作代码，在设备端设置的这个值会传递到平台】

值得注意的是，这两个接口函数都是应用端对设备端的相应读写操作，并且读写的值不会设置到平台相应的属性点。
剩下的都可以参考文档了，比较简单，同理比对就可以很快得出用法。

参考链接

最后附上onenet官方的studio sdk说明书OneNET_Studio_sdk_v1.2.0.pdf,看这个文档真不知道如何使用，所以通过笔记记录下来，分享一波，希望有借鉴意义。