# USB-TRACE-T1

**Repository Path**: osr-tech/usb-trace-t1

## Basic Information

- **Project Name**: USB-TRACE-T1
- **Description**: usb协议触发
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-14
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# USB Catch 软件

![USB Catch 设备](assets/device.png)

## 仓库目录

| 路径 | 内容 | 文档入口 |
| --- | --- | --- |
| `src/desktop/` | 桌面客户端源码 | — |
| `src/ucctl/` | 共用设备 API 与命令行工具 | [CLI / Python API 参考](src/ucctl/README.md) |

## 产品介绍

### 设备连接

![T1 设备连接：HOST、DEVICE、CONTROL 与 TRI1 触发输出](assets/connection-diagram.png)

### 客户端软件

USB Catch 支持 Linux / Windows 下的 USB 实时采集与离线分析。本仓库提供桌面客户端和 CLI / Python API 源码，不含客户端可执行程序包。

![USB Catch 客户端：总线记录、传输结构、设备信息与协议解码](assets/desktop.png)

- 采集与回放：保存采集数据，打开 `.bin` 文件离线分析。
- 协议分析：查看总线事件、事务、传输和设备描述符，检查 PID / CRC。
- 搜索与过滤：HEX / ASCII 搜索，按设备、地址、端点、IO1 区间过滤，折叠 SOF / NAK。
- 设备控制：字节匹配触发、供电控制、固件更新与 UID 读取。

## 源码安装与打包

### 获取源码

环境：Linux / Windows x86-64、64 位 Python 3.12+。以下命令均在仓库根目录执行，以 Python 3.12 为例。

```bash
git clone https://gitee.com/osr-tech/usb-trace-t1.git
cd usb-trace-t1
```

### Linux 运行源码

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -r src/desktop/requirements.txt ./src
PYTHONPATH=src .venv/bin/python -m desktop
```

Ubuntu / Debian 若缺少 Qt xcb 依赖：

```bash
sudo apt install libxcb-cursor0 libxkbcommon-x11-0 libegl1
```

### Windows 运行源码

PowerShell：

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\src\desktop\requirements.txt .\src
$env:PYTHONPATH = (Resolve-Path .\src).Path
.\.venv\Scripts\python.exe -m desktop
```

CMD 中将设置 `PYTHONPATH` 的一行改为 `set "PYTHONPATH=%CD%\src"`。
再次启动时，只需设置 `PYTHONPATH` 并执行最后一条启动命令。连接设备前完成下方的 USB 权限或 WinUSB 驱动配置。

### 自行打包桌面客户端

先创建上述 `.venv`，再在目标系统上使用 PyInstaller 打包。

Linux：

```bash
bash src/desktop/packaging/build-linux.sh --install-deps
```

Windows PowerShell：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\src\desktop\packaging\build-windows.ps1 --install-deps
```

产物位于 `dist/desktop/`：Windows 为 ZIP，Linux 为 tar.gz，附 SHA256 校验文件。
脚本不覆盖同名产物；再次构建可追加 `--output dist/desktop-new`。
Linux 请在计划支持的最低版本发行版上构建。

### 仅安装 CLI / Python API

创建 `.venv` 后安装 `src` 即可。已按上文安装桌面依赖的用户无需重复安装。

Linux：

```bash
.venv/bin/python -m pip install ./src
.venv/bin/ucctl --help
```

Windows PowerShell：

```powershell
.\.venv\Scripts\python.exe -m pip install .\src
.\.venv\Scripts\ucctl.exe --help
```

## 使用说明

### 连接准备

以下权限和驱动配置适用于客户端及 CLI / Python API。

#### Linux USB 访问权限

连接采集器前，从源码目录安装 USB 权限规则：

```bash
sudo install -m 644 src/desktop/packaging/linux/70-usb-catch.rules /etc/udev/rules.d/70-usb-catch.rules
sudo udevadm control --reload-rules
```

重新插拔 CONTROL USB，以普通桌面用户运行客户端。规则适用于本地桌面会话；远程或服务账户需单独配置权限。
仅离线分析无需配置 USB 权限或驱动。

#### Windows 首次连接：安装驱动

使用仓库附带的 `zadig-2.9.exe` 或 [Zadig 官网版本](https://zadig.akeo.ie/)，为采集器的 **Interface 0 和 Interface 1 分别安装 WinUSB**。

![Zadig 中的采集器接口：Interface 0 和 Interface 1](assets/zadig-interfaces.png)

1. 关闭客户端，将采集器的 CONTROL USB 接口连接电脑。
2. 以管理员身份运行 Zadig，勾选 `Options → List All Devices`。
3. 选择 `OSR USB Capture (Interface 0)`，核对 USB ID 为 `1D50:615B`，选择 `WinUSB`，点击 `Install Driver` 或 `Replace Driver`。
4. 对 `Interface 1` 重复安装，确认两个接口均为 WinUSB，再重新插拔设备。

已绑定 WinUSB 的接口无需重复安装。只修改采集器接口，勿替换 USB 复合设备父项或其他设备的驱动。
接口 1 用于切换烧录模式；烧录模式可能枚举为 `1D50:615C` 或 `1209:0010`，也需绑定对应驱动。

### 客户端软件

#### 基本使用

1. 在齿轮设置中选择采集目录。
2. 点击“连接设备”，选择速率和供电策略，再点击“开始采集”。
3. 查看总线事件、事务、传输及 HEX / ASCII；停止后等待缓冲排空和索引保存。
4. 点击“打开文件”选择 `stream.bin` 进行离线分析；已有有效 `.idx` 会复用，首次建索引需要目录可写。

滚动历史或选择记录会暂停“跟随最新”，不会停止采集。“排空旧数据”保存设备缓冲中的残留数据。

“采集开始上电”“采集结束断电”和“写盘过滤 IN→NAK”默认开启。**需要完整原始数据时，请关闭写盘过滤；被过滤的事务无法恢复。** 界面的显示过滤不修改采集文件。

HEX / ASCII 搜索按单包匹配；地址、端点可多选。“仅总线事件”隐藏 USB 数据包和事务。

| 快捷键 | 操作 |
| --- | --- |
| Ctrl+O | 打开文件 |
| Ctrl+F | 定位搜索框 |
| F3 / Shift+F3 | 下一个 / 上一个命中 |
| Ctrl+C | 复制 HEX 选中字节 |

#### IO1 区间过滤

在“过滤”中勾选“仅 IO1 高电平区间（开始 → 结束）”，显示固件 `IO_STATE` 记录的高电平区间，包含两端标记。
采集开始已为高电平时从初始状态算起；没有下降沿时显示到当前已解析末尾；没有高电平记录时结果为空。

跨边界的 USB 事务整笔保留，下方传输上下文不裁剪。此过滤与其他条件取交集，不修改原始文件或索引。

#### 触发与固件更新

触发支持 1–100 字节 HEX，匹配范围为单个 USB 包。可从 HEX 选区填入，点击“应用并 ARM”生效，点击 DISARM 停止触发。

在设置中选择适用于本设备的 `.bit` / `.bin` 固件，点击“更新固件”。更新前停止采集、排空缓冲并停止触发；更新期间不要断电或拔 USB，完成后重新连接。

设置中的“获取 UID”可读取并复制设备唯一标识；硬件、固件及协议版本显示在设置窗口底部。

#### 支持范围

- 仅支持本项目的 `stream.bin`，不支持 USBPcap / pcap 或旧 Analyzer 文件。
- 支持 Control、Bulk、Interrupt 和普通 Isochronous；尚不支持 SPLIT / TT、高速高带宽等时及完整 HID / MSC / UAC / UVC 类解码。
- 重组传输的边界不保证对应主机软件请求；状态栏 CRC 不代表全文件校验结论。

### CLI / Python API

设备控制、采集和触发命令，以及 Python 调用示例，见 [CLI / Python API 使用文档](src/ucctl/README.md)。