简介这是一份基于C实现的MODBUS TCP服务器源码主要面向工业自动化领域的开发者用于快速搭建支持MODBUS TCP通信的服务端程序。源码实现了MODBUS协议中常用的功能码03读取输入寄存器/离散输入与功能码16写多个保持寄存器覆盖请求解析、应答构造和常见错误处理流程可作为理解协议栈、学习TCP/IP网络编程及进行二次开发的基础框架同时帮助理解MODBUS协议规范与报文交互机制。资源压缩包共22个文件、约152KB以7个h头文件与5个cpp源文件为主附带Visual Studio工程配置sln、vcxproj、rc等整体结构清晰便于在Windows环境下直接编译调试。目前已有2173人学习/下载。通过研读源码开发者可以掌握从报文接收到响应返回的完整实现思路并据此便捷地扩展线圈读写等更多功能码适配智能能源管理、环境监测、自动化产线等不同工业控制场景提升设备互联与远程控制的开发效率。1. 为什么 MODBUS TCP SERVER 源码值得翻现场最常见的尴尬是用现成的 Modbus 从站模拟器主站数据读得干干净净等换成一版自己写的服务端连接能建立、报文也发了寄存器却永远返回零或者偶尔飘成乱码。你面前只有一个黑匣子转向现有工具又复现不了最后只能硬着头皮把服务端源码从头到尾查一遍。这正是 MODBUS TCP SERVER 源码的价值所在它不是拿来到处复制粘贴的模板而是你处理现场问题的最后一本底账。这篇文章会从一份最小可运行的服务端源码讲起把 Modbus TCP 的报文结构、寄存器模型、并发处理和事务标识拆清楚再把我在几个设备联网项目里遇到过的坑按“现象—原因—解决”写成排查清单。适合两类人一类是要把 Modbus TCP Server 集成到采集网关、边缘盒子或上位机里的开发工程师另一类是天天跟 PLC、HMI、组态软件对点表被未知从站行为反复折磨的调试工程师。读完你至少能带走两样东西一套可以直接抄作业的源码骨架一份按图索骥的排错手册。至于最后要不要用开源库、要不要自己维护看完第三四章你自己就能拍板。2. 从协议到源码MODBUS TCP SERVER 的最小骨架2.1 先看 7 字节头事务、单元和长度怎么对齐写服务端之前脑子里必须有一张固定的帧结构图否则后面所有字节偏移都会算错。Modbus TCP 的请求由 MBAP Header 和 PDU 组成。MBAP 固定 7 字节事务标识符占 2 字节协议标识符占 2 字节长度字段占 2 字节单元标识符占 1 字节。事务标识符用在同一个连接里把请求和响应配对协议标识符必须为 0表示这是 Modbus 协议长度字段表示单元标识符加 PDU 一共还有多少字节单元标识符在串口透传网关里代表从站地址纯 TCP 场景通常填 0 或 1。服务端最容易翻车的不是总字节数而是长度字段的计算口径。请求头里的 length 是“单元标识符 1 字节 PDU 长度”。也就是说服务端读完 7 字节头之后还要继续读 length-1 个字节才是完整的 PDU。很多新人直接把后续所有可读字节当成一帧收完在连续请求的场景下会把下一个请求的头也吞进去表现就是第一帧正常第二帧开始全部错位。下面这张表列出四个最常用功能码的请求响应格式实现的边界判断基本都围绕它展开。功能码含义请求 PDU响应 PDU0x03读保持寄存器起始地址(2B) 寄存器数量(2B)字节数(1B) 寄存器值(NB)0x04读输入寄存器起始地址(2B) 寄存器数量(2B)字节数(1B) 寄存器值(NB)0x06写单个寄存器地址(2B) 值(2B)地址(2B) 值(2B)0x10写多个寄存器起始地址(2B) 数量(2B) 字节数(1B) 值(NB)起始地址(2B) 数量(2B)注意 Modbus 协议里的寄存器地址从 0 开始而组态软件界面上往往显示成 40001、40002这个 1 的偏移是上位机显示层的事源码里别跟着加。我在项目里见过服务端收到起始地址 0 却去读数组下标 1最后每个点位都差一位。2.2 寄存器模型的取舍用哪种内存结构支撑读写Modbus 的 PDU 不关心数据来自数组、数据库还是某个硬件寄存器服务端源码真正的分水岭在寄存器模型的组织方式。最直接的做法是把每种寄存器区域做成一个数组。保持寄存器用 16 位无符号整数地址连续读写都靠下标索引。先初始化一块长 100 的列表写单个寄存器就更新第 n 个元素读就按切片返回。这个模型跑通协议已经足够但它有个明显缺点当点位数量和业务逻辑变多每个功能码分支都要复制一遍边界判断代码很快会变得没法维护。我建议的顺序是先用简单数组把服务端跑通再做数据访问层抽象。不要一开始就上配置文件、多区域映射那会让问题叠加。真实项目里常见的做法是维护一个点表配置每个条目包含起始地址、数量、读写权限和数据来源服务端在收到请求后根据配置动态查表。这个会在最后一章展开。选型方面还有另一条路直接用现成开源库比如某开发者常用的 Python Modbus 库它内置了 Datablock 和协议解析上位机工具类项目用它非常省事。我当时坚持自己写一遍是因为内核要移植到一个很小的实时系统里第三方库依赖太重不如一套纯 socket 代码容易裁剪。这个选择没有标准答案关键看你的运行环境是否允许引入外部依赖。2.3 最小源码不依赖第三方库的 Python server下面给出一份我裁剪过的最小实现只覆盖读保持寄存器和写单个寄存器以及异常回包。它能让你在本地立刻看到一个可交互的 Modbus TCP Server。import socket import struct import threading # 保持寄存器表地址从 0 开始长度 100 REG_HOLDING [0] * 100 REG_LOCK threading.Lock() def build_response(tid, unit, pdu): # MBAP 中 length 单元标识(1) PDU 长度 length len(pdu) 1 return struct.pack(HHHB, tid, 0, length, unit) pdu def handle_client(conn): try: while True: mbap conn.recv(7) if not mbap: break tid, pid, length, unit struct.unpack(HHHB, mbap) if pid ! 0: break # 还需要读取 length-1 字节的 PDU pdu b remain length - 1 while remain 0: chunk conn.recv(remain) if not chunk: return pdu chunk remain - len(chunk) func pdu[0] if func 0x03: # 读保持寄存器 start, count struct.unpack(HH, pdu[1:5]) # 单次最多读 125 个寄存器 if count 0 or count 125 or start count len(REG_HOLDING): resp build_response(tid, unit, bytes([0x83, 0x02])) else: with REG_LOCK: values REG_HOLDING[start:start count] payload bytes([count * 2]) for v in values: payload struct.pack(H, v) resp build_response(tid, unit, bytes([0x03]) payload) elif func 0x06: # 写单个保持寄存器 addr, value struct.unpack(HH, pdu[1:5]) if addr len(REG_HOLDING): resp build_response(tid, unit, bytes([0x86, 0x02])) else: with REG_LOCK: REG_HOLDING[addr] value resp build_response(tid, unit, bytes([0x06]) struct.pack(HH, addr, value)) else: # 非法功能码 resp build_response(tid, unit, bytes([func | 0x80, 0x01])) conn.sendall(resp) finally: conn.close() def start_server(ip0.0.0.0, port502): srv socket.socket(socket.AF_INET, socket.SOCK_STREAM) srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) srv.bind((ip, port)) srv.listen(5) print(Modbus TCP Server listening on {}:{}.format(ip, port)) while True: conn, addr srv.accept() threading.Thread(targethandle_client, args(conn,), daemonTrue).start() if __name__ __main__: start_server()这段代码有几个值得圈出来的点。tid, pid, length, unit用HHHB一次拆出所有多字节字段都按网络大端解析。build_response统一封装 MBAP 头每个分支不用各自拼长度从根上减少“响应长度算错”的概率。REG_LOCK是必须加的因为多客户端线程同时读写同一个列表不加锁会出现数据交错现场表现是寄存器值莫名其妙归零或者变成旧值。功能码 0x03 的响应里有“字节数”字段这是 01/02/03/04 共有的结构漏掉之后主站会一直等到超时。异常回包必须把功能码最高位置 1例如 0x03 变 0x83同时带异常码 0x02 表示非法数据地址。主站看到高位为 1 才会按异常处理直接回普通功能码会让主站把后面的字节当成正常数据去解析必然错乱。启动后用 Modbus Poll 或其他主站工具连接 502 端口读起始地址 0、数量 10如果返回的数据比你预期少或者读到乱码先看是不是字节数字段和实际返回长度不一致。这是最小实现最容易踩的第一个坑后面避坑章节还会继续展开。3. 源码不只是收发事务标识、并发和连接管理3.1 事务标识符(TID)并发请求配对的关键MBAP 头第一个字段是事务标识英文缩写 TID。在同一个 TCP 连接里客户端可以连续发送多个请求并不严格要求一问一答。服务端必须原样回显请求中的 TID客户端才能把响应和请求对应起来。如果服务端把 TID 改成了自增序列客户端就会出现响应超时、请求错位。有些简单的上位机工具并不校验 TID但不校验不代表你可以随便改。我用过的几款主流组态软件都会在协议栈里核对这个字段一旦发现对不上就把这条响应丢弃。所以源码里最保守的做法是在handle_client入口保存传入的 tidbuild_response原样带回。有一点容易被忽略Modbus TCP 标准允许在同一连接上多路复用事务但很多设备端从站只支持串行处理。如果你的客户端是同一连接并发发请求而你的服务端是一个线程连续阻塞读取响应自然是一个一个返回这时客户端如果做了多事务 pending就会认为部分请求超时。服务端源码要区分好“连接级并发”和“事务级并发”。最简单的办法是限制同一连接同一时刻只处理一个事务客户端通常也会退化为串行。真正要支持事务级并发就得为每个连接维护一个 pending 字典按 TID 找到等待的 writer 再回包复杂度会明显上升。3.2 多客户端连接线程池与 asyncio 的取舍最小源码用threading.Thread对每个客户端起一个线程。这在客户端数量少的时候没有问题五六个主站轮询完全扛得住。但现场往往是多台主站同时连接每台还会建立多条连接线程数一旦跑到几十上百系统上下文切换开销会非常明显服务端响应延迟开始抖动。常见的替代方案有两个。第一是线程池用ThreadPoolExecutor限制最大并发线程数。因为每个连接的处理函数是一个长循环会一直占住一个线程所以线程池大小严格意义上是“最大并发连接数”不是“每秒能处理的请求数”。超出的连接会在 listen 队列里排队如果 backlog 太小新连接会直接被内核拒绝。配合线程池一定要做空闲超时比如 30 秒没收到帧就关闭连接否则一个断开的客户端没被发现线程池里就少了一个可用的线程。第二是 asyncio 单线程事件循环适合连接多、每连接流量小、寄存器响应快的场景。但 asyncio 有个致命禁忌业务代码里不能出现任何阻塞调用比如time.sleep、同步数据库查询、文件锁。一旦阻塞所有客户端的请求一起卡住。用 asyncio 实现 Modbus TCP Server 时读取一帧的标准写法是先读 7 字节头再根据长度字段用readexactly(length - 1)把剩余部分读够不要手动拼包因为 Modbus 帧边界是自描述的长度字段就是最好的拆包依据。下面是 asyncio 服务端处理连接的核心骨架保留了 MPAB 读取逻辑import asyncio import struct async def handle_connection(reader, writer): try: while True: mbap await reader.readexactly(7) tid, pid, length, unit struct.unpack(HHHB, mbap) if pid ! 0: break pdu await reader.readexactly(length - 1) # 按功能码构造响应 pdu逻辑同第二章节 resp build_response(tid, unit, pdu) writer.write(resp) await writer.drain() except (asyncio.IncompleteReadError, ConnectionResetError): pass finally: writer.close() await writer.wait_closed()这里的关键参数是readexactly它要么读满指定字节要么抛异常绝不会出现少读半个数据包的情况。缺点是一旦客户端发了一个不完整的头服务端会一直等下去所以必须在asyncio.wait_for里包一层超时。不要小看这个超时真实网络环境里丢包后客户端重传服务端如果没有超时机制连接会一直挂着慢慢耗尽系统文件描述符。3.3 长连接 vs 短连接哪种现场更常见Modbus TCP 设计默认是长连接。真正的 PLC 主站会保持连接到从站周期性地轮询寄存器断线后还会自动重连。服务端如果处理完一次请求就关闭连接主站每个周期都要重新建连现场会出现“数据刷新慢、状态经常断”的假象。短连接场景主要出现在 Web 后台测试、临时脚本或者需要快速释放端口的工具中。做服务端源码时要两种都支持但不要主动关闭长连接。如果你确实需要回收空闲资源把空闲超时设置得尽量长至少 60 秒以上如果主站轮询周期本身就长要考虑把这个超时再放大。还有一个常被忽略的点半开连接。现场网络抖动之后客户端已经不在但服务端的recv还一直在阻塞它根本不知道对方已经消失。解决方法是给每个连接设置 socket 超时conn.settimeout(60)超时后关闭连接并记录日志。这一步是 demo 代码和生产级代码真正的分界线。某些系统里还需要配合 TCP keepalive让内核层探测对端是否存活但 keepalive 默认探测周期很长不能替代应用层超时。4. 参数与配置让 MODBUS TCP SERVER 源码跑得稳4.1 必调参数超时、缓冲区、地址范围与端口把源码从“能跑”推向“能扛现场”无非是把下面这几个参数调成符合业务的数值。参数推荐值作用调大/调小的影响socket 超时30-60s检测半开连接太小会让慢周期主站误认为断线太大浪费连接资源recv 缓冲区2-8KB接收多帧时缓存Modbus 单帧小于 260B太大并不会提升性能监听 backlog5-10未 accept 的连接队列太小高并发会丢连接太大占用系统内存寄存器区长度按点表实际越界返回异常码设成 65536 没有任何收益反而放宽了越界风险最大连接数按设备性能保护服务不被打爆超过可以拒绝新连接返回日志字节序big-endian寄存器默认大端改成小端会直接造成数据翻倍端口默认是 502Linux 下低于 1024 的端口需要 root 权限很多开发环境会先用 1502 调试上线再映射到 502。如果你用 Docker 部署容器内的 502 可以映射到宿主机的 1502不影响协议本身。SO_REUSEADDR一定要在 bind 之前设置否则服务端程序重启后会因为之前的 TIME_WAIT 状态占用端口而失败。这个选项不会像某些博客讲的那样“解决并发连接被 bind 拒绝”的问题它只是允许重用地址避免快速重启时端口被占用。4.2 功能码的边界03/04/06/16 怎么实现与限制Modbus TCP 的 PDU 理论最大长度是 253 字节这一个数学约束决定了很多功能码的数量上限。读保持寄存器 0x03 和读输入寄存器 0x04 单次最多读 125 个寄存器因为每个寄存器 2 字节125 个就是 250 字节加上功能码和字节数正好 252卡在 253 以内。写多个寄存器 0x10 单次最多写 123 个因为请求里还有起始地址和数量留给数据的空间更少。很多从站源码没有做这个限制收到 count200 的请求时直接越界访问列表并抛异常连接直接断掉。主站看到连接断开通常会连续重试然后报告“从站无响应”。正确的做法是像第二章节代码里那样把边界判断放在任何数据处理之前如果 count 超过上限就返回异常码 0x02 非法数据地址而不是让程序崩溃。06 写单个寄存器是最简单的不存在批量上限问题但要处理地址越界。有些主站用 06 写单个设置项时起始地址正好是点表末尾你如果只判断addr len(REG_HOLDING)就没有给“最后一个合法地址”留空间。常规写法是addr len(REG_HOLDING)对应数组下标 0 到 len-1 合法。01 和 02 线圈/离散输入功能码在现场也很常见。线圈是 bit 存储读取 2000 个线圈需要 250 字节数据正好是 PDU 允许的极限。如果只实现了寄存器客户端发 01 功能码就会收到 0x01 异常。大多数设备端会同时实现 01/02/03/04因为组态软件默认要把所有类型都读一遍。4.3 错误处理异常码返回与日志Modbus 异常码总共就那么几个0x01 非法功能码、0x02 非法数据地址、0x03 非法数据值、0x04 从站设备故障。返回异常时必须把功能码最高位置 1。比如 0x03 变成 0x830x06 变成 0x86。最高位没有置 1 的响应会被主站按正常数据处理这是现场排查时最难发现的错误之一因为报文结构看起来完整实际内容全是错位数据。日志不要贪多。每个连接记录 TID、功能码、起始地址和数量就够了寄存器内容只有在异常时才打印。我见过有人把每个请求的完整十六进制都打进日志结果服务端跑一天日志文件几个 GB真正想看关键信息的时候全被刷没了。生产环境里建议加一个开关默认开“请求摘要日志”级别 INFO调试时开“详细报文日志”级别 DEBUG。抓包工具能覆盖一部分问题但服务端日志能看到“程序内部认为哪里越界”这是 Wireshark 看不到的。5. 避坑MODBUS TCP SERVER 的常见故障排查5.1 现象请求一多寄存器值就被置零现象是单个连接单次请求都正常主站并发轮询或者频繁写操作之后某个寄存器开始变成 0再过一会又恢复。原因通常是两个一是多线程同时写同一个寄存器数组没有加锁Python 里虽然 GIL 保证了单个字节码指令的原子性但列表切片和赋值并不是整体原子操作两个线程交错时会读到旧值二是服务端读取 PDU 时没有严格按 length 字段接收用了一次不完整的 recv导致下一帧的偏移量出错写入请求的地址乱套。解决方法是给寄存器数据加锁并在解析帧时严格按“先读 7 字节头再循环读够 length-1 字节”来收包。第二章节代码里的while remain 0就是这个目的。不要相信一次 recv 能拿到完整 PDU尤其在本地回环之外的以太网环境。5.2 现象连接不释放导致端口耗尽现象是服务端运行一段时间后新的客户端连接全部失败用netstat能看到大量 TIME_WAIT 或者 ESTABLISHED 状态的连接堆积程序日志里全是 bind 或 accept 相关的报错。原因是对端异常断开时服务端 recv 没有返回一直阻塞或者客户端主动关闭时服务端没有进入 close 流程。每个堆积连接占一个文件描述符Linux 默认进程最大文件描述符是 1024很快就会被耗尽。解决方法是给每个连接设置超时时间conn.settimeout(60)在handle_client里把 socket 超时异常统一捕获并关闭连接。同时可以在 accept 后设置 TCP keepalive但 keepalive 默认参数在 Linux 下是 2 小时不适合短周期检测需要配合套接字选项调整探测时间。最稳的还是应用层超时加线程回收。5.3 现象字节序反了明明是 1 读出来是 256现象是写一个寄存器值 1主站读出来是 256写 0x0102读出来 0x0201。原因是 Modbus 寄存器默认大端高字节在前。如果用本地字节序的struct.pack(H, value)在 x86/ARM 小端环境里会把低字节放到内存前面报文变成低字节在前主站按大端解析正好反了。解决方法是所有多字节字段统一用H、I不要用裸的H或I。Python 的struct默认用本地字节序机器不同行为不同最容易踩。排查时写一个固定值 0x1234 到寄存器读回来看字节排列能立刻确认是不是字节序问题。5.4 现象模拟器可以读真实 PLC 请求超时现象是 Modbus Poll、模拟主机都能正常读写换成某品牌 PLC 做主站后服务端日志显示收到了请求但主站一直报超时或者间歇性失败。原因通常是真实 PLC 会一次性建立多个连接并在一个连接里连续发送多个请求还有可能是 PLC 发送了你没有实现的功能码比如 0x10 写多个寄存器而服务端返回了非法的异常码主站协议栈直接放弃重试。解决方法是先抓包看 PLC 实际发出来的请求是什么样子。重点看三个字段TID 是否在同一个连接上递增、功能码是什么、起始地址和数量是多少。抓不到包时在服务端日志里打印收到的原始 PDU 十六进制哪怕不打完整报文也要打功能码和长度。很多问题时隐性的主站只报超时不会告诉你它发送了什么。5.5 现象异步框架里用阻塞读导致整个服务卡死现象是用 asyncio 实现的服务端在低并发时正常客户端连接一多整体响应延迟飙升甚至所有请求都没反应。原因是在异步回调里用了同步的time.sleep、同步 socket 操作或者 CPU 密集型的大循环。asyncio 是单线程事件循环一个阻塞调用会停掉整个循环其他连接即使早就准备好了也无法被处理。解决方法是所有耗时操作放进线程池比如await asyncio.to_thread(do_heavy_work, data)读取网络数据必须用reader.readexactly不要用socket.recv。同时给每个请求的处理加上超时保护避免某个客户端不发完数据时整个事件循环被readexactly永久占住。这个坑最容易在“把原来 thread 版改成 asyncio 版”的时候出现因为很多代码只是换了个壳内部还是一堆阻塞函数。6. 从源码到交付寄存器映射、抓包验证和压测6.1 把寄存器表变成配置而不是把地址写死在 if 里第二章节的源码用的是一个固定长度列表适合跑通协议。真正到一个有几十个点位、不同寄存器代表温度、转速、状态的现场再在 if 分支里手写地址就很痛苦了。我一般会把点表抽成一个配置结构每个数据区包含起始地址、长度、读写权限、当前值来源函数。比如温度寄存器由传感器线程更新设定值寄存器由 Modbus 写请求更新。服务端收到请求后先按功能码找到对应的数据区再做边界判断。这样做的好处是现场点位调整时只改配置不重新编译。点表结构可以用一个简单的 Python 类来表示核心目的是让“地址—数据来源”的映射一目了然。不要在这里过度设计第一个版本用 dict 加回调函数就足够。6.2 抓包验证是源码调试的第一现场Wireshark 是排查 Modbus TCP Server 最直接的证据来源。过滤条件写tcp.port 502逐帧展开 MBAP 和 PDU立刻能看到长度字段是不是正确的、功能码有没有回执、异常码高位有没有置 1。我最常用的验证套路是先写一个寄存器值 0x0102再读回来。如果抓包看到的值是 0x0102说明字节序和收发都正常如果看到 0x0201不用怀疑就是字节序问题。然后再测边界读起始地址 0、数量 125成功改成数量 126应返回 0x83 0x02。这个用例能同时验证正常路径和异常路径。Wireshark 里如果看到 Malformed 标记基本是长度字段和实际数据长度不匹配。此时不要急着改程序先看这一帧的 Byte Count 和后续实际字节数差了几个。常见原因是在响应里多写了地址或者少算了 unit 标识符长度。6.3 给源码加一个最小压测脚本交付之前我会用一个几十行的脚本做一次并发冒烟。下面是一个用 Python 线程池模拟多主站的简单框架每一线程建立独立连接连续执行写后读统计成功率import socket import struct import threading def modbus_read(conn, start, count): # 构造 03 请求 tid 1 pdu struct.pack(BHH, 0x03, start, count) mbap struct.pack(HHHB, tid, 0, len(pdu) 1, 1) conn.sendall(mbap pdu) header conn.recv(7) tid2, pid, length, unit struct.unpack(HHHB, header) data b while len(data) length - 1: data conn.recv(length - 1 - len(data)) return data def worker(ip, port, errors): try: conn socket.create_connection((ip, port), timeout3) for i in range(100): resp modbus_read(conn, 0, 10) if len(resp) 22: # 1字节功能码 1字节数量 20字节数据 errors.append(short response) break conn.close() except Exception as e: errors.append(str(e)) threads [] errors [] for i in range(20): t threading.Thread(targetworker, args(127.0.0.1, 502, errors)) t.start() threads.append(t) for t in threads: t.join() print(errors:, len(errors))这个脚本不对响应内容做过深校验它主要看两件事多连接并发时会不会崩、会不会出现短包。如果 errors 数量逐渐增长下一步就去查服务端 backlog 和线程数如果短包频繁极大概率是响应长度字段写错。6.4 一个长期受用的交付习惯这套源码骨架我在不同项目里打磨过很多轮真正让它稳定下来的不是代码技巧而是“每跑一个用例都留证据”的习惯。本地能连通只是第一步边界返回、异常码、并发读写、抓包一致性这四个验证点缺一不可。现在每接到一个要集成 Modbus 从站的活我都会先花一小时把最小服务和压测脚本搭起来再开始谈业务点表。源码的价值不在第一次运行通过而在后续任何一次故障里你都能翻开它快速定位到那几行可疑的判断。希望帮到你。本文还有配套的精品资源点击获取 Modbus TCP Server源码解析：从寄存器模型到并发与排错实战
简介这是一份基于C实现的MODBUS TCP服务器源码主要面向工业自动化领域的开发者用于快速搭建支持MODBUS TCP通信的服务端程序。源码实现了MODBUS协议中常用的功能码03读取输入寄存器/离散输入与功能码16写多个保持寄存器覆盖请求解析、应答构造和常见错误处理流程可作为理解协议栈、学习TCP/IP网络编程及进行二次开发的基础框架同时帮助理解MODBUS协议规范与报文交互机制。资源压缩包共22个文件、约152KB以7个h头文件与5个cpp源文件为主附带Visual Studio工程配置sln、vcxproj、rc等整体结构清晰便于在Windows环境下直接编译调试。目前已有2173人学习/下载。通过研读源码开发者可以掌握从报文接收到响应返回的完整实现思路并据此便捷地扩展线圈读写等更多功能码适配智能能源管理、环境监测、自动化产线等不同工业控制场景提升设备互联与远程控制的开发效率。1. 为什么 MODBUS TCP SERVER 源码值得翻现场最常见的尴尬是用现成的 Modbus 从站模拟器主站数据读得干干净净等换成一版自己写的服务端连接能建立、报文也发了寄存器却永远返回零或者偶尔飘成乱码。你面前只有一个黑匣子转向现有工具又复现不了最后只能硬着头皮把服务端源码从头到尾查一遍。这正是 MODBUS TCP SERVER 源码的价值所在它不是拿来到处复制粘贴的模板而是你处理现场问题的最后一本底账。这篇文章会从一份最小可运行的服务端源码讲起把 Modbus TCP 的报文结构、寄存器模型、并发处理和事务标识拆清楚再把我在几个设备联网项目里遇到过的坑按“现象—原因—解决”写成排查清单。适合两类人一类是要把 Modbus TCP Server 集成到采集网关、边缘盒子或上位机里的开发工程师另一类是天天跟 PLC、HMI、组态软件对点表被未知从站行为反复折磨的调试工程师。读完你至少能带走两样东西一套可以直接抄作业的源码骨架一份按图索骥的排错手册。至于最后要不要用开源库、要不要自己维护看完第三四章你自己就能拍板。2. 从协议到源码MODBUS TCP SERVER 的最小骨架2.1 先看 7 字节头事务、单元和长度怎么对齐写服务端之前脑子里必须有一张固定的帧结构图否则后面所有字节偏移都会算错。Modbus TCP 的请求由 MBAP Header 和 PDU 组成。MBAP 固定 7 字节事务标识符占 2 字节协议标识符占 2 字节长度字段占 2 字节单元标识符占 1 字节。事务标识符用在同一个连接里把请求和响应配对协议标识符必须为 0表示这是 Modbus 协议长度字段表示单元标识符加 PDU 一共还有多少字节单元标识符在串口透传网关里代表从站地址纯 TCP 场景通常填 0 或 1。服务端最容易翻车的不是总字节数而是长度字段的计算口径。请求头里的 length 是“单元标识符 1 字节 PDU 长度”。也就是说服务端读完 7 字节头之后还要继续读 length-1 个字节才是完整的 PDU。很多新人直接把后续所有可读字节当成一帧收完在连续请求的场景下会把下一个请求的头也吞进去表现就是第一帧正常第二帧开始全部错位。下面这张表列出四个最常用功能码的请求响应格式实现的边界判断基本都围绕它展开。功能码含义请求 PDU响应 PDU0x03读保持寄存器起始地址(2B) 寄存器数量(2B)字节数(1B) 寄存器值(NB)0x04读输入寄存器起始地址(2B) 寄存器数量(2B)字节数(1B) 寄存器值(NB)0x06写单个寄存器地址(2B) 值(2B)地址(2B) 值(2B)0x10写多个寄存器起始地址(2B) 数量(2B) 字节数(1B) 值(NB)起始地址(2B) 数量(2B)注意 Modbus 协议里的寄存器地址从 0 开始而组态软件界面上往往显示成 40001、40002这个 1 的偏移是上位机显示层的事源码里别跟着加。我在项目里见过服务端收到起始地址 0 却去读数组下标 1最后每个点位都差一位。2.2 寄存器模型的取舍用哪种内存结构支撑读写Modbus 的 PDU 不关心数据来自数组、数据库还是某个硬件寄存器服务端源码真正的分水岭在寄存器模型的组织方式。最直接的做法是把每种寄存器区域做成一个数组。保持寄存器用 16 位无符号整数地址连续读写都靠下标索引。先初始化一块长 100 的列表写单个寄存器就更新第 n 个元素读就按切片返回。这个模型跑通协议已经足够但它有个明显缺点当点位数量和业务逻辑变多每个功能码分支都要复制一遍边界判断代码很快会变得没法维护。我建议的顺序是先用简单数组把服务端跑通再做数据访问层抽象。不要一开始就上配置文件、多区域映射那会让问题叠加。真实项目里常见的做法是维护一个点表配置每个条目包含起始地址、数量、读写权限和数据来源服务端在收到请求后根据配置动态查表。这个会在最后一章展开。选型方面还有另一条路直接用现成开源库比如某开发者常用的 Python Modbus 库它内置了 Datablock 和协议解析上位机工具类项目用它非常省事。我当时坚持自己写一遍是因为内核要移植到一个很小的实时系统里第三方库依赖太重不如一套纯 socket 代码容易裁剪。这个选择没有标准答案关键看你的运行环境是否允许引入外部依赖。2.3 最小源码不依赖第三方库的 Python server下面给出一份我裁剪过的最小实现只覆盖读保持寄存器和写单个寄存器以及异常回包。它能让你在本地立刻看到一个可交互的 Modbus TCP Server。import socket import struct import threading # 保持寄存器表地址从 0 开始长度 100 REG_HOLDING [0] * 100 REG_LOCK threading.Lock() def build_response(tid, unit, pdu): # MBAP 中 length 单元标识(1) PDU 长度 length len(pdu) 1 return struct.pack(HHHB, tid, 0, length, unit) pdu def handle_client(conn): try: while True: mbap conn.recv(7) if not mbap: break tid, pid, length, unit struct.unpack(HHHB, mbap) if pid ! 0: break # 还需要读取 length-1 字节的 PDU pdu b remain length - 1 while remain 0: chunk conn.recv(remain) if not chunk: return pdu chunk remain - len(chunk) func pdu[0] if func 0x03: # 读保持寄存器 start, count struct.unpack(HH, pdu[1:5]) # 单次最多读 125 个寄存器 if count 0 or count 125 or start count len(REG_HOLDING): resp build_response(tid, unit, bytes([0x83, 0x02])) else: with REG_LOCK: values REG_HOLDING[start:start count] payload bytes([count * 2]) for v in values: payload struct.pack(H, v) resp build_response(tid, unit, bytes([0x03]) payload) elif func 0x06: # 写单个保持寄存器 addr, value struct.unpack(HH, pdu[1:5]) if addr len(REG_HOLDING): resp build_response(tid, unit, bytes([0x86, 0x02])) else: with REG_LOCK: REG_HOLDING[addr] value resp build_response(tid, unit, bytes([0x06]) struct.pack(HH, addr, value)) else: # 非法功能码 resp build_response(tid, unit, bytes([func | 0x80, 0x01])) conn.sendall(resp) finally: conn.close() def start_server(ip0.0.0.0, port502): srv socket.socket(socket.AF_INET, socket.SOCK_STREAM) srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) srv.bind((ip, port)) srv.listen(5) print(Modbus TCP Server listening on {}:{}.format(ip, port)) while True: conn, addr srv.accept() threading.Thread(targethandle_client, args(conn,), daemonTrue).start() if __name__ __main__: start_server()这段代码有几个值得圈出来的点。tid, pid, length, unit用HHHB一次拆出所有多字节字段都按网络大端解析。build_response统一封装 MBAP 头每个分支不用各自拼长度从根上减少“响应长度算错”的概率。REG_LOCK是必须加的因为多客户端线程同时读写同一个列表不加锁会出现数据交错现场表现是寄存器值莫名其妙归零或者变成旧值。功能码 0x03 的响应里有“字节数”字段这是 01/02/03/04 共有的结构漏掉之后主站会一直等到超时。异常回包必须把功能码最高位置 1例如 0x03 变 0x83同时带异常码 0x02 表示非法数据地址。主站看到高位为 1 才会按异常处理直接回普通功能码会让主站把后面的字节当成正常数据去解析必然错乱。启动后用 Modbus Poll 或其他主站工具连接 502 端口读起始地址 0、数量 10如果返回的数据比你预期少或者读到乱码先看是不是字节数字段和实际返回长度不一致。这是最小实现最容易踩的第一个坑后面避坑章节还会继续展开。3. 源码不只是收发事务标识、并发和连接管理3.1 事务标识符(TID)并发请求配对的关键MBAP 头第一个字段是事务标识英文缩写 TID。在同一个 TCP 连接里客户端可以连续发送多个请求并不严格要求一问一答。服务端必须原样回显请求中的 TID客户端才能把响应和请求对应起来。如果服务端把 TID 改成了自增序列客户端就会出现响应超时、请求错位。有些简单的上位机工具并不校验 TID但不校验不代表你可以随便改。我用过的几款主流组态软件都会在协议栈里核对这个字段一旦发现对不上就把这条响应丢弃。所以源码里最保守的做法是在handle_client入口保存传入的 tidbuild_response原样带回。有一点容易被忽略Modbus TCP 标准允许在同一连接上多路复用事务但很多设备端从站只支持串行处理。如果你的客户端是同一连接并发发请求而你的服务端是一个线程连续阻塞读取响应自然是一个一个返回这时客户端如果做了多事务 pending就会认为部分请求超时。服务端源码要区分好“连接级并发”和“事务级并发”。最简单的办法是限制同一连接同一时刻只处理一个事务客户端通常也会退化为串行。真正要支持事务级并发就得为每个连接维护一个 pending 字典按 TID 找到等待的 writer 再回包复杂度会明显上升。3.2 多客户端连接线程池与 asyncio 的取舍最小源码用threading.Thread对每个客户端起一个线程。这在客户端数量少的时候没有问题五六个主站轮询完全扛得住。但现场往往是多台主站同时连接每台还会建立多条连接线程数一旦跑到几十上百系统上下文切换开销会非常明显服务端响应延迟开始抖动。常见的替代方案有两个。第一是线程池用ThreadPoolExecutor限制最大并发线程数。因为每个连接的处理函数是一个长循环会一直占住一个线程所以线程池大小严格意义上是“最大并发连接数”不是“每秒能处理的请求数”。超出的连接会在 listen 队列里排队如果 backlog 太小新连接会直接被内核拒绝。配合线程池一定要做空闲超时比如 30 秒没收到帧就关闭连接否则一个断开的客户端没被发现线程池里就少了一个可用的线程。第二是 asyncio 单线程事件循环适合连接多、每连接流量小、寄存器响应快的场景。但 asyncio 有个致命禁忌业务代码里不能出现任何阻塞调用比如time.sleep、同步数据库查询、文件锁。一旦阻塞所有客户端的请求一起卡住。用 asyncio 实现 Modbus TCP Server 时读取一帧的标准写法是先读 7 字节头再根据长度字段用readexactly(length - 1)把剩余部分读够不要手动拼包因为 Modbus 帧边界是自描述的长度字段就是最好的拆包依据。下面是 asyncio 服务端处理连接的核心骨架保留了 MPAB 读取逻辑import asyncio import struct async def handle_connection(reader, writer): try: while True: mbap await reader.readexactly(7) tid, pid, length, unit struct.unpack(HHHB, mbap) if pid ! 0: break pdu await reader.readexactly(length - 1) # 按功能码构造响应 pdu逻辑同第二章节 resp build_response(tid, unit, pdu) writer.write(resp) await writer.drain() except (asyncio.IncompleteReadError, ConnectionResetError): pass finally: writer.close() await writer.wait_closed()这里的关键参数是readexactly它要么读满指定字节要么抛异常绝不会出现少读半个数据包的情况。缺点是一旦客户端发了一个不完整的头服务端会一直等下去所以必须在asyncio.wait_for里包一层超时。不要小看这个超时真实网络环境里丢包后客户端重传服务端如果没有超时机制连接会一直挂着慢慢耗尽系统文件描述符。3.3 长连接 vs 短连接哪种现场更常见Modbus TCP 设计默认是长连接。真正的 PLC 主站会保持连接到从站周期性地轮询寄存器断线后还会自动重连。服务端如果处理完一次请求就关闭连接主站每个周期都要重新建连现场会出现“数据刷新慢、状态经常断”的假象。短连接场景主要出现在 Web 后台测试、临时脚本或者需要快速释放端口的工具中。做服务端源码时要两种都支持但不要主动关闭长连接。如果你确实需要回收空闲资源把空闲超时设置得尽量长至少 60 秒以上如果主站轮询周期本身就长要考虑把这个超时再放大。还有一个常被忽略的点半开连接。现场网络抖动之后客户端已经不在但服务端的recv还一直在阻塞它根本不知道对方已经消失。解决方法是给每个连接设置 socket 超时conn.settimeout(60)超时后关闭连接并记录日志。这一步是 demo 代码和生产级代码真正的分界线。某些系统里还需要配合 TCP keepalive让内核层探测对端是否存活但 keepalive 默认探测周期很长不能替代应用层超时。4. 参数与配置让 MODBUS TCP SERVER 源码跑得稳4.1 必调参数超时、缓冲区、地址范围与端口把源码从“能跑”推向“能扛现场”无非是把下面这几个参数调成符合业务的数值。参数推荐值作用调大/调小的影响socket 超时30-60s检测半开连接太小会让慢周期主站误认为断线太大浪费连接资源recv 缓冲区2-8KB接收多帧时缓存Modbus 单帧小于 260B太大并不会提升性能监听 backlog5-10未 accept 的连接队列太小高并发会丢连接太大占用系统内存寄存器区长度按点表实际越界返回异常码设成 65536 没有任何收益反而放宽了越界风险最大连接数按设备性能保护服务不被打爆超过可以拒绝新连接返回日志字节序big-endian寄存器默认大端改成小端会直接造成数据翻倍端口默认是 502Linux 下低于 1024 的端口需要 root 权限很多开发环境会先用 1502 调试上线再映射到 502。如果你用 Docker 部署容器内的 502 可以映射到宿主机的 1502不影响协议本身。SO_REUSEADDR一定要在 bind 之前设置否则服务端程序重启后会因为之前的 TIME_WAIT 状态占用端口而失败。这个选项不会像某些博客讲的那样“解决并发连接被 bind 拒绝”的问题它只是允许重用地址避免快速重启时端口被占用。4.2 功能码的边界03/04/06/16 怎么实现与限制Modbus TCP 的 PDU 理论最大长度是 253 字节这一个数学约束决定了很多功能码的数量上限。读保持寄存器 0x03 和读输入寄存器 0x04 单次最多读 125 个寄存器因为每个寄存器 2 字节125 个就是 250 字节加上功能码和字节数正好 252卡在 253 以内。写多个寄存器 0x10 单次最多写 123 个因为请求里还有起始地址和数量留给数据的空间更少。很多从站源码没有做这个限制收到 count200 的请求时直接越界访问列表并抛异常连接直接断掉。主站看到连接断开通常会连续重试然后报告“从站无响应”。正确的做法是像第二章节代码里那样把边界判断放在任何数据处理之前如果 count 超过上限就返回异常码 0x02 非法数据地址而不是让程序崩溃。06 写单个寄存器是最简单的不存在批量上限问题但要处理地址越界。有些主站用 06 写单个设置项时起始地址正好是点表末尾你如果只判断addr len(REG_HOLDING)就没有给“最后一个合法地址”留空间。常规写法是addr len(REG_HOLDING)对应数组下标 0 到 len-1 合法。01 和 02 线圈/离散输入功能码在现场也很常见。线圈是 bit 存储读取 2000 个线圈需要 250 字节数据正好是 PDU 允许的极限。如果只实现了寄存器客户端发 01 功能码就会收到 0x01 异常。大多数设备端会同时实现 01/02/03/04因为组态软件默认要把所有类型都读一遍。4.3 错误处理异常码返回与日志Modbus 异常码总共就那么几个0x01 非法功能码、0x02 非法数据地址、0x03 非法数据值、0x04 从站设备故障。返回异常时必须把功能码最高位置 1。比如 0x03 变成 0x830x06 变成 0x86。最高位没有置 1 的响应会被主站按正常数据处理这是现场排查时最难发现的错误之一因为报文结构看起来完整实际内容全是错位数据。日志不要贪多。每个连接记录 TID、功能码、起始地址和数量就够了寄存器内容只有在异常时才打印。我见过有人把每个请求的完整十六进制都打进日志结果服务端跑一天日志文件几个 GB真正想看关键信息的时候全被刷没了。生产环境里建议加一个开关默认开“请求摘要日志”级别 INFO调试时开“详细报文日志”级别 DEBUG。抓包工具能覆盖一部分问题但服务端日志能看到“程序内部认为哪里越界”这是 Wireshark 看不到的。5. 避坑MODBUS TCP SERVER 的常见故障排查5.1 现象请求一多寄存器值就被置零现象是单个连接单次请求都正常主站并发轮询或者频繁写操作之后某个寄存器开始变成 0再过一会又恢复。原因通常是两个一是多线程同时写同一个寄存器数组没有加锁Python 里虽然 GIL 保证了单个字节码指令的原子性但列表切片和赋值并不是整体原子操作两个线程交错时会读到旧值二是服务端读取 PDU 时没有严格按 length 字段接收用了一次不完整的 recv导致下一帧的偏移量出错写入请求的地址乱套。解决方法是给寄存器数据加锁并在解析帧时严格按“先读 7 字节头再循环读够 length-1 字节”来收包。第二章节代码里的while remain 0就是这个目的。不要相信一次 recv 能拿到完整 PDU尤其在本地回环之外的以太网环境。5.2 现象连接不释放导致端口耗尽现象是服务端运行一段时间后新的客户端连接全部失败用netstat能看到大量 TIME_WAIT 或者 ESTABLISHED 状态的连接堆积程序日志里全是 bind 或 accept 相关的报错。原因是对端异常断开时服务端 recv 没有返回一直阻塞或者客户端主动关闭时服务端没有进入 close 流程。每个堆积连接占一个文件描述符Linux 默认进程最大文件描述符是 1024很快就会被耗尽。解决方法是给每个连接设置超时时间conn.settimeout(60)在handle_client里把 socket 超时异常统一捕获并关闭连接。同时可以在 accept 后设置 TCP keepalive但 keepalive 默认参数在 Linux 下是 2 小时不适合短周期检测需要配合套接字选项调整探测时间。最稳的还是应用层超时加线程回收。5.3 现象字节序反了明明是 1 读出来是 256现象是写一个寄存器值 1主站读出来是 256写 0x0102读出来 0x0201。原因是 Modbus 寄存器默认大端高字节在前。如果用本地字节序的struct.pack(H, value)在 x86/ARM 小端环境里会把低字节放到内存前面报文变成低字节在前主站按大端解析正好反了。解决方法是所有多字节字段统一用H、I不要用裸的H或I。Python 的struct默认用本地字节序机器不同行为不同最容易踩。排查时写一个固定值 0x1234 到寄存器读回来看字节排列能立刻确认是不是字节序问题。5.4 现象模拟器可以读真实 PLC 请求超时现象是 Modbus Poll、模拟主机都能正常读写换成某品牌 PLC 做主站后服务端日志显示收到了请求但主站一直报超时或者间歇性失败。原因通常是真实 PLC 会一次性建立多个连接并在一个连接里连续发送多个请求还有可能是 PLC 发送了你没有实现的功能码比如 0x10 写多个寄存器而服务端返回了非法的异常码主站协议栈直接放弃重试。解决方法是先抓包看 PLC 实际发出来的请求是什么样子。重点看三个字段TID 是否在同一个连接上递增、功能码是什么、起始地址和数量是多少。抓不到包时在服务端日志里打印收到的原始 PDU 十六进制哪怕不打完整报文也要打功能码和长度。很多问题时隐性的主站只报超时不会告诉你它发送了什么。5.5 现象异步框架里用阻塞读导致整个服务卡死现象是用 asyncio 实现的服务端在低并发时正常客户端连接一多整体响应延迟飙升甚至所有请求都没反应。原因是在异步回调里用了同步的time.sleep、同步 socket 操作或者 CPU 密集型的大循环。asyncio 是单线程事件循环一个阻塞调用会停掉整个循环其他连接即使早就准备好了也无法被处理。解决方法是所有耗时操作放进线程池比如await asyncio.to_thread(do_heavy_work, data)读取网络数据必须用reader.readexactly不要用socket.recv。同时给每个请求的处理加上超时保护避免某个客户端不发完数据时整个事件循环被readexactly永久占住。这个坑最容易在“把原来 thread 版改成 asyncio 版”的时候出现因为很多代码只是换了个壳内部还是一堆阻塞函数。6. 从源码到交付寄存器映射、抓包验证和压测6.1 把寄存器表变成配置而不是把地址写死在 if 里第二章节的源码用的是一个固定长度列表适合跑通协议。真正到一个有几十个点位、不同寄存器代表温度、转速、状态的现场再在 if 分支里手写地址就很痛苦了。我一般会把点表抽成一个配置结构每个数据区包含起始地址、长度、读写权限、当前值来源函数。比如温度寄存器由传感器线程更新设定值寄存器由 Modbus 写请求更新。服务端收到请求后先按功能码找到对应的数据区再做边界判断。这样做的好处是现场点位调整时只改配置不重新编译。点表结构可以用一个简单的 Python 类来表示核心目的是让“地址—数据来源”的映射一目了然。不要在这里过度设计第一个版本用 dict 加回调函数就足够。6.2 抓包验证是源码调试的第一现场Wireshark 是排查 Modbus TCP Server 最直接的证据来源。过滤条件写tcp.port 502逐帧展开 MBAP 和 PDU立刻能看到长度字段是不是正确的、功能码有没有回执、异常码高位有没有置 1。我最常用的验证套路是先写一个寄存器值 0x0102再读回来。如果抓包看到的值是 0x0102说明字节序和收发都正常如果看到 0x0201不用怀疑就是字节序问题。然后再测边界读起始地址 0、数量 125成功改成数量 126应返回 0x83 0x02。这个用例能同时验证正常路径和异常路径。Wireshark 里如果看到 Malformed 标记基本是长度字段和实际数据长度不匹配。此时不要急着改程序先看这一帧的 Byte Count 和后续实际字节数差了几个。常见原因是在响应里多写了地址或者少算了 unit 标识符长度。6.3 给源码加一个最小压测脚本交付之前我会用一个几十行的脚本做一次并发冒烟。下面是一个用 Python 线程池模拟多主站的简单框架每一线程建立独立连接连续执行写后读统计成功率import socket import struct import threading def modbus_read(conn, start, count): # 构造 03 请求 tid 1 pdu struct.pack(BHH, 0x03, start, count) mbap struct.pack(HHHB, tid, 0, len(pdu) 1, 1) conn.sendall(mbap pdu) header conn.recv(7) tid2, pid, length, unit struct.unpack(HHHB, header) data b while len(data) length - 1: data conn.recv(length - 1 - len(data)) return data def worker(ip, port, errors): try: conn socket.create_connection((ip, port), timeout3) for i in range(100): resp modbus_read(conn, 0, 10) if len(resp) 22: # 1字节功能码 1字节数量 20字节数据 errors.append(short response) break conn.close() except Exception as e: errors.append(str(e)) threads [] errors [] for i in range(20): t threading.Thread(targetworker, args(127.0.0.1, 502, errors)) t.start() threads.append(t) for t in threads: t.join() print(errors:, len(errors))这个脚本不对响应内容做过深校验它主要看两件事多连接并发时会不会崩、会不会出现短包。如果 errors 数量逐渐增长下一步就去查服务端 backlog 和线程数如果短包频繁极大概率是响应长度字段写错。6.4 一个长期受用的交付习惯这套源码骨架我在不同项目里打磨过很多轮真正让它稳定下来的不是代码技巧而是“每跑一个用例都留证据”的习惯。本地能连通只是第一步边界返回、异常码、并发读写、抓包一致性这四个验证点缺一不可。现在每接到一个要集成 Modbus 从站的活我都会先花一小时把最小服务和压测脚本搭起来再开始谈业务点表。源码的价值不在第一次运行通过而在后续任何一次故障里你都能翻开它快速定位到那几行可疑的判断。希望帮到你。本文还有配套的精品资源点击获取