# beautifulcom

**Repository Path**: qinganan_admin/beautifulcom

## Basic Information

- **Project Name**: beautifulcom
- **Description**: 使用Python+Pyside6写的串口工具，它有着漂亮UI，简单的操作
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-20
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BeautifulCom

BeautifulCom 是一个基于 Python + PySide6 开发的桌面串口调试工具，窗口标题为“串口魔方”。它面向嵌入式开发、设备联调、AT 指令验证、现场测试和长期串口日志采集等场景，目标是在保留专业调试能力的同时，把常见高频操作做得更直观、更顺手。

传统串口工具往往把连接、发送、日志、快捷指令和数据观察拆得比较散。BeautifulCom 将这些能力放在同一个工作台里：左侧管理串口配置，中间进行终端交互，右侧维护快捷指令，底部可打开实时图表，状态栏持续展示收发统计、循环发送状态和终端跟随状态。对于需要反复切换设备、批量发送 AT 指令、观察日志特征或记录现场数据的工作流，它可以减少大量重复操作。

## 适合场景

- 嵌入式设备串口调试与固件联调
- AT 指令发送、分组管理和批量维护
- 多串口会话并行查看，支持标签页和分屏模式
- 串口日志记录、检索、分包与导出
- 简单遥测数据观察，例如温度、电压、电流等实时曲线
- 关键字 / 正则检测、高亮、自动应答和基础协议联调

## 界面预览

以下截图来自本地虚拟环境中真实运行的 PySide6 界面，不是设计稿或合成图。

### 主界面

左侧是连接管理，中间是终端工作区，右侧是快捷指令面板，底部状态栏展示会话统计。

![BeautifulCom 主界面](assets/screenshots/beautifulcom-main.png)

### 快捷指令与实时图表

| 快捷指令搜索 | 实时图表 |
| --- | --- |
| ![快捷指令搜索](assets/screenshots/beautifulcom-shortcuts.png) | ![实时图表](assets/screenshots/beautifulcom-chart.png) |

### 配置界面

| 串口配置 | 日志设置 |
| --- | --- |
| ![串口配置](assets/screenshots/beautifulcom-serial-config.png) | ![日志设置](assets/screenshots/beautifulcom-log-settings.png) |

| 图表解析规则 | 数据检测规则 |
| --- | --- |
| ![图表解析规则](assets/screenshots/beautifulcom-chart-rules.png) | ![数据检测规则](assets/screenshots/beautifulcom-detection-rules.png) |

| 自动应答 |
| --- |
| ![自动应答设置](assets/screenshots/beautifulcom-auto-reply.png) |

## 主要特性

### 连接与会话

- 支持保存多个串口连接配置，包括端口、波特率、数据位、停止位、校验位、流控和读取方式
- 连接管理面板以卡片形式展示名称、端口、波特率、连接状态和启动打开状态
- 默认使用标签页承载会话，也可以切换为分屏查看多个会话
- 会话区支持发送、接收、清屏、搜索、时间戳、Hex 模式和终端字体缩放
- 状态栏实时展示发送字节数、接收字节数、收包条数、循环发送状态和终端自动跟随状态

> 维护备注：Raw 网络连接和 SSH 连接的底层代码仍保留，但 UI 入口当前默认隐藏。  
> 如需重新显示“新建 Raw 连接”和“新建 SSH 连接”，将 `app/window/layout_mixin.py` 中的 `SHOW_NETWORK_CONNECTION_ENTRY_POINTS` 改为 `True`。

### 快捷指令

- 支持按分组管理快捷指令，适合维护 AT 指令集、设备控制命令和测试脚本片段
- 支持搜索分组、名称和指令内容
- 支持快捷指令导入 / 导出，便于在不同电脑之间同步调试命令库
- 支持循环发送，可用于轮询设备状态、压力测试和周期性采样
- 支持拖拽排序和分组折叠，让常用命令保持在更容易触达的位置
- 支持**动态参数**：指令中可写占位符，每次发送时再填写具体值（见下文）

### 日志与检测

- 支持启用 / 禁用日志记录，并可配置日志保存目录
- 支持多种时间戳格式：时分秒、毫秒、完整日期时间等
- 支持按单文件、文件大小、时间间隔或内容字段进行日志分包
- 支持普通文本或正则表达式检测串口输出，并用不同颜色高亮关键内容
- 适合捕获 `ERROR`、`WARN`、启动完成、低电量、异常状态码等关键事件

### 图表与自动化

- 实时图表支持从串口文本中提取数值并绘制曲线
- 支持自定义正则解析规则，也支持类似 `Temp: 35.5`、`Voltage=5.0` 的简单遥测格式自动提取
- 图表支持暂停、清空、历史查看和时间窗口调整
- 自动应答可以根据接收内容匹配回复文本，并设置延迟时间
- 提供 X/YMODEM 实验性入口，用于后续文件传输联调

## 快捷指令导入导出

软件支持从菜单中直接导入 / 导出快捷指令：

- `文件 -> 导入快捷指令`
- `文件 -> 导出快捷指令`

如果需要让另一台电脑上的 BeautifulCom 自动识别快捷指令文件，也可以将导出的 JSON 放到以下固定位置：

`%APPDATA%\BeautifulCom\imports\shortcut_commands.json`

下次启动软件时会自动检测并导入。

## 快捷指令动态参数

部分指令每次发送时只有少数字段不同（例如 WiFi 名称、设备 ID、引脚号）。可以在指令内容里用占位符写成**模板**，发送时再填写参数，不必为每种取值单独建一条指令。

### 语法

| 写法 | 含义 | 示例模板 | 发送时行为 |
|------|------|----------|------------|
| `{参数名}` | 必填/可填参数 | `AT+NAME={name}` | 弹窗填写 `name` |
| `{参数名:默认值}` | 带默认值 | `AT+BAUD={baud:115200}` | 默认填 `115200`，可改 |
| `{{` / `}}` | 字面量花括号 | `payload={{ok}}` | 实际发送 `payload={ok}` |

规则说明：

- 参数名只能使用字母、数字、下划线，且不能以数字开头（如 `ssid`、`pin1`、`device_id`）
- 同一条指令里同名占位符只填写一次，多处会一起替换
- 不含 `{参数}` 的普通指令行为不变，点发送后直接下发

### 操作步骤

1. 在右侧「快捷指令」中新增或编辑指令，在**指令**字段写入模板，例如：
   - 名称：`连接 WiFi`
   - 指令：`AT+CWJAP="{ssid}","{password}"`
2. 确保当前会话已连接，然后**双击**该指令，或右键选择「发送指令」
3. 若检测到占位符，会弹出「填写参数」对话框：
   - 上方可预览替换后的完整报文
   - 每个参数一行输入框；带默认值的字段会预填
4. 点「发送」后才会真正下发；点「取消」则不发送
5. 上次填写的参数会按该指令记住，下次打开对话框时自动带出（写入本地配置中的 `shortcut_param_cache`）

编辑对话框的指令框 placeholder / 悬停提示中也有简要语法说明。

### 与循环发送、批量发送

| 场景 | 行为 |
|------|------|
| 单次发送 | 有占位符 → 弹窗填参 → 替换后发送 |
| 循环发送 | **启动循环时填一次**，之后周期使用同一最终字符串（不会每个周期都弹窗） |
| 批量发送 | 队列中含占位符的条目会**逐条**弹窗；中途取消则整批中止 |
| 无占位符 | 与原先一致，直接发送 |

### 示例

```text
# WiFi 连接（每次填 SSID / 密码）
AT+CWJAP="{ssid}","{password}"

# 波特率（默认 115200，可改）
AT+UART_DEF={baud:115200},8,1,0,0

# GPIO 写电平
GPIO,SET,{pin},{level:1}

# 需要真正输出花括号时
LOG {{status}}={code}
# 若 code=42，实际发送：LOG {status}=42
```

## 配置文件位置

源码运行时优先读取项目目录下的配置：

`config\app_config.json`

打包安装后优先读取安装目录下的配置：

`{安装目录}\config\app_config.json`

旧版本曾使用的 `%APPDATA%\BeautifulCom\config\app_config.json` 会作为迁移来源；当优先路径不存在时，会自动复制过去。

## 本地运行

项目入口：

```powershell
python .\run.py
```

如果你使用仓库内虚拟环境：

```powershell
.\.venv\Scripts\python.exe .\run.py
```

如果本地环境缺少运行依赖，可以先安装常用依赖：

```powershell
python -m pip install PySide6 pyserial pyqtgraph
```

## Windows 打包

当前 Windows 打包方案：

- 应用目录版：`PyInstaller onedir`
- 安装包：`Inno Setup 6`

必要打包文件：

- `BeautifulCom.spec`
- `packaging/windows/Build-Windows.ps1`
- `packaging/windows/BeautifulCom.iss`
- `packaging/windows/requirements-build.txt`
- `packaging/release_config/app_config.json`

说明：

- `build/` 是 PyInstaller 的中间产物，不需要提交
- `dist/` 和 `dist-installer/` 是打包输出，不需要提交
- 发布版默认快捷指令配置来自 `packaging/release_config/app_config.json`
- 本地个人使用的 `config/app_config.json` 是源码运行时的优先配置

### 1. 安装打包依赖

```powershell
.\.venv\Scripts\python.exe -m pip install -r .\packaging\windows\requirements-build.txt -i https://pypi.org/simple
```

### 2. 仅生成目录版

```powershell
powershell -ExecutionPolicy Bypass -File .\packaging\windows\Build-Windows.ps1 -SkipInstaller
```

输出目录：

`dist\BeautifulCom\`

### 3. 生成安装包

先安装 `Inno Setup 6`，然后执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\packaging\windows\Build-Windows.ps1 -Version 1.0.2
```

输出目录：

`dist-installer\BeautifulCom_Setup_1.0.2.exe`

安装包支持自定义安装目录。

## 仓库建议

建议提交：

- 源代码
- 资源文件
- README 中引用的截图
- 必要打包脚本与 spec
- 发布演示配置

建议不要提交：

- `build/`
- `dist/`
- `dist-installer/`
- 本地日志输出目录

## License

如仓库根目录 `LICENSE` 所示。