# modbus-studio

**Repository Path**: Susan001/modbus-studio

## Basic Information

- **Project Name**: modbus-studio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Modbus Studio

一个面向工程调试场景的 Modbus RTU / Modbus TCP Client + Server 桌面工具。

![Modbus Studio 界面预览](image/a9a44842-7b27-4651-ab8f-f82f5e49a07d%20(1).png)

## 项目状态

- 当前版本：V1.1.3
- 运行平台：Windows
- 技术栈：Electron、Vue 3、Vuex、TypeScript、Element Plus
- 开源协议：MIT

## 快速开始

下载或打包后运行：

```text
Modbus Studio\Modbus Studio.exe
```

开发、构建和打包命令见 [DEVELOPMENT.md](DEVELOPMENT.md)。

## 1. 软件用途

Modbus Studio 是一个用于 Modbus RTU / Modbus TCP 调试的桌面工具，主要用于：

- 作为 Client 连接真实设备并读取、写入点位。
- 作为 Server 模拟从站，供其他主站软件或设备读取、写入。
- 使用寄存器字典统一管理地址、名称、数据类型、倍率、单位、权限和备注。
- 保存工程文件，恢复 Client 数据、Server 数据、寄存器字典、连接配置和报文日志。

## 2. 为什么要做这个软件

在日常上位机、控制器、传感器和 PLC 调试中，很多工程师会使用 Modbus Poll 和 Modbus Slave 这类工具。它们很经典，也很稳定，但在实际项目交付和反复联调时，会遇到一些不方便的地方。

### 2.1 Modbus Poll 的常见问题

Modbus Poll 适合快速读取某一段寄存器，但它更偏“地址段调试”，不是“工程点位调试”。项目点位多了以后，常见问题包括：

- 点位含义需要额外查表，地址 `40001` 到底是什么变量、单位是什么、倍率是多少，不在工具里形成统一上下文。
- 多种数据类型需要人工切换或手动换算，例如 `UINT16`、`INT16`、`FLOAT_ABCD`、倍率 `0.1` 等，容易算错。
- 每次调试不同设备时，都要重新配置功能码、起始地址、数量和显示格式。
- 读取和写入更关注原始寄存器，不够贴近“温度、压力、状态、设定值”这类工程变量。
- 工程资料、报文日志、点位说明通常散落在 Excel、截图、聊天记录和测试记录中，后续复现困难。

### 2.2 Modbus Slave 的常见问题

Modbus Slave 适合临时模拟从站，但它通常更关注四个数据区本身，而不是项目字典。实际模拟设备时会遇到：

- Server 模拟数据和 Client 读取点位往往需要分别配置，两个工具之间不能自然复用同一份点位表。
- 模拟保持寄存器、输入寄存器、线圈、离散输入时，点位名称、单位、倍率和备注不够直观。
- 外部主站写入后，虽然寄存器值变化了，但不容易直接看出对应的是哪个业务变量。
- 项目切换后，模拟数据、连接参数和点位说明不容易完整恢复。
- Client 调试和 Server 仿真分属两个工具，报文日志、工程配置和测试状态无法统一管理。

### 2.3 Modbus Studio 要解决什么

Modbus Studio 的目标不是简单复制 Modbus Poll 或 Modbus Slave，而是把常见 Modbus 调试过程整理成一个完整工程：

- 用一份“寄存器字典”同时驱动 Client 和 Server。
- Client 只读取字典里定义的点位，不读无关地址。
- Server 只模拟字典里定义的点位，不生成无意义的固定地址表。
- 每个点位都有地址、名称、数据类型、长度、读写权限、倍率、单位和备注。
- 原始 HEX 和工程解析值同时显示，写入解析值时自动反算为设备原始值。
- TCP / RTU Client、TCP / RTU Server、报文日志和工程管理放在同一个软件里。
- 工程文件可以保存连接配置、Client 数据、Server 数据、寄存器字典和报文日志，方便下次继续调试或交付给同事。

简单来说，Modbus Poll 和 Modbus Slave 更像“协议调试工具”，而 Modbus Studio 更想做成“项目调试工作台”。它让一次调试留下完整的工程上下文，而不是只留下几个临时地址和一堆零散截图。

## 3. 基本使用流程

推荐按以下顺序使用：

1. 在“寄存器字典”中配置点位。
2. 在“Client”中连接设备，软件会按字典自动循环读取。
3. 如需模拟从站，在“Server”中按同一份字典配置数据并启动服务。
4. 在“报文日志”中查看 TX/RX 原始报文和解析结果。
5. 在“工程管理”中保存为 `.mbs` 工程文件。

## 4. 寄存器字典

寄存器字典是软件的核心。Client 和 Server 都会根据字典中的地址和长度工作，不会读取或显示字典之外的点位。

![寄存器字典视图](image/637e6fa3-892f-444e-9405-574f7d1942a3.png)

### 4.1 字典字段说明

| 字段 | 说明 |
| --- | --- |
| 分组 | 用于分类点位，例如“温度传感器”“系统状态”。 |
| 地址 | Modbus 显示地址，例如 `40001`。 |
| 名称 | 点位名称，例如“设定温度”。 |
| 数据类型 | 解析原始值时使用的数据格式。 |
| 长度 | 占用的 16 位寄存器数量，位区通常为 1。 |
| 读写权限 | `R` 只读、`W` 只写、`RW` 读写。 |
| 比例因子 | 用于工程值换算。 |
| 单位 | 显示单位，例如 `℃`、`kPa`、`%`。 |
| 备注 | 点位用途、范围或调试说明。 |

### 4.2 地址范围

| 地址范围 | Modbus 区域 | Client 行为 | Server 行为 |
| --- | --- | --- | --- |
| `00001` - `09999` | 线圈 Coil | 可读取，可写线圈 | 可模拟，可切换开关值 |
| `10001` - `19999` | 离散输入 Discrete Input | 可读取，只读 | 可模拟，只读区 |
| `30001` - `39999` | 输入寄存器 Input Register | 可读取，只读 | 可模拟寄存器值 |
| `40001` - `49999` | 保持寄存器 Holding Register | 可读取，可写寄存器 | 可模拟寄存器值 |

说明：界面中填写的是常见 Modbus 显示地址，协议报文会自动转换为零基地址。例如 `40001` 会转换为协议地址 `0`。

### 4.3 数据类型

支持的数据类型：

- `UINT16`
- `INT16`
- `UINT32`
- `INT32`
- `FLOAT_ABCD`
- `FLOAT_CDAB`
- `FLOAT_BADC`
- `FLOAT_DCBA`
- `BCD`
- `BIT`

选择数据类型后，软件会自动给出推荐长度，用户也可以手动修改。

### 4.4 比例因子

界面显示的解析值与设备原始值之间按比例因子换算：

```text
解析值 = 原始值 × 比例因子
原始值 = 解析值 ÷ 比例因子
```

示例：

| 原始值 | 比例因子 | 界面解析值 |
| --- | --- | --- |
| `250` | `0.1` | `25` |
| `1234` | `0.01` | `12.34` |

写入“解析值”时，软件会自动反算为原始寄存器值再发送。

## 5. Client 使用

Client 页面用于连接真实 Modbus 设备。

![Client 视图](image/9916707d-9dee-408d-bb40-cac55858d7bc%20(1).png)

### 5.1 连接 RTU 设备

1. 在左侧“连接配置”选择协议类型为 `Modbus RTU`。
2. 点击“刷新”获取串口列表。
3. 选择端口、波特率、数据位、停止位、校验位和超时时间。
4. 点击“连接 RTU”。
5. 连接成功后，状态会显示为已连接。

### 5.2 连接 TCP 设备

1. 在左侧“连接配置”选择协议类型为 `Modbus TCP`。
2. 输入主机地址，例如 `127.0.0.1`。
3. 输入端口，例如 `502`。
4. 设置超时时间。
5. 点击“连接 TCP”。

### 5.3 自动读取

Client 不再依赖手动输入功能码、起始地址和数量。连接成功后，软件会根据寄存器字典自动循环读取：

- 线圈区使用 `01`。
- 离散输入区使用 `02`。
- 保持寄存器区使用 `03`。
- 输入寄存器区使用 `04`。

可在顶部设置“循环周期”，单位为毫秒。

### 5.4 合并读取

“合并读取”开启后，软件会尝试把相邻或接近的字典点位合并为较少的读取请求，减少报文数量。

适合：

- 点位地址连续。
- 设备支持一次读取较长寄存器数量。

如果设备对读取范围要求严格，或不允许读取未定义地址，可以关闭“合并读取”。

### 5.5 数据显示

Client 表格显示：

| 列名 | 说明 |
| --- | --- |
| 地址 | 字典中的显示地址。 |
| 名称 | 点位名称、数据类型和长度。 |
| 原始值 / 状态 | 寄存器显示 HEX，位区显示开关状态。 |
| 解析值 | 根据数据类型和比例因子计算后的值。 |
| 倍率/单位 | 当前点位的比例因子和单位。 |
| 权限 | `R`、`W` 或 `RW`。 |
| 备注 | 字典备注。 |

读取失败的行会高亮提示，方便定位某个地址或长度配置错误。

### 5.6 写入线圈

满足以下条件时可以写线圈：

- 地址在 `00001` - `09999`。
- 权限为 `W` 或 `RW`。
- 当前已经连接设备。

操作方法：

1. 在 Client 表格中找到线圈点位。
2. 点击“原始值 / 状态”列中的开关。
3. 软件会发送写线圈报文。

### 5.7 写入保持寄存器

满足以下条件时可以写保持寄存器：

- 地址在 `40001` - `49999`。
- 权限为 `W` 或 `RW`。
- 当前已经连接设备。

支持两种写入方式：

| 写入位置 | 说明 |
| --- | --- |
| 原始值 / 状态 | 输入 HEX 原始值，例如 `0064` 或 `0000 0064`。 |
| 解析值 | 输入工程值，软件按数据类型和比例因子自动编码。 |

输入完成并确认后，软件会立即写入设备。写入期间如果正在轮询，软件会短暂停止轮询，写入完成后再恢复。

## 6. Server 使用

Server 页面用于模拟 Modbus 从站。

![Server 视图](image/dc49edfa-2797-4e6e-b00c-08309d201ec4.png)

### 6.1 Server 数据来源

Server 不再生成固定地址表，而是完全根据寄存器字典显示数据。

如果某个区域为空，说明寄存器字典中没有该区域的地址。

### 6.2 启动 TCP Server

1. 进入“Server”页面。
2. 协议类型选择 `Modbus TCP`。
3. 设置监听地址，例如 `0.0.0.0`。
4. 设置监听端口，例如 `502`。
5. 点击“启动服务”。

提示：Windows 上监听 `502` 端口可能需要管理员权限。调试时可使用 `1502`、`5020` 等普通端口。

### 6.3 启动 RTU Server

1. 协议类型选择 `Modbus RTU`。
2. 选择串口和波特率。
3. 设置从机地址。
4. 点击“启动服务”。

RTU Server 需要真实串口或虚拟串口工具配合测试。

### 6.4 编辑 Server 数据

Server 表格按四个区域切换：

- 线圈 `0xxxx`
- 离散输入 `1xxxx`
- 输入寄存器 `3xxxx`
- 保持寄存器 `4xxxx`

位区可以直接切换开关值。寄存器区可以编辑：

- 原始值 HEX
- 解析值

如果服务已经启动，修改会立即同步到 Server 内部数据区，外部主站下一次读取即可获得新值。

### 6.5 外部主站写入

当外部主站写入线圈或保持寄存器时：

- Server 会更新对应字典点位的值。
- 报文会记录到“报文日志”。
- “请求计数”会增加。

## 7. 报文日志

报文日志用于查看通信过程。

显示内容包括：

| 字段 | 说明 |
| --- | --- |
| 时间 | 报文发生时间。 |
| 方向 | `TX` 发送或 `RX` 接收。 |
| 协议 | `RTU` 或 `TCP`。 |
| 数据 | 原始十六进制报文。 |
| 解析结果 | 软件解析后的简要说明。 |
| 耗时 | 本次事务耗时，单位 ms。 |
| 状态 | 发送、成功或失败。 |

日志最多保留 1000 条。可以点击“清空日志”清除当前日志。

## 8. 工程管理

工程文件使用 `.mbs` 格式，本质是 JSON 文本文件。

![工程管理视图](image/3e5a3769-11d2-4914-9940-df8c04db8922.png)

### 8.1 新建工程

点击“新建工程”会清空当前配置，包括：

- 连接配置
- Client 数据
- Server 数据
- 寄存器字典
- 报文日志
- 工程路径

如果当前工程有未保存修改，软件会先弹出确认提示。

### 8.2 保存工程

点击“保存工程”会保存当前所有数据，包括：

- 工程名称、描述、版本
- RTU / TCP 连接配置
- Client 从机地址、轮询周期、合并读取配置
- Client 已读取的数据
- Server 配置和当前模拟数据
- 寄存器字典
- 报文日志
- Server 请求计数

第一次保存会弹出文件路径选择框。

### 8.3 另存为

点击“另存为”会强制选择新路径，并把当前工程路径切换到新文件。

### 8.4 打开工程

点击“打开工程”选择 `.mbs` 文件后，软件会恢复保存时的所有配置和数据。

### 8.5 最近工程

最近打开或保存的工程会显示在“最近工程”列表中。点击项目可快速打开；点击删除图标只会移除最近记录，不会删除磁盘上的工程文件。

## 9. 常见问题

### 9.1 打包后打开白屏

确认 `vite.config.ts` 中有：

```ts
base: './'
```

然后重新执行：

```powershell
npm run build
npm run dist
```

旧打包目录不会自动修复，需要使用重新生成的新目录。

### 9.2 打包时报 EBUSY

如果看到类似错误：

```text
EBUSY: resource busy or locked
```

通常是旧的打包目录被其他程序占用，例如 Typora、资源管理器预览、杀毒软件或已经启动的 `Modbus Studio.exe`。

处理方法：

1. 关闭正在运行的 `Modbus Studio.exe`。
2. 关闭打开工程目录文件的编辑器或预览窗口。
3. 删除临时目录：

```powershell
Remove-Item .\release\win-unpacked.tmp -Recurse -Force
```

4. 重新执行：

```powershell
npm run dist
```

### 9.3 TCP 连接失败

检查：

- IP 地址是否正确。
- 端口是否正确。
- Server 是否已经启动。
- 防火墙是否阻止连接。
- 如果本机测试，Client 主机地址可填 `127.0.0.1`。

### 9.4 RTU 串口连接失败

检查：

- 串口是否被其他软件占用。
- 波特率、数据位、停止位、校验位是否与设备一致。
- USB 转串口驱动是否正常。
- 从机地址是否正确。

### 9.5 某些点位读取失败

检查：

- 字典地址是否在正确范围。
- 数据类型长度是否正确。
- 设备是否允许读取该地址。
- 合并读取是否读到了设备不支持的空洞地址。

可以尝试关闭“合并读取”后再测试。

## 10. 推荐调试步骤

### 10.1 本机 TCP 自测

1. 在寄存器字典中添加几个 `40001` 开始的保持寄存器点位。
2. 在 Server 页面选择 `Modbus TCP`，监听端口设置为 `1502`。
3. 点击“启动服务”。
4. 在 Client 页面选择 `Modbus TCP`。
5. 主机地址填写 `127.0.0.1`，端口填写 `1502`。
6. 点击“连接 TCP”。
7. 观察 Client 是否按字典自动读取 Server 数据。
8. 修改 Server 中的解析值，观察 Client 下一轮读取是否变化。

### 10.2 真实设备调试

1. 根据设备说明书建立寄存器字典。
2. 确认地址范围、数据类型、长度和比例因子。
3. 连接 RTU 或 TCP 设备。
4. 观察报文日志是否有正常响应。
5. 对可写点位先用小范围安全值测试写入。
6. 保存工程，方便后续继续调试。

## 11. 数据安全提醒

- 写入真实设备前请确认点位权限、单位和比例因子。
- 对控制类点位建议先在 Server 模拟环境中验证。
- 工程文件会保存报文日志，分享给他人前请确认其中没有敏感设备信息。

## 12. 参与贡献

欢迎提交 Issue 和 Pull Request。贡献前请阅读：

- [开发说明](DEVELOPMENT.md)
- [贡献指南](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
- [更新记录](CHANGELOG.md)

## 13. 开源协议

本项目使用 [MIT License](LICENSE) 开源。