《onenet设备终端接入协议2-EDP》由会员分享,可在线阅读,更多相关《onenet设备终端接入协议2-EDP(24页珍藏版)》请在金锄头文库上搜索。
1、Enhanced Device Protocol(EDP)欢迎访问设备云门户网站版本号修订日期修订内容说明V1.12014.10.30EDP增加存储数据报文;REST API 增加历史数据查询接口,用于上报数据点,或者上报的同时转发数据点。V1.1.12014/11/3EDP增加消息类型9,以支持对存储数据的确认。V1.22015/07/17增加加密机制;命令请求和响应报文;存储数据点,新增3中格式;修改登陆方式为2种;V1.32015/10/14添加连接关闭消息目录Enhanced Device Protocol(EDP)11说明22设备与业务接入模式23接入流程24消息格式34.1消息类型
2、34.2剩余消息长度34.3选项44.4消息体55消息类型55.1连接请求55.2连接响应85.3转发(透传)数据95.4存储(&转发)数据105.5存储确认135.6命令请求145.7命令响应145.8心跳请求155.9心跳响应155.10加密请求165.11加密响应166主要流程176.1登录176.2数据收发(透传)186.3存储数据点(datapoint)186.4存储数据点并获得确认196.5存储数据点并转发206.6命令请求及响应206.7心跳保持216.8数据加密211 说明该接口上的协议基于TCP,但只传输数据包到目的地,不保证传输的顺序与到达的顺序相同,事务机制需要在上层实现
3、;若客户端同时发起两次请求,服务器返回时,不保障返回报文的顺序。2 设备与业务接入模式设备层:利用平台提供的EDPSDK,实现EDP协议,用于上报业务数据点到OnetNet。若需要实时接收业务层下发的控制命令,需要保持EDP长连接。业务应用层:若要自定义实现业务平台,可通过HTTP 协议的RESTful API操作OnetNet提供的资源(设备、数据点、命令控制等资源的增删查改)。适用场景:在充分分析业务数据模型的基础上,认为OneNet提供的设备-数据流-数据点模型适合业务数据存储。优先推荐新业务使用该模式。3 接入流程3.1 访问平台3.2 用户根据业务情况,在“连接请求”章节中选择EDP
4、登录方式;3.3 根据登录方式,填写设备相关属性,在项目下新增设备,获取项目ID、设备ID,以及api-key等信息;3.4 设备发送TCP连接请求到以下地址,发送封装的报文与平台交互。平台服务器地址,TCP 端口876,298764 消息格式消息包括三个部分:必选的消息头(绿色),可选的多个选项(黄色)以及可选的消息体(蓝色)。字节bit76543210Byte 1消息类型保留位(全零)Multi-bytes剩余消息长度(1-4字节,指示选项+消息体的长度)Multi-bytes选项(根据消息类型0个或多个)Multi-bytes消息体(根据消息类型0或多个字节)4.1 消息类型占第一个字节
5、的前4位,取值范围(0-15),定义如下:类型值含义方向1CONN_REQ:连接建立请求C(client)-S(server)2CONN_RESP:连接建立响应S-C3PUSH_DATA:转发(透传)数据双向4CONN_CLOSE:连接关闭S-C8SAVE_DATA:存储(&转发)数据双向9SAVE_ACK:存储确认S-C10CMD_REQS-C11CMD_RESPC-S12PING_REQ: 心跳请求C-S13PING_RESP: 心跳响应S-C14ENCRYPT_REQC-S15ENCRYPT_RESPS-C其他值保留4.2 剩余消息长度用于指示选项和消息体的字节数。目前平台限制EDP协议
6、每条消息剩余长度不能超过4M。该字段占用1-4个字节,长度值的低位部分放在传输的前面字节,高位放在后面。每个字节的最高位为延续指示位。延续指示位为1时,标示后面字节也是长度值,最多可延续4个字节。可表示数据范围如下:字节数最小值最大值10(0x00)127(0x7F)2128(0x80, 0x01)16383 (0xFF, 0x7F)316 384 (0x80, 0x80, 0x01)2 097 151 (0xFF, 0xFF, 0x7F)42 097 152 (0x80, 0x80, 0x80, 0x01) 268 435 455 (0xFF, 0xFF, 0xFF, 0x7F)注意:消息剩
7、余长度 = 选项所占字节数 + 消息体所占字节数,根据该值的大小来确定消息剩余长度字段在EDP数据包中占用多少个字节,比如从上表可以看出,当0剩余长度=127的时候,消息剩余长度字段在EDP数据包中只占一个字节,而不是四个字节;当 127剩余长度=16383的时候,消息剩余长度字段在EDP数据包中占两个字节,而不是四个字节;依此类推。例如,若选项+消息体长度共321=65+2*128字节,则该域(剩余长度)需要两个字节才能表示,第一个字节的延续位置1,按照传输顺序格式如下:字节bit76543210Byte 111000001Byte 200000010解析该长度值的C语言算法可表示为:( (
8、 Byte2 & 127 ) 7 ) | ( Byte1& 127 )编码算法:解码算法:4.3 选项根据消息类型,选项的格式不同;详见后面的命令类型说明。某些选项为固定格式的几个字节,另一些采用length+value的字符串格式,用两个字节指示后面值的长度,字符串最长0xFFFF。字符串详细格式如下:字节bit76543210Byte 1长度高位字节Byte 2长度低位字节0-mulit bytes0或多个字节的内容,最长0xFFFF字节4.4 消息体根据消息类型,消息体可选,详见后面命令类型说明。5 消息类型5.1 连接请求连接请求包含三部分:消息头,一些选项和消息体。其中,选项包括协议
9、名称、协议版本、连接标志、保持连接时间。消息体中可能包含设备ID、用户ID(可选)、鉴权信息。三项内容都为长度+内容的字符串格式。设备ID必须传递,若认证方式中不使用设备ID,应将设备ID长度设置为0;用户ID和鉴权信息,根据标志位若存在必须按顺序出现。用户ID获取方式在OneNet添加项目时,平台生成项目ID。设备ID获取方式在OneNet平台创建设备时平台生成的设备ID号。api-key获取方式在OneNet注册的项目,管理整个项目的api-key,或者用于自己新增具有该设备操作权限的api-key可选的登录认证方式:登陆认证方式携带信息说明消息示例1设备ID + 鉴权信息(api-key
10、)设备ID:申请设备时平台返回的ID;鉴权信息:在平台申请的可以操作该设备的api-key字符串;消息格式见示例12项目ID + 鉴权信息(auth_info)项目ID:在平台添加项目时平台生成的ID;鉴权信息:在平台申请设备时填写设备的auth_info属性(json对象字符串),该属性需要项目内具备唯一性;消息格式见示例2示例1:采用登陆方式1:设备ID“43101”和api-key“abcdefg”,登录平台的连接请求消息格式如下:字节说明bit76543210消息头Byte 1第一字节:Bit(4-7):消息类型,值为1;Bit(0-3):保留位,值为0;00010000变长剩余消息长
11、度(25编码后需要占用1个字节)Byte 2第二字节:消息剩余字节长度,值为2500011001选项1:协议描述(字符串格式)Byte 3长度高位字节,值为000000000Byte 4长度低位字节,值为300000011Byte 5字母E01000101Byte 6字母D01000100Byte 7字母P01010000选项2:协议版本Byte 8一个字节表示,值为100000001选项3:连接标志Byte 9Bit(7):项目ID标志位,值0,Bit(6):鉴权信息标志位,值1,表示后面消息体有该项Bit(0-5):系统保留位,填001000000选项4:保持连接时间(256秒=0x010
12、0)Byte 10第一字节,时间值的高位字节,值100000001Byte 11第二字节,时间值的低位字节,值000000000消息体-设备ID(字符串格式)Byte 12长度高位字节,值为000000000Byte 13长度低位字节,值为500000101Byte 14字符400110100Byte 15字符300110011Byte 16字符100110001Byte 17字符000110000Byte 18字符100110001消息体-鉴权信息(字符串格式)Byte 19长度高位字节,值为000000000Byte 20长度低位字节,值为700000111Byte 21字符a01100001Byte 22字符b01100010Byte 23字符c01100011Byte 24字符d01100100Byte 25字符e01100101Byte 26字符f01100110Byte 27字符g01100111示例2:采用登陆方式2:项目ID“