# modbus-tcp-playback

**Repository Path**: jerronliu/modbus-tcp-playback

## Basic Information

- **Project Name**: modbus-tcp-playback
- **Description**: Modbus TCP Playback - Industrial data replay via Modbus TCP protocol. Upload xlsx power data, map 4 channels to holding registers (FLOAT32), and replay with original timestamp timing. Web UI for control. Perfect for PLC/DCS/SCADA debugging and acceptance testing. 工控数据Modbus TCP回放系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ModbusTCP Playback — 工控 Modbus TCP 数据回放系统

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![pymodbus](https://img.shields.io/badge/pymodbus-3.13%2B-green)](https://github.com/pymodbus-dev/pymodbus)

将工业测量数据（xlsx/csv）按原始时间戳时序，通过 **Modbus TCP** 协议逐行回放到 Holding Register，用于 PLC/DCS/SCADA 系统的**调试、仿真和验收测试**。

## 能做什么

- 上传 xlsx 功率/电流/电压数据文件，自动识别测量列
- 4 通道 FLOAT32 寄存器映射，每通道地址独立可配
- 按原始时间戳的**相对时序**回放（第一行 t=0），精度 ~500ms
- Web 界面一键启动/停止，实时进度 + 寄存器值显示
- 回放结束后可选择：保持最后值 / 自动清零 / 设为指定值
- 任何 Modbus TCP 主站（PLC、SCADA、ModbusTool）均可实时读取

## 快速开始

```bash
git clone https://gitee.com/jerronliu/modbus-tcp-playback.git
cd modbus-tcp-playback

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 启动（Web 界面 + Modbus 服务器）
python app.py --modbus-port 5020 --web-port 8080
```

浏览器打开 `http://127.0.0.1:8080`，上传 xlsx → 点击 Start。

## 使用 ModbusTool 读取

| 参数 | 值 |
|------|-----|
| 协议 | Modbus TCP |
| IP | `127.0.0.1`（或服务器 LAN IP） |
| 端口 | `5020` |
| Device ID | `1` |
| 数据类型 | FLOAT32 (Big-Endian) |

**默认寄存器映射：**

| 通道 | Holding Register | 含义 |
|------|-----------------|------|
| Ch1 | 0-1 | 自定义（如 Urms1 电压） |
| Ch2 | 2-3 | 自定义（如 Irms1 电流） |
| Ch3 | 4-5 | 自定义（如 P1 功率） |
| Ch4 | 6-7 | 自定义（如 Wp1 电能） |

地址可通过 Web 界面自由配置。

## 项目结构

```
├── app.py               # 主入口：FastAPI + ModbusTcpServer + 回放引擎
├── playback_engine.py   # xlsx 解析 + asyncio 时序回放
├── register_codec.py    # FLOAT32 ↔ Modbus 寄存器编解码
├── modbus_server.py     # 独立 CSV 驱动的 Modbus TCP 服务器
├── templates/
│   └── index.html       # Web 控制界面
├── registers.csv        # CSV 寄存器配置示例
└── requirements.txt
```

## 命令行参数

```
python app.py --modbus-host 0.0.0.0 --modbus-port 5020 --web-host 127.0.0.1 --web-port 8080
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--modbus-host` | `127.0.0.1` | Modbus 绑定地址 |
| `--modbus-port` | `502` | Modbus 端口（<1024 需 root) |
| `--web-host` | `127.0.0.1` | Web 界面绑定地址 |
| `--web-port` | `8080` | Web 界面端口 |

## 支持的 xlsx 格式

自动检测以下列名（不区分大小写、忽略空格）：
- 时间戳列：包含 `H:M:S` 的列，格式 `YYYY-MM-DD HH:MM:SS CS`（CS = 厘秒）
- 数据列：`Urms1[V]`、`Irms1[A]`、`P1[W]`、`Wp1[Wh]`

其他列名可手动在下拉框中选择。

## API

| Method | Path | 说明 |
|--------|------|------|
| GET | `/` | Web 控制界面 |
| POST | `/api/upload` | 上传 xlsx 文件 |
| POST | `/api/start` | 启动回放 |
| POST | `/api/stop` | 停止回放 |
| GET | `/api/status` | 回放状态 |

## 依赖

- Python ≥ 3.10
- pymodbus ≥ 3.8
- FastAPI + uvicorn
- pandas + openpyxl

## 适用场景

- PLC/DCS 调试：用历史数据模拟传感器输入
- SCADA 验收测试：验证报警阈值和趋势显示
- 工业协议学习：理解 Modbus TCP FLOAT32 编码
- 数据重放分析：将录波数据按实际时序回放

## License

MIT © 2026 Jerron Liu