简介：面向 Qt 工业通信开发者，这份 QModbus TCP 模式演示工程源自《QModbus TCP模式综合操作详解(二)》，以 RTUMasterTest 为蓝本，专门展示 Modbus TCP 客户端连接、保持寄存器读写与错误处理等关键场景，适合正在学习 QModbus 或需要快速搭建通信测试程序、验证组网逻辑的开发者。压缩包内共 16 个文件，约 190KB，以 cpp/h 源码和 ui 界面文件为主体，另含 qrc 资源、pro 工程配置及若干演示图片，结构清晰，可直接在 Qt 工程中打开编译，方便按模块查阅与二次修改。已有 1360 人学习/下载，在同类 Modbus 通信示例中具有较强参考价值。工程提供 mainwindow、寄存器模型和设置对话框等完整模块，可对照源码理解读写请求组织、响应解析与界面刷新机制，也可通过修改寄存器地址、连接参数或增加自定义槽函数来扩展功能，适合从示例出发快速迁移到实际工业自动化上位机项目中，同时可借助演示图片和界面配置直观观察寄存器变化。 搞工控上位机的，迟早要跟Modbus打交道。我之前写过一篇QModbus的RTU模式推文，反响还行，评论区里不少人催更TCP模式。这次直接开搞，把QModbus TCP模式综合操作这第二篇补上。标题虽然带个"综合操作"，但我拿到手就一直琢磨，怎么让它不只是一篇API的罗列，而是真正能解决实际问题的实战手册。
这篇东西的定位很明确：用Qt的QModbus模块写一个基于TCP的Modbus客户端和服务端，实现多寄存器的读写、异常处理、掉线重连，顺带把调试抓包的过程也聊透。适合正在用Qt写上位机、接PLC或者各类网口仪表、传感器的朋友。如果只是刚接触QModbus，建议先把官方文档过一遍基础类结构，再回来看这篇，会顺畅很多。
1. 为什么TCP模式值得单独写一篇：与RTU的取舍
很多人在RTU模式下能用得好好的，一换到TCP模式就开始懵。原因其实很简单：RTU模式下你要关心波特率、数据位、校验位、从站地址，而TCP模式下这些全部消失了，取而代之的是IP、端口、连接管理。这不是参数列表变了那么简单，而是整个通信的底层思路都变了。
我先快速解释一下TCP模式在协议层面到底做了什么改动。Modbus TCP的报文沿用了Modbus的应用层PDU（Protocol Data Unit），只是在前面套了一个MBAP报文头，用来做报文识别和区分。MBAP头一共7个字节：事务处理标识符（Transaction Identifier）占2字节，协议标识符（Protocol Identifier）占2字节，长度（Length）占2字节，单元标识符（Unit Identifier）占1字节。后面跟着的才是真正的功能码和寄存器地址、寄存器数量、数据载荷。
1.1 报文格式上"少掉了什么，多出了什么"
和RTU模式相比，TCP模式砍掉了CRC16校验码和从站地址，因为TCP/IP协议栈本身提供了可靠传输和差错校验，链路层已经帮你把数据完整性问题处理掉了。
| 报文结构 | RTU模式 | TCP模式 |
|---|---|---|
| 地址标识 | 从站地址（1字节） | 单元标识符（1字节），通常在TCP会话里固定为1或按设备设置 |
| 校验 | CRC16（2字节） | 无，交给TCP/IP底层 |
| 帧结束判定 | 基于时间间隔或帧长度计算 | 基于MBAP头里的Length字段 |
| 最大数据量 | 受串口帧限制，单帧最大256字节左右 | 可达更大，实际受设备实现限制 |
所以你在用QModbus的时候会发现，QModbusTcpClient的构造函数里根本没有串口配置相关的参数，取而代之的是setConnectionParameter里设置NetworkPort和NetworkAddress。这个变化是本质性的：RTU模式要求主站一个一个地轮询从站，而TCP模式下，一个客户端可以同时和多个设备保持长连接，也不存在总线冲突的问题。
1.2 什么时候别用TCP
不过我得泼一盆冷水：不是所有场景都适合从RTU切成TCP。现场环境如果还是传统的RS485总线结构，设备之间距离远且分散，那老老实实用RTU更稳妥。TCP模式依赖网络基础设施，现场如果网络不稳定，交换机丢包、延迟毛刺，反而会比串口通信更让人头疼。
另外一个容易被忽略的点是：大多数Modbus TCP设备的单元标识符（Unit ID）是固定值，不一定等于你原来RTU模式下的从站地址。有的设备是0，有的是1，有的甚至可以配置多个单元ID对应内部多个寄存器块。这块必须看设备手册确认，我就是踩过这个坑——RTU模式下从站地址填3，切到TCP后通信一直超时，最后发现TCP模式下单元标识符必须填255才对。
2. 读写寄存器的API映射：四类请求与对应关系
QModbus库的API设计思路很统一：不管是RTU还是TCP，最终都是通过QModbusClient子类发送请求，请求内容封装在QModbusDataUnit里。所以TCP模式下真正需要掌握的，不是"连接参数怎么设"，而是"我要读的数据在QModbus里该怎么表达"。
2.1 QModbusDataUnit的RegisterType到底对应什么
QModbusDataUnit的RegisterType枚举定义了五种寄存器类型：Invalid、DiscreteInputs（离散输入）、Coils（线圈）、InputRegisters（输入寄存器）、HoldingRegisters（保持寄存器）。在Modbus协议里，这五种类型对应不同的功能码，千万别搞混。
| RegisterType | 功能码 | 读/写 | 典型用途 |
|---|---|---|---|
| Coils | 0x01读/0x05写单/0x0F写多 | 读写 | 开关量输出，如继电器 |
| DiscreteInputs | 0x02 | 只读 | 开关量输入，如限位开关 |
| InputRegisters | 0x04 | 只读 | 模拟量输入，如温度采集 |
| HoldingRegisters | 0x03读/0x06写单/0x10写多 | 读写 | 参数设置、数值读写 |
以实际设备为例：一个温控仪表的当前温度通常映射到InputRegisters，而温度设定值映射到HoldingRegisters。你不能拿QModbusDataUnit::InputRegisters去写数据，如果真这么干，底层会给你一个功能码错误，因为输入寄存器在协议层面就是只读的。
2.2 地址映射的经典坑：0-based还是1-based
很多人卡在QModbus上最大的一个坑就是地址偏移。Modbus协议手册里写寄存器地址是从0开始的，比如"保持寄存器地址40001对应协议地址0x0000"这种表述。但很多国产设备的手册直接给的是PLC风格的地址，比如"设定温度存储在保持寄存器 42401"，这时候很多初学者直接把42401传给QModbus，结果设备毫无响应。
原因在于：设备手册里的地址是"数据地址"（Data Address），它包含了寄存器类型标识。42401这个地址拆开来看是4表示保持寄存器，2401才是真正的寄存器编号。而在Modbus报文里，2401对应的实际协议地址是2400（0x095F）。所以传给QModbus的地址应该填2400，而不是42401。
这里有个通用换算方法：如果手册给的是40001~49999区间，那么协议地址 = 手册地址 - 40001；如果是30001~39999区间，那么协议地址 = 手册地址 - 30001。注意还有一种情况是手册直接给"寄存器编号1~100"，这种就小心了，通常意味着协议地址是0~99，需要减1。我的建议是拿到新设备先跟手册里的"Modbus地址表"和"报文示例"对照一遍，把偏移量彻底搞清再写代码。
3. 客户端完整实现：从连接到多寄存器透传
接下来直接上代码。我的开发环境是Qt 6.5 + MSVC 2019 64位，QModbus模块在Qt Serial Bus组件里。如果你的Qt安装时没有勾选这个组件，请在安装管理器里补上。
模块里的核心类是QModbusTcpClient。我在一个实际项目里用它做主站，同时轮询三台设备，每台设备要读取12个保持寄存器和6个输入寄存器，还要写一个设定值寄存器。下面把核心实现拆开讲。
3.1 建立连接：比你想的更简单，也比你想的更需要管理
#include <QModbusTcpClient> #include <QModbusDataUnit> #include <QModbusReply> QModbusClient* modbusClient = nullptr; void initModbusClient(const QString& ip, quint16 port) { if (modbusClient) { modbusClient->disconnectDevice(); delete modbusClient; modbusClient = nullptr; } modbusClient = new QModbusTcpClient(nullptr); modbusClient->setConnectionParameter(QModbusDevice::NetworkAddressParameter, ip); modbusClient->setConnectionParameter(QModbusDevice::NetworkPortParameter, port); modbusClient->setTimeout(1000); modbusClient->setNumberOfRetries(2); QObject::connect(modbusClient, &QModbusClient::stateChanged, [](QModbusDevice::State state) { qInfo() << "Modbus connection state changed:" << state; }); if (!modbusClient->connectDevice()) { qWarning() << "Connect failed!"; } }这段代码里有几个细节值得注意。setTimeout(1000)是等待从站响应的超时时间，单位是毫秒。setNumberOfRetries(2)是请求失败后的重试次数。这两个参数一定要根据现场情况调，设太短会因为偶尔的网络抖动误报失败，设太长则会让一次真正的断线要等好几秒才能暴露。我的经验是：局域网内设备，超时500~1000ms、重试2次是比较合理的组合；跨三层网络或者无线环境，建议超时拉到2000ms，重试1~2次。
3.2 读保持寄存器：理解异步回调写业务逻辑
bool readHoldingRegisters(int serverAddress, int startAddress, quint16 count) { if (!modbusClient || modbusClient->state() != QModbusDevice::ConnectedState) return false; QModbusDataUnit readUnit(QModbusDataUnit::HoldingRegisters, startAddress, count); if (auto* reply = modbusClient->sendReadRequest(readUnit, serverAddress)) { if (!reply->isFinished()) { QObject::connect(reply, &QModbusReply::finished, reply, [reply, startAddress]() { if (reply->error() == QModbusDevice::NoError) { const QModbusDataUnit result = reply->result(); for (int i = 0; i < result.valueCount(); ++i) { qInfo() << "Address" << result.startAddress() + i << "=" << result.value(i); } } else { qWarning() << "Read error:" << reply->errorString(); } reply->deleteLater(); }); } else { reply->deleteLater(); } return true; } return false; }有朋友问过我：为什么QModbus要设计成异步回调，而不能像串口那样简单粗暴地同步等待？因为Modbus TCP请求发出后，要等待网络往返、从站处理、网络返回，这个时间是不确定的。如果同步阻塞等待，界面线程就卡死了。QModbus的sendReadRequest发出请求后立刻返回，等响应到达后再触发finished信号，这套机制和QNetworkAccessManager是一个套路。
实际操作中有一个细节：删除reply。每次请求都会生成一个QModbusReply对象，如果你不调deleteLater()，跑一个晚上就会发现内存涨上去几百兆。这个我在早期接手一个遗留项目时见过，对方代码里大量泄漏，最后加了一行deleteLater()解决了。
3.3 写单个寄存器和写多个寄存器
bool writeSingleRegister(int serverAddress, int startAddress, quint16 value) { if (!modbusClient || modbusClient->state() != QModbusDevice::ConnectedState) return false; QModbusDataUnit writeUnit(QModbusDataUnit::HoldingRegisters, startAddress, 1); writeUnit.setValue(0, value); if (auto* reply = modbusClient->sendWriteRequest(writeUnit, serverAddress)) { if (!reply->isFinished()) { QObject::connect(reply, &QModbusReply::finished, reply, [reply]() { if (reply->error() == QModbusDevice::NoError) { qInfo() << "Write OK"; } else { qWarning() << "Write error:" << reply->errorString(); } reply->deleteLater(); }); } else { reply->deleteLater(); } return true; } return false; }写多个寄存器的场景也很常见，比如一次下发一组参数曲线。这时用QModbusDataUnit::HoldingRegisters，起始地址和寄存器个数都按实际需要填，然后逐个调用setValue填充数据。
有一种情况要特别留意：如果你的设备手册要求"同一个功能码下，一次写多个连续的寄存器"，而你的数据不是连续存放的，那就得在程序里先拷贝到一个临时数组再一次性写入。不要图省事循环调用sendWriteRequest，多次往返不仅慢，还会增加从站压力。
4. 服务端模拟：调试时比PLC好用的多
开发过程中最烦的事情是什么？是现场设备还没到位，或者设备在一个你够不着的机柜里。这时候一个好的调试手段能救你半条命。QModbus提供了QModbusTcpServer，可以在你电脑上跑一个服务端模拟器，先用假数据把上位机逻辑调通，再切换真机。
4.1 起一个能改寄存器的假从站
#include <QModbusTcpServer> QModbusServer* modbusServer = nullptr; void initModbusServer(quint16 port) { modbusServer = new QModbusTcpServer(nullptr); modbusServer->setConnectionParameter(QModbusDevice::NetworkPortParameter, port); modbusServer->setServerAddress(1); if (!modbusServer->connectDevice()) { qWarning() << "Server start failed"; } }启动后在另一台机器上（或者本机）用Modbus Poll之类的工具就能读到这个假从站了。但你还需要往里填数据，否则读出来全是0，没法验证逻辑。往服务端写数据有两种方式：一种是用modbusServer->setData()，另一种是直接用客户端去写。
最灵活的方式是结合前面写的客户端，在你自己的程序里再开一个QModbusTcpClient指向本机的服务端端口，往里面写测试值。这样做最大的好处是：一套读写代码既当了被测对象，又当了测试数据源，等于自己验证自己。
4.2 服务端模拟解决了什么问题
我一般在三类场景下用服务端模拟。
第一，上位机界面联调。界面要显示温度曲线、阀门开度、电机电流，没设备的时候数据全是空的，UI效果根本看不出好坏。用服务端塞一组模拟数据进去，UI就能正常渲染了。
第二，异常处理测试。真实设备不好故意拔线、断电，但服务端你可以随时stop掉，立刻就能测试客户端的超时重连逻辑。你还可以在服务端只响应部分寄存器，模拟设备的中断响应。
第三，多客户端并发。Modbus TCP的典型应用场景是一台设备被多个上位机同时读取，用服务端模拟器可以轻松验证多客户端同时请求时服务端是否正常。
5. 抓包验证与排查经过：一个实际掉线案例
上一节说的再多，还不如一次真实排查来得有价值。前阵子一个项目现场反馈，某台仪表经常"读不到数据"，但仪表本身的显示屏一直有数值。我远程连上去加日志，结果发现客户端连接状态一直是Connected，但每过两三分钟就会出现一次请求超时。
5.1 排查链路：从应用层到网络层逐层剥
第一反应是看报文。Modbus TCP的调试神器是Wireshark，打开后在过滤栏输入modbus，立刻就能看到所有Modbus报文。我观察到超时那几次，Wireshark里确实显示请求帧发出去了，但一直没有响应帧。而且仔细看TCP层，发现请求发出后大约2秒，TCP层出现了Dup ACK和Retransmission。
这说明问题出在网络传输层，不是仪表的Modbus协议栈。再看物理链路：这台仪表通过一个工业交换机和上位机相连，中间还有一个光纤收发器。我把笔记本直接接到仪表同一台交换机上，连续跑了半小时，一次超时都没有。问题锁定在光纤收发器上——单模光模块配了多模光纤，速率协商异常导致偶发丢包。换了对匹配的模块后，至今没再出问题。
5.2 另一个更隐蔽的坑：单元标识符引发的"假超时"
还有一次，现象是客户端连接一切正常，但读保持寄存器总是报Server address error或者干脆Request timeout。抓包看帧内容，请求帧里的Unit ID是1，返回帧却是异常响应（Exception Code 0x02，Illegal Data Address），不是超时。这说明设备收到了请求，但对寄存器地址不满意。
查手册才发现：这台设备的保持寄存器映射在Modbus地址400001~400100区间，单元标识符固定为255。我把Unit ID改成255，地址从0开始偏移，问题立刻解决。所以遇到"超时"，别急着调网络，Wireshark先看一眼到底是"没响应"还是"响应了异常码"，这两者的排查方向完全不同。
5.3 用Wireshark验证读写的正确性
Wireshark里过滤modbus后，你可以很直观地看到协议分析器帮你解析好的字段：Transaction ID、Protocol ID、Length、Unit ID、Function Code、Starting Address、Quantity。我曾经用这个方法验证过一个上位机软件的字节序问题——它在写浮点数时高字低字反了，界面上看起来数值不对，但设备侧其实已经收到了数据。通过Wireshark对比请求帧里的原始字节顺序，一秒钟就确定了问题在大小端，不在Modbus协议本身。
6. 性能与稳定性陷阱：轮询、超时、地址偏移
最后这部分聊聊实际工程里会遇到的几个关键参数和常见陷阱，这些都是光看官方示例学不到的东西。
6.1 轮询频率别拍脑袋定
Modbus TCP本质上是一个请求-响应模型，一个主站设备同时发的请求太多，从站处理不过来，丢帧回调就会频繁发生。我在一个项目里实测过：对同一个从站连续读10个寄存器，每100ms轮询一次，从站偶尔会出现响应延迟；改成200ms轮询，延迟消失，数据也不影响使用。
如果有多台设备要读取，建议把轮询任务放到一个队列里，逐台请求，响应回来后再发下一个请求，而不是用多个QTimer并行去砸。虽然Modbus TCP支持并发请求，但多数设备对并发处理的鲁棒性并不好，特别是国产仪表和小型PLC。
6.2 连接状态监控与自动重连
TCP连接不是永久的，交换机重启、网线松动、对端设备掉电都会导致连接中断。QModbus的stateChanged信号能捕捉状态变化，但它不会自动重连。你需要自己实现一个重连机制。
我的做法：用一个QTimer定期检查state()，如果处于UnconnectedState或ClosingState，调用connectDevice()尝试重连，同时做一个指数退避——第一次等500ms，第二次1秒，第三次2秒，最大不超过10秒。这个逻辑写起来不复杂，但能极大提高现场设备的自恢复能力，省去大量现场维护成本。
6.3 浮点数大小端问题
Modbus寄存器是16位的，一个float通常占两个寄存器。QModbus读回来的都是quint16，拼成float时要小心字节序。不同的设备厂家对"地址小的寄存器存高字还是低字"这个问题的理解并不一致，这就是著名的Modbus大小端混乱问题。我的做法是封装一个转换工具，两种排列方式都自动识别，通过界面上的"字节序"下拉框让现场工程师试，试对了以后保存配置。用代码写死一种顺序，遇到不同厂家的设备又得改代码重编，这种蠢事我干过一次，不想再干第二次。
6.4 一个隐藏很深的坑：QModbusTcpServer的端口复用
如果你写的服务端要在同一台机器上频繁启停，可能会遇到"端口被占用"的问题。Qt的QModbusTcpServer底层用的是QTcpServer，如果你在旧服务端还没完全释放端口时就创建新实例，有可能报bind failed。正确处理方式是先disconnectDevice()，再deleteLater()，然后延迟几百毫秒再创建新实例。这个坑在真机上不明显，但在Windows下频繁调试时很容易踩到。
7. 最后分享一个调试技巧：临时寄存器验证字节序和地址偏移
在实际项目里，我习惯在服务端模拟器里专门留出一段"临时寄存器区"（比如地址1000~1010），用来做读写验证。当你怀疑客户端的地址偏移写错了，或者大小端搞反了，不需要去翻复杂的数据表，只需要往这段临时区写入一个已知值，比如0x1234，然后从客户端读回来，看看读到的是0x1234还是0x3412。
这个办法帮我快速验证了很多次通讯协议的正确性，也让我在给不同品牌PLC做对接时摸清了不少设备的寄存器映射习惯。很多时候协议栈本身没问题，就是地址换算表写错了，用临时寄存器一验，一目了然。
QModbus的TCP模式说复杂也复杂，说简单也简单。复杂在于你面对的是不同的设备、不同的寄存器映射、不同的网络环境，简单在于只要把协议规则、地址映射、异步回调这三件事搞通了，后面就是重复劳动。希望这篇综合操作能帮少走几个弯路，有不同见解或者更好方案的，欢迎在评论区交流。
本文还有配套的精品资源，点击获取
