# 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-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多功能设备调试工具

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

## 开源仓库

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

## 功能

- 串口调试：端口刷新、设备名称和厂家显示、常用波特率、TXT/HEX 发送接收、自动断帧显示。
- 网络调试：支持 TCP Client、TCP Server、UDP，支持 TXT/HEX 发送接收。
- HID 调试：枚举 HID 设备，按 VID/PID/名称选择，支持 Report ID 和 HEX 数据发送接收。
- 日志查看：发送和接收分方向记录，同时显示 HEX 和 UTF-8 文本。
- 自动断帧：支持按接收空闲时间断帧，也支持按 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 转串口。
- 每个调试页签都有“接收断帧”区域，默认勾选“自动断帧”；开启时接收日志显示时间戳和“接收帧”标记，发送日志也会显示。
- 关闭“自动断帧”时进入原始接收模式，只显示接收内容并连续追加，不显示发送日志，也不显示 `接收 1B HEX:` 这类前缀。
- 接收显示可选择 `HEX + ASCII`、`HEX`、`ASCII`；`HEX + ASCII` 只在开启自动断帧时生效，关闭自动断帧时按紧凑 `HEX` 显示。
- 接收区显示内容自适应：边接收边拖动窗口即可按新宽度重新换行整理 HEX 数据（按字节对齐、不拆散 `A5 01`），历史顺序不变；接收区始终自动跟随最新数据，日志区高度随窗口变化。
- 界面布局为接收日志在上、发送区在下，联调时更方便边看回包边修改发送内容。
- 发送区可填写“周期 ms”并点击“定时发送”，再次点击“停止定时”即可停止。
- 发送区勾选“自动追加校验”后会按所选算法处理；内置算法默认整帧计算并追加到末尾。
- 自定义校验规则写在 `checksum_scripts` 目录的 `.py` 文件中，计算起止字节和校验字节位置也在脚本里声明；修改后点击发送区的“刷新规则”即可出现在算法下拉框。
- 分隔符 HEX 为空时，程序按“空闲时间 ms”断帧，默认 1 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["xor"]`、`helpers["crc16_modbus"]`、`helpers["crc16_ccitt"]`、`helpers["crc32"]`、`helpers["hex_bytes"]`。

## 打包发布

### 生成 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`）
- `README.md`：说明文档

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

### 生成安装包

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

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

- `installer_output\DeviceDebugTool_Setup.exe`

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

### 打包说明

- 串口和 HID 依赖已打入 EXE；首次运行会在程序目录创建 `checksum_scripts` 并复制示例脚本（若不存在）。
- 自定义校验脚本请放在 EXE 同级的 `checksum_scripts` 目录，修改后点击“刷新规则”即可。