OneNET 软件包使用指南
准备工作
OneNET 注册及 ENV 配置
这一部分的内容请阅读软件包中示例说明文档，完成 OneNET 平台的注册和 ENV 的配置。
OneNET port 接口移植（仅适用于开启自动注册功能）
不启用自动注册不需要移植接口，如需启用自动注册功能，请详细阅读软件包中的移植说明文档，完成移植工作。
开始使用
OneNET 初始化
在 ENV 里面已经配置好了连接云平台需要的各种信息，直接调用onenet_mqtt_init函数进行初始化即可，设备会自动连接 OneNET 平台。
推送数据
当需要上传数据时，可以按照数据类型选择对应的 API 来上传数据。代码示例如下：
char str[] = { "hello world" };
/* 获得温度值 */
temp = get_temperature_value();
/* 将温度值上传到 temperature 数据流 */
onenet_mqtt_upload_digit("temperature",temp);
/* 将hello world上传到 string 数据流 */
onenet_mqtt_upload_string("string",str);
除了支持上传数字和字符串外，软件包还支持上传二进制文件。
可以通过onenet_mqtt_upload_bin或onenet_mqtt_upload_bin_by_path来上传二进制文件。代码示例如下
uint8_t buf[] = {0x01, 0x02, 0x03};
/* 将根目录下的1.bin文件上传到 bin 数据流 */
onenet_mqtt_upload_bin_by_path("bin", "/1.bin");
/* 将 buf 中的数据上传到 bin 数据流 */
onenet_mqtt_upload_bin(("bin", buf, 3);
命令接收
OneNET 支持下发命令，命令是用户自定义的。用户需要自己实现命令响应回调函数，然后利用onenet_set_cmd_rsp_cb将回调函数装载上。当设备收到平台下发的命令后，会调用用户实现的命令响应回调函数，等待回调函数执行完成后，将回调函数返回的响应内容再发给云平台。保存响应的内存必须是动态申请出来的，在发送完响应后，程序会自动释放申请的内存。代码示例如下：
static void onenet_cmd_rsp_cb(uint8_t *recv_data, size_t recv_size,uint8_t **resp_data,
size_t *resp_size)
{
/* 申请内存 */
/* 解析命令 */
/* 执行动作 */
/* 返回响应 */
}
int main()
{
/* 用户代码 */
onenet_mqtt_init();
onenet_set_cmd_rsp_cb(onenet_cmd_rsp_cb);
/* 用户代码 */
}
信息获取
数据流信息获取
用户可以通过onenet_http_get_datastream来获取数据流的信息，包括数据流 id，数据流最后更新时间，数据流单位，数据流当前值等等，获取的数据流信息会保存在传入的 datastream 结构体指针所指向的结构体中。代码示例如下
struct rt_onenet_ds_info ds_temp;
/* 获取到 temperature 数据流的信息后保存到 ds_temp 结构体中 */
onenet_http_get_datastream("temperature",ds_temp);
数据点信息获取
数据点信息可以通过以下 3 个 API 来获取
cJSON _onenet_get_dp_by_limit(char _ds_name, size_t limit);cJSON _onenet_get_dp_by_start_end(char _ds_name, uint32_t start, uint32_t end, size_t limit);cJSON _onenet_get_dp_by_start_duration(char _ds_name, uint32_t start, size_t duration, size_t limit);
这三个 API 返回的都是 cJSON 格式的数据点信息，区别只是查询的方法不一样，下面通过示例来讲解如何使用这 3 个 API。
/* 获取 temperature 数据流的最后10个数据点信息 */
dp = onenet_get_dp_by_limit("temperature",10);
/* 获取 temperature 数据流2018年7月19日14点50分0秒到2018年7月19日14点55分20秒的前10个
数据点信息 */
/* 第二、三个参数是Unix时间戳 */
dp = onenet_get_dp_by_start_end("temperature",1531983000，1531983320，10);
/* 获取 temperature 数据流2018年7月19日14点50分0秒往后50秒内的前10个数据点信息 */
/* 第二个参数是Unix时间戳 */
dp = onenet_get_dp_by_start_end("temperature",1531983000，50，10);
注意事项
设置命令响应回调函数之前必须要先调用onenet_mqtt_init函数，在初始化函数里会将回调函数指向RT_NULL。
命令响应回调函数里存放响应内容的 buffer 必须是 malloc 出来的，在发送完响应内容后，程序会将这个 buffer 释放掉。
OneNET API
初始化
OneNET 初始化
int onenet_mqtt_init(void);
OneNET 初始化函数，需要在使用 OneNET 功能前调用。
设置命令响应函数
void onenet_set_cmd_rsp_cb(void(_cmd_rsp_cb)(uint8_t _recv_data, size_t recv_size, uint8_t *_resp_data, size_t _resp_size));
设置命令响应回调函数。
数据上传
mqtt 上传数据到指定主题
rt_err_t onenet_mqtt_publish(const char _topic, const uint8_t _msg, size_t len);
利用 mqtt 向指定 topic 发送消息。
mqtt 上传字符串到 OneNET
rt_err_t onenet_mqtt_upload_string(const char _ds_name, const char _str);
利用 mqtt 向 OneNET 平台发送字符串数据。
mqtt 上传数字到 OneNET
rt_err_t onenet_mqtt_upload_digit(const char *ds_name, const double digit);
利用 mqtt 向 OneNET 平台发送数字数据。
mqtt 上传二进制文件到 OneNET
rt_err_t onenet_mqtt_upload_bin(const char _ds_name, const uint8_t _bin, size_t len);
利用 mqtt 向 OneNET 平台发送二进制文件。会动态申请内存来保存二进制文件，使用前请确保有足够的内存。
mqtt 通过路径上传二进制文件到 OneNET
rt_err_t onenet_mqtt_upload_bin_by_path(const char _ds_name, const char _bin_path);
利用 mqtt 向 OneNET 平台发送二进制文件。
http 上传字符串到 OneNET
rt_err_t onenet_http_upload_string(const char _ds_name, const char _str);
利用 http 向 OneNET 平台发送字符串数据，不推荐使用，推荐使用mqtt上传。
http 上传数字到 OneNET
rt_err_t onenet_http_upload_digit(const char *ds_name, const double digit);
利用 http 向 OneNET 平台发送数字数据，不推荐使用，推荐使用mqtt上传。
信息获取
获取数据流信息
rt_err_t onenet_http_get_datastream(const char _ds_name, struct rt_onenet_ds_info _datastream);
从 OneNET 平台获取指定数据流信息，并将信息保存在 datastream 结构体中。
获取最后N个数据点信息
cJSON _onenet_get_dp_by_limit(char _ds_name, size_t limit);
从 OneNET 平台获取指定数据流的 n 个数据点信息。
获取指定时间内的数据点信息
cJSON _onenet_get_dp_by_start_end(char _ds_name, uint32_t start, uint32_t end, size_t limit);
从 OneNET 平台获取指定数据流指定时间段内的n个数据点信息。时间参数需要填入Unix时间戳。
获取指定时间n秒的数据点信息
cJSON _onenet_get_dp_by_start_duration(char _ds_name, uint32_t start, size_t duration, size_t limit);
从 OneNET 平台获取指定数据流指定时间后n秒内的n个数据点信息。时间参数需要填入Unix时间戳。
设备管理
注册设备
rt_err_t onenet_http_register_device(const char _dev_name, const char _auth_info);
向 OneNET 平台注册设备，并返回设备 id 和 apikey。设备id 和 apikey 会调用 onenet_port_save_device_info交由用户处理。
保存设备信息
rt_err_t onenet_port_save_device_info(char _dev_id, char _api_key);
保存注册后返回的设备信息，需要用户实现。
获取设备注册信息
rt_err_t onenet_port_get_register_info(char _dev_name, char _auth_info);
获取注册设备需要的信息，需要用户实现。
获取设备信息
rt_err_t onenet_port_get_device_info(char _dev_id, char _api_key, char *auth_info);
获取设备信息用于登陆 OneNET 平台，需要用户实现。
设备是否注册
rt_bool_t onenet_port_is_registed(void);
判断设备使用已经注册，需要用户实现。
OneNET 包移植说明
本文主要介绍拿到 OneNET 软件包后，需要做的移植工作。
OneNET 软件包已经将硬件平台相关的特性剥离出去，因此 OneNET 本身的移植工作非常少，如果不启用自动注册功能就不需要移植任何接口。
如果启用了自动注册，用户需要新建 onenet_port.c ，并将文件添加至工程。onenet_port.c 主要是实现开启自动注册后，获取注册信息、获取设备信息和保存设备信息等功能。接口定义如下所示：
/* 检查是否已经注册 */
rt_bool_t onenet_port_is_registed(void);
/* 获取注册信息 */
rt_err_t onenet_port_get_register_info(char *dev_name, char *auth_info);
/* 保存设备信息 */
rt_err_t onenet_port_save_device_info(char *dev_id, char *api_key);
/* 获取设备信息 */
rt_err_t onenet_port_get_device_info(char *dev_id, char *api_key, char *auth_info);
获取注册信息
rt_err_t onenet_port_get_register_info(char _ds_name, char _auth_info)
开发者只需要在该接口内，实现注册信息的读取和拷贝即可。
onenet_port_get_register_info(char *dev_name, char *auth_info)
{
/* 读取或生成设备名字和鉴权信息 */
/* 将设备名字和鉴权信息分别拷贝到 dev_name 和 auth_info 中*/
}
保存设备信息
rt_err_t onenet_port_save_device_info(char _dev_id, char _api_key)
开发者只需要在该接口内，将注册返回的设备信息保存在设备里即可。
onenet_port_save_device_info(char *dev_id, char *api_key)
{
/* 保存返回的 dev_id 和 api_key */
/* 保存设备状态为已注册状态 */
}
检查是否已经注册
rt_bool_t onenet_port_is_registed(void)
开发者只需要在该接口内，返回本设备是否已经在 OneNET 平台注册即可。
onenet_port_is_registed(void)
{
/* 读取并判断设备的注册状态 */
/* 返回设备是否已经注册 */
}
获取设备信息
rt_err_t onenet_port_get_device_info(char _dev_id, char _api_key, char *auth_info)
开发者只需要在该接口内，读取并返回设备信息即可
onenet_port_get_device_info(char *dev_id, char *api_key, char *auth_info)
{
/* 读取设备id，api_key和鉴权信息 */
/* 将设备id，api_key和鉴权信息分别拷贝到 dev_id，api_key 和 auth_info 中*/
}
原作者：RT-Thread 软件包手册
2
/6 
工商网监
湘ICP备2023018690号
3175
淘帖
8
