# serial-protocol-debugger **Repository Path**: eric_pirate/serial-protocol-debugger ## Basic Information - **Project Name**: serial-protocol-debugger - **Description**: 串口协议调试工具 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-17 - **Last Updated**: 2026-08-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: 串口, 工具, exe, Windows ## README # Serial Protocol Debugger **串口协议调试器** — 把「手搓 hex、反复验 CRC、对着协议文档逐字节对」变成可视化点选。 > 主机轮询探头、Modbus 风格 CRC16、自定义前导符……协议再复杂，也只需配一次、反复用。 --- ## 为什么需要它 嵌入式联调里，串口协议调试往往长这样： ``` 打开串口助手 → 查文档拼 hex → CRC 算错 → 改 → 再发 → 响应对不上 → 翻日志猜字节含义 ``` **Serial Protocol Debugger** 把这条链路收成一条线： ``` 定义分段 → 填参数 → 发送 / 轮询 → 自动组帧、验 CRC、解析响应 ``` 不用写脚本，不用记偏移量。协议改了？改 JSON 配置，立刻生效。 --- ## 核心能力 | 能力 | 说明 | | ----------- | ----------------------------------- | | **分段组帧** | 帧头、SN、帧长、CRC……每段独立配置编码方式与长度规则 | | **自动计算** | CRC16、帧长回填、字节和（sum8）发送时自动填入，接收时自动校验 | | **发送 & 轮询** | 单条指令一键发送；轮询模式持续占用串口，适合主机探询场景 | | **响应解析** | 按分段解码返回值，支持枚举映射（如 `0x4F` → `开(O)`） | | **公共字段** | 多个指令共享「序列号」等参数，改一处、列表同步 | | **配置复用** | JSON 导入 / 导出，团队共享同一套协议定义 | | **前导符** | 可选先发 `66 66 66` 等唤醒字节，再发正式帧 | --- ## 快速开始 ### 方式一：Conda（推荐） ```powershell git clone https://gitee.com/eric_pirate/serial-protocol-debugger.git cd serial-protocol-debugger conda env create -f environment.yml conda activate serial-protocol-debugger pip install -e . ``` 若 `environment.yml` 创建失败，可手动： ```powershell conda create -n serial-protocol-debugger python=3.11 -y conda activate serial-protocol-debugger pip install -r requirements.txt pip install -e . ``` ### 方式二：纯 pip ```powershell pip install -e . ``` > 需要 Python **3.11+**，依赖见 `[pyproject.toml](pyproject.toml)`。 ### 启动 ```powershell conda activate serial-protocol-debugger python -m app.main ``` 或安装后直接运行： ```powershell serial-protocol-debugger ``` --- ## 三分钟上手 1. **选串口** — 界面选择 COM 口，按需调整波特率（默认 9600 8N2）。 2. **加载配置** — 内置示例见 `[config/commands.default.json](config/commands.default.json)`。 3. **改参数** — 主列表「参数」列可直接编辑序列号、寄存器地址等。 4. **发送** — 点「发送」收一条响应；点「轮询」持续探询。 默认示例是一条「读寄存器」指令：含前导符、AA/BB 帧头、5 字节 SN、帧长、CRC16 完整链路。 --- ## 协议默认值 开箱即用的协议约定（均可在界面 / 配置中覆盖）： | 项 | 默认值 | | --------- | ------------------------------------ | | 串口 | 9600 8N2 | | 发令前导 | `66 66 66`（可选，约 3ms 后发正式帧） | | 主机 / 从机帧头 | `0xAA` / `0xBB` | | SN | 5 字节，线上小端 | | CRC16 | 多项式 `0xA001`，初值 `FFFF`（Modbus），高字节在前 | | 随机码 | 固定 `0x00`（明文） | --- ## 自由报文配置 用 JSON 描述「发什么、收什么、怎么编解码」。核心思路：**发送用** `segments` **编码，接收用** `response_segments` **解码**。 ### 最小示例 ```json [ { "name": "读寄存器示例", "use_preamble": true, "preamble": "66 66 66", "wait_response": true, "segments": [ {"label": "帧头", "codec": "const_hex", "value": "AA", "length_mode": "fixed", "length_bytes": 1}, {"label": "CRC16", "codec": "crc16", "length_mode": "fixed", "length_bytes": 2, "endian": "be", "crc_init": "FFFF"} ], "response_segments": [ {"label": "帧头", "codec": "const_hex", "value": "BB", "length_mode": "fixed", "length_bytes": 1}, {"label": "CRC16", "codec": "crc16", "length_mode": "fixed", "length_bytes": 2, "endian": "be", "crc_init": "FFFF"} ] } ] ``` 完整示例见 `[config/commands.default.json](config/commands.default.json)`。 ### 支持的编解码类型 | codec | 用途 | | ---------------------------- | ------------------------------- | | `hex` / `const_hex` | 可变 / 固定十六进制 | | `number` / `char` / `string` | 数值、字符、字符串（支持 `utf-8` / `gbk` 等） | | `frame_len` | 帧长字段，发送时按整帧回填，接收时按 L 等待完整包 | | `sum8` | 字节和校验（AA/BB 特殊 +1 规则） | | `crc16` | Modbus 风格 CRC16，通常作为末段 | ### 长度模式 | 模式 | 适用 | 说明 | | ------- | ------- | --------------- | | `fixed` | 编码 & 解码 | 固定字节数 | | `ref` | 编码 & 解码 | 引用更靠前字段的长度 | | `auto` | 编码 | 不定长，按实际编码结果，不补零 | | `rest` | 解码 | 剩余字节，须在帧长段之后 | ### 公共字段 多个指令共享参数时，保存为对象格式： ```json { "common_fields": ["序列号"], "commands": [ ] } ``` `common_fields` 中的字段会同步到所有勾选了「列表」的同名字段。 **完整字段参考（点击展开）** | 字段 | 说明 | | ------------------------- | ---------------------------------------- | | `name` | 显示名称，用于界面与日志 | | `use_preamble` | 是否先发前导符 | | `preamble` | 前导符 hex，默认 `66 66 66` | | `wait_response` | 是否等待并解析响应 | | `segments` | 发送编码分段 | | `response_segments` | 接收解码分段；空则按原始 hex 记录 | | `segments[].label` | 参数名；长度引用时用于定位 | | `segments[].codec` | 见上表 | | `segments[].value` | 编码值；解码时可填期望值 | | `segments[].param` | 是否出现在主列表「参数」列 | | `segments[].length_mode` | `fixed` / `ref` / `auto`（编码）或 `rest`（解码） | | `segments[].length_bytes` | 固定长度；`0` 表示不占报文 | | `segments[].length_ref` | 被引用段；`sum8` 指定求和源 | | `segments[].endian` | `be`（默认）/ `le` | | `segments[].crc_init` | CRC16 初值 hex，默认 `FFFF` | | `segments[].charset` | 字符串编码 | | `segments[].enum` | 线上键 → 展示名，解析时自动转换 | **编码规则摘要：** 长于设定长度报错；短于设定补 `0x00`。`const_hex` 与 `auto` 不补齐。`crc16` 只能作末段，固定 2 字节。 --- ## 开发与测试 ```powershell conda activate serial-protocol-debugger # 开发运行 python -m app.main # 单元测试 python -m pytest -q ``` ### 项目结构 ``` serial-protocol-debugger/ ├── src/ │ ├── app/ # PySide6 界面、轮询/发送 worker │ ├── commands/ # 报文配置、分段编解码 │ ├── protocol/ # CRC16、帧处理 │ └── serial_io/ # 串口封装 ├── config/ # 默认指令配置 ├── tests/ ├── scripts/ # 打包、图标生成 └── packaging/ # PyInstaller spec ``` --- ## 打包（Windows 桌面） ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1 ``` 产物：`dist\SerialProtocolDebugger\`，整目录拷贝到目标机，双击 `SerialProtocolDebugger.exe` 即可，**无需安装 Python**。 ### 图标 - 资源：`assets/app.ico`、`assets/app.png` - 从新 PNG 生成 ico：`python scripts/make_icon.py path\to\source.png` --- ## 参与贡献 欢迎 Issue 和 Pull Request。无论是新 codec、新协议模板，还是文档改进，都很期待。 1. Fork 本仓库 2. 创建特性分支：`git checkout -b feature/my-feature` 3. 提交改动并确保 `pytest` 通过 4. 发起 Pull Request --- ## 开源协议 本项目采用 [MIT License](LICENSE) 开源。 --- 如果它帮你少算了一次 CRC，少改了一版 hex，Star 一下就是最大的鼓励 ⭐