# modbusmaster-pro

**Repository Path**: c7ys/modbusmaster-pro

## Basic Information

- **Project Name**: modbusmaster-pro
- **Description**: 一个全平台使用的modbus调试工具，c++开发。
- **Primary Language**: Unknown
- **License**: LGPL-2.1
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-12
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ModbusMaster - RTU/TCP调试工具

一个基于 Qt 的 Modbus 调试工具，支持模拟设备、真实串口(RTU)和TCP连接。

## 功能特性

- ✅ 支持模拟设备测试
- ✅ 支持真实串口通信 (RTU 模式)
- ✅ 支持 TCP/IP 网络通信 (TCP 模式)
- ✅ 支持 10 种常用 Modbus 功能码
- ✅ 自动轮询功能
- ✅ 自定义命令发送
- ✅ 实时通信日志
- ✅ 寄存器数据表格显示和编辑
- ✅ 智能参数配置（根据功能码自动调整）

## 支持的功能码

| 功能码 | 名称 | 描述 |
|--------|------|------|
| 01 | 读线圈 | 读取线圈的 ON/OFF 状态 |
| 02 | 读离散输入 | 读取离散输入状态 |
| 03 | 读保持寄存器 | 读取保持寄存器值 |
| 04 | 读输入寄存器 | 读取输入寄存器值 |
| 05 | 写单个线圈 | 写入单个线圈状态 |
| 06 | 写单个寄存器 | 写入单个寄存器值 |
| 0F | 写多个线圈 | 写入多个线圈状态 |
| 10 | 写多个寄存器 | 写入多个寄存器值 |
| 16 | 掩码写寄存器 | 对寄存器进行位操作 |
| 17 | 读写寄存器 | 同时读取和写入寄存器 |

## 编译要求

- CMake 3.28+
- C++20
- Qt6 (Core, SerialPort, Network, Widgets)

## 安装依赖

### Ubuntu/Debian
```bash
sudo apt update
sudo apt install qt6-base-dev qt6-serialport-dev qt6-network-dev build-essential cmake
```

### Fedora/RHEL
```bash
sudo dnf install qt6-qtbase-devel qt6-qtserialport-devel cmake gcc-c++
```

### Arch Linux
```bash
sudo pacman -S qt6-base qt6-serialport cmake gcc
```

### Windows
- 使用 Qt Online Installer 安装 Qt6
- 确保安装了 Qt SerialPort 模块

### macOS
```bash
brew install qt@6 cmake
```

## 编译步骤

```bash
mkdir build
cd build
cmake ..
make
```

或者使用 CLion 直接打开项目并编译。

## 运行

```bash
cd build
./modbusmaster-pro
```

## 使用说明

### 模拟设备模式 (默认)

1. 启动程序后自动连接到模拟设备
2. 选择功能码 (默认: 03 读保持寄存器)
3. 设置起始地址和寄存器数量
4. 点击"发送请求"发送单次请求
5. 点击"开始轮询"进行连续轮询

**特殊功能码说明：**
- 功能码 05 (写单个线圈)：使用"写入值"参数而非"寄存器数量"
- 功能码 06 (写单个寄存器)：使用"写入值"参数而非"寄存器数量"
- 选择这些功能码时，"寄存器数量"输入框会自动隐藏，"写入值"输入框会自动显示

### 串口连接模式 (RTU)

1. 在"连接方式"下拉框选择"串口连接"
2. 点击"刷新"按钮检测可用串口
3. 选择串口设备
4. 设置波特率 (默认: 9600)
5. 设置数据位、停止位、校验位
6. 点击"连接设备"
7. 配置参数并发送请求

### TCP 连接模式

1. 在"连接方式"下拉框选择"TCP连接"
2. 输入目标设备的 IP 地址 (如: 192.168.1.100)
3. 设置端口号 (默认: 502，Modbus TCP 标准端口)
4. 设置从站地址 (Unit Identifier)
5. 点击"连接设备"
6. 配置参数并发送请求

**注意**：TCP 模式下的"从站地址"对应 Modbus TCP 协议中的 Unit Identifier 字段，通常用于网关场景。对于直接连接的 TCP 设备，通常设置为 1。

### 寄存器编辑

- 双击表格中的值列可以编辑寄存器值
- 仅保持寄存器和线圈支持编辑

### 自定义命令

- 在底部输入框输入十六进制格式的 Modbus 命令
- 例如: `01 03 00 00 00 0A C5 CD`
- 点击"发送自定义命令"

## Linux 串口权限

如果遇到串口权限问题，请运行:

```bash
sudo usermod -a -G dialout $USER
```

然后注销并重新登录。

## 使用示例

### TCP 连接示例

假设有一个 Modbus TCP 设备 IP 为 `192.168.1.100`，端口 `502`：

1. 选择 "TCP连接" 模式
2. 输入 IP 地址: `192.168.1.100`
3. 端口保持默认: `502`
4. 从站地址设置为: `1`
5. 点击 "连接设备"
6. 功能码选择: `03` (读保持寄存器)
7. 起始地址: `0`
8. 寄存器数量: `10`
9. 点击 "发送请求" 或 "开始轮询"

### RTU 连接示例

假设有一个 Modbus RTU 设备连接在 `/dev/ttyUSB0`，波特率 `9600`：

1. 选择 "串口连接" 模式
2. 点击 "刷新" 找到 `/dev/ttyUSB0`
3. 选择串口: `/dev/ttyUSB0`
4. 波特率: `9600`
5. 数据位: `8`，停止位: `1`，校验位: `无`
6. 从站地址: `1`
7. 点击 "连接设备"
8. 配置参数并发送请求

## 自定义命令示例

### TCP 自定义命令 (十六进制)
```
00 01 00 00 00 06 01 03 00 00 00 0A
```
解析：
- `00 01`: 事务标识符
- `00 00`: 协议标识符 (Modbus)
- `00 06`: 长度 (6字节后续数据)
- `01`: 单元标识符 (从站地址)
- `03`: 功能码 (读保持寄存器)
- `00 00`: 起始地址 0
- `00 0A`: 寄存器数量 10

### RTU 自定义命令 (十六进制)
```
01 03 00 00 00 0A C5 CD
```
解析：
- `01`: 从站地址
- `03`: 功能码 (读保持寄存器)
- `00 00`: 起始地址 0
- `00 0A`: 寄存器数量 10
- `C5 CD`: CRC16 校验码

## 常见问题

### Q: TCP 连接失败，提示"连接被拒绝"
A: 检查：
1. IP 地址是否正确
2. 设备是否开机并连接到网络
3. 端口号是否正确 (Modbus TCP 默认 502)
4. 防火墙是否阻止连接

### Q: 串口连接失败，提示"权限不足"
A: 运行以下命令添加串口权限：
```bash
sudo usermod -a -G dialout $USER
```
然后注销并重新登录。

### Q: 收到"非法功能码"错误
A: 检查：
1. 目标设备是否支持该功能码
2. 设备的 Modbus 协议实现是否完整

### Q: TCP 模式下从站地址应该设置什么？
A: 对于直接连接的 Modbus TCP 设备，通常设置为 `1`。对于通过网关连接的 RTU 设备，从站地址应为实际的 RTU 从站地址。

### Q: RTU 和 TCP 模式可以同时使用吗？
A: 不可以，同一时间只能使用一种连接方式。选择连接方式后，对应的配置项会自动启用/禁用。

## 项目结构

```
modbusmaster-pro/
├── main.cpp              # 主窗口和UI
├── ModbusManager.h       # Modbus管理器头文件
├── ModbusManager.cpp     # Modbus管理器实现（支持RTU和TCP）
├── CMakeLists.txt        # CMake构建配置
├── README.md             # 本文档
└── resources.qrc         # Qt资源文件
```

## 技术栈

- **Qt Framework**: 跨平台GUI框架
- **Qt SerialPort**: 串口通信 (RTU模式)
- **Qt Network**: TCP/IP网络通信 (TCP模式)
- **CMake**: 构建系统
- **C++20**: 编程语言

## Modbus 协议支持

### Modbus RTU (Remote Terminal Unit)
- 传输方式：串口 (RS-232, RS-485)
- 帧格式：从站地址 + 功能码 + 数据 + CRC校验
- 优点：实时性好，适合工业现场
- 缺点：点对点通信，布线复杂

### Modbus TCP (Transmission Control Protocol)
- 传输方式：TCP/IP网络
- 帧格式：MBAP头(7字节) + PDU(功能码+数据)
- MBAP头结构：
  - 事务标识符 (2字节)：请求/响应匹配
  - 协议标识符 (2字节)：Modbus协议为0
  - 长度 (2字节)：后续字节数
  - 单元标识符 (1字节)：从站地址
- 优点：支持以太网，速度快，布线简单
- 缺点：实时性略低于RTU

## TCP 和 RTU 的区别

| 特性 | RTU | TCP |
|------|-----|-----|
| 传输层 | 串口 | TCP/IP |
| 帧头 | 从站地址(1字节) | MBAP头(7字节) |
| 校验 | CRC校验(2字节) | TCP协议保证，无需CRC |
| 网络拓扑 | 点对点 | 星形/总线形 |
| 最大距离 | 取决于串口 | 以太网范围 |
| 最大速率 | 115200 bps | 100 Mbps+ |
| 适用场景 | 本地设备、工业现场 | 远程控制、以太网环境 |

## 许可证

本项目仅供学习和参考使用。