简介针对 libmodbus 在 Windows 平台 Qt5 MinGW 环境下的集成与测试该压缩包提供了一套完整示例工程面向需要基于 Qt 开发 Modbus 通信功能的嵌入式或上位机开发者解决库配置、编译链接与基础功能验证等问题。包内共 21 个文件以 C 头文件与源码9个h、4个c为主涵盖协议接口声明与核心实现配合 Qt 工程文件pro、C 源码cpp和界面文件ui便于构建可交互的测试程序另含说明文档及 URL 快捷方式可直接打开原始博客与汇总页面。压缩包整体仅 39KB结构紧凑适合快速导入 Qt Creator 进行修改和验证。已有 975 人学习下载说明该示例对同类需求具有实际参考价值。通过这一工程读者可省去自行搭建环境的麻烦直接获得一套可运行的 libmodbus 测试代码与工程配置并据此验证读写操作、理解串口与网络通信的基本流程。 在 Windows 下用 Qt5 MinGW 跑 libmodbus说难不算难但坑是真不少。我最近刚好在项目里把整个流程从零到一走了一遍从编译库到写测试程序再到排查各种奇奇怪怪的问题折腾了整整两天。把过程整理出来给准备在 Qt 项目里接入 libmodbus 的朋友做个参考少走点弯路。这篇文章适合这三类人看一是要在 Windows 上做 Modbus 设备调试的二是 Qt 项目里需要集成串口或 TCP 通信功能的三是对 MinGW 工具链不太熟、想搞清楚 MSVC 和 MinGW 到底该选哪个的。我尽量讲得细一点包括环境搭建、库的编译、测试代码怎么写、以及特别容易踩的几个坑。1. 环境准备与工具链选型1.1 为什么选 MinGW 而不是 MSVC很多刚接触 Qt 的人会卡在第一个问题上Qt 5 装哪个版本这其实取决于你用什么编译器。Qt 官方安装包在 Windows 上同时提供 MSVC 和 MinGW 两套预编译套件但这两者完全不兼容——用 MSVC 编译的库不能链接 MinGW 编译的程序反之亦然。所以选 MinGW 的核心原因就是你的 Qt 套件如果是 MinGW 版第三方库就必须用 MinGW 来编译。具体到 libmodbus 这个场景还有一个更实际的理由。libmodbus 本身是 C 库官方没有发布 Windows 预编译二进制得自己用 CMake 构建。MSVC 版需要开发者命令提示符环境一堆环境变量要配而 MinGW 在 Qt Creator 里自带直接用自带的 CMake 和编译器就能搞定省事不少。另外MinGW 生成的程序不依赖 VC 运行库msvcp140.dll、vcruntime140.dll 这些拷到别人机器上跑的时候不容易出现“缺少 DLL”的报错。我在实际测试中发现同一个 libmodbus 源码MinGW 静态库的体积比 MSVC 静态库还小一点这点倒不影响使用但确实说明 MinGW 的代码生成效率不差。1.2 具体环境清单我这边的测试环境是这样的操作系统Windows 10 专业版 22H2Qt 版本Qt 5.15.2编译器MinGW 8.1.0 32位Qt 5.15.2 自带的那个组合构建工具CMake 3.20Qt Creator 内置libmodbus 版本3.1.102024年发布支持到 Modbus TCP/RTU 的新特性这里要特别提醒一句Qt 5.15.2 官方带的 MinGW 是 32 位的在 x64 系统上跑 32 位程序完全没问题但如果你的项目有 64 位依赖就得手动配 64 位 MinGW 了。我自己的项目因为要对接老设备驱动只能用 32 位所以直接用自带套件最省心。安装完 Qt 后记得确认一下环境变量。Qt Creator 会自动识别编译器路径但如果你要在命令行里手动编译得把 C:\Qt\Tools\mingw730_32\bin 和 C:\Qt\5.15.2\mingw73_32\bin 加进 PATH。我就是最开始没加结果 cmake 找到了编译器却找不到 mingw32-make白白折腾了半小时。2. libmodbus 的编译与集成2.1 获取源码与构建流程libmodbus 的源码在 GitHub 官方仓库直接 git clone 或者下载 zip 包都行。下载后解压到一个不含中文和空格的路径比如 D:\libmodbusWindows 下 MinGW 对中文路径的支持时好时坏别给自己找麻烦。libmodbus 官方推荐两种构建方式CMake 和 autotools。在 Windows 上选 CMake 就对了autotools 在 Windows 下要装 MSYS2 环境纯属自虐。如果你用的是新版 libmodbus3.1.x源码目录下有现成的 CMakeLists.txt直接用它就行。打开 Qt Creator选择“打开项目”找到 libmodbus 源码目录下的 CMakeLists.txt配置工程。在构建套件那里选你装好的 Qt 5.15.2 MinGW 套件。CMake 构建目录我建议独立建一个 build 目录别直接放源码目录里后面清理方便。构建完成后在构建目录里能找到这几个关键文件src\libmodbus.dll动态库src\libmodbus.a导入库src\libmodbus.dll.aMinGW 特有的导入库config.h编译配置头文件2.2 静态链接还是动态链接我把两种方式都试了一遍给个对比表对比项静态链接动态链接生成物大小可执行文件偏大约多出 200KB可执行文件小但需要带 DLL部署便利性单文件直接拷贝需同时拷贝 DLL 到运行目录调试体验可以直接跟进库内部代码需要额外加载符号文件编译速度链接慢一点链接快我的建议是调试阶段用动态链接发布阶段换静态链接。动态链接的好处是修改了库代码后重新编译只需要编译库本身不用全量重新链接整个项目发布时换静态链接则可以少带一个 DLL避免目标机器上没有运行库或被杀毒软件误删 DLL 的问题。这里插个题外话很多人会遇到“同一种源码静态库编译出来没问题动态库编译出来却一运行就崩溃”的情况。这种现象在 Windows 下很常见多半是因为动态库跨模块传递了 CRTC 运行时内存对象。libmodbus 内部会用 malloc 分配缓冲区如果你在 Qt 程序里直接操作这些缓冲区并用了 Qt 的释放机制就会出问题。所以用动态库时库内部的内存只能库自己释放你要做的就是调用 modbus_free 而不是 free。2.3 Pro 文件配置与链接参数在 Qt 项目的 .pro 文件里加上下面这些内容就能正常使用 libmodbusINCLUDEPATH D:/libmodbus/src LIBS -LD:/libmodbus/build/src -lmodbus # 如果使用动态库Windows 下需要这行让程序运行时找到 DLL QMAKE_LFLAGS -Wl,--rpath,D:/libmodbus/build/src-lmodbus会自动找 libmodbus.a 或 libmodbus.dll.aMinGW 的导入库不需要手动区分。要注意的是MinGW 对库的命名很敏感如果你下载的是别人编译好的库文件文件名是 libmodbus-1.dll 这种带版本号的链接时得用-lmodbus-1才能对上。如果懒得处理导入库和 DLL 的对应关系还有一种更省心的集成方式直接把 libmodbus 源码里的 src 目录下的所有 .c 和 .h 文件拷到你的工程里用 .pro 文件把他们加入 SOURCES 和 HEADERS。这样不用单独编译库整个工程一起编译调试时可以无缝跳进 modbus 的内部函数。代价是每次全量编译时间会长一点但对小项目来说完全能接受。我的实际体验是全工程重编多了 10 到 15 秒但省了所有链接和部署的麻烦非常适合做学习和验证。3. 编写测试程序与核心逻辑3.1 最小可运行的 Modbus TCP 客户端先来一个最简单的测试程序验证库能不能正常工作。新建一个 Qt Widgets 应用或者 Qt Console 应用都行我这里用 Console 程序做验证避免界面代码干扰调试。#include QCoreApplication #include QDebug #include QThread #include modbus.h int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); // 1. 创建 TCP 连接上下文 modbus_t *ctx modbus_new_tcp(127.0.0.1, 502); if (ctx nullptr) { qCritical() modbus_new_tcp failed: modbus_strerror(errno); return 1; } // 2. 设置响应超时时间单位秒 modbus_set_response_timeout(ctx, 1, 0); // 3. 设置从站地址 modbus_set_slave(ctx, 1); // 4. 连接 if (modbus_connect(ctx) -1) { qCritical() connect failed: modbus_strerror(errno); modbus_free(ctx); return 1; } // 5. 读取保持寄存器 uint16_t regs[16] {0}; int rc modbus_read_registers(ctx, 0, 16, regs); if (rc -1) { qCritical() read failed: modbus_strerror(errno); } else { for (int i 0; i rc; i) { qInfo() reg[ i ] regs[i]; } } // 6. 清理 modbus_close(ctx); modbus_free(ctx); return 0; }这个程序做了三件最基本的事建立连接、读取寄存器、断开连接。如果你已经在电脑上跑了一个 Modbus 模拟服务器比如 Modbus Poll 或者 QModMaster把 IP 和端口换一下就能跑通。这里补充几个关键点。modbus_strerror(errno)可以返回最近的错误描述调试时非常有用。modbus_set_response_timeout如果不设置默认超时时间是 0.5 秒这在调试真实设备时可能不够用。特别是走无线或者 4G 链路的场景响应时间经常超过 1 秒我一般会设置成 2 到 3 秒。3.2 Modbus RTU 串口模式的测试TCP 通了之后再测 RTU 串口模式。这一步才是 Windows 下真正的“坑王”环节因为你不仅要面对协议本身还要面对 Windows 的串口机制。modbus_t *ctx modbus_new_rtu(COM3, 9600, N, 8, 1); if (ctx nullptr) { qCritical() modbus_new_rtu failed: modbus_strerror(errno); return 1; } modbus_set_slave(ctx, 1); if (modbus_connect(ctx) -1) { qCritical() Serial connect failed: modbus_strerror(errno); modbus_free(ctx); return 1; }COM 口的名字在 Windows 上有讲究老式串口名通常是 COM1、COM2但 USB 转串口的设备名可能是 COM10 以上的序号。如果你使用的是 COM10 以上的端口libmodbus 内部对 Windows 的 COM 端口处理存在一些兼容性差异可能需要手动调整代码。在我的测试中COM3 这种短名称是直接可以用的。有人可能会遇到modbus_connect返回 -1但errno却不是期望的EBADF或EACCES这时候可以先检查这个 COM 口是否被其他程序占用。RTU 模式下串口参数波特率、校验位、数据位、停止位必须和从站完全一致否则读回来的数据全都是乱码或者直接超时。常见的参数组合是9600, 8, N, 1但实际设备使用 19200 甚至 115200 的也很多拿到设备先确认参数再测试。RTU 还有一种特殊的调试手段如果你的 USB 转串口模块支持回环测试把 TX 和 RX 用杜邦线短接你发的数据会原样被自己收到。这种情况下可以先用串口助手看回环数据是否正常确认物理链路 OK 再去测协议。3.3 线程模型与界面刷新Qt 项目里最大的坑其实是线程问题。Modbus 通信是阻塞的如果在 UI 线程里直接调用 modbus_read_registers界面会直接卡死特别是网络不通的时候哪怕设置了超时那 2 到 3 秒的卡顿也会让用户体验非常糟糕。我常用的方案是 QThread 工作线程 信号槽回报数据。工作线程里跑一个循环定时读取寄存器然后通过信号把数据发回主线程更新界面。class ModbusWorker : public QObject { Q_OBJECT public: explicit ModbusWorker(QObject *parent nullptr) : QObject(parent) {} public slots: void start() { modbus_t *ctx modbus_new_tcp(192.168.1.10, 502); if (modbus_connect(ctx) -1) { emit errorOccurred(modbus_strerror(errno)); return; } while (!m_stop) { uint16_t regs[32] {0}; int rc modbus_read_registers(ctx, 0, 32, regs); if (rc 0) { emit dataReady(QByteArray( reinterpret_castconst char *(regs), rc * 2)); } QThread::msleep(500); } modbus_close(ctx); modbus_free(ctx); } void stop() { m_stop true; } signals: void dataReady(const QByteArray data); void errorOccurred(const QString msg); private: volatile bool m_stop false; };主线程或者 MainWindow 里用 QThread 的 start 信号触发 worker然后在 dataReady 信号里更新界面。这里有一个新手特别容易犯的错QThread::sleep会阻塞整个线程但如果你把 modbus 读取放在 worker 对象所在的线程里阻塞在 worker 线程是没问题的。问题往往出在QThread子类里重写run()函数然后在 run 里又 new 了一个 worker 对象——这样 worker 依旧在主线程里跑事件循环读写还是会卡界面。正确的做法是用 moveToThread 把 worker 移动到子线程或者干脆在 run() 里手动写循环像我上面这样把start()作为 slot 调用配合信号触发。这两种方式我都验证过都能工作但 moveToThread 方式结构更清晰将来要加停止/暂停控制也方便。3.4 Qt 调试模式下查看整个二维数组在 Qt 里调试 Modbus 程序时经常要查看寄存器数组或 modbus 的映射表。默认的调试器GDB在变量窗口里只能看到数组首元素想一次看全整个二维数组得自己配置。以 Qt Creator GDB 为例右键变量窗口里的数组变量选择“添加表达式监视”然后在表达式里输入*((uint16_t (*)[32])regArray)这行的意思是把 regArray 强制转换成指向长度为 32 的 uint16_t 数组的指针然后解引用。这样监视时就能看到整个数组的所有元素还能在数组透视里看到每个下标对应的值。如果是二维数组uint16_t buf[4][10]要分两步*((uint16_t (*)[40])buf)或者直接监视buf4GDB 的语法可以显示连续内存区域比如buf4会显示前四个元素对于二维数组实际上会先显示第一行但配合 GDB 的set print array-index on可以看得更清楚。不过更实用的还是指针转换成二维数组的方式我调试 Modbus 寄存器表时基本都是这么干的。提示有时候监视窗口显示的值是“Cannot access memory at address”这是没查对数组名所在作用域把断点打在数组所在的函数体里就能查到了。4. 常见问题与排查技巧实录4.1 链接报错 undefined reference这个绝对是我的头号坑。用 MinGW 链接 libmodbus 时如果 .pro 文件里写的是-L... -lmodbus报一堆undefined reference to modbus_new_tcp之类的错误最常见的两个原因一是导入了 MSVC 编译的 .lib。MSVC 的 .lib 和 MinGW 的 .a 格式不兼容互相链接必然失败。解决办法只有一条用同一套 MinGW 工具链重新编译 libmodbus。二是库文件顺序错误。GCC 和 MinGW 的链接器在解析库依赖时有严格的顺序问题被依赖的库要放在依赖它的库后面。如果 libmodbus 和 Qt 网络模块有交叉调用可能需要调整 .pro 文件里 LIBS 的顺序。我的经验是把-lmodbus放到所有-lQt5Network等 Qt 库的后面甚至放到文件最后一行问题就解决了。还有一种情况是 mingw32-make 在编译 libmodbus 时由于源码里的某些源文件用了较新的 C99 特性导致编译阶段就出错了。老版本的 MinGW比如 5.3.0 或 7.3.0对 C99 支持不太好建议直接用更新的 MinGW 版本或者 Qt 套件自带的那个 MinGW 8.1.0编译 libmodbus 3.1.10 版本完全没问题。4.2 串口打不开或收发没反应串口打不开先排除这几个方面COM 端口被其他程序占用比如串口调试助手、另一个 Modbus 工具COM 端口号超过 9 导致的 Win32 API 访问问题USB 转串口模块驱动异常设备管理器里显示黄色感叹号最典型的症状是modbus_connect到 RTU 时返回 -1errno却是EBADF。原因通常是 COM 口被 Qt 自身的QSerialPort先打开了然后又创建了 libmodbus 的上下文去打开同一个口Windows 默认不允许同一串口被打开两次。你需要在测试前彻底关闭所有其他占用串口的程序。如果串口能打开但收发数据完全没反应用逻辑分析仪或者示波器看一下 TX 引脚有没有波形。如果没有波形检查一下是不是用错了串口号有波形但设备没回大概率是参数不匹配波特率、校验位随便哪个错了都收不到回复或者从站地址设错了。设备默认地址一般是 1我之前测过一个电表地址是 247用默认 1 去读怎么都读不出来查了半天资料才发现地址对不上。4.3 TCP 连接超时的调整技巧libmodbus 的 TCP 模式下连接超时的机制和串口不一样。串口的超时只体现在收发字节上而 TCP 连接本身就可能因为网络不通导致 connect 阻塞很久。默认情况下libmodbus 内部使用select系统调用实现收发超时但在 Windows 上select只能用于 socket且默认对连接的建立过程没有限制。我遇到过这样的情况设备 IP 根本不通modbus_connect却阻塞了将近 30 秒才返回错误。这在调试阶段还能忍但放到正式程序里就是灾难。解决方案是在 connect 之前设置一个连接超时保护libmodbus 3.1.x 版本里没有现成的 API需要手动修改 socket 的 connect 超时。可以参照网上常见的做法把modbus_connect内部用到的connect()替换为带超时的非阻塞连接或者在调用前先 ping 一下设备 IP。我自己的团队用了一个更粗暴但有效的方式在连接之前先尝试用QTcpSocket做一次带超时的握手测试通不过就直接提示用户网络不可达。4.4 修改 modbus 库代码后不生效这是一个比较少人注意但很坑的问题修改了 libmodbus 源码的某个函数后重新编译了动态库但程序的行为完全没有变化。用依赖查看工具检查一下发现程序加载的 DLL 根本不是当前构建目录里的 libmodbus.dll而是系统目录或者项目构建目录里残留的旧版本。解决方法是显式地清理掉所有旧的 DLL 文件并检查程序的构建输出目录里拷贝了哪个版本的 DLL。我一般把构建目录下的 src\libmodbus.dll 直接拷贝到 exe 同级目录再在 .pro 文件里把DESTDIR设置成$$OUT_PWD/——这样每次构建后 DLL 会自动拷贝到 exe 所在目录避免加载到别的地方的旧文件。结尾说实话在 Windows Qt5 MinGW 这个组合下跑 libmodbus本身不难但要把环境理顺需要一点耐心。最让我意外的其实不是库本身而是 Qt 和 MinGW 工具链的配合——很多看起来像是 libmodbus 的问题实际上是工具链或平台 API 差异造成的。这篇文章里写的每一步我都实际跑过包括中间踩过的坑如果你照着做应该能比我少折腾一半时间。最后再分享一个实用的小技巧调试 Modbus 协议时在 .pro 文件里加一行DEFINES MODBUS_DEBUGlibmodbus 会在控制台输出所有收发帧的十六进制数据。开这个输出之后你会发现排查协议问题直接降了一个难度不用靠猜直接看帧就知道问题出在哪一步。本文还有配套的精品资源点击获取