# embed_tools

**Repository Path**: asila1024/embed_tools

## Basic Information

- **Project Name**: embed_tools
- **Description**: 项目小工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: modbus

## README

# Modbus RTU 主站调试工具

一个基于 Python + tkinter 的 Modbus RTU 串口调试工具，带图形界面。包含 **Modbus 主站调试** 与 **双串口数据转换** 两大功能，可用于现场调试压缩机、变频器等 Modbus 从站设备。当前版本 **v1.0.0**。

## 功能特性

### 1. Modbus 主站

- **串口配置**：端口 / 波特率 / 校验位 / 数据位 / 停止位 / 默认从站地址 / 超时时间
- **命令管理**：添加、编辑、删除多条命令，支持功能码：
  - 读：`01 读线圈`、`02 读离散输入`、`03 读保持寄存器`、`04 读输入寄存器`
  - 写：`05 写单个线圈`、`06 写单个寄存器`、`10 写多个寄存器`
- **发送方式**：选中一条手动发送（支持多选），或一键发送全部
- **报文显示**：TX / RX 原始报文（十六进制）
- **数值解析**：寄存器数据按多种方式直观解码显示：
  - `uint16`（16 位无符号）
  - `int16`（16 位有符号）
  - `uint32`（32 位无符号，相邻 2 寄存器，大端）
  - `int32`（32 位有符号）
  - `float32`（IEEE754 单精度浮点，相邻 2 寄存器，大端）
- **命令持久化**：命令列表自动保存 / 加载到 `commands.json`

### 2. 串口转换

- 分别配置 **端口 1** 和 **端口 2** 的串口参数（端口 / 波特率 / 校验 / 数据位 / 停止位）
- 双向透明转发：端口 1 收到的数据 → 从端口 2 发出；端口 2 收到的数据 → 从端口 1 发出
- 转发日志实时显示每条转发记录，可一键清空

## 环境要求

- Windows / Linux / macOS
- Python 3.8+（需自带 tkinter）
- 依赖库：`pyserial`

## 安装与运行

### 源码运行

```bash
# 1. 安装依赖
pip install pyserial

# 2. 运行程序
python modbus_gui.py
```

Windows 下也可以直接双击 `run.bat`，脚本会自动检查并安装 `pyserial` 后启动程序。

### 直接使用打包好的 exe

`dist\ModbusRTU_Tool.exe` 为已打包的独立可执行文件，无需安装 Python，双击即可运行。

> 注意：`commands.json` 保存在 exe 所在目录，可随程序一起拷贝使用。

## 使用说明

### Modbus 主站

1. 在「串口连接」面板选择端口并设置参数，点击 **打开串口**；
2. 在命令列表区点击 **添加命令**，填写命令参数：

   | 字段 | 说明 |
   | --- | --- |
   | 名称 | 命令名称，便于识别 |
   | 从站地址 | 从站地址（1-247） |
   | 功能码 | 读 / 写功能码 |
   | 寄存器地址 | 起始寄存器 / 线圈地址（支持十进制或 `0x` 前缀十六进制） |
   | 数量/数值 | 读：寄存器个数；写单个：数值（线圈填 0/1）；写多个：逗号分隔多个值 |
   | 备注 | 可选说明文字 |

3. 选中命令点击 **发送选中 ▶**，或点击 **发送全部** 逐条发送；
4. 在「解析结果」面板查看 TX/RX 报文和寄存器数值，可切换解码方式；
5. 每条命令的发送状态（OK / 超时 / 通信错等）显示在列表「状态」列。

### 串口转换

1. 切换到「串口转换」标签页；
2. 分别配置端口 1 和端口 2 的串口参数；
3. 点击 **开始转换**，两个端口即开始双向数据转发；
4. 在转发日志中查看每条数据转发记录，点击 **停止转换** 结束。

## 打包为 exe

项目使用 PyInstaller 打包。Windows 下直接双击 `build_exe.bat`，脚本会自动完成：

1. 查找带 tkinter 的 Python 解释器；
2. 安装 `pyinstaller`、`pyserial`；
3. 打包为单文件无控制台窗口的 `dist\ModbusRTU_Tool.exe`。

构建结果写入 `build_log.txt`（完整日志）和 `build_result.txt`（一句话结论）。

也可以手动执行：

```bash
pyinstaller --noconfirm --onefile --windowed ^
  --name ModbusRTU_Tool ^
  --hidden-import serial ^
  --hidden-import serial.tools.list_ports ^
  modbus_gui.py
```

## 项目结构

```
modbus_tools/
├── modbus_gui.py          # GUI 主程序（tkinter）
├── modbus_rtu.py          # Modbus RTU 协议层：CRC16、组帧、响应解析、数值解码
├── commands.json          # 命令列表持久化文件（自动生成）
├── build_exe.bat          # PyInstaller 打包脚本（Windows）
├── run.bat                # 一键运行脚本（Windows）
├── ModbusRTU_Tool.spec    # PyInstaller 配置文件
└── dist/
    └── ModbusRTU_Tool.exe # 打包产物
```

## 开发注意事项

- **`build_exe.bat` 必须保持 GBK(CP936) 编码 + CRLF 换行**。不要用 UTF-8 重新保存，否则 cmd 按 GBK 解析会拆坏中文注释，导致后续命令被截断、打包失败。编辑该文件时如需改注释，请只用 ASCII。
- **版本号**定义在 `modbus_rtu.py` 顶部的 `__version__` 常量（当前 v1.0.0），GUI 标题栏会自动显示 `v{version}`。升级版本只需改这一处。
- 协议层与 GUI 分离：`modbus_rtu.py` 仅依赖标准库 + pyserial，协议逻辑都在此模块，可独立运行自测：

  ```bash
  python modbus_rtu.py
  ```