onenet设备终端接入协议.docx
《onenet设备终端接入协议.docx》由会员分享，可在线阅读，更多相关《onenet设备终端接入协议.docx（45页珍藏版）》请在冰豆网上搜索。
onenet设备终端接入协议
--本页仅作为文档封面，使用时请直接删除即可----内页可以根据需求调整合适字体及大小--
onenet设备终端接入协议2-EDP（总24页）
EnhancedDeviceProtocol（EDP）
欢迎访问设备云门户网站注册用户，获取最新文档。
版本号
修订日期
修订内容
说明
增加存储数据报文；
RESTAPI增加历史数据查询接口，用于上报数据点，或者上报的同时转发数据点。
增加消息类型9，以支持对存储数据的确认。
2015/07/17
增加加密机制；
命令请求和响应报文；
存储数据点，新增3中格式；
修改登陆方式为2种；
2015/10/14
添加连接关闭消息
1说明
该接口上的协议基于TCP，但只传输数据包到目的地，不保证传输的顺序与到达的顺序相同，事务机制需要在上层实现；若客户端同时发起两次请求，服务器返回时，不保障返回报文的顺序。
2设备与业务接入模式
设备层：
利用平台提供的EDPSDK，实现EDP协议，用于上报业务数据点到OnetNet。
若需要实时接收业务层下发的控制命令，需要保持EDP长连接。
业务应用层：
若要自定义实现业务平台，可通过HTTP协议的RESTfulAPI操作OnetNet提供的资源（设备、数据点、命令控制等资源的增删查改）。
适用场景：
在充分分析业务数据模型的基础上，认为OneNet提供的设备-数据流-数据点模型适合业务数据存储。
优先推荐新业务使用该模式。
3接入流程
3.1访问平台注册用户；
3.2用户根据业务情况，在“连接请求”章节中选择EDP登录方式；
3.3根据登录方式，填写设备相关属性，在项目下新增设备，获取项目ID、设备ID，以及api-key等信息；
3.4设备发送TCP连接请求到以下地址，发送封装的报文与平台交互。
平台服务器地址，TCP端口876,29876
4消息格式
消息包括三个部分：
必选的消息头（绿色），可选的多个选项（黄色）以及可选的消息体（蓝色）。
字节\bit
7
6
5
4
3
2
1
0
Byte1
消息类型
保留位（全零）
Multi-bytes
剩余消息长度（1-4字节，指示选项+消息体的长度）
Multi-bytes
选项（根据消息类型0个或多个）
Multi-bytes
消息体（根据消息类型0或多个字节）
4.1消息类型
占第一个字节的前4位，取值范围（0-15），定义如下：
类型值
含义
方向
1
CONN_REQ：
连接建立请求
C（client）->S（server）
2
CONN_RESP：
连接建立响应
S->C
3
PUSH_DATA：
转发（透传）数据
双向
4
CONN_CLOSE：
连接关闭
S->C
8
SAVE_DATA：
存储（&转发）数据
双向
9
SAVE_ACK：
存储确认
S->C
10
CMD_REQ
S->C
11
CMD_RESP
C->S
12
PING_REQ:
心跳请求
C->S
13
PING_RESP:
心跳响应
S->C
14
ENCRYPT_REQ
C->S
15
ENCRYPT_RESP
S->C
其他值
保留
4.2剩余消息长度
用于指示选项和消息体的字节数。
目前平台限制EDP协议每条消息剩余长度不能超过4M。
该字段占用1-4个字节，长度值的低位部分放在传输的前面字节，高位放在后面。
每个字节的最高位为延续指示位。
延续指示位为1时，标示后面字节也是长度值，最多可延续4个字节。
可表示数据范围如下：
字节数
最小值
最大值
1
0（0x00）
127（0x7F）
2
128（0x80,0x01）
16383（0xFF,0x7F）
3
16384（0x80,0x80,0x01）
2097151（0xFF,0xFF,0x7F）
4
2097152（0x80,0x80,0x80,0x01）
268435455（0xFF,0xFF,0xFF,0x7F）
注意：
消息剩余长度=选项所占字节数+消息体所占字节数，根据该值的大小来确定消息剩余长度字段在EDP数据包中占用多少个字节，比如从上表可以看出，当0<剩余长度<=127的时候，消息剩余长度字段在EDP数据包中只占一个字节，而不是四个字节；当127<剩余长度<=16383的时候，消息剩余长度字段在EDP数据包中占两个字节，而不是四个字节；依此类推。
例如，若选项+消息体长度共321=65+2*128字节，则该域（剩余长度）需要两个字节才能表示，第一个字节的延续位置1，按照传输顺序格式如下：
字节\bit
7
6
5
4
3
2
1
0
Byte1
1
1
0
0
0
0
0
1
Byte2
0
0
0
0
0
0
1
0
解析该长度值的C语言算法可表示为：
（（Byte2&127）<<7）|（Byte1&127）
编码算法:
解码算法:
4.3选项
根据消息类型，选项的格式不同；详见后面的命令类型说明。
某些选项为固定格式的几个字节，另一些采用length+value的字符串格式，用两个字节指示后面值的长度，字符串最长0xFFFF。
字符串详细格式如下：
字节\bit
7
6
5
4
3
2
1
0
Byte1
长度高位字节
Byte2
长度低位字节
0-mulitbytes
0或多个字节的内容，最长0xFFFF字节
4.4消息体
根据消息类型，消息体可选，详见后面命令类型说明。
5消息类型
5.1连接请求
连接请求包含三部分：
消息头，一些选项和消息体。
其中，选项包括协议名称、协议版本、连接标志、保持连接时间。
消息体中可能包含设备ID、用户ID（可选）、鉴权信息。
三项内容都为长度+内容的字符串格式。
设备ID必须传递，若认证方式中不使用设备ID，应将设备ID长度设置为0；用户ID和鉴权信息，根据标志位若存在必须按顺序出现。
用户ID获取方式
在OneNet添加项目时，平台生成项目ID。
设备ID获取方式
在OneNet平台创建设备时平台生成的设备ID号。
api-key获取方式
在OneNet注册的项目，管理整个项目的api-key,或者用于自己新增具有该设备操作权限的api-key
可选的登录认证方式：
登陆认证方式
携带信息
说明
消息示例
1
设备ID+鉴权信息（api-key）
设备ID：
申请设备时平台返回的ID；
鉴权信息：
在平台申请的可以操作该设备的api-key字符串；
消息格式见示例1
2
项目ID+鉴权信息（auth_info）
项目ID：
在平台添加项目时平台生成的ID；
鉴权信息：
在平台申请设备时填写设备的auth_info属性（json对象字符串），该属性需要项目内具备唯一性；
消息格式见示例2
示例1：
采用登陆方式1：
设备ID“43101”和api-key“abcdefg”，登录平台的连接请求消息格式如下：
字节
说明\bit
7
6
5
4
3
2
1
0
消息头
Byte1
第一字节：
Bit（4-7）：
消息类型，值为1；
Bit（0-3）：
保留位，值为0；
0
0
0
1
0
0
0
0
变长剩余消息长度（25编码后需要占用1个字节）
Byte2
第二字节：
消息剩余字节长度，值为25
0
0
0
1
1
0
0
1
选项1：
协议描述（字符串格式）
Byte3
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte4
长度低位字节，值为3
0
0
0
0
0
0
1
1
Byte5
字母’E’
0
1
0
0
0
1
0
1
Byte6
字母’D’
0
1
0
0
0
1
0
0
Byte7
字母’P’
0
1
0
1
0
0
0
0
选项2：
协议版本
Byte8
一个字节表示，值为1
0
0
0
0
0
0
0
1
选项3：
连接标志
Byte9
Bit（7）：
项目ID标志位，值0，
Bit（6）：
鉴权信息标志位，值1，表示后面消息体有该项
Bit（0-5）：
系统保留位，填0
0
1
0
0
0
0
0
0
选项4：
保持连接时间（256秒=0x0100）
Byte10
第一字节，时间值的高位字节，值1
0
0
0
0
0
0
0
1
Byte11
第二字节，时间值的低位字节，值0
0
0
0
0
0
0
0
0
消息体-设备ID（字符串格式）
Byte12
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte13
长度低位字节，值为5
0
0
0
0
0
1
0
1
Byte14
字符’4’
0
0
1
1
0
1
0
0
Byte15
字符’3’
0
0
1
1
0
0
1
1
Byte16
字符’1’
0
0
1
1
0
0
0
1
Byte17
字符’0’
0
0
1
1
0
0
0
0
Byte18
字符’1’
0
0
1
1
0
0
0
1
消息体-鉴权信息（字符串格式）
Byte19
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte20
长度低位字节，值为7
0
0
0
0
0
1
1
1
Byte21
字符’a’
0
1
1
0
0
0
0
1
Byte22
字符’b’
0
1
1
0
0
0
1
0
Byte23
字符’c’
0
1
1
0
0
0
1
1
Byte24
字符’d’
0
1
1
0
0
1
0
0
Byte25
字符’e’
0
1
1
0
0
1
0
1
Byte26
字符’f’
0
1
1
0
0
1
1
0
Byte27
字符’g’
0
1
1
0
0
1
1
1
示例2：
采用登陆方式2：
项目ID“101”和鉴权信息“{“mac”:
“FF”}”，登录平台的连接请求消息格式如下：
字节
说明\bit
7
6
5
4
3
2
1
0
消息头
Byte1
第一字节：
Bit（4-7）：
消息类型，值为1；
Bit（0-3）：
保留位，值为0；
0
0
0
1
0
0
0
0
变长剩余消息长度（25编码后需要占用1个字节）
Byte2
第二字节：
消息剩余字节长度，值为30
0
0
0
1
1
1
1
0
选项1：
协议描述（字符串格式）
Byte3
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte4
长度低位字节，值为3
0
0
0
0
0
0
1
1
Byte5
字母’E’
0
1
0
0
0
1
0
1
Byte6
字母’D’
0
1
0
0
0
1
0
0
Byte7
字母’P’
0
1
0
1
0
0
0
0
选项2：
协议版本
Byte8
一个字节表示，值为1
0
0
0
0
0
0
0
1
选项3：
连接标志
Byte9
Bit（7）：
项目ID标志位，值1，表示后面消息体有该项
Bit（6）：
鉴权信息标志位，值1，表示后面消息体有该项
Bit（0-5）：
系统保留位，填0
1
1
0
0
0
0
0
0
选项4：
保持连接时间（256秒=0x0100）
Byte10
第一字节，时间值的高位字节，值1
0
0
0
0
0
0
0
1
Byte11
第二字节，时间值的低位字节，值0
0
0
0
0
0
0
0
0
消息体-设备ID（字符串格式）
Byte12
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte13
长度低位字节，值为0
0
0
0
0
0
0
0
0
消息体-项目ID（字符串格式）
Byte14
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte15
长度低位字节，值为3
0
0
0
0
0
0
1
1
Byte16
字符’1’
0
0
1
1
0
0
0
1
Byte17
字符’0’
0
0
1
1
0
0
0
0
Byte18
字符’1’
0
0
1
1
0
0
0
1
消息体-鉴权信息（字符串格式）
Byte19
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte20
长度低位字节，值为9
0
0
0
0
0
1
1
1
Byte21
字符’{’
0
1
1
1
1
0
1
1
Byte22
字符’”’
0
0
1
0
0
0
1
0
Byte23
字符’m’
0
1
1
0
1
1
0
1
Byte24
字符’a’
0
1
1
0
0
0
0
1
Byte25
字符’c’
0
1
1
0
0
0
1
1
Byte26
字符’”’
0
0
1
0
0
0
1
0
Byte27
字符’:
’
0
0
1
1
1
0
1
0
Byte28
字符’”’
0
0
1
0
0
0
1
0
Byte29
字符’F’
0
1
0
0
0
1
1
0
Byte30
字符’F’
0
1
0
0
0
1
1
0
Byte31
字符’”’
0
0
1
0
0
0
1
0
Byte32
字符’}’
0
1
1
1
1
1
0
1
5.2连接响应
连接响应报文包含：
消息头，2个必选项和可能的消息体。
其中，选项包括一个字节的响应标志和一个字节的返回码选项；消息体根据授权码标志位，可能携带平台返回的授权码。
举例格式如下：
字节
说明\bit
7
6
5
4
3
2
1
0
消息头
Byte1
第一字节：
Bit（4-7）：
消息类型，值为2；
Bit（0-3）：
保留位，值为0；
0
0
1
0
0
0
0
0
Byte2
第二字节：
消息剩余字节长度，值为2
0
0
0
0
0
0
1
0
选项1：
选项-标志
Byte3
Bit（1-4）：
系统保留位
Bit（0）：
授权码标志位，值1，表示后面消息体携带有授权码
0
0
0
0
0
0
0
1
选项2：
选项-返回码
Byte4
一个字节表示，根据验证情况，枚举值如下：
0：
连接成功；
1：
验证失败-协议错误；
2：
验证失败-设备ID鉴权失败；
3：
验证失败-服务器失败；
4：
验证失败-用户ID鉴权失败；
5：
验证失败-未授权；
6：
验证失败-授权码无效；
7：
激活失败-激活码未分配；
8：
激活失败-该设备已被激活；
9：
验证失败-重复发送连接请求包；
10-255：
保留值；
0
0
0
0
0
0
0
0
消息体-授权码（字符串格式）
Byte5
长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte6
长度低位字节，值为7
0
0
0
0
0
1
1
1
Byte7
字符’a’
0
1
1
0
0
0
0
1
Byte8
字符’b’
0
1
1
0
0
0
1
0
Byte9
字符’c’
0
1
1
0
0
0
1
1
Byte10
字符’d’
0
1
1
0
0
1
0
0
Byte11
字符’e’
0
1
1
0
0
1
0
1
Byte12
字符’f’
0
1
1
0
0
1
1
0
Byte13
字符’g’
0
1
1
0
0
1
1
1
5.3转发（透传）数据
该消息是一个双向消息，可以从设备到云，也可以由设备云发向设备。
由消息头、一个选项和消息体组成，其中选项必须包括一个地址。
Push_data消息方向
选项（地址）说明
C->S（设备到平台）
平台收到该消息，选项中的地址是该数据转发的目的地址（目的设备ID号）；
若目的地址的长度为零，即没有目的地址，则平台将该消息转发到设备注册时的默认目的地址（设备申请时，填写的route_to字段）。
S->C（平台到设备）
设备收到该消息，选项中的地址是该数据发送的发送者（源）地址；
示例：
通过设备云发送数据到ID为21573的设备。
字节
说明\bit
7
6
5
4
3
2
1
0
消息头
Byte1
第一字节：
Bit（4-7）：
消息类型，值为3；
Bit（0-3）：
保留位，值为0；
0
0
1
1
0
0
0
0
剩余消息长度（283编码后需要占用2个字节）
Byte2
消息剩余字节长度（283）-编码第一字节（低）
1
0
0
1
1
0
1
1
Byte3
消息剩余字节长度（283）-编码第二字节（高）
0
0
0
0
0
0
1
0
选项1：
目的或源地址（字符串格式）
Byte4
固定两字节长度高位字节，值为0
0
0
0
0
0
0
0
0
Byte5
固定两字节长度低位字节，值为5
0
0
0
0
0
1
0
1
Byte6
字符’2’
0
0
1
1
0
0
1
0
Byte7
字母’1’
0
0
1
1
0
0
0
1
Byte8
字母’5’
0
0
0
0
0
1
0
1
Byte9
字母’7’
0
0
1
1
0
1
1
1
Byte10
字母’3’
0
0
1
1
0
0
1
1
消息体（用户数据）
Byte11
升级会员 