iotechsys/pymodbus-sim

Python Modbus SIM 镜像文档

镜像概述

Python Modbus SIM是一个轻量级的Modbus协议模拟器，基于Python语言开发，旨在为Modbus主站应用的开发、测试和调试提供模拟环境。该镜像可模拟Modbus从站设备，支持Modbus TCP和RTU两种通信模式，允许用户自定义寄存器配置和数据模拟规则，帮助开发者在无真实硬件的情况下验证主站通信逻辑。

核心功能与特性

• 多协议支持：兼容Modbus TCP和RTU协议，满足不同网络环境需求
• 全类型寄存器模拟：支持Modbus标准寄存器类型，包括：
  • 线圈（Coils，读/写）
  • 离散输入（Discrete Inputs，只读）
  • 保持寄存器（Holding Registers，读/写）
  • 输入寄存器（Input Registers，只读）
• 自定义数据配置：支持通过配置文件定义寄存器初始值、数据变化规则（固定值、随机值、递增/递减序列）
• 多客户端并发：支持多个Modbus主站客户端同时连接，模拟真实环境中的多设备通信场景
• 实时数据更新：可配置寄存器数据动态更新频率，模拟设备状态变化
• 轻量级部署：基于Alpine Linux构建，镜像体积小，资源占用低

使用场景

• Modbus主站应用开发：在无真实从站设备时，验证主站读写逻辑
• 通信协议调试：排查Modbus数据帧格式、地址映射、错误处理等问题
• 自动化测试环境：集成到CI/CD流程，实现Modbus通信功能的自动化测试
• 培训与教学：为Modbus协议学习提供安全、可控的实验环境
• 设备兼容性验证：模拟不同厂商从站设备的寄存器布局，验证主站兼容性

使用方法

基本部署（Docker Run）

bash
# Modbus TCP模式示例
docker run -d \
  --name modbus-sim-tcp \
  -p 502:502 \
  -e MODBUS_PROTOCOL=TCP \
  -e MODBUS_SLAVE_ID=1 \
  -e TCP_PORT=502 \
  docker.xuanyuan.run/python-modbus-sim:latest

# Modbus RTU模式示例（需挂载串口设备）
docker run -d \
  --name modbus-sim-rtu \
  --device=/dev/ttyUSB0:/dev/ttyUSB0 \
  -e MODBUS_PROTOCOL=RTU \
  -e MODBUS_SLAVE_ID=1 \
  -e RTU_PORT=/dev/ttyUSB0 \
  -e RTU_BAUDRATE=9600 \
  -e RTU_PARITY=N \
  -e RTU_STOPBITS=1 \
  docker.xuanyuan.run/python-modbus-sim:latest

环境变量配置

自定义寄存器配置

通过挂载配置文件自定义寄存器初始值和数据规则，配置文件为JSON格式，示例如下：

json
{
  "coils": {
    "0": {"value": true, "mode": "fixed"},          // 线圈0，固定值true
    "1-5": {"value": false, "mode": "random"},       // 线圈1-5，随机值
    "6": {"value": 0, "mode": "toggle", "interval": 2} // 线圈6，每2秒翻转一次
  },
  "discrete_inputs": {
    "0-3": {"value": true, "mode": "fixed"}          // 离散输入0-3，固定值true
  },
  "holding_registers": {
    "0": {"value": 1234, "mode": "fixed"},           // 保持寄存器0，固定值1234
    "1": {"value": 0, "mode": "increment", "step": 1, "max": 100}, // 从0开始递增，步长1，最大值100
    "2-5": {"value": 0, "mode": "random", "min": 0, "max": 65535} // 保持寄存器2-5，0-65535随机值
  },
  "input_registers": {
    "0": {"value": 5678, "mode": "fixed"},           // 输入寄存器0，固定值5678
    "1": {"value": 200, "mode": "decrement", "step": 5, "min": 0} // 从200开始递减，步长5，最小值0
  }
}

挂载配置文件启动容器：

bash
docker run -d \
  --name modbus-sim-custom \
  -p 502:502 \
  -e MODBUS_PROTOCOL=TCP \
  -v /host/path/to/config.json:/app/config.json \
  docker.xuanyuan.run/python-modbus-sim:latest

数据模式说明

配置文件中mode字段支持以下数据生成模式：

• fixed：固定值，保持value字段设定值
• random：随机值，需配合min/max（数值类型）或无参数（布尔类型）
• increment：递增模式，需配合step（步长）和max（最大值，到达后重置）
• decrement：递减模式，需配合step（步长）和min（最小值，到达后重置）
• toggle：翻转模式（仅布尔类型），按interval间隔切换true/false

日志查看

bash
# 实时查看日志
docker logs -f modbus-sim-tcp

# 查看历史日志
docker logs modbus-sim-tcp

注意事项

• TCP模式下需确保宿主机端口未被占用，如默认502端口可能被系统服务占用，可通过TCP_PORT环境变量修改
• RTU模式需宿主机具备串口设备，并通过--device参数正确挂载
• 配置文件格式错误会导致容器启动失败，建议启动前验证JSON格式有效性
• 高并发场景下建议调整宿主机内核参数（如TCP连接数限制）以优化性能