ONENET设备终端接入协议

1、(MQTT )Message Queuing Telemetry Transport版本号修订日期修订内容说明2015/9/8草稿2016/4/8重构Liuyua n2016/4/19丰富报文格式，业务流程Leih ong2016/7/13增加设备间订阅，创建topic功能Leih ong目录1 说明 错误 ! 未定义书签。2 接入流程 错误 ! 未定义书签。3 Packet 格式说明 错误 ! 未定义书签。Fixed header 错误 ! 未定义书签。Variable Header &Payload 错误 ! 未定义书签。4 支持的 packet 错误 ! 未定义书签。CONNEC.T 错

2、误 !未定义书签。Fixed Header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。Payload 错误 ! 未定义书签。CONNAC.K 错误 ! 未定义书签。Fixed Header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。PUBLISH( client - server ) 错误 ! 未定义书签。Fixed header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。Payload 错误 ! 未定义书签。PUBLISH( server - client ) 错误 ! 未定义书签。Fixed h

3、eader 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。Payload 错误 ! 未定义书签。PUBACK 错误 !未定义书签。Fixed header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。SUBSCRIBE 错误 ! 未定义书签。Fixed header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。Payload 错误 ! 未定义书签。SUBACK 错误 !未定义书签。Fixed header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。Payload 错误 ! 未

4、定义书签。UNSUBSCRIB.E 错误 ! 未定义书签。Fixed header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。Payload 错误 ! 未定义书签。UNSUBACK 错误 ! 未定义书签。Fixed header 错误 ! 未定义书签。VariableHeader 错误 ! 未定义书签。5 接入流程 错误 ! 未定义书签。连接鉴权 错误 !未定义书签。消息发布 错误 !未定义书签。数据点上报 错误 !未定义书签。平台命令（下发&回复） 错误！未定义书签。创建Topic 错误!未定义书签。订阅 错误!未定义书签。取消订阅 错误!未定义书签。推送设备

5、 Topic 错误!未定义书签。1说明MQTT协议详细内容请参见MQTT version官方文档，本文档对此不做详细说明，仅指明On eNet的要求、默认参数、以及当前实现与MQTT官方文档的差异。该版本支持的功能：鉴权；数据点上报（平台指定topic）;仓U建 topic;获取项目的topic列表；订阅/取消平台的topic;设备间topic订阅； 平台命令下发；QosO（c?S） ,Qos1（C-S）;2接入流程2.1访问平台注册用户；2.2用户根据业务情况，在“连接请求”章节中选择EDP登录方式（目前公测阶段，页面还未提供MQTT登录选项，登录方式与 EDP兼容）;ID、设备ID，以及a

6、uthinfo 等信息;2.3登录需填写设备相关属性，在项目下新增设备，获取项目 2.4设备发送TCP连接请求到以下地址，发送封装的报文与平台交互。平台服务器地址，TCP端口 60023 Packet格式说明包格式包含三部分:Fixed Header所有packet中都必须有Varable Header部分包含有Payload部分包含有Fixed headerBit76543210byte 1MQTT Packet Type0000byte2 - 5Remaining Length （该字段占用 1-4个字节）该版本支持的所有类型:名字值流向描述CONNECT1C-S客户端请求与服务端建立连接

7、CONNACK2S-C服务端确认连接建立PUBLISH3C?S发布消息PUBACK4C?S收到发布消息确认SUBSCRIBE8C-S订阅请求SUBACK9S-C订阅确认UNSUBSCRIBE10C-S取消订阅UNSUBACK11S-C取消订阅确认Variable Header &Payload消息类型VariableHeaderPayloadCONNECT有有CONNACK有有PUBLISH有有PUBACK有无SUBSCRIBE有有SUBACK有有UNSUBSCRIBE有有UNSUBACK有无4 支持的packet4.1 CONNECTFixed HeaderBit76543210byte 1

8、MQTT Packet Type0000byte2 - 5Remaining Length (该字段占用 1-4个字节)VariableHeaderDescripti on76543210byte 1-2ProtocolName Len gth0000000000000100byte 3 M01001101byte 4 Q，01010001byte 5 T01010100byte 6 T01010100Byte7Protocol Level00000001Byte8Connect FlagUser flagPassword flagWillReta inFlagWillQosFlagWillF

9、lagClea nSessi onFlagReserveByte9-10KeepAlive(1) 版本必须设置为4,平台只支持版本v，不支持更老的版本。使用第三方客户端时需要注意选择正确的版本。(2) user flag与password flag平台不允许匿名登陆，因此这两个标志位在连接时必须设置为1，否则认为协议错误，平台将会断开连接。(3) will flag与Willretainflag/Willqosflag平台暂不支持 will flag ，WillRetain Flag 与 WillQos Flag必须设置为 0。(4) Clea nSessio nFlag若客户端将clean

10、session标志位设置为0，当其断开后，平台将会保存session , session需保持的内容包含: 客户端订阅的topic列表.客户端保存session的内容包含：已经发送到服务端的但还没有收到确认的Qos1消息列表.待发送的Qos0列表.(5) Reserve保留位，置0。(6) KeepAlive保活时间每个客户端可自定义设置连接保持时间，最短120秒，最长65535秒。PayloadDescripti on是否必须存在格式Field1Clie ntIde ntifier是2字节字串长度 + utf8 字串Field2UserName是2字节字串长度 + utf8 字串Field3

11、UserPassword是2字节字串长度 + utf8 字串与鉴权相关的字段包含client id ， username和password，支持鉴权方式。字段设置消息示例clie nt_id设置为平台创建设备时的clie nt_id= ” 123”设备idusername=” 433223”username设置为项目IDpassword= ”注册的鉴权信息”password设置为鉴权信息(auth info )”各字段说明如下：项目ID :在平台添加项目时平台生成的ID ；鉴权信息(auth_info ):在平台申请设备时填写设备的auth_info 属性(数字+字母的字符串)，该属性需要产品

12、内具备唯一性；4.2 CONNACKFixed HeaderBit76543210byte 1MQTT Packet Type0000byte2 - 5Remaining Length (该字段占用 1-4个字节)VariableHeaderDescripti on76543210byte 1Ackno wledge Flags0000000Spbyte 2Retur n CodexxxxxxxxSp: Session Present Flag， session信息在服务器已保持，置1;未保存，置 0。返回码说明:返回码描述0成功1协议版本错误2非法的clientid3服务不可用4用户名或密码

13、错误5非法链接（比如token非法）失败：*如果connect包不符合协议内容约束，则直接断掉连接，而不需要发送conn ack包.*如果鉴权或授权失败，回复一个带非0错误码的conn ack包.成功：*必须断掉重复的 clie ntid.*执行cleansession 对应的操作.*必须回复一个connack ,回复码为0.*开始消息传递，并加入keepalive的监视.PS:客户端需要等到服务端的connack报文，才能发送后续的数据包.4.3 PUBLISH（client - server ）Fixed headerBit76543210byte 1MQTT Packet TypeDUP

14、 flagQoS LevelRETAINbyte2 - 5Remaining Length （该字段占用 1-4个字节）DUP:QoS1 :如果为0,则表示是第一次发送该包，如果为 1,则表示为重复发送的包。Qos0 : DUF必须为0QOS:指定了该publish包的qos等级如下RETAIN: 暂不实现Qos值Bit2Bit1描述000取多发送一次101至少发送一次PS:该版本只实现Qos0, Qos1VariableHeaderDescripti on.格式是否必须Field1TopicName2字节字串长度 + utf8 字串是Field2PacketIde ntifier2字节QoS

15、0:否,QoS1:是Payload内容根据不同业务自定义4.4 PUBLISH(server - client )Fixed headerBit76543210byte 1MQTT Packet TypeDUP flagQoS LevelRETAINbyte2 - 5Remaining Length （该字段占用 1-4个字节）DUP:1,则表示为重复发送的包。QoS1 :如果为0,则表示是第一次发送该包，如果为QosO : DUP必须为0QOS:指定了该publish包的qos等级如下RETAIN:Qos值Bit2Bit1描述000取多发送一次PS:该版本只实现Qos0VariableHea

16、derDescripti on格式Field1TopicName字节字串长度 + utf8 字串Payload内容根据不同业务自定义4.5PUBACKFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （该字段占用 1-4个字节）VariableHeaderDescripti on76543210byte 12PacketIde ntifierPacketIde ntifier4.6 SUBSCRIBEFixed headerBit76543210byte 1MQTT Packet Type0000b

17、yte2 5Remaining Length （该字段占用 1-4个字节）VariableHeaderDescripti on76543210byte 12PacketIde ntifierPacketIde ntifierPayloadDescripti on格式Byte1 nTopicName2字节字串长度 + utf8 字串Byte n+1Reserved保留字节（兼容说明可以包含一个或多个 topic.topic必须是数字、英文、反斜杠（/）的组合，目前不支持通配符。每个客户端最多订阅 100个topic ；以下topic被系统保留使用，（客户端不能订阅）：类型说明$开头平台保留4.7

18、 SUBACKFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （该字段占用 1-4个字节）VariableHeaderDescripti on76543210byte 12PacketIde ntifierPacketIde ntifierPayloadDescripti on76543210byte 1retcode返回码说明:返回码描述0x00成功0x80失败4.8 UNSUBSCRIBEFixed headerBit76543210byte 1MQTT Packet Type0000byte

19、2 5Remaining Length （该字段占用 1-4个字节）VariableHeaderDescripti on76543210byte 12PacketIde ntifierPacketIde ntifierPayloadDescripti on格式Byte1 nTopicName字节字串长度 + utf8 字串可以包含一个或多个topic.UNSUBACKFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （该字段占用 1-4个字节）VariableHeaderDescripti on76

20、543210byte 12PacketIde ntifierPacketIde ntifier5接入流程5.1连接鉴权DeviceOnenet设备向平台发起connect请求.connect中携带鉴权信息,具体参见（报文格式参考 平台拿到鉴权信息进行鉴权.鉴权通过后，如果cleansession=0,平台将会加载保存的设备的一些信息.如订阅列表中描述）.如果cleansession=1,设备没有保存信息在平台，则不加载设备相关信息返回鉴权结果ConnAck（报文格式参考.5.2 消息发布数据点上报设备使用publish报文来上传数据点，报文格式如下:VariableHeaderField名称说

21、明格式FieldlTopicName=”$dp”$dp为系统上传数据点的指令2字节字串长度+ utf8 字串Payload:Payload包含真正的数据点内容，支持的格式如下:字节说明bit76543210Byte 1BitO-5数据类型指示，目前支持：Type = 1Byte nDeviceOn eNetPublish $dp(QosO)存储Qos1(Clie nt-Server)DeviceOn eNet设备发布Qos0消息（上报数据点） 平台收到上报数据点后保存起来平台给设备回复PubAck（报文格式参考平台命令（下发&回复）命令下发平台使用publish报文来下发平台指令，报文格式如下

22、:FixHeader :参考 VariableHeaderField名称说明格式Field1TopicName=” $creq/cmduuid ”$creq为系统下发Cmd的指令，2字节字串长度 + utf8 字串cmduuid为该条指令的uuidPayload:Payload包含真正的指令内容QosO(Server-Clie nt)On eNetDevice命令下发：平台向设备发送topic为$creq的消息（该topic为平台命令）.设备收到topic为$creq的topic时，需将其作为平台下发的指令来处理命令回复设备使用publish报文来回复平台指令，报文格式如下:FixHeader

23、 :参考 VariableHeaderField名称说明格式Field1TopicName=” $crsp/cmduuid ”$crsp为系统处理设备回复cmd的 指令,cmduuid为该条指令的uuid2字节字串长度 + utf8 字串Payload:Payload包含真正回复的指令内容QosO(Clie nt-Server)On eNetDeviceQos1(Client Server)Device如果设备回复响应时以 Qos1回复，则平台需要给设备回复一个Puback消息5.3 创建 TopicOn eNetDeviceJHTTP请求HTTP响应设备通过发送HTTP请求进行topic的创建操作 平台收到请求后创建topic并返回结果 请求及响应定义如下：DeviceOn eNet报文格式参考HTTP方法POSTURL头部api-key:xxxx-ffff-zzzzz，必须 master keyURL参数HTTP body