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
推荐阅读：
