4. pymodbus库入门：同步客户端创建、连接与断开、读取保持寄存器（03功能码）示例

在工业物联网边缘网关的Modbus TCP通信调试中，pymodbus是Python生态中最成熟、最广泛使用的Modbus协议库。本章将聚焦于pymodbus的同步客户端模式，从创建客户端实例、建立TCP连接、执行03功能码读取保持寄存器，到安全断开连接，形成完整的通信闭环。

4.1 pymodbus同步客户端核心概念

pymodbus提供两种客户端模式：同步（Sync）和异步（Async）。在边缘网关场景中，同步模式因其代码简单、调试直观、资源占用可控，常用于数据采集频率固定、连接数量较少的工控节点。

4.2 创建同步客户端实例

使用 ModbusTcpClient 类创建同步客户端对象。构造函数需要指定目标设备的IP地址和端口号，可选参数包括超时时间、单元标识符（Unit ID）等。

from pymodbus.client import ModbusTcpClient

# 创建客户端实例
client = ModbusTcpClient(
    host='192.168.1.100',   # 目标PLC或网关IP
    port=502,                # Modbus TCP标准端口
    timeout=5,               # 通信超时（秒）
    retries=3,               # 失败重试次数
    retry_on_empty=True      # 空响应时自动重试
)

4.3 建立与断开TCP连接

连接管理是通信可靠性的基础。pymodbus同步客户端提供 connect() 和 close() 方法，分别用于建立和释放TCP连接。

# 建立连接
if client.connect():
    print("✅ Modbus TCP 连接成功")
    print(f"   - 目标: {client.host}:{client.port}")
    print(f"   - 超时: {client.timeout}s")
else:
    print("❌ 连接失败，请检查网络和设备状态")
    exit(1)

# ... 执行读写操作 ...

# 断开连接
client.close()
print("🔌 连接已安全关闭")

4.4 读取保持寄存器（03功能码）

03功能码用于读取从站设备中连续的保持寄存器数据。每个保持寄存器为16位（2字节），可存储整数、浮点数或状态字。pymodbus通过 read_holding_registers() 方法实现此功能。

# 读取保持寄存器示例
# 参数：address=起始地址, count=读取数量, unit=从站ID
response = client.read_holding_registers(
    address=0,      # 起始寄存器地址（0-based）
    count=10,       # 连续读取10个寄存器
    unit=1          # 从站单元标识符
)

# 检查响应是否成功
if not response.isError():
    # 获取寄存器值列表
    registers = response.registers
    print("📊 读取保持寄存器成功:")
    for i, value in enumerate(registers):
        print(f"   寄存器[{i}] = {value} (0x{value:04X})")
else:
    print(f"❌ 读取失败: {response}")

4.5 完整示例：边缘网关数据采集

以下是一个完整的边缘网关数据采集脚本，包含连接、读取、异常处理和断开连接的完整流程。

import time
from pymodbus.client import ModbusTcpClient
from pymodbus.exceptions import ModbusException

def collect_plc_data(host='192.168.1.100', port=502, unit_id=1):
    """采集PLC保持寄存器数据"""
    client = ModbusTcpClient(host=host, port=port, timeout=5)
    
    try:
        # 1. 建立连接
        if not client.connect():
            raise ConnectionError("无法连接到PLC")
        print(f"✅ 已连接到 {host}:{port}")
        
        # 2. 读取保持寄存器（地址0-9，共10个）
        response = client.read_holding_registers(
            address=0, count=10, unit=unit_id
        )
        
        if response.isError():
            raise ModbusException(f"Modbus错误: {response}")
        
        # 3. 解析数据
        registers = response.registers
        data = {
            'temperature': registers[0] / 10.0,  # 假设精度0.1
            'pressure':    registers[1] / 100.0,  # 假设精度0.01
            'flow_rate':   registers[2],
            'status_word': registers[3],
            'timestamp':   time.time()
        }
        
        print(f"📊 采集数据: {data}")
        return data
        
    except ModbusException as e:
        print(f"❌ Modbus通信异常: {e}")
        return None
    except ConnectionError as e:
        print(f"❌ 连接异常: {e}")
        return None
    except Exception as e:
        print(f"❌ 未知异常: {e}")
        return None
    finally:
        # 4. 安全断开连接
        client.close()
        print("🔌 连接已关闭")

# 执行采集
if __name__ == '__main__':
    result = collect_plc_data()
    if result:
        print("采集任务完成")
    else:
        print("采集任务失败")

4.6 常见错误与调试方法

通过启用pymodbus的调试日志，可以查看完整的Modbus请求/响应报文，快速定位通信问题：

import logging
logging.basicConfig()
logging.getLogger('pymodbus').setLevel(logging.DEBUG)

# 此时运行读取代码，控制台将输出：
# DEBUG:pymodbus:Transaction - SEND: ...
# DEBUG:pymodbus:Transaction - RECV: ...