uMQTT

1、介绍

uMQTT 软件包是 RT-Thread 自主研发的，基于 MQTT 3.1.1 协议的客户端实现，它提供了设备与 MQTT Broker 通讯的基本功能

uMQTT 软件包功能如下:

实现基础的连接、订阅、发布功能;
具备多重心跳保活，设备重连机制，保证 mqtt 在线状态，适应复杂情况;
支持 QoS=0, QoS=1, QoS=2 三种发送信息质量;
支持多客户端使用;
用户端接口简便，留有多种对外回调函数;
支持多种技术参数可配置，易上手，便于产品化开发；
功能强大，资源占用率低，支持功能可裁剪。

资源占用(测试环境 W60X ):

ROM	RAM	动态RAM
12.97KByte	0.01KByte	4.9KByte

1.1 目录结构

umqtt
├───docs                                // 说明文档
├───inc  
│   ├───umqtt_internal.h                // 内部打包及发送相关头文件
│   ├───umqtt_cfg.h                     // 结构体配置头文件
│   └───umqtt.h                         // 对外提供接口头文件
├───src
│   ├───pkgs                            // 完成对 paho_mbedded 软件库的功能裁剪移植
│   │   ├───umqtt_pkgs_decode.c         // 打包实现源文件
│   │   ├───umqtt_pkgs_encode.c         // 解包实现源文件
│   ├───trans                           
│   │   └───umqtt_trans.c               // 传输层相关源文件
│   └───umqtt_utils.c                   // 通用接口实现文件
├───samples                             // finsh 调试接口示例
├───tests                               // 测试用例
├───LICENSE                             // 软件包许可证
├───README.md                           // 软件包使用说明
└───SConscript                          // RT-Thread 默认的构建脚本

1.2 许可证

uMQTT 软件包遵循 Apache-2.0 许可，详见 LICENSE 文件。

1.3 依赖

RT_Thread 3.0+
SAL 层组件

2、获取软件包

uMQTT 软件包相关配置选项介绍

--- umqtt: A MQTT Client for RT-Thread
[ ]   Enable MQTT example
[ ]   Enable MQTT test
(4)   subtopic name list numbers
(1024) send buffer size
(1024) receive buffer size
(1000) uplink timer def cycle, uint:mSec
(5)   reconnect max count
(60)  reconnect time interval, uint:Sec
(5)   keepalive func, max count
(30)  heartbeat interval, uint:Sec
(4)   connect timeout, uint:Sec
(100) receive timeout, uint:mSec
(4)   send timeout, uint:Sec
(4096) receive thread stack size
(8)   thread priority
(4)   async message ack queue count
(0xFFFF) connect information, keepalive interval, uint:Sec
[ ]   Enable change connect keepalive time, uint:Sec
      Version (latest)  --->

subtopic name list numbers: 内部允许最大同时订阅数量
send buffer size: 发送数据缓存大小
receive buffer size: 接收数据缓存大小
uplink timer def cycle, uint:mSec: 定时器运行周期, 单位: mSec
reconnect max count: 最大重连次数
reconnect time interval, uint:Sec: 重连间隔时间, 单位: Sec
keepalive func, max count: 保活机制中心跳重连次数
heartbeat interval, uint:Sec: 心跳发送间隔, 单位: Sec
connect timeout, uint:Sec: 连接超时时间, 单位: Sec
receive timeout, uint:mSec: 接收超时时间, 单位: mSec
send timeout, uint:Sec: 发送超时时间, 单位: Sec
receive thread stack size: 内部接收线程堆栈
thread priority: 内部线程优先级
async message ack queue size: 接收线程处理完接收数据向外部传送处理结果消息队列大小
connect information, keepalive interval, uint:Sec：MQTT 协议中 CONNECT 命令下 KEEPALIVE 值，默认最大 0xFF, 单位: Sec
Enable change connect keepalive time, uint:Sec: 允许修改 MQTT 连接信息中的 keepalive 时间, 单位: Sec
Version: 软件版本号

3、使用 uMQTT 软件包

3.1 软件包工作原理

uMQTT 软件包主要用于在嵌入式设备上实现 MQTT 协议，软件包的主要工作基于 MQTT 协议实现。软件包分层图如下:

umqtt_分层图

软件包实现过程中主要做了:

根据 MQTT 3.1.1 协议规定，进行软件包数据协议的封包解包；
传输层函数适配对接 SAL 层；
umqtt 客户端层，根据协议包层和传输层编写符合应用层的接口。实现基础连接、断连、订阅、取消订阅、发布消息等功能。支持 QoS0/1/2 三种发送信息质量。利用 uplink timer 定时器，实现多重心跳保活机制和设备重连机制，增加设备在线稳定性，适应复杂情况。

3.2 用户 API 介绍

3.2.1 创建对象

umqtt_client_t umqtt_create(const struct umqtt_info *info);

创建客户端结构体对象。

参数	描述
info	用户信息配置
返回值	描述
!= RT_NULL	umqtt 客户端结构体指针
== RT_NULL	创建失败

3.2.2 删除对象

int umqtt_delete(struct umqtt_client *client);

删除客户端结构体对象，并释放内存。

参数	描述
client	umqtt 客户端结构体指针
返回值	描述
UMQTT_OK	成功

3.2.3 启动客户端

int umqtt_start(struct umqtt_client *client);

启动客户端会话，进行网络连接，和 MQTT 协议连接。

参数	描述
client	umqtt 客户端结构体指针
返回值	描述
>=0	成功
<0	失败

3.2.4 停止客户端

void umqtt_stop(struct umqtt_client *client);

停止客户端会话，关闭接收线程，暂停 uplink 定时器，发送 MQTT 断开连接命令，关闭 socket 套接字。

参数	描述
client	umqtt 客户端结构体指针
返回值	描述
无	无

3.2.5 发布消息

int umqtt_publish(struct umqtt_client *client, enum umqtt_qos qos, const char *topic, void *payload, size_t length, int timeout);

针对订阅主题发布相关质量的消息。

参数	描述
client	umqtt 客户端结构体指针
qos	消息发送质量
topic	发布主题
payload	发布消息
length	发布消息的长度
timeout	发布消息超时时间, 单位:mSec
返回值	描述
>=0	成功
<0	失败

3.2.6 订阅主题

int umqtt_subscribe(struct umqtt_client *client, const char *topic, enum umqtt_qos qos, umqtt_subscribe_cb callback);

订阅主题，并设置对应主题接收 publish 消息时的回调函数。

参数	描述
client	umqtt 客户端结构体指针
topic	订阅主题
qos	订阅质量
callback	对应主题接收 publish 消息时的回调函数
返回值	描述
>=0	成功
<0	失败

3.2.7 取消订阅主题

int umqtt_unsubscribe(struct umqtt_client *client, const char *topic);

取消相关主题的订阅，并释放相关的资源。

参数	描述
client	umqtt 客户端结构体指针
topic	取消订阅主题
返回值	描述
>=0	成功
<0	失败

3.2.8 异步发送消息

int umqtt_publish_async(struct umqtt_client *client, enum umqtt_qos qos, const char *topic, void *payload, size_t length);

异步发送消息，只负责将信息发送出去，不负责阻塞接收。

参数	描述
client	umqtt 客户端结构体指针
qos	发送消息质量
topic	发送消息对应主题
payload	发布的消息
length	发布的消息长度
返回值	描述
>=0	成功
<0	失败

3.2.9 设定获取参数

int umqtt_control(struct umqtt_client *client, enum umqtt_cmd cmd, void *params);

根据相关命令设定或者读取内部相关参数。

参数	描述
client	umqtt 客户端结构体指针
cmd	设定或者读取内部相关参数
params	设定数据时，为返回值结构体；读取数据时，为 RT_NULL
返回值	描述
>=0	设定数据时, 成功; 读取数据时, 为具体返回数据
>0	设定数据时, 失败; 读取数据时, 为具体返回数据

3.3 示例介绍

3.3.1 准备工作

menuconfig 配置获取软件包和示例代码

打开 RT-Thread 提供的 ENV 工具，使用 menuconfig 配置软件包, 启用 UMQTT 软件包，并配置使能测试例程 (Enable MQTT example), 如下所示:

RT-Thread online packages
    IoT - internet of things  --->
        [*] umqtt: A MQTT Client for RT-Thread.  --->
            [*] Enable MQTT example                     # 开启 UMQTT 例程

使用 pkgs --update 命令下载软件包;
编译下载;
使用 emqx 搭建 MQTT Broker 。

3.3.2 启动例程

启动 umqtt 客户端

启动 umqtt 客户端流程:

申明 struct umqtt_info 结构体变量作为 umqtt 客户端用户配置变量
测试 MQTT Broker 的 URI 进行赋值
创建 umqtt 客户端
声明并设置连接、在线、离线、心跳回调函数
调用 umqtt_start() 函数，启动 umqtt 客户端

msh />umqtt_ex_start
[D/umqtt.sample]  umqtt example start!
[I/umqtt]  connect success!
[I/umqtt.sample]  umqtt start success!

订阅功能

msh />umqtt_ex_subscribe "test0"
[D/umqtt.sample]  umqtt example subscribe!
[D/umqtt]  start assign datas !
[D/umqtt] subscribe ack ok!

发布消息

msh />umqtt_ex_publish test 0 hello                     # 消息发送质量 qos0
[D/umqtt.sample]  umqtt example publish!
[D/umqtt.sample]  umqtt topic recv callback! name length: 4, name: testhello, packet id: 0, payload len: 6

msh />umqtt_ex_publish test 1 hello_this                # 消息发送质量 qos1 
[D/umqtt.sample]  umqtt example publish!
[D/umqtt.sample]  umqtt topic recv callback! name length: 4, name: test, packet id: 1, payload len: 11
[I/umqtt]  publish qos1 ack success!

msh />umqtt_ex_publish test 1 hello_this_world          # 消息发送质量 qos2 
[D/umqtt.sample]  umqtt example publish!
[D/umqtt.sample]  umqtt topic recv callback! name length: 4, name: test, packet id: 2, payload len: 17
[I/umqtt]  publish qos2 ack success!

取消订阅

msh />umqtt_ex_unsubscribe test
[D/umqtt.sample]  umqtt example unsubscribe!
[I/umqtt]  unsubscribe ack ok!

停止 umqtt 客户端

msh />umqtt_ex_stop
[D/umqtt.sample]  umqtt example stop!

4、注意事项

本版本暂不支持加密通信协议;
使用 emqx 搭建 MQTT Broker 。

5、联系方式 & 感谢

联系人: springcity
Email: caochunchen@rt-thread.com

RT-Thread-packages / umqtt

readme