# serial-helper

**Repository Path**: xonghanwei/serial-helper

## Basic Information

- **Project Name**: serial-helper
- **Description**: No description available
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Serial Port Assistant

> 面向 Windows 的中文串口调试助手。  
> 为嵌入式、单片机、模块联调和工业串口现场准备，覆盖收发、过滤、高亮、协议解析、脚本自动化、实时波形和日志记录。

<p align="center">
  <a href="https://github.com/haodehaode378/serial-port-assistant/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/haodehaode378/serial-port-assistant/windows-build.yml?branch=main&label=Windows%20Build"></a>
  <a href="https://github.com/haodehaode378/serial-port-assistant/releases"><img alt="Release" src="https://img.shields.io/github/v/release/haodehaode378/serial-port-assistant?label=release"></a>
  <img alt="Qt" src="https://img.shields.io/badge/Qt-6.11-41CD52">
  <img alt="C++" src="https://img.shields.io/badge/C%2B%2B-17-00599C">
  <img alt="Platform" src="https://img.shields.io/badge/platform-Windows-blue">
  <img alt="UI" src="https://img.shields.io/badge/UI-%E4%B8%AD%E6%96%87-red">
</p>

## 界面预览

![主界面](img/main-window.png)

| 协议解析 | 脚本自动化 |
|---|---|
| ![协议解析](img/protocol-view.png) | ![脚本自动化](img/script-view.png) |

| 实时波形 |
|---|
| ![实时波形](img/waveform-view.png) |

## 为什么做这个

常见串口工具要么只适合简单收发，要么功能分散在多个窗口里。Serial Port Assistant 的目标是把日常调试流程放在一个清晰的中文桌面工具中：

- 打开串口后立即收发数据。
- 在接收区快速过滤、定位关键字。
- 用快捷按钮和定时发送反复测试设备响应。
- 对协议帧做拆包、校验和分区显示。
- 用脚本把重复调试动作自动化。
- 长时间运行时持续记录日志，方便复盘问题。

## 功能亮点

| 能力 | 说明 |
|---|---|
| 多会话串口 | 每个 Tab 独立维护串口、收发区、日志和统计 |
| 中文界面 | 菜单、按钮、状态栏、提示信息面向中文用户 |
| HEX / ASCII | 支持文本发送、十六进制字节发送、HEX 显示和时间戳 |
| 定时发送 | 支持 50 ms 到 60 s 周期发送，适合压力测试和轮询 |
| 快捷发送 | 内置常用命令按钮，可配合发送历史快速复用 |
| 自动应答 | 支持按 ASCII / HEX 匹配接收数据，并按规则延迟回复 |
| 数据过滤 | 支持关键字高亮、只看匹配、忽略匹配 |
| 协议解析 | 支持帧头、帧尾、长度域、CRC8、CRC16 Modbus、CRC32 |
| 实时波形 | 支持多通道数据曲线和常见整数/浮点格式 |
| 脚本自动化 | 基于 QJSEngine，提供 serial、logger、timer、sys、plot API |
| 日志记录 | 自动写入 logs 目录，支持日志轮转 |
| 打包发布 | GitHub Actions 自动构建、测试、打包 Windows portable 版本 |

## 下载

最新正式版本：

[下载 v0.6.0 Windows 便携版](https://github.com/haodehaode378/serial-port-assistant/releases/tag/v0.6.0)

下载 `SerialPortAssistant-v0.6.0-win64-portable.zip`，解压后运行：

```text
ComAssistant.exe
```

## 快速开始

推荐使用 com0com 创建一对标准 COM 名称：

```text
COM7 <-> COM8
```

测试流程：

1. 打开程序，新建两个会话。
2. 会话 1 选择 `COM7`，波特率 `115200`，点击“打开串口”。
3. 会话 2 选择 `COM8`，波特率 `115200`，点击“打开串口”。
4. 在会话 1 输入 `Hello`，点击“发送”。
5. 会话 2 应收到 `Hello`。
6. 勾选“HEX 发送”，发送 `48 65 6C 6C 6F`，接收结果等价于 `Hello`。

如果 `CNCA0/CNCB0` 提示“找不到文件”，优先改用 `COM7/COM8`、`COM9/COM10` 这类标准 COM 名称。

## 构建

环境要求：

| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / Windows 11 |
| Qt | Qt 6.11.x |
| 编译器 | MSVC 2022 x64 或 MinGW 13.1 x64 |
| 构建工具 | CMake 3.28+ |
| 串口模块 | Qt SerialPort |

使用脚本构建：

```powershell
.\scripts\build.ps1
```

手动构建：

```powershell
cmake -S . -B build/msvc -G "Visual Studio 17 2022" -A x64
cmake --build build/msvc --config Release
```

运行测试：

```powershell
ctest --test-dir build/msvc -C Release --output-on-failure
```

打包便携版：

```powershell
.\scripts\package.ps1 -BuildDir build/msvc -Configuration Release -Installer None
```

## 脚本示例

每秒发送一次心跳：

```js
timer.loop(1000, function() {
    serial.send("ping\r\n");
    logger.info("heartbeat", "sent ping");
});
```

收到 `OK` 后自动回复：

```js
serial.onReceive(function(text, hex) {
    logger.info("rx", text);
    if (text.indexOf("OK") >= 0) {
        serial.send("next\r\n");
    }
});
```

向波形窗口添加数据点：

```js
plot.addPoint(12.5, 0);
plot.addPoint(7.8, 1);
```

脚本运行在独立线程中，并带有超时中断保护。脚本 API 不暴露文件系统、进程和网络能力。

## 文档

- [用户手册](docs/user-manual.md)：安装、com0com 测试、收发、过滤高亮、协议解析、波形、脚本和常见问题。
- [全功能手动测试说明](docs/manual-test-plan.md)：发布前按步骤验收主界面、串口收发、过滤高亮、协议、波形、脚本和打包结果。
- [架构说明](docs/architecture.md)：项目结构和核心数据流。
- [验收记录](docs/external-acceptance.md)：外部测试和打包验证记录。

## 项目结构

```text
project/
├── src/
│   ├── app/        # QApplication、主题管理
│   ├── core/       # 串口、配置、日志、协议、脚本、内存监控
│   ├── ui/         # 主窗口、会话、收发区、协议视图、波形视图
│   └── util/       # HEX/ASCII 工具和常量
├── res/            # QSS 主题和 Qt 资源
├── tests/          # 单元测试和集成测试
├── scripts/        # 构建、验证、打包辅助脚本
├── packaging/      # Windows 安装包配置
├── docs/           # 架构、手册和验收文档
└── img/            # README 截图
```

## 当前状态

- [x] 串口基本收发
- [x] HEX / ASCII 切换
- [x] 定时发送和快捷发送
- [x] 自动应答规则
- [x] 接收区保存
- [x] 数据过滤和关键字高亮
- [x] 日志保存和轮转
- [x] 协议解析
- [x] 实时波形
- [x] 脚本自动化
- [x] 多串口会话
- [x] Windows CI 构建、测试、打包
- [x] GitHub Release 发布
- [x] 更完整的错误可见性
- [x] 协议预设库和示例数据
- [x] 亮暗主题切换
- [x] 应用图标和中文便携包说明

`v0.6.0` 已发布：新增自动应答规则、亮暗主题切换、应用图标、中文便携包说明和更完整的串口调试体验。

## 许可证

当前仓库尚未声明开源许可证。正式开放协作前建议补充 `LICENSE` 文件，例如 MIT、Apache-2.0 或 GPL-3.0。