# serialtool

**Repository Path**: zackSpace/serialtool

## Basic Information

- **Project Name**: serialtool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## SerialAssistant（Python 串口助手）

基于 Python + PySide6 的桌面串口调试工具，支持串口收发（文本/HEX）、自动发送、文件分块发送，并提供扩展功能页（快速发送、循环发送、发送历史、网络调试 TCP/UDP/SSL/MQTT）。

### 主要功能

- 串口打开/关闭、参数设置（波特率/校验/数据位/停止位、RTS/DTR）
- 接收区支持文本/HEX 显示与流式追加
- 发送支持文本/HEX、可选追加 CRLF、自动发送
- 文件发送：按块发送、可配置发送间隔
- 扩展页：
  - 快速发送（指令列表）
  - 循环发送（按时间/次数截止）
  - 发送历史
  - 网络调试（TCP/UDP/SSL/MQTT）
- Windows 打包：PyInstaller 一键生成 EXE，并生成 update.json（用于更新描述）

---

## 环境要求

- Windows 10/11（当前项目脚本以 Windows 为主）
- Python 3.9+（建议使用 3.10/3.11/3.12/3.13 任一稳定版本）

核心依赖：
- PySide6（GUI）
- pyserial（串口）

可选依赖：
- paho-mqtt（网络调试里 MQTT 功能）

打包依赖：
- pyinstaller
- pillow（可选：把 PNG 自动转换成 ICO 用作 exe 图标）
- colorama（可选：build.py 彩色输出）

---

## 安装依赖（推荐方式）

在项目根目录（`D:\Project\Python\serialtool`）使用 PowerShell 执行：

```powershell
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install -U pip
python -m pip install -r .\requirements.txt
```

如果需要打包：

```powershell
python -m pip install -r .\requirements-dev.txt
```

### 常见注意事项

- 如果你使用的是 Windows Store 的 Python，`pip install` 可能会提示 `Defaulting to user installation...`，这是正常现象。
- 安装 PySide6 后可能提示 `pyside6-uic.exe ... is not on PATH`，这不影响运行；只有在命令行直接调用 `pyside6-uic` 时才需要把对应 Scripts 目录加到 PATH。
- PowerShell 里不要用 `&&` 连接命令（部分环境会报解析错误），请分成两条命令或用 `;`。

---

## 运行（源码）

```powershell
python .\main.py
```

入口文件在 `main.py`，会启动主窗口并处理单实例/多配置目录逻辑。

---

## 更新 UI（如果你修改了 .ui 文件）

UI 原文件：`app/ui/main_window.ui`  
生成文件：`app/ui/ui_main_window.py`

```powershell
python .\app\ui\build_ui.py
```

---

## 打包编译（生成 EXE）

项目提供了 Windows 构建脚本 `build.py`：

```powershell
python .\build.py
```

构建产物：
- `.\dist\SerialAssistant.exe`
- `.\dist\update.json`

### 打包常见问题

- `PermissionError: [WinError 32] ... dist\\SerialAssistant.exe`  
  说明旧 exe 正在运行或被占用（例如杀毒/索引/资源管理器预览）。请关闭正在运行的程序后重试。

- `ValueError: ... icon ... png ... only ('exe', 'ico') images may be used`  
  Windows 下 EXE 图标推荐使用 ICO。你可以安装 Pillow 让构建脚本自动把 PNG 转 ICO：

  ```powershell
  python -m pip install pillow
  python .\build.py
  ```

---

## 项目结构（简要）

- `main.py`：程序入口（创建 QApplication、单实例/多开配置目录选择、启动主窗口）
- `app/main_window.py`：主窗口与主要业务逻辑（串口收发、UI 绑定、扩展页、设置保存）
- `app/serial_worker.py`：串口读写后台线程（pyserial）
- `app/file_sender.py`：文件发送线程（分块发送）
- `app/extensions/`：扩展功能页（快速发送/循环发送/历史/网络调试）
- `build.py`：PyInstaller 打包脚本（生成 exe 与 update.json）