8.3 KiB
SerialMate — RS485/串口调试助手
LT8619C 调试工具集配套工具：串口收发 + 协议包解析 + 曲线绘制。 帧格式（包头/板ID/LEN/CRC）全可定制，默认与 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 令牌在命令帧的值 D5RX 包头 HDR 令牌在响应帧的值 B5板ID ID 令牌的值（TX 用；RX 侧仅透出） 01LEN 口径 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 轴范围）、实时（取消 滞后跳回最新）、滚轮在图上缩放时间窗（2s15min）。 实例：回包 payload01 AE 75 6D（前 2 字节固定、第 34 字节是 16 位大端 采样值 0x74440x7696）→ 勾选通道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
- 串口卡选 USB-RS485 适配器，115200 8N1，连接；
- 发送框输入
M1回车——自动包装为D5 01 02 4D 31 81发出， 接收区回ok（协议卡默认即 DLPilot 协议）； - 查温度：发
M201，回包okTL:246译码显示"成功"，曲线卡勾选通道 设为"文本数字·第1个·×0.1"，周期发送勾上，即可看温度曲线； - 换任何自定义协议：改协议卡的帧构成（字段顺序/有无板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光机"）。
开发 / 发布
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；协议语义唯一权威是上游固件仓
protocols.md（本仓 DLPilot 目录有引用说明）。