# DeviceDebugTool

**Repository Path**: ghosthack/device-debug-tool

## Basic Information

- **Project Name**: DeviceDebugTool
- **Description**: 一款多功能调试工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多功能设备调试工具

一个面向 Windows 的 Python 桌面调试工具，集成串口、网络和 HID 调试，适合嵌入式设备、上位机协议和现场联调。

## 开源仓库

- Gitee：https://gitee.com/ghosthack/device-debug-tool
- 许可证：[MIT](LICENSE)
- 开发者：人生不问过往

## 功能

- 串口调试：端口自动枚举（约 500ms）、设备名称和厂家显示、常用或自定义波特率、TXT/HEX 发送接收、自动断帧显示；端口消失时自动关闭。
- 网络调试：支持 TCP Client、TCP Server、UDP，支持 TXT/HEX 发送接收。
- HID 调试：枚举 HID 设备并自动刷新，按 VID/PID/名称选择，支持 Report ID 和 HEX 数据发送接收；设备断开时自动关闭。
- 日志查看：发送和接收分方向记录，同时显示 HEX 和 UTF-8 文本。
- 全局接收过滤：菜单「过滤 → 过滤窗口」，串口/网络/HID 接收统一过滤；组内 OR、组间 AND，支持包含/不包含/开头是/结尾是。
- 协议解析：接收设置可选内置 Modbus RTU，或在 `protocol_scripts` 中用 Python 脚本自定义解析；断帧后自动追加「解析」行。
- 自动应答：菜单「自动应答」，按 HEX/文本规则匹配接收并自动回包。
- 日志导出：接收区「导出」保存为文本文件；「清空」同时清零本页签收发统计。
- 快捷发送：发送区内可配置常用指令按钮，一键发送。
- 收发统计：接收设置栏右侧显示 RX/TX 字节数及实时 RX 速率。
- 界面主题：菜单「视图」可选原色/深色，下次启动自动恢复。
- 自动断帧：支持按接收空闲时间断帧，也支持按 HEX 分隔符断帧。
- 定时发送：串口、网络和 HID 都支持手动发送和按周期自动发送。
- 自动校验：发送时可自动追加内置校验，也可在 `checksum_scripts` 中用 Python 脚本自定义校验规则。
- 设置记忆：关闭程序时自动保存上次配置到 `settings.json`，下次启动会恢复窗口大小、当前页签、主题、连接参数、接收/发送选项、发送内容、过滤与自动应答规则。

## 安装

在当前目录执行：

```powershell
python -m pip install -r requirements.txt
```

如果暂时只用网络功能，可以不安装依赖，程序仍可启动；串口和 HID 页签会提示缺少依赖。

## 使用说明

- 程序内点击菜单 **帮助 → 使用说明** 可查看完整操作指南。
- 程序目录下的 `使用说明.md` 也可直接用文本编辑器打开。

## 启动

双击 `run.bat`，或者执行：

```powershell
python device_debug_tool.py
```

## 使用建议

- HEX 输入支持 `01 02 FF`、`0x01 0x02 0xFF`、`0102FF` 这几种格式。
- 串口端口下拉框会显示端口号、设备名称和厂家，方便区分多个 USB 转串口；列表约每 500ms 自动刷新，无需手动点刷新。
- 波特率可从下拉选择常用值（9600～921600），也可直接输入任意正整数（如 1500000）。
- 每个调试页签都有“接收断帧”区域，默认勾选“自动断帧”；开启时接收日志显示时间戳和“接收帧”标记，发送日志也会显示。
- 关闭“自动断帧”时进入原始接收模式，只显示接收内容并连续追加，不显示发送日志，也不显示 `接收 1B HEX:` 这类前缀。
- 接收显示可选择 `HEX + ASCII`、`HEX`、`ASCII`；`HEX + ASCII` 只在开启自动断帧时生效，关闭自动断帧时按紧凑 `HEX` 显示。
- 接收区显示内容自适应：边接收边拖动窗口即可按新宽度重新换行整理 HEX 数据（按字节对齐、不拆散 `A5 01`），历史顺序不变；接收区始终自动跟随最新数据，日志区高度随窗口变化。
- 全局过滤：菜单「过滤 → 过滤窗口」，勾选「启用过滤」并配置条件组后，仅匹配的接收内容会汇入过滤结果（带来源前缀 `[串口]`/`[网络]`/`[HID]`）；发送与系统消息不参与过滤。
- 界面布局为连接区、接收设置（含统计）、接收日志、发送区（含快捷发送）；日志在上、发送在下，联调时更方便边看回包边修改发送内容。
- 主题：菜单「视图」切换原色/深色；原色为暖米白配色，深色为炭灰蓝配色。
- 发送区可填写“周期 ms”并点击“定时发送”，再次点击“停止定时”即可停止。
- 发送区勾选“自动追加校验”后会按所选算法处理；内置算法默认整帧计算并追加到末尾。
- 自定义校验规则写在 `checksum_scripts` 目录的 `.py` 文件中，计算起止字节和校验字节位置也在脚本里声明；修改后点击发送区的「刷新」即可出现在算法下拉框。
- 自定义协议解析写在 `protocol_scripts` 目录的 `.py` 文件中，实现 `parse(data)` 或 `parse(data, helpers)`；修改后点击接收设置「协议」旁的「刷新」即可出现在协议下拉框。
- 分隔符 HEX 为空时，程序按“空闲时间 ms”断帧，默认 5 ms；也可填写「帧长」按固定字节数断帧（优先级：分隔符 > 帧长 > 空闲）。
- 接收采用后台线程 + 1 ms 队列轮询，串口/网络/HID 读取超时均为 1 ms，提高响应速度。
- 分隔符 HEX 不为空时，程序遇到分隔符立即输出一帧，例如填写 `0D 0A` 可按回车换行断帧。
- 串口文本发送默认追加 `\r\n`，调试 AT 指令、简单命令协议会更方便；如果协议不需要换行，可以取消勾选。
- TCP Server 需要等客户端连上后才能发送。
- UDP 发送使用“UDP 远端”的地址和端口，接收时会显示来源地址。
- HID 在 Windows 上可能需要设备权限或厂商驱动；部分设备要求第一个字节是 Report ID。

## 脚本校验规则

在 `checksum_scripts` 目录中新建一个 `.py` 文件：

```python
NAME = "MY-SUM16"
WIDTH = 2
ENDIAN = "ui"
START_BYTE = 2
END_BYTE = 6
CHECK_BYTE = 7


def calculate(data):
    return sum(data)
```

- `NAME`：算法下拉框里显示的名称。
- `WIDTH`：`calculate()` 返回整数时输出几个字节，例如 `1`、`2`、`4`。
- `ENDIAN`：`ui` 使用界面选择的字节序，也可以固定为 `little` 或 `big`。
- `START_BYTE`：从第几个字节开始计算，字节序号从 `1` 开始。
- `END_BYTE`：算到第几个字节，写 `None` 表示算到发送内容末尾。
- `CHECK_BYTE`：校验值写到第几个字节，写 `None` 表示追加到末尾。
- `calculate(data)`：计算函数，`data` 是按 `START_BYTE` 到 `END_BYTE` 截取后的 `bytes`。
- `calculate()` 可以返回整数、`bytes`、HEX 字符串如 `"AA 55"`，或字节列表如 `[0x12, 0x34]`。

如果需要辅助算法，也可以写成：

```python
NAME = "MY-CRC-XOR"
WIDTH = 1
ENDIAN = "ui"
START_BYTE = 1
END_BYTE = None
CHECK_BYTE = None


def calculate(data, helpers):
    return helpers["xor"](data) ^ 0xFF
```

可用 `helpers` 命令（校验脚本与协议脚本通用）：

| 类别 | 命令 | 说明 |
|------|------|------|
| 校验 | `sum8` `sum16` `lrc8` `xor` `xor_not` | 常用单/双字节校验 |
| 校验 | `crc16_modbus` `crc16_ccitt` `crc32` | CRC 算法，返回整数 |
| 格式 | `to_hex` `hex_preview` `format_ascii` | HEX/ASCII 格式化 |
| 编解码 | `hex_bytes` `text_bytes` | HEX 或文本转 `bytes` |
| 读字段 | `u8` `u16_le` `u16_be` `u32_le` `u32_be` | `offset` 从 0 起 |
| 切片 | `slice(data, start_byte=1, end_byte=None)` | 字节序号从 1 起 |
| 搜索 | `find` `starts_with` `contains` | `pattern` 为 HEX 文本 |
| CRC | `verify_crc16_modbus` | 返回 `(bool, 说明文字)` |
| CRC | `append_crc16_modbus` `append_crc16_ccitt` | 追加 CRC 到帧尾 |
| 其它 | `to_bytes` `parse_modbus_rtu` | 整数转字节、内置 Modbus 解析 |

模板见 `checksum_scripts/_template.py`、`protocol_scripts/_template.py`。

## 脚本协议解析

在 `protocol_scripts` 目录中新建一个 `.py` 文件（以 `_` 开头的文件不会被加载）：

```python
NAME = "我的协议"


def parse(data, helpers):
    preview = helpers["hex_preview"](data)
    return f"长度 {len(data)}B | {preview}"
```

- `NAME`：协议下拉框里显示的名称。
- `parse(data)` 或 `parse(data, helpers)`：解析函数，`data` 为当前断帧后的 `bytes`，返回字符串显示在「解析」日志行。
- `helpers` 命令与校验脚本相同，详见上文「可用 helpers 命令」表格。

内置 **Modbus RTU** 无需脚本；自定义协议与内置协议并列出现在接收设置「协议」下拉框，点「刷新」更新列表。须开启**断帧**后解析才会生效。

示例脚本见 `protocol_scripts` 目录（`frame_info.py`、`_template.py`）。

## 打包发布

### 生成 EXE（便携版）

双击 `build_exe.bat`，或在项目目录执行：

```powershell
python -m pip install -r requirements.txt pyinstaller
python -m PyInstaller --noconfirm device_debug_tool.spec
```

输出目录 `dist\`：

- `DeviceDebugTool.exe`：主程序
- `checksum_scripts\`：校验脚本示例（`sum16.py`、`xor_not.py`、`sum8_byte4.py`）
- `protocol_scripts\`：协议解析脚本示例（`frame_info.py`、`crc16_modbus_check.py`、`_template.py`）
- `version.json`：版本清单（程序启动时读取版本号）
- `README.md`：说明文档

可将整个 `dist` 目录复制到其他电脑直接运行，无需安装 Python。

### 生成安装包

1. 先安装 [Inno Setup 6](https://jrsoftware.org/isdl.php)
2. 双击 `build_installer.bat`

安装包版本号自动读取 `version.json`，与程序内显示版本一致。

会先生成 EXE，再输出安装包：

- `installer_output\DeviceDebugTool_Setup.exe`

安装后包含：主程序、桌面/开始菜单快捷方式、校验与协议脚本示例目录、说明文档。`settings.json` 会保存在安装目录，用于记忆上次设置。

### 发布到 Gitee

版本号以仓库根目录 `version.json` 为唯一来源；程序启动时自动读取，推送到 `main` 时会通过 git hook 自动递增 patch 并同步该文件。

1. 运行 `install_git_hooks.bat` 安装 pre-push 钩子（每台开发机只需一次）。
2. 双击 `build_installer.bat` 生成 `installer_output\DeviceDebugTool_Setup.exe`。
3. 配置 Gitee [私人令牌](https://gitee.com/profile/personal_access_tokens)（环境变量 `GITEE_TOKEN` 或 `--token`）。
4. 执行 `python publish_release.py` 上传 Release 并回写 `version.json` 的 sha256。
5. 若 sha256 有更新，再 commit 并 push `version.json`。

跳过某次自动版本同步：`set SKIP_VERSION_SYNC=1` 后再 push。

### 打包说明

- 串口和 HID 依赖已打入 EXE；首次运行会在程序目录创建 `checksum_scripts`、`protocol_scripts` 并复制示例脚本（若不存在）。
- 自定义校验脚本请放在 EXE 同级的 `checksum_scripts` 目录，修改后点击发送区「刷新」即可。
- 自定义协议脚本请放在 EXE 同级的 `protocol_scripts` 目录，修改后点击接收设置「协议」旁的「刷新」即可。