Modbus RTU/TCP控件包：RS-485链路、502端口与寄存器映射

简介面向工控上位机与自动化设备通讯开发者的Modbus控件包整合Modbus RTU与Modbus TCP/IP两种通讯方式可用于快速采集仪表、PLC等从站数据并适配VC、VB、C#、Delphi等常见开发环境。压缩包共60个文件、约478KB包含VB示例工程及工程文件、DLL组件、CHM与XML帮助文档、说明文本和可执行工具等便于对照示例理解调用方式与部署结构。功能覆盖01读线圈、02读输入状态、03读保持寄存器、04读输入寄存器以及05与06强制线圈和预置寄存器、17报告从站ID、22屏蔽写寄存器、23读写寄存器等常用操作。已有1770人学习下载适合需要快速搭建通讯测试、设备联调与数据采集原型的中初级开发者参考。1. 从一根 RS-485 线到 502 端口Modbus 控件包到底封装了什么现场最常见的画面是一台工控机同时挂着几条 RS-485 总线和几个以太网从站Modbus RTU 与 Modbus TCP/IP 控件包要做的不只是“多支持一个协议”还要把串口帧、CRC、MBAP 头、超时重试和寄存器映射收进同一套调用接口。它适合做设备接入、数据采集、边缘网关和测试工具的开发者新手能靠示例源码跑通第一条读寄存器命令熟手更关心连接复用、异常码和批量读写边界。下面按“选链路、跑最小主站、做映射、排故障”的顺序拆开。2. 先定拓扑再选协议RTU 串口链路与 TCP/IP 连接模型的取舍Modbus RTU 和 Modbus TCP/IP 经常被放在同一个控件包里卖但它们的故障模型完全不同。RTU 的问题多出在物理层和帧边界线序、终端电阻、波特率、校验位、3.5 字符间隔任何一个不对主站看到的都是“没回包”。TCP/IP 的问题多出在连接和拆包502 端口通不代表帧完整recv一次读到的不一定是一条响应。选型时先看现场拓扑不要先看代码接口。2.1 RS-485 半双工链路波特率、校验位与 3.5 字符间隔RTU 跑在 RS-485 上时通常是半双工总线主站发一帧从站在自己的地址被命中后回一帧。串口参数必须和从站手册完全一致波特率、数据位、校验位、停止位少一项都可能导致整条总线沉默。常见配置是 9600 或 19200、8 数据位、无校验或偶校验、1 或 2 停止位但这不是万能配方某公司的仪表用 8E1另一台设备用 8N2 很常见。帧边界靠静默时间判断。标准里说 3.5 个字符时间的总线空闲作为帧结束9600 波特率下大约 4ms19200 下大约 2ms高波特率下很多实现固定用 1.75ms 左右。这里的坑在于 USB 转 RS-485 转换器驱动和芯片会把字节间隔拉长主站如果按“读到没数据为止”收包很容易把一帧拆成两段或者把下一帧的尾巴粘进来。我一般让协议层按功能码计算期望长度收满就停不靠“等安静”判断整帧。总线本身也要看A/B 线序反接、没有共地、终端电阻缺失、从站地址重复、转换器方向控制异常都会表现成“主站发了但没响应”。排查时先一对一短距离接线确认从站地址和串口参数再上总线。终端电阻常见是 120Ω长距离或高波特率时更重要但并不是每段都随便加先看现场拓扑。2.2 TCP/IP 连接模型502 端口、MBAP 头与流式拆包Modbus TCP/IP 把 PDU 套在 MBAP 头里默认端口 502。MBAP 头 7 个字节事务号 2 字节、协议号 2 字节、长度 2 字节、单元号 1 字节。长度字段表示“单元号 PDU”的字节数所以收到的总长度是 6 length。事务号用来匹配请求和响应协议号通常为 0单元号在网关后面常用来区分串口从站。TCP 是字节流不是消息流。主站发一条读保持寄存器请求对端可能先回 3 个字节再回剩下的也可能两个响应粘在一起。只调用一次recv(1024)然后直接解析是现场最常见的翻车点之一。正确做法是先读满 7 字节 MBAP 头解析 length再循环读满length - 1字节的 PDU。每个连接上最好串行发请求或者用请求队列加事务号匹配别在一个 socket 上并发乱发。TCP 侧还要区分短连接和长连接。短连接实现简单但每次采集都三次握手设备多时开销明显长连接要处理断线重连、半开连接和空闲保活。我的习惯是采集周期小于 5 秒时用长连接超过 30 秒或设备支持连接数很少时用短连接并且在连接对象上记录最后成功时间连续失败就重建。2.3 控件包最小 API 面连接、四类读写、批量与异常一个能落地的控件包不需要一开始就堆很多花样最小 API 面应该覆盖打开/关闭连接、读线圈、读离散输入、读保持寄存器、读输入寄存器、写单线圈、写单寄存器、写多线圈、写多寄存器以及把异常响应转换成明确的异常对象。接口里要能看到从站号或单元号、起始地址、数量、超时时间不能把这些藏在全局变量里。批量读写要设上限。读保持寄存器一次最多 125 个寄存器读线圈一次最多 2000 个位写多寄存器一次最多 123 个寄存器写多线圈一次最多 1968 个位。超过上限时控件包应该主动拆包而不是把请求原样发出去等从站返回异常码 0x03。拆包后还要保证业务层拿到的是一段连续数据别让调用方自己拼。异常处理要保留原始信息。Modbus 异常响应的功能码最高位置 1后面跟异常码常见 0x01 非法功能、0x02 非法数据地址、0x03 非法数据值、0x04 从站故障、0x06 从站忙。控件包如果只抛一个“读取失败”现场排查会变成黑匣子。至少把从站号、功能码、起始地址、数量、异常码和耗时带出来。3. 把控件包跑通从串口参数到第一个保持寄存器读写的完整命令拿到一个带示例源码的压缩包先别急着编译整个工程。先确认它面向的是 RTU、TCP 还是两者都支持再看示例入口怎么传串口名、IP、端口、从站号和起始地址。最小验证目标只有一个读到一个已知的保持寄存器并且能把值稳定打印出来。这个目标跑通之前不要碰批量采集和业务映射。3.1 串口和网口参数先定成一张表RTU 侧先把下面几项对齐任何一项不一致都可能完全没响应参数常见值说明波特率9600 / 19200 / 38400以从站手册为准不要猜数据位8Modbus 串行链路常见配置校验位None / Even / Odd必须和从站一致停止位1 或 2无校验时有些设备用 2 位单帧超时300500ms不是重试总时长帧间隔3.5 字符时间高波特率常见固定 1.75msTCP 侧则先确认 IP、端口、单元号和连接方式。端口默认 502但网关映射到串口从站时单元号必须和网关配置一致。超时先设 500ms 到 1s别一上来设 5s否则一台离线设备就能把采集线程拖住。3.2 RTU 最小主站组帧、CRC16 与收发等待下面这段代码只做一件事读从站 1 的保持寄存器起始地址 0数量 2。它不依赖控件包用来验证串口参数和帧格式。实际项目里可以把read_holding_rtu换成控件包调用但底层逻辑是一样的。import serial import struct def crc16_modbus(data: bytes) - int: crc 0xFFFF for byte in data: crc ^ byte for _ in range(8): if crc 0x0001: crc (crc 1) ^ 0xA001 else: crc 1 return crc def read_holding_rtu(port: str, slave: int, start: int, count: int) - list[int]: # 功能码 0x03start 用协议地址例如手册 40001 对应 0 body struct.pack(BBHH, slave, 0x03, start, count) frame body struct.pack(H, crc16_modbus(body)) with serial.Serial( portport, baudrate9600, bytesize8, parityserial.PARITY_NONE, stopbits1, timeout0.5, # 单次读等待上限 inter_byte_timeout0.01 # 字节间断开时尽快返回 ) as ser: ser.reset_input_buffer() ser.write(frame) head ser.read(2) # 从站地址 功能码 if len(head) ! 2: raise TimeoutError(RTU 响应头不完整) addr, func head if addr ! slave: raise ValueError(f从站地址不匹配期望 {slave}实际 {addr}) if func 0x80: # 异常响应功能码最高位置 1 tail ser.read(3) # 异常码 1B CRC 2B if len(tail) ! 3: raise TimeoutError(异常响应不完整) raise RuntimeError(fModbus 异常响应异常码{tail[0]:02X}) byte_count_raw ser.read(1) if len(byte_count_raw) ! 1: raise TimeoutError(缺少字节数) byte_count byte_count_raw[0] data ser.read(byte_count 2) # 数据区 CRC if len(data) ! byte_count 2: raise TimeoutError(RTU 数据区或 CRC 不完整) payload, crc_recv data[:-2], data[-2:] calc struct.pack(H, crc16_modbus(head payload)) if crc_recv ! calc: raise ValueError(CRC 校验失败) return list(struct.unpack( H * (byte_count // 2), payload)) print(read_holding_rtu(COM3, slave1, start0, count2))这段代码的关键不在serial.Serial而在收包长度。正常响应是“地址 1 字节 功能码 1 字节 字节数 1 字节 数据 N 字节 CRC 2 字节”所以先读 2 字节判断是否异常再读字节数最后按字节数读满数据区和 CRC。timeout0.5控制单次读等待inter_byte_timeout0.01让字节之间断开时尽快返回避免 USB 转换器把一帧拖成几次读。CRC 初值 0xFFFF多项式 0xA001结果按低字节在前写入帧尾。struct.pack(H, crc)里的就是小端不要写成H。如果 CRC 一直错先确认你算的是“地址 功能码 起始地址 数量”这 6 个字节不包括 CRC 本身。3.3 TCP 最小主站MBAP 封包与 recv 循环TCP 侧最容易写错的是“只收一次”。下面这个函数先读 7 字节 MBAP 头再按长度字段读满 PDU。它适合做控件包协议层的回归测试也适合在没有示例源码时快速验证网关。import socket import struct def recv_exact(sock: socket.socket, n: int) - bytes: buf b while len(buf) n: chunk sock.recv(n - len(buf)) if not chunk: raise ConnectionError(连接被对端关闭) buf chunk return buf def read_holding_tcp(host: str, port: int, unit: int, start: int, count: int, timeout: float 1.0) - list[int]: trans_id 0x0001 pdu struct.pack(BHH, 0x03, start, count) # MBAP事务号 2B 协议号 2B 长度 2B 单元号 1B # 长度字段 单元号 1B PDU 长度 mbap struct.pack(HHHB, trans_id, 0, len(pdu) 1, unit) with socket.create_connection((host, port), timeouttimeout) as sock: sock.sendall(mbap pdu) head recv_exact(sock, 7) tid, pid, length, uid struct.unpack(HHHB, head) if tid ! trans_id: raise ValueError(事务号不匹配) if pid ! 0: raise ValueError(协议号不为 0) body recv_exact(sock, length - 1) # 去掉已经读到的单元号 func body[0] if func 0x80: raise RuntimeError(fModbus 异常响应异常码{body[1]:02X}) byte_count body[1] if byte_count ! count * 2: raise ValueError(返回字节数与请求数量不一致) return list(struct.unpack( H * count, body[2:2 byte_count])) print(read_holding_tcp(192.168.1.10, 502, unit1, start0, count2))recv_exact是这段代码的核心。TCP 不保证一次recv返回完整消息可能只给半截 MBAP 头也可能把两个响应粘在一起。先读 7 字节头解析length再读length - 1字节才能把一条响应从字节流里切出来。trans_id用来匹配请求单连接串行请求时也要检查避免把上一次的迟到响应当成这一次的结果。如果网关后面挂的是 RTU 从站unit必须和网关配置的从站号一致。某些网关把单元号 0 或 255 用作广播或特殊用途读寄存器时不要随便填。端口不是 502 时先确认网关是否做了端口映射不要只改代码不改配置。3.4 示例源码的阅读顺序入口层、协议层、业务映射层带示例源码的控件包常见分层是入口层、协议层、业务映射层。入口层负责创建连接、传串口名或 IP、设置从站号和超时协议层负责组帧、CRC/MBAP、异常码解析业务映射层负责把寄存器地址、数据类型、缩放系数对应到业务变量。阅读时先找入口再跟到协议层最后看映射表不要一上来扎进工具类。第一步改三处串口名或 IP、从站号、起始地址。第二步只读一个保持寄存器确认返回值不是异常码。第三步再读连续两个寄存器验证字节序。第四步才跑示例里的批量采集。示例代码如果默认扫描很多地址先注释掉避免一启动就打到不存在的从站上拖长超时。如果示例里把协议层和业务层揉在一个文件里优先把“组帧/解帧”抽出来单独测。控件包是否好用不取决于示例界面多漂亮而取决于异常响应、超时、拆包、地址偏移这些边界有没有写清楚。4. 寄存器映射落地四类区、地址偏移与 32 位浮点的拼装规则Modbus 的寄存器表看起来简单真正落地时最容易错的是地址编号和数据拼装。手册上写 40001代码里到底填 0 还是 1两个 16 位寄存器拼成 32 位浮点先来的字是高字还是低字批量读 130 个寄存器为什么从站直接回异常。这些问题不解决控件包跑通了也采不到正确值。4.1 四类寄存器与功能码0x、1x、3x、4x 只是文档习惯Modbus 把数据分成四类区文档里常用 0x、1x、3x、4x 编号但线上传输的起始地址通常从 0 开始。四类区的读写能力和功能码不一样数据区文档常见编号功能码读写线上地址线圈0xxxx0x01 / 0x05 / 0x0F读写从 0 开始离散输入1xxxx0x02只读从 0 开始输入寄存器3xxxx0x04只读从 0 开始保持寄存器4xxxx0x03 / 0x06 / 0x10读写从 0 开始这里的 0x、1x、3x、4x 是文档编号习惯不是请求帧里的地址前缀。比如手册写“保持寄存器 40001”协议地址通常是 0写“40002”协议地址通常是 1。但现场确实有设备把 40001 映射到地址 1所以第一次对接不要批量猜先读单个寄存器试 0 和 1看哪个返回值合理。功能码也要对上。读线圈用 0x01读离散输入用 0x02读保持寄存器用 0x03读输入寄存器用 0x04写单线圈 0x05写单寄存器 0x06写多线圈 0x0F写多寄存器 0x10。用错功能码从站可能回 0x01 非法功能也可能直接不回具体看实现。批量上限要记住读保持寄存器一次最多 125 个读输入寄存器也是 125 个读线圈和离散输入一次最多 2000 个位写多寄存器一次最多 123 个写多线圈一次最多 1968 个位。控件包如果没做拆包业务层传 200 个寄存器就会吃异常码 0x03。4.2 32 位数据跨两个寄存器ABCD 与 CDAB 的转换代码32 位整数或浮点会占两个 16 位寄存器。常见字序有两种ABCD 表示高字在前CDAB 表示低字在前。比如浮点 1.0 的二进制是0x3F800000ABCD 顺序下寄存器是[0x3F80, 0x0000]CDAB 顺序下是[0x0000, 0x3F80]。读出来是 0、极小值或明显不合理的大数先换字序不要先怀疑传感器。import struct def regs_to_u32(regs: list[int], order: str CDAB) - int: # regs[0] 是线上先到的第一个 16 位寄存器 first, second regs[0] 0xFFFF, regs[1] 0xFFFF if order ABCD: # 高字在前first高字second低字 return (first 16) | second if order CDAB: # 低字在前first低字second高字 return (second 16) | first raise ValueError(只处理最常见的 ABCD / CDAB) def regs_to_f32(regs: list[int], order: str CDAB) - float: raw regs_to_u32(regs, order) return struct.unpack(f, raw.to_bytes(4, big))[0] # 1.0 的位模式是 0x3F800000CDAB 下低字 0x0000 先到 print(regs_to_f32([0x0000, 0x3F80], CDAB)) # 1.0 print(regs_to_f32([0x3F80, 0x0000], ABCD)) # 1.0这段代码只处理 ABCD 和 CDAB覆盖大多数设备。少数设备还会在寄存器内部交换字节出现 BADC 或 DCBA表现是数值完全乱掉。遇到这种情况先把原始两个寄存器打印成十六进制用已知值反推不要在主站里反复改缩放系数。缩放系数是工程单位换算字序是协议层问题两者不要混在一起。如果读的是 32 位有符号整数把regs_to_u32的结果按有符号解释即可如果是两个 16 位寄存器分别表示两个独立变量就不要拼成 32 位。先看手册的数据类型再看寄存器数量最后决定拼不拼。4.3 批量读写上限与地址偏移从站手册的 40001 到底填什么地址偏移是现场血泪经验最多的地方。手册写“4000140010”有的设备协议地址是 09有的设备是 110。判断方法不是猜而是做一次单寄存器读用起始地址 0 读 1 个如果返回异常码 0x02再用 1 试如果两个都成功但值不对检查是不是读错了数据区或功能码。批量读之前先确认首地址和数量。比如要读 4000140010 共 10 个寄存器协议地址从 0 开始就填start0, count10从 1 开始就填start1, count10。不要用“40001 偏移”直接算线上地址也不要把文档编号原样塞进请求帧。写寄存器时更要注意。写单寄存器 0x06 的报文里带的是完整 16 位值写多寄存器 0x10 先写起始地址和数量再写字节数最后写数据。字节数必须等于寄存器数量乘 2少一个字节从站就会回 0x03。浮点写入前先在本地按目标字序打包再拆成两个 16 位寄存器不要写一个寄存器再写另一个除非设备明确支持这种两步写入。5. 避坑与本文还有配套的精品资源点击获取