1. MQTT簡介

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

1.1 發布和訂閱

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

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

l MQTT傳輸的消息分為：主題（topic）和負載（payload）兩部分。

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

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

1.2 服務質量QoS（Quality of Service levels）

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

1.2.1 QoS 0

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

1.2.2 QoS 1

至少一次，確保消息到達，但消息重復可能會發生。

1.2.3 QoS 2

只有一次，確保消息到達一次。這一級別可用于如下情況，在計費系統中，消息重復或丟失會導致不正確的結果。

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

1.3 開源項目介紹

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

其官網是：https://www.eclipse.org/

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

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

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

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

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

其官網是：https://mosquitto.org/

在Ubuntu系統中，可以直接通過下方命令進行安裝相關開發庫：

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

1.4 常規通信模型

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

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

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

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

若要MQTT Server跟隨Ubuntu開機啟動，可補充執行下方命令：

sudo systemctl enable mosquitto

1.5 演示說明

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

首先對板卡上電、連網。然后通過串口調試或ssh調試，進入板卡后臺。安裝MQTT相關資源：

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

2. 快速上手

2.1 開發環境準備

如果您初次閱讀此文檔，請閱讀《入門指南/開發環境準備/Easy-Eai編譯環境準備與更新》，并按照其相關的操作，進行編譯環境的部署。

在PC端Ubuntu系統中執行run腳本，進入EASY-EAI編譯環境，具體如下所示。

cd ~/develop_environment ./run.sh 2204

2.2 源碼下載以及例程編譯

在EASY-EAI編譯環境下創建存放源碼倉庫的管理目錄：

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

通過git工具，在管理目錄內克隆遠程倉庫

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

注：

* 此處可能會因網絡原因造成卡頓，請耐心等待。

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

進入到對應的例程目錄執行編譯操作，具體命令如下所示：

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

注：

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

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

2.3 例程運行

通過串口調試或ssh調試，進入板卡后臺，定位到例程部署的位置，如下所示：

cd /userdata/Demo/netProtocol-mqtt

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

./test-mqtt_subscription &

注：

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

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

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

./test-mqtt_publish

2.4 運行效果

API的詳細說明，以及API的調用（本例程源碼），詳細信息見下方說明。

3. Mosquitto庫函數說明

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

3.1 引用方式

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

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

3.2 初始化Mosquitto庫

設置證書的函數原型為：

int mosquitto_lib_init(void);

具體介紹如下所示。

3.3 創建一個新的Mosquitto客戶端實例

創建一個新的Mosquitto客戶端實例的函數原型為：

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

具體介紹如下所示。

3.4 設置連接回調函數

用于處理與Broker的連接狀態變化，函數原型如下所示。

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

具體介紹如下所示。

3.5 設置斷開連接回調函數

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

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

具體介紹如下所示。

3.6 設置消息發布回調函數

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

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

具體介紹如下所示。

3.7 設置訂閱回調函數

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

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

具體介紹如下所示。

3.8 連接到指定的 Broker

函數原型如下所示。

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

具體介紹如下所示。

3.9 訂閱一個主題

函數原型如下所示。

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

具體介紹如下所示。

3.10 發布一條消息到指定主題

函數原型如下所示。

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

具體介紹如下所示。

3.11 與 Broker 斷開連接

函數原型如下所示。

void mosquitto_disconnect(struct mosquitto *mosq);

具體介紹如下所示。

3.12 銷毀 Mosquitto 客戶端實例

函數原型如下所示。

void mosquitto_destroy(struct mosquitto *mosq);

具體介紹如下所示。

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

函數原型如下所示。

void mosquitto_lib_cleanup(void);

具體介紹如下所示。

4. 使用實例

l 發送示例代碼路徑為：

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

l 訂閱示例代碼路徑為：

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