玩轉OneNET物聯網平臺之MQTT服務① —— OneNetMqtt全方位調試

1.MQTT簡介

    MQTT協議是一個面向物聯網應用的即時通信協議，使用TCP/IP提供網絡連接，能夠對負載內容實現消息屏蔽傳輸，開銷小，可以有效降低網絡流量。
    參考博主線上博文：玩轉PubSubClient MQTT庫

特點及功能

• 長連接協議（保持心跳，keepAlive）
• 終端數據點上報，支持的數據點類型包括

整型（int）
浮點數（float）
字符串（string）
JSON格式
二進制數據

• 平臺消息下發
• 基於Topic的訂閱、發佈以及消息推送，可以實現設備間的消息單播以及組播

典型應用場景
    MQTT協議適用於設備和平臺需要保持長連接的使用場景，MQTT特點在於可以實現設備間的消息單播以及組播，可以不依賴於其他服務（下發命令服務，推送服務等）實現讓設備以應用服務器的方式對真實設備進行管理和控制。

讀者所需知識儲備：

• 玩轉PubSubClient MQTT庫
• 玩轉OneNET物聯網平臺之簡介

2.MQTT接入說明

    接入流程分爲：

• 平臺域（也就是OneNet平臺上的操作）
• 設備域（8266設備上的SDK，我們這裏用PubSubClient）

    接入步驟如下：

2.1 Step1 —— 創建產品，選擇接入協議

• 首先您需要在平臺創建一個接入協議爲MQTT的產品，查看產品創建
• 創建產品後，記錄該產品的產品ID（ProductId）

2.2 Step2 —— 創建設備，記錄設備ID等信息

創建設備有兩種方式：

• 第一種 可以通過頁面點擊添加設備，輸入設備名稱和鑑權信息（即設備編號，在8266中我們可以使用 ESP+Mac地址的方式或者ESP+ChipId的方式），具體平臺的資源模型可詳情請查看第一章 資源模型，並記錄下該設備編號（deviceId）.
• 第二種 可以通過調用創建設備API 實現設備的創建，輸入設備的設備名、接入協議、鑑權信息以及MasterKey等信息，即可在平臺上創建設備（博主比較喜歡這一種，也比較靈活）。

2.3 Step3 —— 建立設備與平臺間的協議連接

• MQTT服務器地址域名爲：mqtt.heclouds.com

    使用Step1和Step2中的參數作爲登錄參數，使用SDK中的對應接口組織MQTT連接報文，發送到平臺，與平臺建立MQTT連接

    若已經連接成功，在設備信息中會看到一個在線標記：

    對於初學者，博主建議先用OneNet提供的MQTT調試工具來試玩一下，已親測可用。

2.4 Step4 —— 數據流創建，數據點上傳

• 利用SDK中提供的接口函數，編寫代碼將數據上傳到平臺

2.5 Step5 —— 數據流展示，查看數據點

• 在OneNET上的設備管理下點擊數據展示，進入數據展示頁面，點擊下拉菜單，查看近期上傳的數據點；也可以選擇時間區間來查看歷史時間

3. MQTT API

    API根據用途做了幾種分類，博主這裏不重複，請參考 玩轉OneNET物聯網平臺之簡介

    當然，OneNet爲了簡單方便調試API，也給我們提供了調試界面，具體請參考

    博主在這裏不會去講解各個API的詳細用法，請大家自行去查閱官方文檔（查閱官方文檔也是鍛鍊能力的一種）。

3.1 新增設備

• 具體參考 OneNet官方文檔 - 新增設備
• 此方法比較重要，請仔細理解

3.2 註冊設備

• 具體參考 OneNet官方文檔 - 註冊設備

3.3 更新設備信息

• 具體參考 OneNet官方文檔 - 更新設備信息

3.4 查詢設備詳情

• 具體參考 OneNet官方文檔 - 查詢設備詳情

3.5 批量查詢設備信息

• 具體參考 OneNet官方文檔 - 批量查詢設備信息

3.6 批量查詢設備狀態

• 具體參考 OneNet官方文檔 - 批量查詢設備狀態

3.7 刪除設備

• 具體參考 OneNet官方文檔 - 刪除設備

3.8 新增數據流

• 具體參考 OneNet官方文檔 - 新增數據流

3.9 更新數據流屬性

• 具體參考 OneNet官方文檔 - 更新數據流屬性

3.10 查詢數據流詳情

• 具體參考 OneNet官方文檔 - 查詢數據流詳情

3.11 批量查詢數據流信息

• 具體參考 OneNet官方文檔 - 批量查詢數據流信息

3.12 刪除數據流

• 具體參考 OneNet官方文檔 - 刪除數據流

3.13 查詢設備歷史數據

• 具體參考 OneNet官方文檔 - 查詢設備歷史數據

3.14 批量查詢設備最新數據

• 具體參考 OneNet官方文檔 - 批量查詢設備最新數據

3.15 新增數據點

• 具體參考 OneNet官方文檔 - 新增數據點

3.16 上傳文件

• 具體參考 OneNet官方文檔 - 上傳文件

3.17 獲取文件

• 具體參考 OneNet官方文檔 - 獲取文件

3.18 發送命令

• 具體參考 OneNet官方文檔 - 發送命令

3.19 查詢命令狀態

• 具體參考 OneNet官方文檔 - 查詢命令狀態

3.20 查詢命令響應

• 具體參考 OneNet官方文檔 - 查詢命令響應

3.21 查詢設備歷史命令

• 具體參考 OneNet官方文檔 - 查詢設備歷史命令

3.22 新增觸發器

• 具體參考 OneNet官方文檔 - 新增觸發器

3.23 更新觸發器

• 具體參考 OneNet官方文檔 - 更新觸發器

3.24 查詢觸發器

• 具體參考 OneNet官方文檔 - 查詢觸發器

3.25 刪除觸發器

• 具體參考 OneNet官方文檔 - 刪除觸發器

3.26 新增apikey

• 具體參考 OneNet官方文檔 - 新增apikey

3.27 更新apikey

• 具體參考 OneNet官方文檔 - 更新apikey

3.28 查詢apikey

• 具體參考 OneNet官方文檔 - 查詢apikey

3.29 刪除apikey

• 具體參考 OneNet官方文檔 - 刪除apikey

3.30 發佈消息

• 具體參考 OneNet官方文檔 - 發佈消息

3.31 查詢訂閱topic的設備

• 具體參考 OneNet官方文檔 - 查詢訂閱topic的設備

3.32 查詢設備訂閱的topic

• 具體參考 OneNet官方文檔 - 查詢設備訂閱的topic

3.33 查詢產品的topic

• 具體參考 OneNet官方文檔 - 查詢產品的topic

4.設備端接入MQTT流程

前提：

• 讀者已經瞭解MQTT協議
• 讀者已經在OneNet上建立了Mqtt協議產品，比如博主這裏建立了彩燈-MQTT項目

4.1 連接鑑權

    在 2.3 Step3 —— 建立設備與平臺間的協議連接中說到，我們第一步就是和OneNet平臺建立連接鑑權：

• 設備向平臺發起 connect 請求.connect 中攜帶鑑權信息
• 平臺拿到鑑權信息進行鑑權
• 鑑權通過後，如果 cleansession=0, 平臺將會加載保存的設備的一些信息.如訂閱列表； 如果 cleansession=1, 設備沒有保存信息在平臺，則不加載設備相關信息
• 返回鑑權結果 ConnAck 報文

4.2 消息發佈

4.2.1 數據點上報協議說明

    設備使用publish報文來上傳數據點， 報文格式如下：

• VariableHeader

字段	Field名稱	說明	格式
Field1	TopicName=”$dp”	$dp爲系統上傳數據點的指令	2字節字串長度 + utf8字串

• Payload
  Payload包含真正的數據點內容,支持的格式如下：

數據類型 1(type == 1)格式說明：

數據類型 2(type == 2)格式說明：

數據類型 3(type == 3)格式說明：

數據類型 4(type ==4)格式說明：

數據類型 5(type ==5)格式說明：

數據類型 6(type ==6)格式說明：

數據類型 7(type == 7)格式說明：（每次最多 500 個數據流的浮點數）:

4.2.2 數據點上報 —— 質量等級Qos0(Client->Server)

• 設備發佈 Qos0 消息(上報數據點)
• 平臺收到上報數據點後保存起來.

4.2.3 數據點上報 —— 質量等級Qos1(Client->Server)

• 設備發佈 Qos1 消息(上報數據點)
• 平臺收到上報數據點後保存起來.
• 平臺給設備回覆相應的 PubAck報文

4.2.4 數據點上報 —— 質量等級Qos2(Client->Server)

• 設備發佈 Qos2 消息(上報數據點)
• 平臺收到上報數據點後保存起來
• 平臺給設備回覆相應的 PubRec 報文
• 設備需回覆平臺 PubRel 報文，如超時不回平臺則會斷開相應連接
• 平臺給設備回覆 PubComp 報文

注意：

• 數據點上報功能不支持 Retain 特性

4.2.5 下發平臺命令協議說明

    平臺使用publish 報文來下發平臺指令， 報文格式如下：

FixHeader：

• 參考MQTT篇關於固定頭的說明

VariableHeader：

字段	Field名稱	說明	格式
Field1	TopicName=”$creq/cmduuid”	$creq 爲系統下發Cmd 的指令，cmduuid 爲該條指令的uuid	2 字節字串長度+ utf8 字串

Payload:

• Payload 包含真正的指令內容

注意點：

• 因爲這裏的cmduuid爲某條指令的uuid，所以我們可以考慮正則表達式的topic

4.2.6 下發平臺命令 —— 質量等級Qos0(Server->Client)

• 平臺向設備發送topic 爲$creq 的消息(該topic 爲平臺命令). 設備收到topic 爲$creq 的topic 時，需將其作爲平臺下發的指令來處理.

注意：

• 目前命令下發以Qos0 級別進行推送

4.2.7 命令回覆協議說明

    平臺使用publish 報文來回復平臺指令， 報文格式如下：

FixHeader：

• 參考MQTT篇關於固定頭的說明

VariableHeader：

字段	Field名稱	說明	格式
Field1	TopicName=”$crsp/cmduuid”	$crsp爲系統處理設備回覆cmd 的指令，cmduuid 爲該條指令的uuid	2 字節字串長度+ utf8 字串

Payload:

• Payload 包含真正的指令內容

注意點：

• 因爲這裏的cmduuid爲某條指令的uuid，所以我們可以考慮正則表達式的topic

4.2.8 命令回覆 —— 質量等級Qos0(Client->Server)

4.2.9 命令回覆 —— 質量等級Qos1(Client<-> Server)

• 如果設備回覆響應時以Qos1 回覆，則平臺需要給設備回覆一個Puback 報文

4.2.10 命令回覆 —— 質量等級Qos2(Client<-> Server)

如果設備回覆響應時以Qos2 回覆，則:

• 1.平臺需回覆設備一個PubRec 報文
• 2.設備在收到PubRec 後需向平臺回覆PubRel 報文
• 3.平臺收到PubRel 報文後，向設備回覆PubComp 報文

4.3 創建Topic

• 設備通過發送HTTP 請求進行topic 的創建操作.
• 平臺收到請求後創建topic 並返回結果.

請求及響應定義如下：

4.4 訂閱

• 設備發起訂閱請求報文
• 平臺收到請求後更新topic 列表
• 平臺給設備回覆SubAck報文

注意：

• subscribe 的request qos 級別可以爲0、1、2

4.5 取消訂閱

• 設備發起取消訂閱請求
• 平臺收到請求後更新topic 列表
• 平臺給設備回覆UnSubAck

4.6 推送設備Topic

4.6.1 Publish 報文推送協議說明

FixHeader：

• 參考MQTT篇關於固定頭的說明

VariableHeader：

字段	Field名稱	說明	格式
Field1	TopicName	填寫設備訂閱的topic	2 字節字串長度+ utf8 字串

Payload:

• Payload 爲設備自定義內容

4.6.2 Publish 報文推送 —— 質量等級Qos0

• 設備發起推送topic 請求(以Qos0 級別)
• 平臺收到請求後,將topic 以Qos0 級別推送到相關訂閱設備(支持離線設備推送)
• 平臺不返回PubAck 或PubRec 等報文

4.6.3 Publish 報文推送 —— 質量等級Qos1

• 設備發起推送topic 請求(以Qos1 級別)
• 平臺收到請求後,將topic 以Qos1 級別推送到相關訂閱設備(支持離線設備推送)
• 平臺返回PubAck 報文

4.6.4 Publish 報文推送 —— 質量等級Qos2

• 設備發起推送topic 請求(以Qos2 級別)
• 平臺收到請求後,回覆PubRec 報文
• 設備收到PubRec 後需回覆PubRel 報文(如超時不回覆,平臺會斷開與設備的連接)
• 平臺收到PubRel 報文後,回覆PubComp 給設備
• 平臺在回覆PubComp 後會以Qos2 級別推送到相關訂閱設備(支持離線設備推送)
• 設備需回覆PubRec 報文(如超時不回覆,平臺會斷開與設備的連接)
• 平臺發送PubRel 報文給設備
• 設備需回覆PubComp(發佈完成)

4.6.5 HTTP 請求推送

• 設備以HTTP 的方式發起推送topic 請求
• 平臺收到請求後,將topic 推送到相關訂閱設備.(目前只支持在線推送)
• 平臺返回推送結果

請求及響應定義如下：

4.7 離線Topic

    普通推送（上面的推送設備Topic）只針對在線設備進行topic消息的推送，離線設備不會收到訂閱的topic 的消息。

    離線Topic則會將該消息推送給在線以及離線設備。

注意點：

• 如果設備在上線時設置了clean session flag，服務端會刪除其訂閱的topic 及相關的離線topic 消息。
• 如果設備沒有設置clean session flag，如果有與該設備相關的離線topic 消息，則在鑑權成功後將離線消息
  推送給設備。
• 遺囑消息(will msg)只會推送給訂閱了該will topic 的在線的設備，離線設備不會收到。
• 離線消息的有效期默認爲2 天(暫不支持用戶設定有效期)，服務器只會推送在2 天內的最近10 條消息。

4.8 數據點訂閱

含義：

• 同一產品下的設備可以訂閱其他設備的數據點，訂閱的topic 格式爲：/deviceid/數據流名稱。即
  被關注的設備在上傳了該數據流名稱的數據點後，訂閱了該topic 的其他設備都會收到上傳的數據點。

例子：

• A、B 設備的deviceid 分別爲9277、9278。
• A 設備訂閱了名爲/9278/9527 的topic(9278 爲設備B 的id，9527 爲B 設備上傳的數據流名稱)。
• B 設備上傳了名爲9527 的數據流(數據點爲11; 15;78…)。
• A 設備會收到多條(取決於設備B 上傳的數據點的個數)推送的topic 名爲/9278/9527 的publish 消息，消息的
  payload 中則包含設備B 上傳的數據點。

注意點：

• 目前支持訂閱的數據點的類型爲Type1~Type7

5.常見問題

5.1 MQTT連接鑑權時,Payload中ClientIdentifier;UserName;UserPassword分別填寫什麼？

• ClientIdentifier: 創建設備時得到的設備ID，爲數字字串；
• UserName: 註冊產品時，平臺分配的產品ID，爲數字字串；
• UserPassword: 爲設備的鑑權信息（即唯一設備編號，SN），或者爲apiKey，爲字符串。

5.2 MQTT需要在連接鑑權通過後才能發送其它報文嗎？

• 是的，MQTT協議必須在鑑權通過後(收到ConnAck後)，才能發送後續報文進行交互，不然服務器會直接丟棄報文。

5.3 MQTT可以訂閱Topic有什麼限制？

• OneNET不支持訂閱$開頭的系統Topic。

5.4 如何利用MQTT協議上傳數據到雲平臺？

• 設備完成連接鑑權之後，將數據按照一定的格式（見協議文檔說明）打包，將數據發佈到$dp系統Topic上即可。

5.5 訂閱之前是否需要創建Topic？

• 設備在執行訂閱時，OneNET會自動判斷該Topic是否存在，若不存在則自動創建該Topic。

5.6 設備可否通過訂閱的方式，獲取其他設備的數據流信息？

• 可以，可以通過訂閱 /device_id/數據流名 的方式，及時獲取到某設備最新的數據點信息。

5.7 設備發佈消息(Publish)有什麼限制？？

• 發佈消息只能在同一產品ID下進行，不能進行跨產品間的Publish消息推送。

6. 新手手把手感受OneNet MQTT案例

    博主這裏認爲大家已經註冊了OneNet賬號。接下來請按照下面步驟進行：

6.1 創建 ESP8266智能燈系統 產品（MQTT協議）

注意點：

• 務必選擇MQTT協議

    創建完畢後，我們點擊查看具體的產品信息：

注意點：

• 需要記錄產品ID，其用來區分產品唯一標識符
• Master-APIkey，網絡請求鑑權信息，接口調用需要帶入

6.2 API調試創建 deviceA和deviceB兩個設備

API接口定義：

• 參考官方文檔 創建設備

操作步驟：

• 通過API調試工具創建deviceA

http body：

{
    "title": "mqtt_device_A",
    "desc": "mqtt_device_A",
    "tags": ["china", "mobile"],
    "location": {
        "lon": 109,
        "lat": 23.54
    },
    "auth_info": "mqtt_device_A",
    "other": {
        "version": "1.0.0",
        "manufacturer": "china mobile"
    }
}

• 通過API調試工具創建deviceB

http body：

{
    "title": "mqtt_device_B",
    "desc": "mqtt_device_B",
    "tags": ["china", "mobile"],
    "location": {
        "lon": 109,
        "lat": 23.54
    },
    "auth_info": "mqtt_device_B",
    "other": {
        "version": "1.0.0",
        "manufacturer": "china mobile"
    }
}

• 查看設備列表

6.3 官方工具調試deviceA和deviceB

    讀者請自行下載 MQTT-device 工具。下載完工具之後請複製出兩份，一個工具代表deviceA，一個工具代表deviceB，我們模擬Mqtt操作。

6.3.1 配置deviceA

注意點：

• 重點關注博主標紅的地方，DeviceID和ProductID、AuthInfo需要填寫讀者自身創建的
• 配置完畢連接服務器

6.3.2 配置deviceB

注意點：

• 重點關注博主標紅的地方，DeviceID和ProductID、AuthInfo需要填寫讀者自身創建的
• 配置完畢連接服務器

6.3.3 deviceA訂閱主題“deviceB_to_A”

注意點：

• 主題名爲“deviceB_to_A”

6.3.4 deviceB訂閱主題“deviceA_to_B”

注意點：

• 主題名爲“deviceA_to_B”

6.3.5 deviceB發佈信息給deviceA

6.3.6 deviceA發佈信息給deviceB

6.3.7 平臺下發命令給deviceA

6.3.8 deviceA上傳數據點到平臺

7.總結

本篇作爲OneNet Mqtt篇的開頭篇，主要講解了Mqtt的使用注意事項，並且在調試工具下模擬Mqtt的常用操作，請關注接下來的篇章。