OneNET平台设备接入

在OneNET平台上创建产品

在产品中创建设备，为设备新增数据流。设备端编写终端接入代码，主要完成数据采集、协议封装、数据上传等工作。终端设备的数据上传成功后，平台在相应数据流下会生成随时间推移的数据点。为了更直观的呈现数据的变化情况，用户可以运用应用孵化器自定义个性化应用并发布。

设备可通过私有协议和标准协议与平台对接私有协议说明：

RGMP(remote gateway management protocol)是平台的私有协议，平台不提供协议报文说明，根据开发者定义的设备数据模型，平台将自动生成SDK源码，开发者将SDK嵌入到设备中，实现与平台的对接。

标准协议说明：

包括HTTP/EDP/MQTT/MODBUS/JT/T808。平台提供每种协议的报文说明文档，开发者可以根据文档自己实现设备与平台对接的协议，也可以用平台提供的相应协议SDK实现与平台的对接。

1)标准协议 – EDP协议

EDP协议(Enhanced Device Protocol)

EDP协议是OneNET平台根据物联网特点专门定制的完全公开的基于TCP的长连接协议，提供设备接入、加密传输、数据存储等功能，协议的特点和功能包括：

长连接协议终端数据点上报，支持的数据点类型包括：整型(int)浮点数(float)字符串(string)JSON二进制数据平台数据下发端到端数据转发

2) 标准协议 – Modbus协议

Modbus协议

Modbus协议是应用于电子控制器上的一种通用工业标准协议。此协议支持传统的RS-232、RS-422、RS-485和以太网设备。典型工业设备包括 PLC、DTU等均使用Modbus协议作为它们之间的标准协议，协议的特点和功能包括：

长连接协议OneNET平台为Modbus主机通过单条数据流的属性确定单条下发命令的内容以及周期自动将终端上报的数据转化为数据流中的数据点

3) 标准协议 – MQTT协议

MQTT协议

MQTT协议是一个面向物联网应用的即时通信协议，使用TCP/IP提供网络连接，能够对负载内容实现消息屏蔽传输，开销小，可以有效降低网络流量，协议的特点和功能包括：

长连接协议终端数据点上报，支持的数据点类型包括：整型(int)浮点数(float)字符串(string)JSON格式平台消息下发基于Topic的订阅、发布以及消息推送，可以实现设备间的消息单播以及组播

4) 标准协议 – HTTP协议

HTTP协议

OneNET支持设备采用HTTP协议即遵循RestFul原则接入平台，协议具有接入鉴权、控制命令下发、告警出发等功能，适合平台与平台之间数据对接，其特点和功能包括：

短连接协议终端数据点上报，支持的数据点类型包括：整型(int)浮点数(float)字符串(string)JSON格式二进制数据平台侧相关资源管理

5) 标准协议 – JT/T808协议

JT/T808协议

OneNET基于JT/T808协议定义了一个扩展协议JTEXT，可以让已经基于JT/T808协议传输数据的设备快速接入平台，协议的特点和功能包括：

交通部定制的用于车辆动态监控的标准通信协议设备和平台可以保持长连接，可及时检测设备的上/下线状态标准的"位置信息汇报"等消息格式，方便已支持JT/T808协议的终端快速接入平台基于"上/下数据透传"模式，可以灵活上传用户自定义的数据，查询数据最新响应

6) 私有协议 – RGMP协议

为简化开发者的开发流程，提高用户设备数据传输的安全性，OneNET为设备接入平台提供了专门的私有协议，即RGMP协议(Remote Gateway Management Protocol)。RGMP 协议与公开协议最大的不同是OneNET平台不提供协议的报文说明，而是根据开发者定义的设备数据模型自动生成SDK源码，开发者将SDK嵌入到设备中，实现与平台的对接。RGMP协议具有业务数据格式灵活、数据传输紧凑高效以及实时性高等优点，其主要特点和功能包括：

私有的报文格式，保证数据安全性远程配置更新平台通知信息下发远程固件升级(OTA)终端数据点上报，支持的数据点类型包括：

整型(int)

浮点数(float)

字符串(string)

二进制数据

布尔值

第三方平台接入

用于开发者使用OneNET提供的数据推送和API服务来开发自己的个性化业务系统

在OneNET平台填写用于接收数据的第三方URL地址，该URL地址应为一个可达地址，并提供Token验证的get方法：

Token值作为用户在OneNET上的身份标识，用于消息摘要

随机生成EncodingAESKey和选择消息加解密方式后

对已配置成功的配置内容，用户可进行编辑、修改操作

第三方平台接入 - 数据推送消息格式

平台以HTTP POST请求形式向第三方平台注册地址推送数据，推送数据相关信息以JSON串的形式置于HTTP请求中的body部分。

第三方平台在接收数据时，根据加密选择，会接收到数据的明文消息或者密文消息。

明文格式

根据msg部分type字段的不同，可分为数据点消息、设备上下线消息

在明文传输时，存在msg、msg_signature、nonce字段，分别表示明文传输的数据、msg部分的消息摘要、用于摘要计算的随机字符串

密文格式

在加密传输时，存在enc_msg、msg_signature、nonce字段，enc_msg字段表示加密传输的数据，后两字段与明文传输一致

第三方平台接入 - 加解密方案

平台基于AES算法提供加解密技术

EncodingAESKey即消息加解密Key的BASE64编码形式，长度固定为43个字符，从a-z,A-Z,0-9共62个字符中选取。由服务开启时填写，后也可申请修改。

AES密钥计算为 AESKey=Base64_Decode(EncodingAESKey + "=")，EncodingAESKey尾部填充一个字符的"=", 用Base64_Decode生成32个字节的AESKey。

AES采用CBC模式，秘钥长度为32个字节(256位)，数据采用PKCS#7填充 ,初始化iv向量取秘钥前16字节；

PKCS#7：K为秘钥字节数(采用32)，buf为待加密的内容，N为其字节数。Buf 需要被填充为K的整数倍。在buf的尾部填充(K-N%K)个字节，每个字节的内容 是(K- N%K)。

BASE64采用MIME格式，字符包括大小写字母各26个，加上10个数字，和加号"+"，斜杠"/"，一共64个字符，等号"="用作后缀填充；

出于安全考虑，平台网站提供了修改EncodingAESKey的功能(在EncodingAESKey可能泄漏时进行修改，对应上第三方平台申请时填写的接收消息的加密对称密钥)，所以建议保存当前的和上一次的EncodingAESKey，若当前EncodingAESKey生成的AESKey解密失败，则尝试用上一次的AESKey的解密。

平台的加密消息部分为enc_msg= Base64_Encode( AES_Encrypt[random(16B)+msg_len(4B)+msg] )，即以16字节随机字节串拼接4字节表示消息体长度的字节串(此处4字节长度表示为网络字节序),再加上消息本身的字节串作为AES加密的明文，再以AES算法对明文进行加密生成密文，最后对密文进行BASE64的编码操作生成加密消息体。

对加密消息体的解密流程为：1)首先进行加密消息体的BASE64解码操作，aes_msg=Base64_Decode(enc_msg)；2)对获取的解码内容以AES算法进行解密操作，获取明文部分，plain_msg=AES_Decrypt(aes_msg)，解密中使用的秘钥由EncodingAESKey计算得来，使用的初始化iv向量为计算出的aes秘钥的前16字节;3)去掉plain_msg的前16字节，再以前4字节取出消息体长度，根据消息体长度获取真实的消息部分(推荐以消息体长度获取真实消息，以兼容plain_msg未来可能出现的结构变更)。

第三方平台接入 - 摘要计算方案

为了验证消息体的合法性，每一条平台推送消息中包含了消息签名，第三方可用以验证消息体的真实性，明文消息对msg部分整体进行摘要计算，密文消息对enc_msg部分整体进行摘要计算。具体做法如下：

msg_signature=Base64(md5(sort(token+ nonce+ enc_msg/msg)))，即按token、nonce(8字节随机串)、消息体(明文或密文)的顺序以字节为单位拼接为一个整体，计算其md5值并按BASE64编码做为消息摘要。验证时，取出nonce部分计算收到消息的md5值,计算相应的BASE64编码，与收到的msg_signature进行比较，即可知道是否存在消息篡改。

第三方平台接入 - 开放API

OneNET提供以下类别的开放API

● 设备

● 数据流

● 数据点

● 触发器

● 二级制数据

● 命令

● MQTT相关

命令是指应用发送命令数据给OneNET设备云、再由OneN 设备云转发给终端设备、终端设备收到命令后可以向设备云反馈响应的一种工作机制。

命令下发后，应用可以通过API查询命令状态和提取命令的响应数据。

命令的执行步骤如下：

1、 应用通过API向设备云发送命令数据；

2、 设备云生成该命令的uuid作为该命令的唯一标识并向应用返回，同时向终端设备转发命令数据；

3、 终端设备收到命令数据后执行命令数据，可以生成响应，也可以不响应；

4、 设备云跟踪记录命令的响应，如果设备有响应，就关联命令uuid和响应结果；

5、 应用通过API向设备云提取命令执行结果(API请求中携带命令uuid标识)。

平台界面 – 创建产品

平台界面 – 创建设备

平台界面 – 添加数据流

平台界面 – 添加触发器

用户可以用触发器对数据流进行监控，实现特定条件的事件告警，目前触发器支持以短信、邮件以及用户提供的URL地址三种途径推送事件告警信息。用户事先设定好所要监控的数据流、事件触发条件、告警信息的接受方式，一旦监控的数据流数据满足设定的条件，触发器就会以设定的接受方式发送告警信息。

平台界面 – 添加应用

用户可以为设备下的数据流创建相关的应用，发布对用户数据的直观展示页面，目前在OneNET应用孵化器中提供了曲线图、柱状图、表盘、物体位置、图片和开关等应用，用户添加应用进行数据展示的前提是用户数据已经上传至平台。