HX Wireless BLE Analyzer 用户指南

HX Wireless BLE Analyzer 用于实时 BLE 抓包、设备筛选、解密和 Timing 分析。本文对应 **v0.8.6 Windows 本地测试版**；公开下载仍以[下载与快速开始](https://docs.wireless-tech.cn/doc/184/)提供的版本为准。截图含演示数据和真实历史抓包，新版客户视图默认融合跨节点同包。

顶部是采集和更新操作，右侧是分析侧栏，底部可展开 Timing。上图用于定位界面区域；下文的融合规则适用于 v0.8.6 测试版。

## 开始抓包或打开文件

1. 打开已有记录时，点击「打开 PCAPNG」，选择 PCAPNG 文件，便可离线查看包列表、详情和时序。
2. 实时抓包时，用支持数据传输的 Type-C 线连接 HX 采集器，结束占用同一采集器的其他录制或升级任务。Windows 若未识别设备，检查 WinUSB 驱动。
3. 点击「开始抓包」。先用全部外设发现广播。要跟踪某个设备的 ACL 连接，请先选中该设备，再让它发起一次新连接。
4. 点击「停止抓包」结束录制，保留 PCAPNG。若仅暂停了实时预览，可点「继续实时预览」。暂停预览期间仍会写入文件。

Windows 公开测试包默认在解压目录的 `captures` 保存抓包。macOS 测试 App 默认在用户资源库的 `Application Support/HX Wireless BLE Analyzer/captures` 保存抓包。通过「About」可核对当前数据目录。

### 从包列表直接抓指定设备

在左侧设备分组或可识别归属的报文上右键，选择「抓取此设备」。软件用该设备的 MAC 地址开始新的录制。**录制期间执行此操作会丢弃正在录制的文件。需要保留本次抓包时，请先点「停止抓包」。**

在已识别归属的报文上右键，菜单显示广播名、MAC 地址和地址类型。

在「全部外设 · 按设备归组」下拉框中，已捕获到有效广播名称的设备会在 MAC 地址前显示名称，也会列出地址类型和客户视图的包数。短名称、完整名称都可能来自广播或扫描响应。设备没有发出名称、名称报文未抓到或无法可靠解析时，仍可用 MAC 地址选择设备。同名设备请按地址区分。

## 显示筛选、包详情和 ATT 事务

通过工具栏显示或隐藏「分析侧栏」，也可拖动分隔线调整宽度。鼠标停在工具栏按钮上，可查看对应功能说明。

- **详情**显示选中包的协议字段和 HEX。展开感兴趣的协议层，或点击时序帧结构中的字段定位相关字节。
- **显示筛选**可按目标设备、包类型等条件缩小当前列表。修改筛选只改变界面显示，已写入的 PCAPNG 仍保留对应报文。要改变采集目标，请使用「抓取此设备」。
- **解密密钥**用于输入当前分析所需的解密或地址解析资料。结果直接体现在相关报文和详情中。
- **选区统计**用于查看 Timing 所选时段的统计。分析 GATT 交互时，可以切换到「ATT 事务」查看已关联的请求和响应，并回到对应帧。

在右侧「显示筛选」切换到「包类型」，展开分类后点选。

## 四节点同包融合与调试视图

采集器由四个接收节点组成。v0.8.6 测试版默认把它们对**同一个空口包**的观测合成一条，抓包列表、Timing 和设备计数都按整体采集器显示。选中融合包时，右侧「详情」会列出 Node、原始帧号和接收时间偏差。Status 正常时只显示 `OK`，时间依据在详情中查看。原始 PCAPNG、帧号和 HEX 不改写。

| 客户视图 | 调试视图 |
| --- | --- |
| 同一空口包只占一条；可看 1–4 个接收节点 | 勾选「显示筛选 → 通用 → 调试：逐条显示各节点接收记录」，查看每条原始观测 |

软件仅在完整空口字节、信道、PHY、方向一致，属于不同节点和同一同步时钟域，并且时间相差不超过 100 µs 时融合。CRC 失败、字节不完整、本地时钟或证据不足的包保持独立，避免把重传误合并。普通广播、扩展广播、建链、ACL、LL 控制及等时包适用同一规则。选择按采集节点或接口查看 Timing 时会自动打开调试视图。

![四节点同包在客户视图合为一条，详情保留各节点来源](https://docdisk.wireless-tech.cn/img/2026/11/12/511c76d2f097434fa696d937a6f65b786794.png)

上图用于定位「显示筛选」入口。新版测试包另附完整的图文指南和融合实拍截图。

## 在原报文中查看解密内容

1. 选择要分析的报文。离线解密 ACL 时，先选中所属连接。要获取完整加密上下文，请在目标连接前开始抓包。
2. 打开「解密密钥」，选择 Key Type，填写对应资料，点「应用密钥」。
3. 回到左侧报文列表，选中原先加密的包，在「详情」中查看通过完整性验证后的明文和可解析字段。需要定位时，可按设备或协议筛选。密钥应用后会重新解析可关联的报文。HEX 区保留抓包中的字节，明文及解码字段可在详情中查看。

| Key Type | 输入与抓包条件 |
| --- | --- |
| Passkey | 输入 6 位十进制配对码。用于 Legacy Pairing，需抓到双方的 Confirm 和 Random 交换。 |
| OOB | 输入 Legacy OOB 的 TK，32 个十六进制字符，需抓到双方的 Confirm 和 Random。 |
| LTK / SC LTK | 输入 32 个十六进制字符的实际长期密钥。应抓到连接建立和加密握手。Secure Connections 界面上的 6 位确认数字属于配对确认，SC LTK 请从有权访问的设备或系统取得。 |
| IRK | 输入 32 个十六进制字符，选择对应的可解析私有地址。用于将 RPA 归属到设备身份。 |
| Mesh Key | 选择「Mesh NetKey」，输入 32 个十六进制字符和对应的 IV Index。解析 Access 层时再添加适用的「Mesh AppKey」或「Mesh DevKey」。AppKey 直接输入 32 个十六进制字符，DevKey 按 `SRC=KEY` 输入，其中 SRC 为 0x0001–0x7FFF 的单播地址。 |
| EAD | 输入 `SessionKey:IV`，前段为 32 个十六进制字符，后段为 16 个十六进制字符。 |

Passkey 和 OOB 请在 Legacy Pairing 开始前应用。IRK 请先将录制目标设为设备当前的 RPA，再应用密钥。实时录制时，可使用「仅重解码所选 ACL 连接」限制 LTK/SC LTK 的应用范围。密钥用完可点「清除全部密钥」。分享抓包前请确认内容，捕获文件可能包含采集端已经解密的载荷。

如果仍只有密文，先核对连接、密钥类型和握手覆盖范围。MIC 或 CMAC 校验失败时，核对密钥、IV、连接上下文和抓包完整性。

选择 EAD 并应用演示密钥后，左侧原报文显示「EAD 明文」。

选中同一报文，在「详情」可查看通过 MIC 验证的明文。下方 HEX 仍显示原始捕获字节。

## 分析时序与空口帧结构

选中报文后打开 Timing。时序条显示该包在时间轴上的位置，选中帧的放大结构可独立查看。字段较多时横向滚动，悬停查看字段全名，点击字段定位详情或 HEX。缩放只改变显示比例，时间差以标尺和 A/B 读数为准。

选中 ADV_EXT_IND 后展开 Timing。下方分行显示空口字段、包头字段和载荷字段，图中可见 AuxPtr。

- **查看单包**：点击时序中的包条定位帧。用鼠标滚轮缩放时间轴，Ctrl 加滚轮可查看单包。
- **测量间隔**：右键放置 A、B，拖动标记，可吸附到包头或包尾。查看两点间隔或对应选区统计。
- **扩展广播与 AUX**：先看主广播的 AuxPtr。它提供后续包的信道、偏移和 PHY。已捕获且能关联的 AUX 报文可进一步查看。若只捕获到指针，或缺少确认子类型所需的证据，仍可检查当前帧已经收到的公共字段。
- **连接、Mesh 与等时包**：对于可识别的帧，按已捕获内容展示对应帧结构，例如 ACL 数据或控制报文、Mesh 广播承载、CIS/BIS。Mesh 在其承载帧中展开，能看到的网络层、传输层和 Access 字段取决于捕获内容和可用密钥。
- **时间来源**：在右侧详情查看所选包的时间依据。使用文件时间和估算包长时，读数适合定位和对照；跨采集节点做精确测量前，先确认同步时钟域。

### CRC、未知 PDU 与原始数据

CRC 是空口帧的完整性检查。显示「CRC 未通过」表示抓包中记录的接收 CRC 检查失败，或对该帧可用字节进行的 CRC 检查失败。对带接收 CRC 检查结果的文件，软件优先采用该结果。加密载荷也有空口 CRC，解密使用的 MIC 或 CMAC 是另一项检查。

无法可靠确定帧型时，Analyzer 显示「未知 PDU」或「子类型未知」，保留原始 HEX。排查大量未知帧时，先核对捕获来源、接收状态、信道和采集节点。客户视图的包数与原始 PCAPNG 接收记录数不同；未知或异常记录不会因为证据不足而强行融合。

## 指示灯

以下灯号适用于 **Node v1.5.13 候选固件**，尚需实板观察确认。现网 Node v1.5.12 仍使用旧灯号；只更新 Analyzer GUI 不会改变指示灯。候选固件的四颗无线节点采用同一规则，只需区分闪烁、常亮和熄灭：

| 灯号 | 含义 |
| --- | --- |
| 抓包期间蓝灯均匀闪烁 | 扫描或等待目标设备的跟随数据。这是唯一的闪灯方式。 |
| 抓包期间蓝灯常亮 | 本节点实际收到选中设备需要跳频跟随的连接、周期广播或等时数据。 |
| 红灯常亮 | 本轮出现队列溢出、传输丢弃或同步错误；停止后保持，下一轮抓包清除。 |
| 两灯熄灭 | 当前没有抓包会话，也没有锁存异常。 |

停止后蓝灯熄灭而红灯仍亮，表示上一轮异常尚被锁存，也可能是节点的软件故障。先查看工作台异常计数；重启后仍持续时联系维护人员。

单板 WB09 与电脑蓝牙已实测连接和 10 轮双向 GATT 往返，但实时抓包在板到电脑方向两轮分别漏 1 条和 2 条。应用数据互发本身通过，完整抓包验收还在定位中。扩展广播和扩展连接的界面显示已用真实历史文件复查。

## 检查和安装更新

新版测试构建可自动检查。停止抓包后，也可通过「检查更新」手动检查。发现可安装版本时，窗口显示软件和已连接设备的固件版本变化及更新说明。阅读后选择「立即更新」，一次确认即可安装窗口列出的适用更新。若要继续当前工作，可选择「稍后」。

涉及固件时，请先停止抓包并保持 USB 和供电。软件更新成功后会重启应用，固件更新完成后会重新读取版本。公开可用的版本以下载页面和更新窗口实际提供的条目为准。详见 [检查与安装更新](https://docs.wireless-tech.cn/doc/186/)。

遇到设备识别、空列表、AUX 或解密问题，请查看 [常见问题](https://docs.wireless-tech.cn/doc/185/)。