瑞芯微(EASY EAI)RV1126B mqtt

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