# 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 目录有引用说明）。