USB Trace 采集分析

面向嵌入式调试的 USB Trace 采集分析工具：从目标板抓取 VCD 波形与 LOG 日志两大类数据，解码成标准 VCD，做确定性的事实提取与断言检查。

同一套引擎，两种用法：本扩展的图形面板，以及内置的命令行 usbtrace （全命令支持 --json，适合脚本与 AI 自动化）。两者读写同一份配置文件 （多标签时每个标签一份，1 号标签即主配置），面板里设好参数后，命令行未显式指定的选项会自动取配置文件里的值（子命令本身仍要给出，例如 usbtrace capture vcd）。

术语

USB Trace —— 本工具链的统称，涵盖下面两大类。

VCD —— 波形类。来自 USB trace 字流，解码为标准 VCD 文件。

LOG —— 日志类。来自接口 0 的 HCI/debug 日志。

文中出现「USB Trace」时指整体，「VCD」「LOG」分别指其中一类。

快速开始

装好 Python 3.8+，并确保 python 在 PATH 中（或用设置 usbtrace.pythonPath 指定解释器路径）。
按 Ctrl+Shift+P 运行 USB Trace: 自测（不接硬件），输出窗口出现 ALL PASS 即环境正常。

运行 USB Trace: 打开工具面板，在面板左侧：

要选什么	选什么
文件命名参照	一个 bin 文件（只用于命名产物，不要求文件存在）
信号参考文件	你的 `def.h`（决定能解析出哪些信号）
分析规则文件	断言规则 `spec.json`

再确认**系统时钟频率（MHZ）**与固件一致。

在停止设置 → VCD 把「时长（秒）」设为 3，点 VCD采集。
点 打开 VCD 看波形（只打开当前配置的最新产物；其他路径用 打开 VCD 文件…，或命令面板 USB Trace: 打开 VCD 文件…），点 分析 生成分析报告。

装好插件后会自动弹出分步引导（也可以用命令面板运行 Welcome: Open Walkthrough 找到「USB Trace 快速上手」）。更详细的说明见下方文档。

功能

采集

VCD 采集 —— 边采边解码为标准 VCD，GTKWave 可直接打开。
LOG 采集 —— 从 interface 0 读取 HCI/debug 日志，实时解析滚动显示并写文件；日志区默认自动跟随最新一条（向上翻阅旧日志时暂停，滚回底部恢复）。
两路独立可并行，也可用「联动停止」让一侧停止时带动另一侧。
停止方式：VCD = 时间 / task 信号触发；LOG = 时间 / 字符串触发。两者都支持按钮强制停止，按钮永远最高优先级。
时长为 0 表示不限，一直采到点停止。
支持未上电等待与断线自动重连；时长从设备首次就绪开始算，所以「先启动采集、再给设备上电」能采到完整时长（抓启动过程就靠这个）。
设备枚举徽标 —— 打开面板自动枚举当前配置的设备：(device found) 时默认启动日志采集，不在线显示 (device not found)；点击徽标可重新枚举。

USB Shell

日志区下方直接发 hex 命令（如 11 03 31 查 TWS 角色）：命令走 LOG 接口 (MI_00) 的 EP5 OUT，固件输出照常走 EP3 IN 日志流，和日志在同一个面板里看。
内置「查询状态 11 03 31」「保存配对信息 11 03 10」两条常用命令；任意命令可「存为常用」保存到用户级列表，支持删除。
支持输入历史（↑/↓）、危险命令（关机/配对/切换模式/改名）二次确认。
命令行同样可用：capture log --stdin-shell，见 CLI 参考。

多设备 / 多标签

采集预设 —— 把整套参数存成命名快照，一键切换（例如左右耳 0x120 / 0x121）。
多标签并行 —— 每台设备一个标签，各自独立的配置与采集进程，可同时采集与观察；同一设备重复采集、或覆盖模式下输出文件相同会阻止启动。
预设库全局共享；标签标题显示预设名与设备号，关闭后再按同一编号新建会沿用上次参数。

分析

波形分析 —— 信号/事件统计、周期与抖动、脉冲宽度、多 bit 单调性、关联 LOG 的标签趋势。确定性事实提取，不做启发式结论，结论留给人或 AI。
断言检查 —— 按 spec 校验事件是否存在、周期是否达标、时序先后、事件时刻的信号取值。
LOG 规则检测 —— 8 类可配置规则（关键字、序号跳变、标签缺失、计数上下限、数值范围、趋势、静默间隔、解析失败）。
打开任意 VCD —— 面板「打开 VCD 文件…」或命令面板 USB Trace: 打开 VCD 文件…，选择任意路径的 .vcd 用 VS Code 默认编辑器打开。

自动化

内置命令行 usbtrace，全命令 --json（stdout 只输出一个 JSON 对象）、退出码统一。
usbtrace run 一键跑完采集 → 分析 → 断言。
usbtrace schema --json 自描述命令目录。

常见问题

症状	先查什么
一直「等待设备上电...」	板子是否上电、USB 是否接好、VID/PID 是否对（用 `USB Trace: 设备信息` 确认）
板子确实连着、却仍一直「等待设备上电...」（64 位 Python）	0.2.4 及以前在 64 位 Python 下取不到设备接口路径	升级到 0.2.5+
采集到 0 字节	设备没被识别到 / 固件没在跑 —— 用 `USB Trace: 设备信息` 确认设备在线，核对 VID/PID
所有时间成比例偏大/偏小	系统时钟频率是否与固件配置一致
task 信号下拉框是空的	信号参考文件是否还指向内置示例 —— 点「浏览...」选中你自己的 `def.h`
「打开 VCD」提示文件不存在	还没采集过
改动参数后命令行没生效	是否取消了「自动保存」—— 勾回，或点「保存配置」
提示找不到 Python	安装 Python 3.8+，或在设置里填 `usbtrace.pythonPath`

采集与设备枚举仅支持 Windows（通过 usbprint.sys 访问目标板）， 32 位与 64 位 Python 均可。解码、分析、断言、自测跨平台可用。

命令行

装了扩展后，CLI 会被落位到不含版本号的稳定路径，扩展升级后依然有效： ~/.usbtrace/usbtrace（Windows 为 %USERPROFILE%\.usbtrace\usbtrace.cmd）。

~/.usbtrace/usbtrace doctor --json

没配过的话 doctor 会返回 ready: false 并列出 blockers（缺什么、怎么修），而不是「全部通过」。只做分析不做采集时用 doctor --for analyze。

不确定路径在哪时，运行命令 USB Trace: CLI 路径。从源码仓库开发时也可直接用仓库根的 ./usbtrace。

常用命令：

usbtrace doctor --json                 # 自检：ready=true 才表示「可以采集」
usbtrace run --seconds 3 --json        # 一键：并行采集 → 分析 → 断言
usbtrace capture log --stop-string ASSERT --json
usbtrace capture log --stream --stdin-shell --seconds 30   # 边看日志边下发 USB Shell 命令
usbtrace analyze vcd --with-check --json

退出码统一：0 成功 / 1 断言失败 / 4 仅日志规则命中（多为关键词误报）/ 2 用法错误 / 3 运行时错误。run 的 summary.verdict 会直接给出结论。

完整命令、参数、输出字段与自动化配方 → python/CLI.md

文档

装好插件后，点采集面板顶部的 「帮助文档」 按钮即可打开下面两份文档，也可以从命令面板运行：

命令	内容
`USB Trace: 使用指南`	界面详解、操作步骤、产物读法、断言与规则写法、故障排查、设置速查
`USB Trace: 命令行参考`	全部命令/参数/输出字段、退出码、自动化配方

在线版本：

文档	讲什么
UserGuide.md	怎么用：界面详解、操作步骤、产物说明、故障排查、设置速查
python/CLI.md	命令行参考：全部命令/参数/输出字段、退出码、自动化配方
CHANGELOG.md	版本变更记录

设置

设置项	说明
`usbtrace.pythonPath`	Python 解释器路径（留空则自动探测 `python` / `python3` / `py -3`）

其余参数（时钟频率、VID/PID/设备编号、文件路径、停止方式、联动停止、自动化模式等）保存在工作区 .vscode/usbtrace.json，与命令行共用同一份。

面板上的「自动保存」（默认勾选）会在参数变更时立即写盘；取消勾选时，点「保存配置」或任意采集/分析操作同样会保存。

目录结构

usbtrace / usbtrace.cmd      命令行入口（转发到 python/usbtrace_cli.py）
python/                      Python 引擎（命令行与扩展共用）
  usbtrace_cli.py            唯一 CLI 入口
  cliutil.py                 输出信封、退出码、错误模型
  usbcapture.py              USB Trace 采集传输层（VCD + LOG）/ 设备枚举（Windows）
  tracevcd.py                字流 → VCD 解码器
  logparse.py                LOG 包解析
  loganalysis.py             LOG 事实提取 + 规则引擎
  analyze_vcd.py             波形事实提取
  usbshell.py                USB Shell 命令解析（hex → EP5 OUT 帧）
  vcdcheck/vcdcheck.py       断言引擎
  config.py                  配置读写、路径解析
src/                         VS Code 扩展（TypeScript）
  extension.ts  commands.ts  captureManager.ts  configFile.ts  cli.ts  python.ts
  devices.ts                 设备号推导与采集产物路径
  presets.ts                 采集预设的交互流程
  shell.ts                   USB Shell 输入解析与危险命令判定
  vcdFile.ts                 选择并打开任意 VCD 文件
  docs.ts  deploy.ts         文档打开、CLI 稳定路径落位
  webview/                   面板 UI 与 webview 资源
  walkthrough/               首次安装引导的 markdown
scripts/                     构建脚本

构建（开发）

npm install
npm run copy-assets    # 复制 Python 脚本/静态资源/文档到 resources/
npm run compile        # tsc 编译到 out/
npm run package        # 打包（内置 copy-assets + compile），产出 usbtrace-x.x.x.vsix

scripts/copy-assets.js 决定哪些 Python 模块与文档进 .vsix； 新增模块或文档必须同步加进去，否则打包出的扩展会缺文件。
resources/ 与 out/ 是构建产物（已 gitignore），每次构建会重建。

USB Trace 采集分析

Aaronlu2026

USB Trace 采集分析

快速开始

功能

常见问题

命令行

文档

设置

目录结构

构建（开发）