企业官网建设流程全解析

MQTT-C 使用指南：2000 行 C 代码如何在嵌入式设备上跑通完整 MQTT 通信

【免费下载链接】MQTT-CA portable MQTT C client for embedded systems and PCs alike.项目地址: https://gitcode.com/gh_mirrors/mq/MQTT-C

当你的 STM32 只有几十 KB 内存，却想用 MQTT 协议和云端保持实时通信时，很多主流客户端库会直接让你绝望——动辄上万行的代码、厚重的依赖、复杂的配置，光移植就要折腾好几天。MQTT-C 正是为了解决这个痛点而生的：它是一个用纯 C 语言编写、仅含两个源文件（总代码量不到 2000 行）的 MQTT v3.1.1 客户端，专为嵌入式系统和 PC 应用设计，让任何平台上的设备都能用最少的资源跑起可靠的 MQTT 通信。

一、先聊聊嵌入式上跑 MQTT 的真实困境

MQTT 协议本身是为低带宽、高延迟、资源受限的网络设计的，但"协议轻量"不代表"实现轻量"。很多 C 语言 MQTT 客户端库为了兼容各种场景，代码动辄几千上万行，还强依赖某些平台特性。当你面对的是一个只有几十 KB RAM 的微控制器，或者一个没有完整操作系统的裸机环境时，你会发现：

• 内存预算根本不够：完整客户端内部要维护大量状态机、队列、动态分配，光初始化就要吃掉一大块内存
• 移植成本高：库内部直接调用 POSIX socket 或特定 RTOS 的 API，换一个平台就要改源码
• 线程模型死板：要么强制要求多线程，要么完全没有并发保护

MQTT-C 的三个核心设计，恰好一一回应了这些问题。这也是它值得你花十分钟了解的原因。

核心卖点一：整个库只有两个源文件

MQTT-C 的全部逻辑都集中在src/mqtt.c和src/mqtt_pal.c两个文件里，总计不足 2000 行，且是 ANSI C（C89）兼容代码。这意味着：

• 你可以直接把这两个.c文件拷进你的工程一起编译，不需要任何复杂的构建系统
• 内存占用极低，缓冲区和内部队列大小完全由你掌控
• 代码量少，意味着出问题时你可以真正读懂每一行，而不是面对一个黑盒

核心卖点二：平台抽象层让移植变成"填空"

MQTT-C 通过include/mqtt_pal.h和src/mqtt_pal.c提供了一个透明的平台抽象层（PAL）。你只需要为你的平台提供几个类型、宏和两个函数：字节序转换、获取当前时间、互斥锁操作，以及mqtt_pal_sendall/mqtt_pal_recvall两个收发函数。项目文档里对需要定义的每一项都有明确清单，照着mqtt_pal.h里的注释填空即可，无需改动核心代码。

核心卖点三：线程安全与单线程模式兼得

所有公开 API 都是线程安全的，你可以在一个专用线程里调用mqtt_sync周期性地驱动客户端收发数据；也可以完全不创建线程，在裸机的主循环里每隔一段时间调用一次。这种灵活性让它在 RTOS 和 bare-metal 环境下都能工作。

二、15 分钟跑通你的第一个 MQTT Demo

理论讲完了，我们直接动手。整个过程只需要三步：拉取代码、编译、运行。

第一步：获取项目

git clone https://gitcode.com/gh_mirrors/mq/MQTT-C cd MQTT-C

第二步：编译示例程序

项目提供了makefile和 CMake 两套构建方式。最省事的做法是直接用 Makefile：

make all

编译完成后，所有示例程序和单元测试都会输出到bin/目录。如果你只想快速验证，也可以手动只编译这两个源文件：

gcc -o my_app my_app.c src/mqtt.c src/mqtt_pal.c -Iinclude

第三步：让发布者和订阅者对话

MQTT 是发布/订阅模型，所以我们要同时跑两个程序。先打开一个终端，启动订阅者（默认连接公共测试代理test.mosquitto.org，端口 1883，订阅datetime主题）：

./bin/simple_subscriber

再打开另一个终端，启动发布者——它会在你每次按下回车键时，把当前时间发布到datetime主题：

./bin/simple_publisher

回到订阅者的终端，你会看到类似这样的输出：

Received publish('datetime'): The time is 2026-08-15 13:34:45

到这里，一个完整的 MQTT 发布/订阅链路就已经打通了。如果你有自己的代理，把地址和端口作为参数传进去即可，比如./bin/simple_subscriber 192.168.1.100 1883 my_topic。

三、拆解核心代码：2000 行如何撑起完整协议

跑通 Demo 之后，我们来拆解一下examples/simple_publisher.c，看看 MQTT-C 的 API 到底有多简洁。整个客户端的使用流程可以浓缩为四步。

1. 初始化：分配内存的是你，不是库

struct mqtt_client client; uint8_t sendbuf[2048]; /* 发送缓冲区 */ uint8_t recvbuf[1024]; /* 接收缓冲区 */ mqtt_init(&client, sockfd, sendbuf, sizeof(sendbuf), recvbuf, sizeof(recvbuf), publish_callback);

这里有个很关键的设计：收发缓冲区由你提供。MQTT-C 不做任何堆内存分配，所有内存都是静态的或由调用者指定，这正是它能用在裸机环境的原因。sockfd是一个已连接到代理的非阻塞 TCP socket，示例里用templates/posix_sockets.h中的open_nb_socket创建。

2. 连接：一个函数搞定所有参数

mqtt_connect(&client, NULL, /* client_id，传 NULL 表示匿名会话 */ NULL, NULL, 0, /* will 消息，不需要就传 NULL */ NULL, NULL, /* 用户名密码 */ MQTT_CONNECT_CLEAN_SESSION, /* 要求全新会话 */ 400); /* keep-alive 时间（秒） */

mqtt_connect的参数虽多但很直白：客户端 ID、遗嘱消息（will message）、用户名密码、连接标志和心跳间隔。400 秒是文档建议的心跳值。如果连接失败，你可以通过client.error和mqtt_error_str(client.error)拿到可读的错误描述。

3. 发布与订阅：一行代码一条消息

/* 发布：主题 + 数据 + 长度 + QoS 等级 */ mqtt_publish(&client, "sensors/temperature", "25.5", 4, MQTT_PUBLISH_QOS_1); /* 订阅：主题 + 最大 QoS 等级 */ mqtt_subscribe(&client, "home/livingroom/temp", 0);

MQTT 的三种 QoS 等级（最多一次、至少一次、精确一次）MQTT-C 全部支持。对可靠性要求不高的传感器数据用 QoS 0 即可，关键控制指令用 QoS 1 或 2 更稳妥。

4. 驱动收发：mqtt_sync 是心脏

你可能注意到了，发布和订阅之后并没有立刻看到数据流动——因为 MQTT-C 是非阻塞驱动模型，你必须周期性调用mqtt_sync来驱动收发。示例里用一个线程每 100ms 调用一次：

void* client_refresher(void* client) { while(1) { mqtt_sync((struct mqtt_client*) client); usleep(100000U); /* 100ms */ } return NULL; }

在单线程环境下，你完全可以把这行调用放进主循环，效果一样。收到消息时，你在mqtt_init里注册的publish_callback回调会被触发，示例订阅者的回调会把主题名和消息内容打印出来。

四、进阶玩法：断线自动重连与 TLS 加密

Demo 跑通只是开始。真实项目中，设备离线重连和通信加密是绕不开的两件事，MQTT-C 对这两点都提供了开箱即用的支持。

断线自动重连：一个回调函数搞定

examples/reconnect_subscriber.c演示了完整的自动重连方案。思路是：用mqtt_init_reconnect初始化客户端，并传入一个reconnect_callback。当连接出错时，库会自动调用这个回调，你在里面负责重新建立 socket、调用mqtt_reinit重新绑定缓冲区和 socket，再调用mqtt_connect恢复会话，之后重新订阅需要的主题：

void reconnect_client(struct mqtt_client* client, void **state) { /* 1. 关闭旧 socket，处理错误 */ /* 2. 重新建立 TCP 连接 */ /* 3. mqtt_reinit 重新绑定 socket 和缓冲区 */ /* 4. mqtt_connect 恢复会话 */ /* 5. mqtt_subscribe 重新订阅主题 */ }

配合mqtt_sync的周期性调用，客户端在断网后就能自动恢复，无需人工干预。

一把梭的加密支持

如果你的数据需要加密传输，MQTT-C 通过编译期宏切换多种 TLS 后端，且核心代码无需改动——PAL 层把 socket 句柄抽象成了mqtt_pal_socket_handle，可以指向普通 fd、OpenSSL 的 BIO、mbedTLS 的 SSL context 或 BearSSL 上下文。项目里提供了对应的示例：

• examples/openssl_publisher.c：基于 OpenSSL 的加密发布者
• examples/mbedtls_publisher.c、examples/bearssl_publisher.c：面向嵌入式场景的 TLS 方案
• examples/bio_publisher.c：使用 OpenSSL BIO socket 的无加密版本

编译时按需定义MQTT_USE_OPENSSL、MQTT_USE_MBEDTLS或MQTT_USE_BEARSSL等宏即可，CMake 也内置了FindMbedTLS.cmake等查找脚本，集成很方便。

五、动手试试吧

如果你正在为一个微控制器项目选择 MQTT 客户端，或者单纯想找一个代码量小、能读懂每一行的 C 语言实现，MQTT-C 值得你花一个下午试试。它的价值可以总结为三点：全库仅两个源文件、不到 2000 行，让你在资源受限设备上毫无负担；平台抽象层让移植只需填写几个函数；线程安全且支持单线程模式，从裸机到 RTOS 再到 PC 全场景覆盖。完整 API 文档和全部示例都随仓库提供（docs/目录与examples/目录），直接拉取代码、运行make all，就能开始你的第一条 MQTT 消息。

【免费下载链接】MQTT-CA portable MQTT C client for embedded systems and PCs alike.项目地址: https://gitcode.com/gh_mirrors/mq/MQTT-C