OneNet接入用户手册--实战篇v1.0.pdf

1、 1 / 66 OneNet 接入用户手册 实战篇 v1.0 2 / 66 目 录 1. 准备工作 . 3 1.1 接入流程总览 3 1.2 用户注册 3 2. 添加设备 . 5 3. 通信方式选择 9 4. 用调试工具连接平台 9 4.1 GPRS 方式 . 11 4.1.1 硬件准备 . 12 4.1.2 串口配置 . 14 4.1.3 RestFul API 上传数据 . 16 4.1.4 EDP 协议上传数据 . 20 4.2 WIFI 方式 25 4.2.1 准备工作 25 4.2.2 串口配置 . 26 4.2.3 RestFul API 上传数据 . 26 4.2.4 EDP 方

2、式上传数据 . 28 4.3 以太网口 31 4.3.1 准备工作 31 4.3.2 RestFul API 上传数据 . 32 4.3.3 EDP 方式上传数据 . 32 5. 硬件选择 . 35 6. 代码实例 . 36 6.1 ONENET 数据上传（ EDP 协议） . 37 6.2 数据（透传）转发（ EDP 协议） . 40 6.3 RESTFUL API 数据上传 . 47 6.4 事件告警（触发器使用） . 52 7. 添加应用 . 59 8. 常见问题 . 64 3 / 66 1. 准备工作 1.1 接入流程总览 OneNet 接入过程大致如下： 开 始用 户 注 册数 据

3、上 传结 束终 端 和 服 务 器 建立 T C P 连 接设 备 创 建用户要接入 OneNet，首先要在 OneNet 平台上进行注册用户、创建设备等一系列准备工作，然后要通过网络和 OneNet 服务器建立TCP 连接，最后将用户数据按照一定的协议 (比如： EDP、 RestFul API)打包上传至 OneNet 平台，从而实现设备终端接入。 1.2 用户注册 在接入 OneNet 之前，需在平台网站注册用户账户， 登陆网址：http:/ ： 4 / 66 点击云平台入口 ”马上接入 ”： 注册账号并登陆： 5 / 66 2. 添加设备 用户注册账号并登陆后，进入“设备管理”入口，点

4、击“添加一个设备”进行设备创建： 输 入 设备 创建信息 : 6 / 66 EDP 扩展信息设置界面如下，其中默认路由在使用 EDP 协议进行数据转发是才进行设置： 平台收到 EDP 数据消息，若 EDP 数据包中的目的地址长度为 0，即没有目的地址，则平台将该消息转发到设备注册时的默认目的地址即默认路由。 添加数据流 : 7 / 66 在一个设备下面可以连续添加多个数据流，如下图，我们添加了sys_time、 bin_data 两个数据流。 我们可以为我们的设备添加多个不同的 ApiKey，这些 ApiKey可以分发给不同的终端设备，平台使用 ApiKey 对终端设备 进行数据访问鉴权，当要

5、限制某个终端设备访问平台数据的时候，可以改变或者删除分配给该终端设备的 ApiKey，那么该终端设备就无法对平台数据进行操作。这里我们联系添加了两个 ApiKey，添加第一个 ApiKey8 / 66 如下图： 添加第二个 ApiKey： 在触发器模块当中添加触发器，对设定条件的事件告警进行监控，触发器的原理是：一旦监控的数据流数据满足设定的条件，就会触发一个 HTTP 请求，将异常事件的内容发送给设定的服务器，所以用户9 / 66 如果要使用触发器功能，必须建立自己的 HTTP 服务器，触发器添加如下图所示： 3. 通信方式选择 设备终端接入 OneNet 平台的通信方式也是多种多样的，比较

6、常用的有 GPRS、无线 WIFI、以太网口。 GPRS 方式需要 GPRS 模块和SIM 卡的支持， 无线 WIFI 模块需要 WIFI 模块支持。 4. 用调试工具连接平台 为了熟悉设备云的 接入 过程， 用户 可以在 PC 机上使用测试工具手动连接平台，并向指定设备传输数据，三种通信方式 （ GPRS、无线 WIFI、以太网口） 下，连接平台的操作过程略有不同，下面对三种方式 接入设备云过程 依次进行说明。 我们的目标是向设备云平台设备 ID 为 131658 的设备下 sys_time10 / 66 数据流传输数据一个整型数据 50。 运用 ApiKey1 作为该设备上传数据的 Api

7、Key。 RestFul API 基于 HTTP 协议（详见http:/www.w3.org/Protocols/HTTP/1.0/spec.html）和 json 数据格式（详见 http:/www.json.org/json-zh.html），适合平台资源管理、平台与平台之间数据对接、使用短连接上报终端数据、时间序列化数据存储等场景， EDP 协议基于 TCP 协议的，该协议只传输数据包到达目的地，不保证传输的顺序与到达的顺序相同，事务机制需要在上层实现；若客户端同时发起两次请求，服务器返回时，不保障返回报文的顺序。，EDP 协议适合于数据的长连接上报、透传、转发、存储、数据主动下发等场景

8、。 下面分别讲述 在 PC 机上使用测试工具运用 RestFul API 方式和EDP 方式手动连接平台，并向指定设备传输数据上传数据过程，旨在让大家了解数据上传的基本过程和原理。 按照 RestFul 方式封装的数据包为： 按照以上方式封装数据包的过程中，需要注意： 1）每行结束的回车换行符不能少； 2） Content-Length 字段的值必须准确，否则服务器无法解析用户数据。 EDP 协议封装的数据包是二进制形式，分为两部分，一部分为设11 / 66 备连接请求，另一部 分为设备所发送的数据，设备连接请求十六进制表示为： /*类型 *剩余包长度 *协议描述 长度 *协议版本 *连接标志

9、 *连接时间（ 128s） *设备 ID 长度 */ 10 2F 00 03 45 44 50 01 40 00 80 00 06 /*设备 ID*ApiKey 长度 *ApiKey（ 128s） */ 31 33 31 36 35 38 00 1C 6D 67 44 69 56 73 51 37 45 38 62 50 55 77 66 42 44 74 54 79 34 4B 38 79 4D /*ApiKey*/ 74 4D 41 我们要上传的 JSON 格式数据为： “datastreams“: “id“: “sys_time“, “datapoints“: “value“: “21“

10、 对应以上 JSON 串按照 EDP 协议进行封装，对应的 EDP 数据 包十六进制表示为： /*类型 *剩余包长度 *ID flag *ID 长度 *设备 ID*JSON 数据 标记 *JSON 长度 */ 80 6A 80 00 06 31 33 31 36 35 38 01 00 5E /*JSON 串 */ 7B 0A 09 22 64 61 74 61 73 74 72 65 61 6D 73 22 3A 09 5B 7B 0A 09 09 09 22 69 64 22 3A 09 22 73 79 73 5F 74 69 6D 65 22 2C 0A 09 09 09 22 64

11、61 74 61 70 6F 69 6E 74 73 22 3A 09 5B 7B 0A 09 09 09 09 09 22 76 61 6C 75 65 22 3A 09 22 32 31 22 0A 09 09 09 09 7D 5D 0A 09 09 7D 5D 0A 7D 需要说明的是，以上 EDP 协议数据包是二进制形式的数据，看上去比较晦涩，这里是为了演示实验， 我们 截取了 程序当中的两个数据包 展示给大家。在实际接入过程中，有相关的数据 包 封装函数（这些函数由开发者社区当中名为 edp_c 的 SDK 包提供）生成这些数据包，用户无需自行封装。 4.1 GPRS 方式 12

12、/ 66 4.1.1 硬件准备 使用 GPRS 传输数据需要 GPRS 模块，下图为一个 SIM900A 模块实物图 ： 该模块支持 3.3V 和 5V TTL 串口输入，同时支持 RS232 串口作为输入，硬件资源示意图如下： 13 / 66 SIM 卡卡座如下图所示： 首先按照图片上箭头的方向用力并稍微用力按压卡座的翻盖将卡座打开。 打开后将 SIM 卡插入卡座中，在将卡座翻盖向上推的同时请稍微向下按压翻盖，即可安装好 SIM 卡。 除此之外 ，需要一用 USB 转 TTL 串口工具，注意在使用前需要安装驱动，这里不在讲述驱动安装过程，将 USB 转 TTL 串口与SIM900A 模块连接

13、，如下图： 14 / 66 4.1.2 串口配置 右键单击“我的电脑”，选择“属性”，进入如下页面，点击“设备管理器”，查看串口编号： 15 / 66 如果 USB 转 TTL 串口的驱动安装正确，在插上 USB 转串口工具后，会出现如下界面： 打开串口调试工具。 选择“ COM11”，并按照下图配置串口： 16 / 66 注意，串口的配置和 SIM900A 模块内串口配置一一对应。 配置完成后点击“ 打开串口 ”按钮打开串口： 4.1.3 RestFul API 上传数据 串口配置完成，就可以利用串口调试工具操作 SIM900A 模块与17 / 66 OneNet 建立连接、传输数据了。 首

14、先在模块串口调试工具中输入“ AT”并加上回车，点击“ 手动发送 ”按钮， SIM900A 模块返回“ OK”，说明模块工作正常，如下图： 依次发送如下几个命令到 SIM900A 模块： AT+CGCLASS=“B“ AT+CGDCONT=1,“IP“,“CMNET“ AT+CGATT=1 AT+CIPCSGP=1,“CMNET“ AT+CLPORT=“TCP“,“2000“ 这几个命令 用于设置移动台类别、连接方式、接入点、 附着 GPRS业务 、设置本地端口 等。起到一个前期准备的作用。 接下来就可以和OneNet 建立 TCP 连接了，发送命令： AT+CIPSTART=“TCP“,“1

15、83.230.40.33“,“80“ /和 OneNet 建立 TCP 连接 AT+CIPSEND /开始数据透传 18 / 66 到此，我们可以发送前面准备好的数据 了，如下图： 并以 0x1a（表示透传结束）结尾 ，结尾 0x1a 必须以十六进制形式发送 ： 19 / 66 返回数据如下： 说明数据上传 OneNet 成功，并且 OneNet 主动关闭了 TCP 连接，那么下次再传数据就必须重新建立连接，重复以下动作： 1）和 OneNet 建立 TCP 连接，发送指令为： AT+CIPSTART= “TCP“,“183.230.40.33“,“80“ 2）开启透传，发送指令为： AT+C

16、IPSEND 3）发送 HTTP 数据包 4）发送透传结束符 这样就可以实现数据持续上传。 在 OneNet 端 的 Demo-test 设备下 （ 设备 ID 为 131658） ，可以观20 / 66 察数据上传的情况： 点击“请求日志”中的任一条记录查看设备上传数据的日志，如下图： 4.1.4 EDP 协议 上传数据 用 EDP 协议接入 OneNet 过程和 RestFul API 方式类似，步骤如下： 21 / 66 1） 配置 GPRS 模块； 模块配置和用 RestFul API 接入 OneNet 相同 ，依次发送如下几个命令到 SIM900A 模块 ： AT+CGCLASS=

17、“B“ AT+CGDCONT=1,“IP“,“CMNET“ AT+CGATT=1 AT+CIPCSGP=1,“CMNET“ AT+CLPORT=“TCP“,“2000“ 注意：这些配置完成后，若模块重新上电，可直接进入第二步，与服务器建立 TCP 连接。 2） 和 OneNet 服务器建立 TCP 连接 ，依次发送命令： AT+CIPMODE=1 /进入透明传输模式 AT+CIPSTART=“TCP“,“183.230.40.39“,“876“ /和服务器建立 TCP 连接 命令执行结果如下图所示： 如图，发送命令 AT+CIPSTART=“TCP“,“183.230.40.39“,“876“

18、后，模块返回： OK CONNECT 表明模块与服务器 183.230.40.39 建立 TCP 连接成功，可以发送数据到服务器。 22 / 66 3） 和 OneNet 上创建的设备建立连接，这里的建立连接和上一步的建立 TCP 连接不是一回事，这里的建立连接主要是和 OneNet 平台上的设备、用户相关联，起着鉴权的作用， 而建立 TCP 连接起着在SIM900A 模块和 OneNet 服务器 之间建立通信管道的作用。 比如，在此我们要关联的设备 ID 为 131658 ，鉴权 ApiKey 为mgDiVsQ7E8bPUwfBDtTy4K8yMtMA，那么 根据这两个信息生成的连接请求数据

19、包 如下 ： 10 2F 00 03 45 44 50 01 40 00 80 00 06 31 33 31 36 35 38 00 1C 6D 67 44 69 56 73 51 37 45 38 62 50 55 77 66 42 44 74 54 79 34 4B 38 79 4D 74 4D 41 发送数据包后返回如下： 如果此处发送的包有错误，服务器会自动关闭 TCP 连接，返回如下： 23 / 66 此时需要返回第二步开始重新建立 TCP 连接。 4） 上传用户数据 与 OneNet 连接请求成功后，就是连续不断向指定的设备发送数据了，发送我们预先准备好的数据包： 80 6A 80

20、 00 06 31 33 31 36 35 38 01 00 5E 7B 0A 09 22 64 61 74 61 73 74 72 65 61 6D 73 22 3A 09 5B 7B 0A 09 09 09 22 69 64 22 3A 09 22 73 79 73 5F 74 69 6D 65 22 2C 0A 09 09 09 22 64 61 74 61 70 6F 69 6E 74 73 22 3A 09 5B 7B 0A 09 09 09 09 09 22 76 61 6C 75 65 22 3A 09 22 32 31 22 0A 09 09 09 09 7D 5D 0A 09

21、 09 7D 5D 0A 7D 选择自动发送，这样 PC 的串口就通过 SIM900A 模块连续不断的上传用户数据了，如下图： 24 / 66 登陆 OneNet，在 Demo-test 设备下，查看数据，如下图： 展开 sys_time 数据流，发现有数据更新，说明数据上传成功 ，注意：运用 EDP 协议上传数据的时候没有请求日志。 25 / 66 4.2 WIFI 方式 4.2.1 准备工作 选用 ESP8266 串口 WIFI 模块，通过 AT 指令控制 WIFI 模块接入互联网，依次完成与接入互联网、与 OneNet 服务器建立 TCP 连接、传输数据等操作， ESP8266 串口 W

22、IFI 模块硬件实物图如下： 与 PC 连接得实物图如下： 26 / 66 4.2.2 串口配置 串口配置请参见 4.1.2 小结：串口配置。 4.2.3 RestFul API 上传数据 串口配置完成，就可以利用串口调试工具操作 ESP8266 串口WIFI 模块，使其与 OneNet 建立连接、传输数据。 首先在模块串口调试工具中输入“ AT”并加上回车，点击“手动发送”按钮， SIM900A 模块返回“ OK”，说明模块工作正常，如下图： 1） 配置 WIFI 模块； 模块配置和用 RestFul API 接入 OneNet 相同， 依次发送如下几个命令到 WIFI 模块： AT+CWM

23、ODE=3 /设置 WIFI 应用模式 AT+RST /重置 WIFI 模块 AT+CIFSR/查询本地 IP AT+CWJAP=“your ssid“,“password“ /连接无线路由器 27 / 66 注意：这些配置完成后，若模块重新上电，可直接进入第二步，与服务器建立 TCP 连接。 2） 和 OneNet 服务器建立 TCP 连接，依次发送命令： AT+CIPSTART=“TCP“,“183.230.40.33“,80 /和服务器建立 TCP 连接 AT+CIPMODE=1 /进入透明传输模式 AT+CIPSEND /开始传输 命令执行结果如下图所示： 到此，我们可以发送前面准备好

24、的数据了，发送 HTTP 数据报为： POST /devices/131658/datapoints HTTP/1.1 api-key: mgDiVsQ7E8bPUwfBDtTy4K8yMtMA Host: 28 / 66 Content-Length:63 “datastreams“:“id“:“sys_time“,“datapoints“:“value“:50 返回结果如下图： 该返回结果说明，本次上传数据成功 ，数据上传成功后， OneNet服务器会关闭 TCP 连接，那么下次进行数据 传送，需要重复步骤 2)。 4.2.4 EDP 方式上传数据 用 EDP 协议接入 OneNet 过程

25、和 RestFul API 方式类似，步骤如下： 1） 配置 WIFI 模块； 模块配置和用 RestFul API 接入 OneNet 相同， 依次发送如下几个命令到 WIFI 模块： AT+CWMODE=3 AT+RST AT+CIFSR AT+CWJAP=“your ssid“,“password“ 2） 和 OneNet 服务器建立 TCP 连接，依次发送命令： AT+CIPSTART=“TCP“,“183.230.40.33“,80 /和服务器建立 TCP 连接 AT+CIPMODE=1 /进入透明传输模式 AT+CIPSEND /开始传输 命令执行结果如下图所示： 29 / 66

26、和 OneNet 平台上设备建立连接，发送数据包为： 10 2F 00 03 45 44 50 01 40 00 80 00 06 31 33 31 36 35 38 00 1C 6D 67 44 69 56 73 51 37 45 38 62 50 55 77 66 42 44 74 54 79 34 4B 38 79 4D 74 4D 41 至此，可以连 续不断发送准备好的用户数据包： 80 6A 80 00 06 31 33 31 36 35 38 01 00 5E 7B 0A 09 22 64 61 74 61 73 74 72 65 61 6D 73 22 3A 09 5B 7B 0

27、A 09 09 09 22 69 64 22 3A 09 22 73 79 73 5F 74 69 6D 65 22 2C 0A 09 09 09 22 64 61 74 61 70 6F 69 6E 74 73 22 3A 09 5B 7B 0A 09 09 09 09 09 22 76 61 6C 75 65 22 3A 09 22 32 31 22 0A 09 09 09 09 7D 5D 0A 09 09 7D 5D 0A 7D 设置好发送间隔，选择串口调试工具的自动发送选项，点击“手动发送”，这样我们就可以通过串口 WIFI 模块和 OneNet 服务器实现了 EDP 数据传输，执行结果如下图： 30 / 66 在 OneNet 平台的 Demo-test 设备下，点击相应的数据流 sys_time,查看数据上传情况。 上图表明，数据持续更新中， EDP 协议上传数据到 Demo-test 设备下成功，注意：在“ 请求日志”相应区域， 没有相关的数据更新日志记录。