ONENET设备终端接入协议MQTT

1、(MQTT)MessageQueuingTelemetryTransport版本号修订日期修订内容说明V1.12015/9/8草稿V2.02016/4/8重构LiuyuanV2.12016/4/19丰富报文格式，业务流程LeihongV2.22016/7/13增加设备间订阅，创建topic功能Leihong目录1 说明32 接入流程33 Packet格式说明43.1 Fixedheader43.2 VariableHeader&Payload44 支持的packet54.1 CONNECT54.1.1 FixedHeader54.1.2 VariableHeader54.1.3 Pay

2、load64.2 CONNACK64.2.1 FixedHeader64.2.2 VariableHeader64.3 PUBLISH(client->server)74.3.1 Fixedheader74.3.2 VariableHeader74.3.3 Payload84.4 PUBLISH(server->client)84.4.1 Fixedheader84.4.2 VariableHeader84.4.3 Payload84.5 PUBACK94.5.1 Fixedheader94.5.2 VariableHeader94.6 SUBSCRIBE94.6.1 Fixedh

3、eader94.6.2 VariableHeader94.6.3 Payload94.7 SUBACK104.7.1 Fixedheader104.7.2 VariableHeader104.7.3 Payload104.8 UNSUBSCRIBE104.8.1 Fixedheader104.8.2 VariableHeader114.8.3 Payload114.9 UNSUBACK114.9.1 Fixedheader114.9.2 VariableHeader115 接入流程125.1 连接鉴权125.2 消息发布135.2.1 数据点上报135.2.2 平台命令（下发&回复）1

4、75.3 创建Topic195.4 订阅205.5 取消订阅215.6 推送设备Topic211说明MQTT协议详细内容请参见MQTTversion3.1.1官方文档，本文档对此不做详细说明，仅指明OneNet的要求、默认参数、以及当前实现与MQTT官方文档的差异。该版本支才I的功能：鉴权；数据点上报（平台指定topic）;创建topic;获取项目的topic列表；订阅/取消平台的topic;设备间topic订阅；平台命令下发；Qos0（cS）,Qos1（C->S）;2接入流程1.1 访问平台MQTT登1.2 用户根据业务情况，在“连接请求”章节中选择EDP登录方式（目前公测阶段，页面还

5、未提供录选项，登录方式与EDP兼容）；1.3 登录需填写设备相关属性，在项目下新增设备，获取项目ID、设备ID,以及authinfo等信息;1.4 设备发送TCP连接请求到以下地址，发送封装的报文与平台交互。平台服务器地址9,TCP端口60023 Packet格式说明包格式包含三部分:FixedHeader所有packet中都必须有VarableHeader部分包含有Payload部分包含有3.1 FixedheaderBit76543210byte1MQTTPacketType0000byte2-5RemainingLength（该字段占用1-4个字节）该版本支持的所

6、有类型:名字值流向描述CONNECT1C->S客户端请求与服务端建立连接CONNACK2S->C服务端确认连接建立PUBLISH3CS发布消息PUBACK4CS收到发布消息确认SUBSCRIBE8C->S订阅请求SUBACK9S->C订阅确认UNSUBSCRIBE10C->S取消订阅UNSUBACK11S->C取消订阅确认3.2 VariableHeader&Payload消息类型VariableHeaderPayloadCONNECT有有CONNACK有有PUBLISH有有PUBACK有无SUBSCRIBE有有SUBACK有有_UNSUBSCRIB

7、E有有UNSUBACK有无4 支持的packet4.1 CONNECT4.1.1 FixedHeaderBit76543210byte1MQTTPacketType0000byte2-5RemainingLength(该字段占用1-4个字节)4.1.2 VariableHeaderDescription76543210byte1-2ProtocolNameLength0000000000000100byte3M，01001101byte4Q，01010001byte5T，01010100byte6T，01010100Byte7ProtocolLevel00000001Byte8ConnectF

8、lagUserflagPasswordflagWillRetainFlagWillQosFlagWillFlagCleanSessionFlagReserveByte9-10KeepAlive(1) 版本必须设置为4,平台只支持版本v3.1.1,不支持更老的版本。使用第三方客户端时需要注意选择正确的版本。(2) userflag与passwordflag平台不允许匿名登陆，因此这两个标志位在连接时必须设置为1,否则认为协议错误，平台将会断开连接。(3) willflag与Willretainflag/Willqosflag平台暂不支持willflag,WillRetainFlag与WillQo

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

10、ield2UserName是2字节字串长度+utf8字串Field3UserPassword是2字节字串长度+utf8字串与鉴权相关的字段包含clientid,username和password,支持鉴权方式。字段设置消息示例client_id设置为平台创建设备时的设备idusername设置为项目IDpassword设置为鉴权信息(auth_info)”client_id="123"username="433223”password="注册的鉴权信息”各字段说明如下：项目ID：在平台添加项目时平台生成的ID;鉴权信息(auth_info)：在平台申请设

11、备时填写设备的auth_info属性(数字+字母的字符串)，该属性需要产品内具备唯一性；4.2CONNACK4.2.1FixedHeaderBit76543210byte1MQTTPacketType0000byte2-5RemainingLength(该字段占用1-4个字节)4.2.2VariableHeaderDescription76543210byte1AcknowledgeFlags0000000Spbyte2ReturnCodexxxxxxxx1;未保存，置0。Sp:SessionPresentFlagsession信息在服务器已保持，置返回码说明:返回码描述0成功1协议版本错误2

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

13、43210byte1MQTTPacketTypeDUPflagQoSLevelRETAINbyte2-5RemainingLength（该字段占用1-4个字节）DUP:QoS1:如果为0,则表示是第一次发送该包，如果为1,则表示为重复发送的包。Qos0:DUP必须为0QOS:指定了该publish包白qqos等级如下RETAIN:暂不实现Qos值Bit2Bit1描述000取夕发送次101至少发送一次PS该版本只实现Qos0,Qos14.3.2 VariableHeaderDescription格式是否必须Field1TopicName2字节字串长度+utf8字串是Field2PacketIde

14、ntifier2字节QoS0:否，QoS1:是4.3.3 Payload内容根据不同业务自定义4.4 PUBLISH(server->client)4.4.1 FixedheaderBit76543210byte1MQTTPacketTypeDUPflagQoSLevelRETAINbyte2-5RemainingLength（该字段占用1-4个字节）DUP:QoS1:如果为0,则表示是第一次发送该包，如果为1,则表示为重复发送的包。Qos0:DUP必须为0QOS:指定了该publish包白qqos等级如下RETAIN:Qos值Bit2Bit1描述000取夕发送次PS该版本只实现Qos0

15、4.4.2VariableHeaderDescription格式Field1TopicName2字节字串长度+utf8字串4.4.3Payload内容根据不同业务自定义4.5PUBACK4.4.1FixedheaderBit76543210byte1MQTTPacketType0000byte25RemainingLength（该字段占用1-4个字节）4.4.2VariableHeaderDescription76543210byte12PacketIdentifierPacketIdentifier4.6SUBSCRIBE4.5.1FixedheaderBit76543210byte1MQT

16、TPacketType0000byte25RemainingLength（该字段占用1-4个字节）4.5.2VariableHeaderDescription76543210byte12PacketIdentifierPacketIdentifier4.5.3PayloadDescription格式Byte1nTopicName2字节字串长度+utf8字串Byten+1Reserved保留字节（兼谷mqtt-v3.1.1）topic说明可以包含一个或多个topic.topic必须是数字、英文、反斜杠（/）的组合，目前不支持通配符。每个客户端最多订阅100个topic;以下topic被系统保留使

17、用，（客户端不能订阅）：说明$开头平台保留4.7 SUBACK4.7.1 FixedheaderBit76543210byte1MQTTPacketType0000byte25RemainingLength（该字段占用1-4个字节）4.6.2VariableHeaderDescription76543210byte12PacketIdentifierPacketIdentifier4.6.3PayloadDescription76543210byte1retcode返回码说明:返回码描述0x00成功0x80失败4.8 UNSUBSCRIBE4.8.1 FixedheaderBit7654321

18、0byte1MQTTPacketType0000byte25RemainingLength（该字段占用1-4个字节）4.7.2VariableHeaderDescription76543210byte1-2PacketidentifierPacketidentifier4.7.3PayloadDescription格式Byte1-nTopicName2字节字串长度+utf8字串可以包含一个或多个topic.4.9 UNSUBACK4.9.1 FixedheaderBit76543210byte1MQTTPacketType0000byte25RemainingLength（该字段占用1-4个字

19、节）4.9.2 VariableHeaderDescription76543210byte1-2PacketidentifierPacketidentifier5接入流程5.1连接鉴权OnenetDevice（Connect谭权请求（ConnAck谭权结果力口载session设备向平台发起connect请求.connect中携带鉴权信息，具体参见（报文格式参考4.1）平台拿到鉴权信息进行鉴权.鉴权通过后，如果cleansession=0,平台将会加载保存的设备的一些信息.如订阅列表（4.1.2中描述）.如果cleansession=1,设备没有保存信息在平台，则不加载设备相关信息返回鉴权结果C

20、onnAck（报文格式参考4.2）.5.2消息发布5.2.1数据点上报设备使用publish报文来上传数据点，报文格式如下:VariableHeader：Field名称说明格式FieldlTopicName="$dp"$dp为系统上传数据点的指令2字节字串长度+utf8字串Payload:Payload包含真正的数据点内容，支持的格式如下:说明bit76543210Byte1Bit0-5数据类型指示，目前支持：Type=1可离散浮点数数据流Type=7Bit6-7flags根据具体类型不同意义00000001Byte2根据数据类型指小/、同oooByten数据类型1格式说明

21、:Byte1数据点类型值：1/1:json格式1字符串00000001Byte2指小后面json子符串长度固定两字节长度局仅字节，值为0x00Byte3固定两字节长度低位字节，值为0x41Byte4（datastreams”:/可以同时传递多个数据流（id"'temperature",datapoints”:（“at":“2013-04-2222:22:22”/可选"value”:36.5/用户自定义）,（id":"location”datapoints”:,Byten数据类型7（type=7格式说明：（每次最多500个数据流

22、的浮点数）Byte1Bit0-5数据类型指示：type=7/可离散浮点数数据流Bit6:保留，置0Bit7:时间指示位，1,携带6字节时间10000111Byte2年（后两位），例如2016年，则该字节为1600010000Byte3月（1-12）Byte4日（1-31）Byte5小时（023）Byte6分钟（059）Byte7秒（059）Byte8数据流名称（取值范围1-65535）高位字节，值为0x00Byte9低位字节，值为0x01Byte10数据流个数（取值范围1-500）高位字节，值为0x00Byte11低位字节，值为0x01Byte104字由float类型，低位在前，局位在后Byt

23、e11Byte12Byte13.Byten数据流名称（取值范围1-65535）高位字节，值为0x24Byten+1低位字节，值为0x37Byten+2数据流个数（取值范围1-500）高位字节，值为0x01Byten+3低位字节，值为0x00Byten+24字由float类型，低位在前，局位在后Byten+4Byten+5Byten+Qos0(Client->Server)OneNetDevicePublish$dp(Qos0)存储设备发布Qos0消息（上报数据点）平台收到上报数据点后保存起来.Qos1(Client->Server)设备发布Qos0消息

24、（上报数据点）平台收到上报数据点后保存起来.平台给设备回复PubAck（报文格式参考4.5）5.2.2平台命令（下发&回复） 命令下发平台使用publish报文来下发平台指令，报文格式如下:FixHeader：参考4.3.1VariableHeader：Field名称说明格式Field1TopicName="$creq/cmduuid”$creq为系统下发Cmd的指令，cmduuid为该条指令的uuid2字节字串长度+utf8字串Payload:Payload包含真正的指令内容.1Qos0(Server->Client)DeviceOneNe

25、tPublish$creq(Qos0)命令下发：平台向设备发送topic为$534的消息（该topic为平台命令）.设备收到topic为$534的topic时，需将其作为平台下发的指令来处理命令回复设备使用publish报文来回复平台指令，报文格式如下:FixHeader：参考4.3.1VariableHeader：Field名称说明格式Field1TopicName="$crsp/cmduuid”$crsp为系统处理设备回复cmd的指令，cmduuid为该条指令的uuid2字节字串长度+utf8字串Payload:Payload包含真正回复的指令内容.1

26、Qos0(Client->Server).1Qos1(Client<->Server)如果设备回复响应时以Qos1回复，则平台需要给设备回复一个Puback消息5.3仓1J建TopicIDevice)OneNethttp请求HTTP响应设备通过发送HTTP请求进行topic的创建操作平台收到请求后创建topic并返回结果.请求及响应定义如下：HIIP方法POSTURLHIIP头部api-key:xxxx-ffff-zzzzz,必须masterkeyURL参数Hiipbody内容（namexxxxxxtopic名子，只能由英文，下划线，反斜杠组成，最长1024个子符，同一广品下topicname/