ONENET設(shè)備終端接入?yún)f(xié)議4-MQTT

1、Message Queuing Telemetry Transport (MQTT)版本號(hào)修訂日期修訂內(nèi)容說明2019/8草稿201重構(gòu)Liuyuan201W19豐富報(bào)文格式，業(yè)務(wù)流程Leihong20113增加設(shè)備間訂閱，創(chuàng)建topic功能Leihong目錄1 說明32 接入流程33 Packet格式說明4Fixed header4Variable Header &Payload44 支持的packet5CONNECT5Fixed Header5VariableHeader5Payload 6CON NACK6Fixed Header6VariableHeader6PUBLISH (

2、client -> server) 7Fixed header7VariableHeader7Payload8PUBLISH (server -> client) 8Fixed header8VariableHeader8Payload8PUBACK9Fixed header9VariableHeader9SUBSCRIBE9Fixed header9VariableHeader9Payload9SU BACK10Fixed header10VariableHeader10Payload10UNSUBSCRIBE10Fixed header10VariableHeader11Pay

3、load11UNSUBACK11Fixed header11VariableHeader115 接入流程12連接鑒權(quán)12消息發(fā)布13數(shù)據(jù)點(diǎn)上報(bào)13平臺(tái)命令（下發(fā)&回復(fù)）17創(chuàng)建 Topic19訂閱21取消訂閱21推送設(shè)備Topic221說明MQTT協(xié)議詳細(xì)內(nèi)容請(qǐng)參見MQTT version官方文檔，本文檔對(duì)此不做詳細(xì)說明，僅指明OneNet的要求、默認(rèn) 參數(shù)、以及當(dāng)前實(shí)現(xiàn)與MQTT官方文檔的差異。該版本支持的功能：鑒權(quán)；數(shù)據(jù)點(diǎn)上報(bào)卜平臺(tái)指定topic）;創(chuàng)建topic;獲取項(xiàng)目的topic列表；訂閱/取消平臺(tái)的topic;設(shè)備間topic訂閱；平臺(tái)命令下發(fā)；QosO(c?S) zQos

4、l(C->S);接入流程2.1 訪問平臺(tái)注冊(cè)用戶；2.2 用戶根據(jù)業(yè)務(wù)情況，在“連接請(qǐng)求”章節(jié)中選擇EDP登錄方式（目前公測(cè)階段，頁面還未提供MQTT登錄 選項(xiàng)，登錄方式與EDP兼容）；2.3 登錄需填寫設(shè)備相關(guān)屬性，在項(xiàng)目下新增設(shè)備，獲取項(xiàng)目ID、設(shè)備ID,以及authinfo等信息：2.4 設(shè)備發(fā)送TCP連接請(qǐng)求到以下地址，發(fā)送封裝的報(bào)文與平臺(tái)交互。平臺(tái)服務(wù)器地址，TCP端口 6002Packet格式說明包格式包含三部分:Fixed Header所有packet中都必須有Varable Header部分包含有Payload部分包含有Fixed headerBit76543210byt

5、e 1MQTT Packet Type0000byte2 - 5Remaining Length （該字段占用1-4個(gè)字節(jié)）該版本支持的所有類型:名字值流向描述CONNECT1c->s客戶端請(qǐng)求與服務(wù)端建立連接CONNACK2s->c服務(wù)端確認(rèn)連接建立PUBLISH3c?s發(fā)布消息PUBACK4c?s收到發(fā)布消息確認(rèn)SUBSCRIBE8c->s訂閱請(qǐng)求SUBACK9s->c訂閱確認(rèn)UNSUBSCRIBE10c->s取消訂閱UNSUBACK11s->c取消訂閱確認(rèn)Variable Header &Payload消息類型Variable HeaderPa

6、yloadCONNECT有有CONNACK有有PUBLISH有有PUBACK有無SUBSCRIBE有有SUBACK有有UNSUBSCRIBE有有UNSUBACK有無4支持的packet4.1 CONNECTFixed HeaderBit76543210byte 1MQTT Packet Type0000byte2 - 5Remaining Length (該字段占用1-4個(gè)字節(jié))VariableHeaderDescription76543210byte 1-2ProtocolNameLength0000000000000100byte 3'M，01001101byte 49，01010

7、001byte 5T01010100byte 6T01010100Byte7Protocol Level00000001Byte8Connect FlagUser flagPasswordflagW 川 RetainFlagWillQosFlagWillFlagCleanSession FlagReserveByte9-10KeepAlive(i) 版本必須設(shè)置為4,平臺(tái)只支持版本v ,不支持更老的版本。使用第三方客戶端時(shí)需要注意選擇正確的版本。(2) user flag 與 password flag平臺(tái)不允許匿名登陸，因此這兩個(gè)標(biāo)志位在連接時(shí)必須設(shè)置為1,否則認(rèn)為協(xié)議錯(cuò)誤，平臺(tái)將會(huì)斷開連接

8、。(3) will flag 與 Willretainflag/Willqosflag平臺(tái)暫不支持will flag* WillRetain Flag與WillQos Flag必須設(shè)置為0。(4) CleanSessionFlag若客戶端將clean session標(biāo)志位設(shè)置為0,：與其斷開后，平臺(tái)將會(huì)保存session, session需保持的內(nèi)容包含: 客戶端訂閱的topic列表.客戶端保存session的內(nèi)容包含：已經(jīng)發(fā)送到服務(wù)端的但還沒有收到確認(rèn)的Qosl消息列表.待發(fā)送的QosO列表.(5) Reserve保留位，置0。(6) KeepAlive保活時(shí)間每個(gè)客戶端可自定義設(shè)置連接保持

9、時(shí)間，最短120秒，最長65535秒。PayloadDescription是否必須存在格式FieldlClient Identifier是2字節(jié)字串長度+utf8字串Field2UserName是2字節(jié)字串長度+utf8字串Field3UserPassword是2字節(jié)字串長度+utf8字串與鑒權(quán)相關(guān)的字段包含client id, username和password,支持鑒權(quán)方式。字段設(shè)置消息示例clientjd設(shè)置為平臺(tái)創(chuàng)建設(shè)備時(shí)的設(shè)備idusername設(shè)置為“項(xiàng)目ID”password設(shè)置為“鑒權(quán)信息(auth_info)clientJd=/123/, username=”433223 p

10、assword="注冊(cè)的鑒權(quán)信息”各字段說明如下：項(xiàng)目ID：在平臺(tái)添加項(xiàng)目時(shí)平臺(tái)生成的ID：鑒權(quán)信息(auth_info)：在平臺(tái)申請(qǐng)?jiān)O(shè)備時(shí)填寫設(shè)備的auth_inf。屬性(數(shù)字+字母的字符串)，該屬性需要產(chǎn)品 內(nèi)具備唯一性：4.2 CONNACKFixed HeaderBit76543210byte 1MQTT Packet Type0000byte2 - 5Remaining Length （該字段占用1-4個(gè)字節(jié)）VariableHeaderDescription76543210byte 1Acknowledge Flags0000000Spbyte 2Return CodeX

11、XXXXXXXSp: Session Present Flag, session信息在服務(wù)器已保持，置1；未保存，置0。返回碼說明:返回碼描述0成功1協(xié)議版本錯(cuò)誤2非法的clientid3服務(wù)不可用4用戶名或密碼錯(cuò)誤5非法鏈接（比如token非法）失?。?如果connect包不符合協(xié)議內(nèi)容約束，則直接斷掉連接，而不需要發(fā)送connack包.*如果鑒權(quán)或授權(quán)失敗，回復(fù)一個(gè)帶非0錯(cuò)誤碼的connack包.成功：* 必須斷掉重復(fù)的clientid.* 執(zhí)行cleansession對(duì)應(yīng)的操作.* 必須回復(fù)一個(gè)connack,回復(fù)碼為0.* 開始消息傳遞，并加入keepalive的監(jiān)視.PS：客戶端需要

12、等到服務(wù)端的connack報(bào)文，才能發(fā)送后續(xù)的數(shù)據(jù)包.43 PUBLISH (client -> server)Fixed headerBit76543210byte 1MQTT Packet TypeDUP flagQoS LevelRETAINbyte2 - 5Remaining Length （該字段占用1-4個(gè)字節(jié)）DUP:QoSl：如果為0,則表示是第一次發(fā)送該包，如果為1,則表示為重復(fù)發(fā)送的包。QosO： DUP必須為0QOS:指定了該publish包的qos等級(jí)如下RETAIN:暫不實(shí)現(xiàn)Qos值Bit2Bitl描述000最多發(fā)送一次101至少發(fā)送一次PS:該版本只實(shí)現(xiàn)Qos

13、O, QoslVariableHeaderDescription格式是否必須FieldlTopicName2字節(jié)字串長度+utf8字串是Field2Packetidentifier2字在QoSO:否，QoSl:是Payload內(nèi)容根據(jù)不同業(yè)務(wù)自定義.4.4 PUBLISH (server -> client)Fixed headerBit76543210byte 1MQTT Packet TypeDUP flagQoS LevelRETAINbyte2 - 5Remaining Length （該字段占用1-4個(gè)字節(jié)）DUP:QoSl：如果為0,則表示是第一次發(fā)送該包，如果為1,則表示為

14、重復(fù)發(fā)送的包。QosO： DUP必須為0QOS:指定了該publish包的qos等級(jí)如下RETAIN:Qos值Bit2Bitl描述000最多發(fā)送一次PS:該版本只實(shí)現(xiàn)QosOVariableHeaderDescription格式FieldlTopicName2字節(jié)字串長度+utf8字串Payload內(nèi)容根據(jù)不同業(yè)務(wù)自定義.4.5 PUBACKFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （該字段占用1-4個(gè)字節(jié)）VariableHeaderDescription76543210byte 12Pa

15、cketidentifierPacketidentifier4.6 SUBSCRIBEFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （該字段占用1-4個(gè)字節(jié)）VariableHeaderDescription76543210byte 12PacketidentifierPacketidentifierPayloadDescription格式BytelnTopicName2字節(jié)字串長度+utf8字串Byten+1Reserved保留字節(jié)（兼容說明可以包含一個(gè)或多個(gè)topic.topic必須是數(shù)字、

16、英文、反斜杠（/）的組合，目前不支持通配符。每個(gè)客戶端最多訂閱100個(gè)topic：以下topic被系統(tǒng)保留使用，（客戶端不能訂閱）：類型說明$開頭平臺(tái)保留4.7 SUBACKFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （該字段占用1-4個(gè)字節(jié)）VariableHeaderDescription76543210byte 12PacketidentifierPacketidentifierPayloadDescription76543210byte 1retcode返回碼說明:返回碼描述0x00成

17、功0x80失敗4.8 UNSUBSCRIBEFixed headerBit76543210byte 1MQTT Packet Type0000byte2 5Remaining Length （該字段占用1-4個(gè)字節(jié)）VariableHeaderDescription76543210byte 12PacketidentifierPacketidentifierPayloadDescription格式Bytel-nTopicName2字節(jié)字串長度+utf8字串可以包含一個(gè)或多個(gè)topic.UNSUBACKFixed headerBit76543210byte 1MQTT Packet Type00

18、00byte2 5Remaining Length （該字段占用1-4個(gè)字節(jié)）VariableHeaderDescription76543210byte 12PacketidentifierPacketidentifier5接入流程5.1連接鑒權(quán)DeviceOnenet(ConnAck)鑒權(quán)結(jié)果 .(Connect)鑒權(quán)請(qǐng)求鑒權(quán)加載 session設(shè)備向平臺(tái)發(fā)起connect請(qǐng)求.connect中攜帶鑒權(quán)信息，具體參見(報(bào)文格式參考平臺(tái)拿到鑒權(quán)信息進(jìn)行鑒權(quán).鑒權(quán)通過后，如果cleansession=0,平臺(tái)將會(huì)加載保存的設(shè)備的一些信息.如訂閱列表中描述 如果cleansession=l,設(shè)備沒

19、有保存信息在平臺(tái)，則不加載設(shè)備相關(guān)信息.返回鑒權(quán)結(jié)果ConnAck(報(bào)文格式參考.5.2消息發(fā)布數(shù)據(jù)點(diǎn)上報(bào)設(shè)備使用publish報(bào)文來上傳數(shù)據(jù)點(diǎn)，報(bào)文格式如下:VariableHeader：Field名稱說明格式FieldlTopicName=/$dp/$dp為系統(tǒng)上傳數(shù)據(jù)點(diǎn)的指令2字節(jié)字串長度+utf8字串Payload:Payload包含真正的數(shù)據(jù)點(diǎn)內(nèi)容，支持的格式如下:字節(jié)說明bit76543210Byte 1BitO-5數(shù)據(jù)類型指示，目前支持：Type = 1Byte nQosl(Client->Server)設(shè)備發(fā)布QosO消息（上報(bào)數(shù)據(jù)點(diǎn)） 平臺(tái)收到上報(bào)數(shù)據(jù)點(diǎn)后保存起來.平臺(tái)

20、給設(shè)備回復(fù)PubAck（報(bào)文格式參考平臺(tái)命令（下發(fā)&回復(fù)）命令下發(fā)平臺(tái)使用publish報(bào)文來下發(fā)平臺(tái)指令，報(bào)文格式如下:FixHeader：參考 VariableHeader：Field名稱說明格式FieldlTopicName=/$creq/cmduuid/$creq為系統(tǒng)卜發(fā)Cmd的指令， cmduuid為該條指令的uuid2字節(jié)字串長度+utf8字串Payload:Payload包含真正的指令內(nèi)容.1 QosO(Server->Client)Publish $creq(QosO)命令下發(fā)：平臺(tái)向設(shè)備發(fā)送topic為$（：耳的消息（該topic為平臺(tái)命令）.設(shè)備收到topi

21、c為$creq的topic時(shí)，需將其作為平臺(tái)下發(fā)的指令來處理.命令回復(fù)設(shè)備使用publish報(bào)文來回復(fù)平臺(tái)指令，報(bào)文格式如下:FixHeader：參考 VariableHeader：Field名稱說明格式FieldlTopicName=/,$crsp/cmduuidz/$crsp為系統(tǒng)處理設(shè)備回第cmd的 指令,cmduuid為該條指令的uuid2字節(jié)字串長度+utf8字串Payload:Payload包含真正回復(fù)的指令內(nèi)容.1 QosO(Client->Server).1 Qosl(Client<-> Server)如果設(shè)備回復(fù)響應(yīng)時(shí)以Qosl回復(fù)，則平臺(tái)需要給設(shè)備回復(fù)一個(gè)Puback消息5.3 創(chuàng)建 Topic設(shè)備通過發(fā)送HTTP請(qǐng)求進(jìn)行topic的創(chuàng)建操作. 平臺(tái)收到請(qǐng)求后創(chuàng)建topic并返回結(jié)果.請(qǐng)求及響應(yīng)定義如下:HTTP方法POSTURL頭部api-key:xxxx-ffff-zz