feat: 新增 SerialMate 串口调试助手 v0.1.0
- 协议帧构成令牌序列可定制(包头/板ID/LEN口径/5种CRC x 3种覆盖), 默认兼容 DLPilot 光机协议
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
# SerialMate — RS485/串口调试助手
|
||||
|
||||
> LT8619C 调试工具集配套工具：串口收发 + 协议包解析 + 曲线绘制。
|
||||
> 帧格式（包头/板ID/LEN/CRC）全可定制，默认与 [DLPilot](../DLPilot) 光机
|
||||
> RS485 协议一致，可用来直接调试板载 GD32E230 网关或任意同构协议设备。
|
||||
|
||||
## 功能
|
||||
|
||||
- **串口收发**：端口自动枚举、波特率 1200~921600、数据位/校验/停止位可选，
|
||||
参数热切换；半双工 RS485 友好（每周期最多写一帧，留应答间隙）。
|
||||
- **协议解析**（可关，关=原始透传）：
|
||||
增量字节流定界 + CRC 校验，失败逐字节重同步，噪声自动丢弃；
|
||||
接收帧 ID 位按 DLPilot 语义译码显示（0xF0=成功、0xFD=参数越界…）。
|
||||
- **帧构成定制**（协议卡，发送/接收共用同一布局，仅包头值分方向）：
|
||||
帧构成用**令牌序列**定义，默认 `HDR ID LEN PAYLOAD CRC`（即 DLPilot 五段式）：
|
||||
|
||||
| 令牌 | 含义 |
|
||||
|---|---|
|
||||
| `HDR` | 包头（值取 TX包头 / RX包头 字段） |
|
||||
| `ID` | 板ID（RX 侧多为响应 TYPE 码，不校验仅透出显示） |
|
||||
| `LEN` | 长度字节，口径可选：**payload 长度（默认）** / 到帧尾(payload+CRC) / 整帧 |
|
||||
| `PAYLOAD` | 协议载荷（发送框内容，别名 DATA） |
|
||||
| `CRC` | 校验（算法/覆盖范围见下表，必须在末尾） |
|
||||
| 十六进制字面量 | 固定字节，如 `AA 55` 双字节同步头 |
|
||||
|
||||
示例：`AA 55 LEN PAYLOAD CRC`（AA55 同步头、无板ID）·
|
||||
`HDR LEN PAYLOAD ID CRC`（板ID 在载荷后）· `HDR LEN ID PAYLOAD CRC`（板ID 在长度后）。
|
||||
约束：LEN/PAYLOAD/CRC 恰好各一次，LEN 前至少一个 HDR 或字面量作同步头。
|
||||
|
||||
| 项 | 说明 | 默认 |
|
||||
|---|---|---|
|
||||
| TX 包头 | HDR 令牌在命令帧的值 | `D5` |
|
||||
| RX 包头 | HDR 令牌在响应帧的值 | `B5` |
|
||||
| 板ID | ID 令牌的值（TX 用；RX 侧仅透出） | `01` |
|
||||
| LEN 口径 | payload 长度 / 到帧尾(payload+CRC) / 整帧 | payload 长度 |
|
||||
| CRC 算法 | SUM8 累加和 / CRC8 / CRC16 MODBUS / CRC16 XMODEM / CRC16 CCITT-FALSE | SUM8 |
|
||||
| CRC 覆盖 | 含包头(整帧) / 不含包头(跳过第1字节) / 仅 payload | 不含包头 |
|
||||
- **接收显示**：payload 一键切换 **字符串 / HEX**；可选附原始帧 hex；
|
||||
时间戳；日志保存为 txt。
|
||||
- **曲线**：4 通道，每帧有效数据按通道提取一个数值，支持三种提取方式
|
||||
（二进制定长 u8~f32 大小端 / 文本第 N 个数字 / 自定义正则）+ 倍率，
|
||||
y 轴自动或手动量程，暂停/清空；绘图区可**弹成独立窗口**（"弹出"按钮，
|
||||
关掉窗口即嵌回），通道配置与暂停等控件留在主界面照常控制。弹出窗口内：
|
||||
纵轴每条参考线标注数值刻度；**时间窗**可选宽度（跟随/10s/30s/1min/5min/
|
||||
15min），配合横向滑条回看历史总体趋势或缩小窗口细看局部走势，拉到最右
|
||||
恢复实时跟随（冻结查看请配合"暂停"）；窗口宽度不向数据收敛——数据不足时
|
||||
显示完整的所选时间轴、曲线贴右端随采集逐渐填满（示波器式），右下角标注
|
||||
"已采集 Xs / 窗口 Ns"；**鼠标悬停**在曲线上，绘图区顶部的小读数框持续显示
|
||||
光标处时间点 T 与各通道在该时刻的 Y 轴数值（±10px 容差取最近采样）；
|
||||
弹出窗口工具栏：**暂停渲染**（只冻结画面方便查看，采集继续入库，点"继续
|
||||
渲染"后把积累的数据一次性画出来；画面中央会显示"已冻结渲染"角标；注意
|
||||
与主界面"暂停"的区别：那个会丢弃暂停期间的数据）、**自动Y**（开/关自动
|
||||
纵轴，关闭后可在图上按住左键上下拖动自定义 Y 轴范围）、**实时**（取消
|
||||
滞后跳回最新）、**滚轮**在图上缩放时间窗（2s~15min）。
|
||||
实例：回包 payload `01 AE 75 6D`（前 2 字节固定、第 3~4 字节是 16 位大端
|
||||
采样值 0x7444~0x7696）→ 勾选通道1，方式=二进制，偏移=2，格式=u16 大端，
|
||||
倍率按传感器量纲填（如 0.01）；最新值显示在通道行尾并进入曲线。
|
||||
注意偏移是 payload 内的字节序号（0=第 1 字节），选错位宽/偏移会把多个字段
|
||||
拼成一个数（如 u32@偏移0 会把整包读成 28,210,029）；数值显示为千分位普通
|
||||
小数，≥10 亿才用科学计数。
|
||||
- **板型档案**：不同板子的"协议参数 + 命令预设表"存为命名档案，保存在 exe
|
||||
同目录的 `board_profiles.json`。发送卡选中板型即一键套用其协议参数
|
||||
（包头/板ID/帧构成/LEN口径/CRC）并切换命令预设；**新建板型**按当前协议参数
|
||||
建档、命令预设从空白开始；**存为板型**把当前配置存成档案（同名覆盖）；
|
||||
**删除板型**带确认（至少保留一个）；"存入预设"把当前输入的命令加入当前
|
||||
板型（可自定义显示名称）；**配置**打开表格编辑器（名称/命令两列，+加行
|
||||
−删行，保存写回档案）；预设下拉以"名称 · 命令"同显。
|
||||
- **发送**：
|
||||
- **自动包装**：输入协议载荷（如 `M731S0T1000`）自动组帧加包头/板ID/LEN/CRC；
|
||||
多条用 `/` 分隔依次发送（如 `M1/M731S0T1000`）；
|
||||
- **HEX 直发**：输入完整帧 hex 原样发出；
|
||||
- 周期发送（100ms~60s）、输入框实时组帧预览、预设命令一键填入、
|
||||
命令历史 ↑↓ 回溯、回车即发送。
|
||||
|
||||
## 运行
|
||||
|
||||
- 直接运行 `release/SerialMate.exe`（免安装，Windows 10/11 x64）；
|
||||
- 或源码运行：`py -3 -m pip install PySide6 PySide6-Fluent-Widgets pyserial`，
|
||||
然后 `cd src && python main.py`。
|
||||
|
||||
## 界面速览
|
||||
|
||||
```
|
||||
┌ SerialMate ─────────────────────────────────────────────────┐
|
||||
│ 串口卡 协议卡 │ 接收卡(payload 字符串/HEX) │
|
||||
│ COMx 115200 8N1 D5/B5/01 │ ← 12:00:00 B=0xF0 成功 LEN=2 ok │
|
||||
│ 曲线卡(4通道) │ ┌───────── 滚动曲线 ─────────┐ │
|
||||
│ ☑ DMD温度 文本数字 第1个 ×0.1 │ └────────────────────────────┘ │
|
||||
│ │ 发送卡: [M1/M731S0T1000] 发送 │
|
||||
└────────────────────────────────┴──────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 典型用法：调光机 RS485
|
||||
|
||||
1. 串口卡选 USB-RS485 适配器，115200 8N1，连接；
|
||||
2. 发送框输入 `M1` 回车——自动包装为 `D5 01 02 4D 31 81` 发出，
|
||||
接收区回 `ok`（协议卡默认即 DLPilot 协议）；
|
||||
3. 查温度：发 `M201`，回包 `okTL:246` 译码显示"成功"，曲线卡勾选通道
|
||||
设为"文本数字·第1个·×0.1"，周期发送勾上，即可看温度曲线；
|
||||
4. 换任何自定义协议：改协议卡的**帧构成**（字段顺序/有无板ID/字面量同步头）、
|
||||
包头/板ID/LEN 口径/CRC 即可，收发解析同步生效；调好后点"存为板型"，
|
||||
以后一键切换。
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
SerialMate/
|
||||
├── src/ 源代码（protocol 协议 / link 串口线程 / main GUI / selftest 自检）
|
||||
├── assets/ serial-mate.ico 图标（assets/make_icon.py 生成）
|
||||
├── release/ SerialMate.exe + README（发布文件夹，zip 只上传 Release）
|
||||
└── README.md 本文
|
||||
```
|
||||
|
||||
运行时用户数据与 exe 同目录平铺：`serial_mate.json`（串口/协议/通道记忆）、
|
||||
`board_profiles.json`（板型档案，首次运行自动生成默认"DLPilot光机"）。
|
||||
|
||||
## 开发 / 发布
|
||||
|
||||
```powershell
|
||||
cd src
|
||||
python selftest.py # 协议回归(无依赖, 改 protocol.py 后必跑)
|
||||
python selftest_loop.py # 链路回环自检(loop:// 虚拟口, 需 pyserial)
|
||||
python main.py # 源码运行
|
||||
python build_exe.py # → ../release/SerialMate.exe
|
||||
python package_release.py <版本> # → release/SerialMate-v<版本>-win64.zip
|
||||
python publish_gitea.py ../release/SerialMate-v<版本>-win64.zip --replace --insecure
|
||||
```
|
||||
|
||||
工程约束与进度见 [AGENTS.md](AGENTS.md)；协议语义唯一权威是上游固件仓
|
||||
`protocols.md`（本仓 DLPilot 目录有引用说明）。
|
||||
Reference in New Issue
Block a user