Python实现Modbus RTU串口通信:上位机协议解析与数据封装
本文详细讲解如何使用Python及pyserial实现Modbus RTU上位机串口通信,包含底层报文帧结构分析、CRC16校验算法、请求帧组包封装、响应帧解包验证以及32位浮点数高低字节序解析等实用技术。
在工业自动化与智能测量领域,Modbus RTU 依托 RS-485 物理总线以结构紧凑、成本低廉及抗干扰能力强的特点,成为各类传感器、变频器及 PLC 的主流通信标准。Python 凭借丰富的生态,常常被选作开发测试工具或监控上位机的语言。许多开发者在开发过程中倾向直接调用高级黑盒库,但在面临非标设备调试、硬件字节倒序(Byte Swap)、分包粘包及通信性能调优时,往往因缺乏对协议底层的透彻理解而难于排查故障。本文从 Modbus RTU 物理帧结构切入,手把手使用 pyserial 与纯 Python 代码实现协议请求帧的数据封装、CRC16 校验计算、串口收发控制以及响应报文的完整解包与工程量还原。
一、Modbus RTU 报文帧结构与通信机理
Modbus RTU 通信建立在半双工的“一主多从”主从查询机制上:总线上同一时刻只允许一个上位机(Master)发起请求,对应地址的从机(Slave)在接收并核对正确后返回响应。RTU(Remote Terminal Unit)模式采用二进制编码,每个字节均为 8 位二进制数据,相比 ASCII 模式具备更高的数据传输密度。
一个标准的 Modbus RTU 报文帧由四个基础部分组成:
- 从站地址(Slave Address,1 字节):取值范围为
0x01至0xF7(1~247),0x00为广播地址。从机仅响应与自身地址匹配的请求。 - 功能码(Function Code,1 字节):告知从机需要执行的操作类型,常用如
0x03(读取保持寄存器)、0x04(读取输入寄存器)、0x06(写单个寄存器)、0x10(写多个寄存器)。 - 数据域(Data Field,N 字节):在请求帧中通常包含寄存器起始地址和操作长度;在响应帧中包含返回的字节计数值和具体寄存器数据。
- CRC16 校验码(2 字节):用于保证传输完整性的循环冗余校验码,遵循低字节在前(CRC Low)、高字节在后(CRC High)的特殊传输顺序。
在物理时序上,Modbus RTU 依靠静默时间(无数据传输的线路空闲时间)界定一帧的起始与结束。标准协议规定,帧间间隔至少需要 3.5 个字符传输时间(t3.5)。如果两个字节之间的间隔超过 1.5 个字符时间(t1.5),从机将认为产生帧不完整错误。在编写上位机程序时,虽然 PC 端操作系统无法保证微秒级实时性,但合理配置串口的读取超时时间(Timeout)并及时清空接收缓冲区,是规避粘包与脏数据的关键前提。
二、底层 CRC16 循环冗余校验算法实现
Modbus RTU 采用特定的 CRC-16 校验多项式(0xA001,即逆序的 0x8005)。每一笔发送或接收的报文中,除最后的两个 CRC 字节外,前序所有字节均须参与校验计算。校验码计算完成后,必须将 16 位的数值拆分为低字节与高字节,且低字节必须先于高字节发送。
下面给出完整的纯 Python 实现函数。函数既可返回 16 位整型,也可直接返回长度为 2 的 bytes 序列(已自动完成低前高后字节倒序):
def calculate_crc16(data: bytes) -> bytes:
"""
计算 Modbus RTU 报文的 CRC-16 校验码。
:param data: 待计算的原始字节序列(不含校验码自身)
:return: 长度为 2 的 bytes 对象,格式为 [CRC_Low, CRC_High]
"""
crc = 0xFFFF
for byte in data:
crc ^= byte
for _ in range(8):
if crc & 0x0001:
crc = (crc >> 1) ^ 0xA001
else:
crc >>= 1
# 转换为 2 字节,低字节在前,高字节在后
crc_low = crc & 0xFF
crc_high = (crc >> 8) & 0xFF
return bytes([crc_low, crc_high])
避坑提示:很多上位机刚上手时出现“从机无任何响应”或“通信返回 CRC Error”,百分之九十是由于在拼装报文时误将 crc_high 放在了前面。务必记住:网络传输大端居多,但 Modbus RTU 的 CRC16 字段是严格的小端传输(低字节先发)。
三、上位机数据封装(请求帧组包)
上位机向从机发送请求前,必须将业务参数(站号、操作寄存器地址、读写数量或具体数值)组织成符合规约的二进制字节流。在 Python 中,建议使用内置的 struct 模块进行二进制打包,既直观又不易出错。
1. 读取保持寄存器(功能码 0x03)组包
假设需要读取从机 1 号站中起始地址为 0x0000(对应 PLC 保持寄存器 40001)、连续 2 个寄存器的数据:
- 从机站号:
0x01(1 字节) - 功能码:
0x03(1 字节) - 起始地址:
0x0000(2 字节,大端模式>H) - 读取点数:
0x0002(2 字节,大端模式>H)
import struct
def pack_read_holding_registers(slave_id: int, start_address: int, count: int) -> bytes:
"""
封装 0x03 读取保持寄存器请求帧
"""
if not (1 <= slave_id <= 247):
raise ValueError("从机地址范围须为 1-247")
if not (1 <= count <= 125):
raise ValueError("单个请求读取寄存器数量不能超过 125")
# 打包 PDU (协议数据单元):>B B H H 表示大端无符号字符与无符号短整型
pdu = struct.pack(">BBHH", slave_id, 0x03, start_address, count)
# 计算并追加 CRC
crc = calculate_crc16(pdu)
return pdu + crc
2. 写入单个寄存器(功能码 0x06)组包
功能码 0x06 用于预置单个 16 位寄存器的值:
def pack_write_single_register(slave_id: int, address: int, value: int) -> bytes:
"""
封装 0x06 写单个保持寄存器请求帧
"""
pdu = struct.pack(">BBHH", slave_id, 0x06, address, value & 0xFFFF)
return pdu + calculate_crc16(pdu)
3. 写入多个寄存器(功能码 0x10)组包
写多个寄存器时,数据域除了起始地址和寄存器数量外,还必须附带数据字节数(Byte Count = 2 × 数量)以及各寄存器的具体内容:
def pack_write_multiple_registers(slave_id: int, start_address: int, values: list) -> bytes:
"""
封装 0x10 写多个保持寄存器请求帧
"""
count = len(values)
byte_count = count * 2
header = struct.pack(">BBHHB", slave_id, 0x10, start_address, count, byte_count)
# 逐个将数值打包为 2 字节大端短整型
data_bytes = b"".join(struct.pack(">H", v & 0xFFFF) for v in values)
pdu = header + data_bytes
return pdu + calculate_crc16(pdu)
四、上位机串口交互与响应协议解包
上位机向串口写入完整请求报文后,即进入监听与解包流程。从硬件物理交互到业务对象还原,需要依次经过状态流转与校验核对。
1. 响应帧解析三步法
接收到从机响应报文后,严谨的解析器必须按序完成以下三项校验:
- CRC 校验核对:将接收到的报文除去末尾两字节,重新运行
calculate_crc16。若重算结果与帧末尾的接收 CRC 不一致,说明总线受到电磁干扰或发生字节截断,必须直接丢弃并记录校验错误。 - 从站号与功能码比对:接收报文的从站号须与请求站号一致。
- 从机异常应答处理:当从机无法执行上位机指令时(例如访问了不存在的寄存器),从机会将功能码的最高位置 1(即
原功能码 + 0x80),并在数据域返回 1 字节的异常码(Exception Code)。例如,请求0x03发生错误时,返回功能码为0x83。
| 异常码 | 标准名称 | 工业含义与产生原因 |
|---|---|---|
0x01 |
Illegal Function | 从机不支持当前功能码(例如从机只支持读,上位机发送了写指令) |
0x02 |
Illegal Data Address | 寄存器起始地址超出从机分配范围,或地址与数量组合越界 |
0x03 |
Illegal Data Value | 请求数据域中的数值不符合从机规定(如写入超出量程的数值) |
0x04 |
Slave Device Failure | 从机硬件故障,内部执行处理失败 |
2. 常见数据格式与字节序转换(浮点数与整型)
Modbus 协议规范只定义了 16 位的寄存器单元。但在工业现场,传感器温度、压力、电量往往采用 32 位单精度浮点数(IEEE-754 标准)或 32 位双字整型表示,这就需要占用两个连续的保持寄存器(共 4 字节)。
由于各 PLC 和仪表厂家的实现差异,4 字节在两个寄存器中的存储顺序存在四种常见格式:
- Big-Endian(ABCD):大端模式,高字在前,字内高字节在前(常见于西门子、施耐德部分型号)。
- Little-Endian(DCBA):小端模式,低字在前,字内低字节在前。
- Word Swap / Big-Endian Byte Swap(CDAB):双字节字反转,最常见于各类工业智能仪表。
- Byte Swap(BADC):单字内字节反转,字高低不变。
使用 Python 的 struct 模块,可以非常灵活高效地处理上述四种字节顺序:
import struct
def parse_modbus_float(raw_4bytes: bytes, byte_order: str = "CDAB") -> float:
"""
将 Modbus 连续两个寄存器读取到的 4 字节二进制还原为 32 位浮点数
:param raw_4bytes: 长度为 4 的原始 bytes
:param byte_order: ABCD, CDAB, BADC, DCBA 四种排列方式
:return: 浮点数值
"""
if len(raw_4bytes) != 4:
raise ValueError("输入数据必须严格为 4 字节")
b0, b1, b2, b3 = raw_4bytes[0], raw_4bytes[1], raw_4bytes[2], raw_4bytes[3]
if byte_order == "ABCD":
ordered = bytes([b0, b1, b2, b3])
elif byte_order == "CDAB":
# 常见于各类工业仪表 (Word Swap)
ordered = bytes([b2, b3, b0, b1])
elif byte_order == "BADC":
ordered = bytes([b1, b0, b3, b2])
elif byte_order == "DCBA":
ordered = bytes([b3, b2, b1, b0])
else:
raise ValueError(f"不支持的字节序: {byte_order}")
# 以标准大端格式解包为 IEEE-754 32 位单精度浮点数
return struct.unpack(">f", ordered)[0]
五、完整可运行的上位机通信驱动类
结合前面讨论的帧结构组包、CRC16 校验以及解包流程,我们可以封装一个高可靠的 ModbusRTUMaster 上位机驱动类。该类使用 pyserial 管理底层硬件串口通信,提供自动重试、超时保护及常用读写功能接口。
import time
import struct
import serial
class ModbusRTUMaster:
"""
轻量级原生 Python Modbus RTU 上位机通信驱动
"""
def __init__(self, port: str, baudrate: int = 9600, timeout: float = 1.0):
"""
初始化串口参数
:param port: 串口号,Windows如 'COM3', Linux/macOS如 '/dev/ttyUSB0'
:param baudrate: 波特率,默认 9600
:param timeout: 读超时时间,单位秒
"""
self.ser = serial.Serial(
port=port,
baudrate=baudrate,
bytesize=serial.EIGHTBITS,
parity=serial.PARITY_NONE,
stopbits=serial.STOPBITS_ONE,
timeout=timeout
)
def close(self):
"""关闭串口"""
if self.ser.is_open:
self.ser.close()
@staticmethod
def crc16(data: bytes) -> bytes:
"""Modbus CRC-16 计算,返回 [Low, High]"""
crc = 0xFFFF
for b in data:
crc ^= b
for _ in range(8):
if crc & 1:
crc = (crc >> 1) ^ 0xA001
else:
crc >>= 1
return bytes([crc & 0xFF, (crc >> 8) & 0xFF])
def _send_and_receive(self, request_frame: bytes, expected_min_len: int) -> bytes:
"""底层收发控制:清理缓冲、发送数据、阻塞并收取响应"""
# 1. 彻底清空可能残留的无用数据
self.ser.reset_input_buffer()
self.ser.reset_output_buffer()
# 2. 发送请求报文
self.ser.write(request_frame)
self.ser.flush()
# 3. 读取响应头前 3 字节 (站号, 功能码, 字节数/异常码)
header = self.ser.read(3)
if len(header) < 3:
raise TimeoutError("从机响应超时或未连接")
slave_id, func_code, third_byte = header[0], header[1], header[2]
# 4. 判断是否为异常响应 (功能码最高位置1)
if func_code & 0x80:
crc_err = self.ser.read(2)
full_err_frame = header + crc_err
if self.crc16(full_err_frame[:-2]) != full_err_frame[-2:]:
raise ValueError("从机异常响应帧 CRC 校验失败")
raise RuntimeError(f"从机返回异常应答: 原始功能码 0x{func_code & 0x7F:02X}, 异常码 0x{third_byte:02X}")
# 5. 正常应答:根据功能码计算剩余应读字节长度
if func_code in (0x03, 0x04):
# 读操作:third_byte 为数据字节计数 Byte Count
remaining_len = third_byte + 2 # 数据域 + 2字节CRC
body_and_crc = self.ser.read(remaining_len)
full_frame = header + body_and_crc
elif func_code in (0x06, 0x10):
# 写操作响应固定为 8 字节,前面已读 3 字节,还需读 5 字节
remaining_len = 5
body_and_crc = self.ser.read(remaining_len)
full_frame = header + body_and_crc
else:
raise NotImplementedError(f"暂未实现功能码 0x{func_code:02X} 的接收解析")
# 6. CRC 完整性验证
if len(full_frame) < expected_min_len:
raise ValueError(f"接收报文截断,预期至少 {expected_min_len} 字节,实收 {len(full_frame)} 字节")
payload, recv_crc = full_frame[:-2], full_frame[-2:]
if self.crc16(payload) != recv_crc:
raise ValueError(f"CRC 校验错误: 计算值 {self.crc16(payload).hex()} != 接收值 {recv_crc.hex()}")
return full_frame
def read_holding_registers(self, slave_id: int, start_addr: int, count: int) -> list:
"""
功能码 0x03:读取保持寄存器
:return: 包含 16 位无符号整数的列表
"""
# 组装请求帧
pdu = struct.pack(">BBHH", slave_id, 0x03, start_addr, count)
request = pdu + self.crc16(pdu)
# 期望最小长度:站号(1) + 功能码(1) + 字节数(1) + 2*count + CRC(2)
expected_len = 5 + 2 * count
response = self._send_and_receive(request, expected_len)
# 提取数据段并解析为 16 位寄存器数组
data_bytes = response[3:-2]
registers = [struct.unpack(">H", data_bytes[i:i+2])[0] for i in range(0, len(data_bytes), 2)]
return registers
def write_single_register(self, slave_id: int, addr: int, value: int) -> bool:
"""
功能码 0x06:写入单个保持寄存器
"""
pdu = struct.pack(">BBHH", slave_id, 0x06, addr, value & 0xFFFF)
request = pdu + self.crc16(pdu)
response = self._send_and_receive(request, 8)
# 成功时响应帧应与请求帧完全一致
return response == request
调用示例与实战验证
以下示例展示如何利用上述驱动读取某工业传感器中 1 号站的温度与湿度。假设设备手册标明:寄存器起始地址为 0x0000,连续读取 2 个寄存器(分别代表温度与湿度,值扩大 10 倍存储为无符号整数):
if __name__ == "__main__":
# 根据实际运行环境调整串口名称
PORT_NAME = "COM3" # Linux下例如 "/dev/ttyUSB0"
try:
master = ModbusRTUMaster(port=PORT_NAME, baudrate=9600, timeout=1.0)
print(f"成功打开串口: {PORT_NAME}")
# 读取 1 号从机 0x0000 起始的 2 个寄存器
regs = master.read_holding_registers(slave_id=1, start_addr=0x0000, count=2)
raw_temp, raw_humi = regs[0], regs[1]
temperature = raw_temp / 10.0
humidity = raw_humi / 10.0
print(f"读取成功 -> 环境温度: {temperature:.1f} °C, 相对湿度: {humidity:.1f} %RH")
# 写入 1 号从机报警阈值 (寄存器 0x000A) 为 500 (即 50.0 度)
success = master.write_single_register(slave_id=1, addr=0x000A, value=500)
if success:
print("写入报警阈值成功")
except Exception as err:
print(f"通信发生错误: {err}")
finally:
master.close()
六、Modbus RTU 上位机开发核心要素与故障排查矩阵
在现场工程部署与调试过程中,通信异常往往由硬件电气特性、底层驱动及软件时序交叉引发。掌握系统性的排障路径,能极大缩短上位机联调时间。
通过掌握底层帧结构、编写精准的 CRC 校验机制以及利用 struct 模块进行结构化数据打包,上位机不再依赖沉重的第三方集成黑盒,不仅能更敏锐地捕捉和定位偶发性工业总线通信故障,也为后续开发定制化工业物联网网关、现场自动化检测工装及仪器仪表测试平台奠定了扎实的代码基石。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













