README.md 5.3 KB
RyanMqtt
使用遇到问题可以提 issue / RT-Thread 社区提问，谢谢。
1、介绍
RyanMqtt 实现了 MQTT3.1.1 协议的客户端。此库针对资源受限的嵌入式设备进行了优化。
初衷：在使用RT-Thread时，没有非常合适的 mqtt 客户端。项目中 mqtt 又是非常核心的功能。随即参考 MQTT3.1.1 标准和项目需求设计的 mqtt 客户端，它拥有以下特点。
- 严格遵循 MQTT3.1.1 协议标准
- 稳定的全 QOS 等级实现消息实现，用户可控的消息丢弃，避免 RyanMqttQos2 / RyanMqttQos1 消息无限堆积重发消耗的内存空间
- 支持多客户端
- 客户端多功能参数配置，丰富的用户可选的事件回调，满足实际项目的绝大部分需求
- 完整的 MQTT 主题通配符支持，“/”、“#”、“+”、“$”
- 可选择的 keepalive、reconnet、lwt、session 等
- 资源占用少，依赖少
- 优化过的并发能力，无等待的连续 200 条 RyanMqttQos2 消息稳定发送和接收(取决于硬件内存大小、也取决于硬件收发能力)
- 跨平台，只需实现少量的平台接口即可
- 没有内置 TLS 支持，用户可以在接口层自己实现 TLS（作者对 TLS 并不熟悉、项目中也暂未使用到、使用 TLS 的项目也不会只有 mqtt 使用，用户自己实现也可以防止 TLS 模块间冲突）
- 不支持裸机平台，裸机想要稳定的 MQTT3.1.1 实现可以参考coreMQTT
2、设计
RyanMqtt 设计时参考了mqttclient、esp-mqtt、coreMQTT。
- 平台兼容层封装不同操作系统内核接口，方便实现跨平台
- 核心库使用著名的 paho mqtt 库作为 mqtt 封包库
- 核心线程是每个客户端必须创建的线程，统一处理客户端所有的操作，比如 mqtt 状态机、事件回调、心跳保活、消息解析、消息超时处理、消息重发等
- 系统服务管理模块提供 RyanMqtt 实现功能的工具，包含 session 状态、事件处理、通配符匹配、消息链表等
- 用户应用模块提供给用户调用的丰富的接口，包含 RyanMqtt 客户端申请 / 销毁、mqtt 多参数配置、事件注册 / 注销、QOS 消息丢弃、 mqtt 连接 / 停止 / 重连 / 发布 / 订阅 / 取消订阅等
3、平台接口
RyanMqtt 库希望应用程序为以下接口提供实现：
system 接口
RyanMqtt 需要 RTOS 支持，必须实现如下接口才可以保证 mqtt 客户端的正常运行
| 函数名称 | 函数简介 |
|---|---|
| platformMemoryMalloc | 申请内存 |
| platformMemoryFree | 释放已申请内存 |
| platformDelay | 毫秒延时 |
| platformThreadInit | 初始化线程 |
| platformThreadStart | 开启线程 |
| platformThreadStop | 挂起线程 |
| platformThreadDestroy | 销毁线程 |
| platformMutexInit | 初始化互斥锁 |
| platformMutexLock | 获取互斥锁 |
| platformMutexUnLock | 释放互斥锁 |
| platformMutexDestroy | 销毁互斥锁 |
| platformCriticalEnter | 进入临界区 / 关中断 |
| platformCriticalExit | 退出临界区 / 开中断 |
network 接口
RyanMqtt 依赖于底层传输接口 API，必须实现该接口 API 才能在网络上发送和接收数据包
MQTT 协议要求基础传输层能够提供有序的、可靠的、双向传输（从客户端到服务端 和从服务端到客户端）的字节流
| 函数名称 | 函数简介 |
|---|---|
| platformNetworkConnect | 根据 ip 和端口连接服务器 |
| platformNetworkRecvAsync | 非阻塞接收数据 |
| platformNetworkSendAsync | 非阻塞发送数据 |
| platformNetworkClose | 断开 mqtt 服务器连接 |
time 接口
RyanMqtt 依靠函数生成毫秒时间戳，用于计算持续时间和超时，内部已经做了数值溢出处理
| 函数名称 | 函数简介 |
|---|---|
| platformUptimeMs | 自系统启动以来 ms 时间戳 |
4、示例
RT-Thread 平台
- 接口示例请参考 platform/rtthread 文件夹
- RyanMqtt 使用示例请参考 example 文件夹
- 需要使能 SAL 或者 LWIP，示例使用 socket 实现数据收发。
- 需要 MSH 组件，示例默认挂载到 MSH 组件
其余平台暂无示例
5、依赖
请根据自己平台实现RyanLogPrintf, 在common/RyanMqttLog.h
6、声明
- 请勿将此库 QOS 消息等级用于支付等可能造成重大损失的场景，如需使用请自行深度评估后使用，作者不对使用此库造成的任何损失负责。一般也不会选择只是用 qos2 来保证安全。（尽管此库 RyanMqttQos2 消息等级经过很多测试，但是异步组件由于诸多因素例如波动非常大的网络甚至无法建立稳定连接、mqtt 服务端的策略配置等，无法做到绝对的实时性，需要用户自己做到数据的最终一致性。）