1. MQTT簡介

MQTT（Message Queuing Telemetry Transport，消息隊列遙測傳輸協(xié)議），是一種基于發(fā)布/訂閱（publish/subscribe）模式的“輕量級”通訊協(xié)議。MQTT最大優(yōu)點在于，用極少的代碼和有限的帶寬，為連接遠(yuǎn)程設(shè)備提供實時可靠的消息服務(wù)。作為一種低開銷、低帶寬占用的即時通訊協(xié)議，使其在物聯(lián)網(wǎng)、小型設(shè)備、移動應(yīng)用等方面有較廣泛的應(yīng)用。

1.1 發(fā)布和訂閱

MQTT使用的發(fā)布/訂閱消息模式，它提供了一對多的消息分發(fā)機(jī)制，從而實現(xiàn)與應(yīng)用程序的解耦。這是一種消息傳遞模式，消息不是直接從發(fā)送器發(fā)送到接收器（即點對點），而是由MQTT server（或稱為 MQTT Broker）分發(fā)的。

l 在MQTT通訊過程中，有三種身份，分別是發(fā)布者（publisher）、代理（broker）、和訂閱者（subscriber）。

l MQTT傳輸?shù)南⒎譃椋褐黝}（topic）和負(fù)載（payload）兩部分。

發(fā)布者向代理（MQTT Broker）發(fā)布topic的消息，代理將該消息推送到所有訂閱該topic的訂閱者。

* 發(fā)布消息的客戶端就是發(fā)布者，訂閱topic消息的客戶端就是訂閱者

1.2 服務(wù)質(zhì)量QoS（Quality of Service levels）

服務(wù)質(zhì)量是 MQTT 的一個重要特性。當(dāng)我們使用 TCP/IP 時，連接已經(jīng)在一定程度上受到保護(hù)。但是在無線網(wǎng)絡(luò)中，中斷和干擾很頻繁，MQTT 在這里幫助避免信息丟失及其服務(wù)質(zhì)量水平。

1.2.1 QoS 0

至多一次，消息發(fā)布完全依賴底層 TCP/IP 網(wǎng)絡(luò)。會發(fā)生消息丟失或重復(fù)。這一級別可用于如下情況，環(huán)境傳感器數(shù)據(jù)，丟失一次讀記錄無所謂，因為不久后還會有第二次發(fā)送。

1.2.2 QoS 1

至少一次，確保消息到達(dá)，但消息重復(fù)可能會發(fā)生。

1.2.3 QoS 2

只有一次，確保消息到達(dá)一次。這一級別可用于如下情況，在計費系統(tǒng)中，消息重復(fù)或丟失會導(dǎo)致不正確的結(jié)果。

* 帶有唯一消息 ID 的消息會存儲兩次，首先來自發(fā)送者，然后是接收者。QoS 級別 2 在網(wǎng)絡(luò)中具有最高的開銷，因為在發(fā)送方和接收方之間需要兩個流.

1.3 開源項目介紹

根據(jù)廣泛使用情況和社區(qū)活躍度，Eclipse Paho C庫是目前中最常用的最流行的C語言MQTT客戶端開源庫，可應(yīng)用于Windows/MAC/Linux/FreeRTOS/ESP32等平臺。

其官網(wǎng)是：https://www.eclipse.org/

其gitHub倉庫是：https://github.com/eclipse-paho/paho.mqtt.c

在Ubuntu系統(tǒng)中，既可以通過直接編譯gitHub倉庫得到所需的庫和頭文件，也可以通過下方命令直接安裝（此步可不執(zhí)行）：

sudo apt-get update sudo apt-get install libpaho-mqtt-dev

雖然Paho C有著支持的平臺全，兼容性好的優(yōu)點。但也有著【API較底層】，易用性差，需要進(jìn)一步封裝的局限性。

因此本文采用Eclipse旗下的另外一個MQTT項目：mosquitto。此項目對于資源受限的嵌入式設(shè)備較為合適，雖然沒有Paho C那么全面，但也能滿足基本需要，并且更加易用。

其官網(wǎng)是：https://mosquitto.org/

在Ubuntu系統(tǒng)中，可以直接通過下方命令進(jìn)行安裝相關(guān)開發(fā)庫：

sudo apt-get update sudo apt-get install libmosquitto-dev

1.4 常規(guī)通信模型

一個常規(guī)的使用方式：MQTT Server代理程序部署在云端，板卡作為發(fā)布者和訂閱者進(jìn)行數(shù)據(jù)收發(fā)通信，通信模型如下。

若想在局域網(wǎng)使用，可以在PC平臺(Windows/Linux)上部署一個MQTT Server代理程序，板卡作為發(fā)布者和訂閱者進(jìn)行數(shù)據(jù)收發(fā)通信，通信模型如下。

比如，可以通過以下命令，在Ubuntu系統(tǒng)中部署一個MQTT Server：

sudo apt-get update sudo apt-get install mosquitto sudo systemctl start mosquitto

若要MQTT Server跟隨Ubuntu開機(jī)啟動，可補(bǔ)充執(zhí)行下方命令：

sudo systemctl enable mosquitto

1.5 演示說明

本文為了便于對demo解說，因此會把【代理】、【訂閱者】、【發(fā)布者】都部署在【同一臺板卡設(shè)備】中。

首先對板卡上電、連網(wǎng)。然后通過串口調(diào)試或ssh調(diào)試，進(jìn)入板卡后臺。安裝MQTT相關(guān)資源：

sudo apt-get update sudo apt-get install libmosquitto-dev mosquitto sudo systemctl enable mosquitto && sudo systemctl start mosquitto

2. 快速上手

2.1 開發(fā)環(huán)境準(zhǔn)備

如果您初次閱讀此文檔，請閱讀《入門指南/開發(fā)環(huán)境準(zhǔn)備/Easy-Eai編譯環(huán)境準(zhǔn)備與更新》，并按照其相關(guān)的操作，進(jìn)行編譯環(huán)境的部署。

在PC端Ubuntu系統(tǒng)中執(zhí)行run腳本，進(jìn)入EASY-EAI編譯環(huán)境，具體如下所示。

cd ~/develop_environment ./run.sh 2204

2.2 源碼下載以及例程編譯

在EASY-EAI編譯環(huán)境下創(chuàng)建存放源碼倉庫的管理目錄：

cd /opt mkdir EASY-EAI-Toolkit cd EASY-EAI-Toolkit

通過git工具，在管理目錄內(nèi)克隆遠(yuǎn)程倉庫

git clone https://github.com/EASY-EAI/EASY-EAI-Toolkit-1126B.git

注：

* 此處可能會因網(wǎng)絡(luò)原因造成卡頓，請耐心等待。

* 如果實在要在gitHub網(wǎng)頁上下載，也要把整個倉庫下載下來，不能單獨下載本實例對應(yīng)的目錄。

進(jìn)入到對應(yīng)的例程目錄執(zhí)行編譯操作，具體命令如下所示：

cd EASY-EAI-Toolkit-1126B/Demos/netProtocol-mqtt/ ./build.sh

注：

* 由于依賴庫部署在板卡上，因此交叉編譯過程中必須保持/mnt掛載。

注：若編譯失敗，提示找不到mosquitto.h，請查看本文章節(jié)：==1.5演示說明==

2.3 例程運行

通過串口調(diào)試或ssh調(diào)試，進(jìn)入板卡后臺，定位到例程部署的位置，如下所示：

cd /userdata/Demo/netProtocol-mqtt

首先運行【訂閱者】程序，如下所示：

./test-mqtt_subscription &

注：

* 若運行失敗，提示“連接失敗: Connection refused”，請查看本文章節(jié)：==1.5演示說明==

* 由于【訂閱者】是后臺運行，若要重新運行，記得先把它kill掉。

然后接著運行【發(fā)布者】程序。如下所示：

./test-mqtt_publish

2.4 運行效果

API的詳細(xì)說明，以及API的調(diào)用（本例程源碼），詳細(xì)信息見下方說明。

3. Mosquitto庫函數(shù)說明

本章節(jié)介紹本例程涉及mosquitto庫的接口使用方法，更多的接口說明參考官網(wǎng)API文檔：https://mosquitto.org/api/files/mosquitto-h.html

3.1 引用方式

EASY EAI api庫位于本倉庫的easyeai-api目錄中。為方便客戶在本地工程中直接調(diào)用我們的EASY EAI api庫，此處列出工程中需要鏈接的庫以及頭文件等，方便用戶直接添加。

API源代碼路徑為EASY-EAI-Toolkit-1126B/easyeai-api/netProtocol/mqtt/。用戶可通過源代碼了解接口實現(xiàn)，甚至可對源碼進(jìn)行修改。

3.2 初始化Mosquitto庫

設(shè)置證書的函數(shù)原型為：

int mosquitto_lib_init(void);

具體介紹如下所示。

3.3 創(chuàng)建一個新的Mosquitto客戶端實例

創(chuàng)建一個新的Mosquitto客戶端實例的函數(shù)原型為：

struct mosquitto *mosquitto_new(const char *id, bool clean_session, void *userdata);

具體介紹如下所示。

3.4 設(shè)置連接回調(diào)函數(shù)

用于處理與Broker的連接狀態(tài)變化，函數(shù)原型如下所示。

void mosquitto_connect_callback_set(struct mosquitto *mosq, void (*on_connect)(struct mosquitto *, void *,int));

具體介紹如下所示。

3.5 設(shè)置斷開連接回調(diào)函數(shù)

用于處理與Broker的斷開連接事件，函數(shù)原型如下所示。

void mosquitto_disconnect_callback_set(struct mosquitto *mosq, void (*on_disconnect)(struct mosquitto *, void *, int));

具體介紹如下所示。

3.6 設(shè)置消息發(fā)布回調(diào)函數(shù)

用于處理消息成功發(fā)送到Broker的事件，函數(shù)原型如下所示。

void mosquitto_publish_callback_set(struct mosquitto *mosq, void (*on_publish)(struct mosquitto *, void *, int));

具體介紹如下所示。

3.7 設(shè)置訂閱回調(diào)函數(shù)

用于處理成功訂閱一個或多個主題的事件，函數(shù)原型如下所示。

void mosquitto_subscribe_callback_set(struct mosquitto *mosq, void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *));

具體介紹如下所示。

3.8 連接到指定的 Broker

函數(shù)原型如下所示。

int mosquitto_connect(struct mosquitto *mosq, const char *host, int port, int keepalive);

具體介紹如下所示。

3.9 訂閱一個主題

函數(shù)原型如下所示。

int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const char *sub, int qos);

具體介紹如下所示。

3.10 發(fā)布一條消息到指定主題

函數(shù)原型如下所示。

int mosquitto_publish(struct mosquitto *mosq, int *mid, const char *topic, int payloadlen, const void *payload, int qos, bool retain);

具體介紹如下所示。

3.11 與 Broker 斷開連接

函數(shù)原型如下所示。

void mosquitto_disconnect(struct mosquitto *mosq);

具體介紹如下所示。

3.12 銷毀 Mosquitto 客戶端實例

函數(shù)原型如下所示。

void mosquitto_destroy(struct mosquitto *mosq);

具體介紹如下所示。

3.13 清理并釋放 Mosquitto 庫使用的資源

函數(shù)原型如下所示。

void mosquitto_lib_cleanup(void);

具體介紹如下所示。

4. 使用實例

l 發(fā)送示例代碼路徑為：

EASY-EAI-Toolkit-1126B/Demos/netProtocol-mqtt/test-mqtt_publish.c

l 訂閱示例代碼路徑為：

EASY-EAI-Toolkit-1126B/Demos/netProtocol-mqtt/test-mqtt_subscription.c