# 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-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BeautifulCom

BeautifulCom（窗口标题「串口魔方」）是基于 **Python + PySide6 / QML** 的桌面串口调试工作台。面向嵌入式联调、AT 指令、现场日志采集和简单遥测观察：左侧管连接，中间是终端，右侧是快捷指令库，底部可展开实时曲线。

## 适合场景

- 嵌入式固件 / 模组串口调试与联调
- AT 指令库维护、分组、批量与循环发送
- 多会话标签页并行查看（可分屏对照）
- 串口日志记录、时间戳、分包与导出
- 温度 / 电压 / 角速度等文本遥测的实时曲线
- 关键字与正则高亮、自动应答

## 界面预览

以下截图来自本机真实运行的 QML 工作台（`assets/screenshots/`），不是设计稿。

### 主工作台

三栏布局：连接列表 · 会话终端 · 快捷指令；底部为实时图表（可开关、可独立 Y 轴、可历史浏览）。

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

### 图表与快捷指令

| 实时图表（侧栏收起时更突出） | 快捷指令面板 |
| --- | --- |
| ![实时图表](assets/screenshots/beautifulcom-chart.png) | ![快捷指令](assets/screenshots/beautifulcom-shortcuts.png) |

### 配置对话框

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

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

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

### 更新截图

在**有显示器的交互桌面**中执行（无头 / 远程会话下窗口抓图可能失败或黑屏）：

```powershell
.\.venv\Scripts\python.exe .\scripts\capture_readme_screenshots.py
```

脚本会打开会话、灌入演示终端与曲线、依次抓主窗与各配置对话框，并校验非黑屏后才覆盖 `assets/screenshots/`。

## 主要特性

### 连接与会话

- 保存多套串口配置：端口、波特率、数据位 / 停止位 / 校验 / 流控、读取方式、行尾
- 左侧连接列表 + 顶部会话 Tab；支持分屏对照两个会话
- 终端：发送 / 接收、清屏、搜索、时间戳、Hex、字体缩放、**默认跟随尾部**（仅用户操作暂停跟随）
- 状态栏：TX / RX 字节、收包条数、循环 / 批量发送状态、图表与跟随状态

> 维护备注：Raw / SSH 底层仍保留，UI 入口默认隐藏。需要时将 `app/window/layout_mixin.py` 中 `SHOW_NETWORK_CONNECTION_ENTRY_POINTS` 改为 `True`。

### 快捷指令

- 按分组管理 AT / 控制指令；搜索分组、名称与内容
- 导入 / 导出指令库；拖拽排序与分组折叠
- 单条循环、多选批量、整组循环（可设轮数；状态栏可停）
- **动态参数**占位符：发送前弹窗填参（见下文）

### 日志与检测

- 可开关日志目录；多种时间戳格式
- 按单文件、大小、时间间隔或内容标记分包
- 关键字 / 正则检测并用颜色高亮（如 `ERROR`、`Boot OK`）

### 图表与自动化

- 从串口文本抽数值画曲线：自定义**正则**规则、**CSV 多通道**，或 `Temp: 35.5` / `Voltage=5.0` 类智能提取
- 暂停、清空、时间窗（5s～5m）、独立 Y、图例点选显隐、十字线读数
- **历史模式**：远端数据桶抽样，并可在用户缓存目录落盘（`chart_history`），长时间挂机不无限涨内存
- 自动应答：匹配包含文本后延时回复
- X/YMODEM 实验性入口（文件传输联调）

## 架构速览（维护）

入口：`run.py` → `backend/app_controller.py`（QML 对外 API 保持稳定）。

控制器按领域拆为 mixin，**行为与原先单文件一致**：

| 模块 | 职责 |
|------|------|
| `session_controller_mixin.py` | 会话 Tab、连接 / 断开、分屏、端口 |
| `chart_controller_mixin.py` | 实时图开关、浮窗几何、解析规则 |
| `send_controller_mixin.py` | 发送、快捷指令、批量 / 循环 |
| `chart_engine.py` | 解析、环形缓冲 + 历史抽样、Canvas 数据 |

热路径：Worker 批读 → `SessionRuntime.pending` → 约 16ms `flush` → 终端行模型 + 图表合批绘制。

QML 目录约定见 `qml/README.md`（控件树与 demo 独立，禁止 junction）。

## 快捷指令导入导出

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

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

如果需要让另一台电脑上的 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 / 悬停提示中也有简要语法说明。

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

| 场景 | 行为 |
|------|------|
| 单次发送 | 有占位符 → 弹窗填参 → 替换后发送 |
| 单条循环发送 | 右键单条 → **循环发送…**；**启动时填一次参**，之后按间隔重复同一最终字符串 |
| 多条批量发送 | Ctrl/Shift 多选 → 右键 **批量发送 / 循环…** → 调整顺序与条间间隔（**含首条**默认 **0.1s=100ms**，**0.05=50ms**）→ 单次跑完队列 |
| 多条循环发送 | 同上对话框中勾选 **「循环发送整组」**，可设轮数（**0=无限**）；整组 A→B→C 跑完后回到队首继续；状态栏「批量循环中」可点停 |
| 后续加固 | 见 `docs/TODO_repeat_send.md`（TX 背压、互斥、失败提示等，按需改） |
| 批量/循环填参 | 队列中含占位符的条目会**启动前逐条**弹窗；中途取消则整批中止 |
| 无占位符 | 与原先一致，直接发送 |

### 示例

```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
```

## 配置文件位置

源码运行时优先读取项目目录下的**个人配置**（已加入 `.gitignore`，勿提交）：

`config\app_config.json`

仓库内提供模板（可提交）：

`config\app_config.example.json`

首次运行若尚无个人配置，会从 example（或 `packaging/release_config`）自动复制一份到 `config\app_config.json`。

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

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

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

## 本地运行

默认入口为 **QML 工作台**（`python run.py`）。

| 脚本 | 作用 |
|------|------|
| `run.py` | 产品入口 |
| `qml_beautiful_theme.py` | 产品 Theme（复用 `qml-beautiful-demo`，**不能删**） |
| `tools/ensure_qml_trees.py` | 保证 `qml/{Controls,Components,Icons}` 与 demo **独立目录**（禁止 junction） |

产品与 demo 的控件树在 Git 里是两份；**不要**用 `mklink /J` 把产品目录链到 demo，否则 `git pull` 后会出现假的未提交 QML。若已误链：

```powershell
python .\tools\ensure_qml_trees.py --fix
```

```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` 是源码运行时的优先配置（gitignore）
- 新环境可复制 `config/app_config.example.json` → `config/app_config.json`
- **安装包与 onedir 默认跑 QML 工作台**（spec 已包含 `qml/` 与 Qt Quick）；体积会大于早期纯 Widgets 包

### 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` 所示。