企业官网建设流程全解析

• 嵌入式
• 硬件开发
• 固件
• 通信

本文以官方 Synchronization Checklist 为主线，结合 External Clock Interface 与 Hardware Triggering 文档以及hackrf_clock、hackrf_debug、hackrf_transfer的源码实现，系统讲解如何让多台 HackRF 设备实现真正意义上的同步工作。读完本文，你将掌握共享时钟的接线与电气规格、用hackrf_clock检测/启用时钟信号的完整命令、用hackrf_transfer -H完成硬件触发同步采集的实战流程，以及借助hackrf_debug定位 USB 吞吐丢样的方法。

为什么需要多设备同步

在很多应用场景中，单台 HackRF 设备无法满足需求：例如使用相控阵天线（phased antenna array）实现测向（direction finding）或波束成形（beamforming）时，需要多台 HackRF 同时采样同一信号的不同空间相位。此时，各设备之间不仅要求载波频率与采样率精确一致，还要求采样起始时刻严格对齐——前者依赖共享时钟，后者依赖硬件触发。

HackRF 的触发机制提供了误差小于一个采样周期的时间同步能力（见 hardware_triggering.rst），因此在合理的接线与配置下，多台 HackRF 可以组成低成本的多通道相参接收系统。

同步的两大支柱：共享时钟 + 硬件触发

多设备同步本质上需要解决两个独立的问题：

本文的排查清单正是围绕这两大支柱展开。以下按官方清单的顺序逐项排查。

排查第 1 项：固件与主机软件版本

症状特征：多设备无论如何配置都无法同步。

排查动作：确认所有设备运行最新固件，主机端使用最新版 host 软件与 libhackrf。

官方文档明确指出"There have been many bug fixes"，历史版本中存在的同步相关缺陷较多。另外，清单中两项关键诊断能力（hackrf_clock -i的时钟检测、hackrf_debug -S的 M0 状态读取）均要求2022.09.1 或更新版本的主机软件，旧版本会给出错误结果。

排查第 2 项：操作是否指向了正确的目标设备

症状特征：配置了时钟或触发，但同步毫无效果——可能你改错了设备。

排查动作：连接多台 HackRF 后，必须显式指定每一条命令操作哪台设备。命令行工具统一通过-d <serial number>参数指定目标设备：

hackrf_clock -i -d 00000000000000000000000000000000000000001234 hackrf_debug -S -d 00000000000000000000000000000000000000005678

先用hackrf_info列出所有已连接设备的序列号（这也是 hardware_triggering.rst 推荐的第一步）。-d选项在hackrf_clock、hackrf_debug、hackrf_transfer中均已实现（例如 hackrf_clock.c 中的-d, --device <serial_number>说明），并最终通过 libhackrf 的hackrf_open_by_serial()打开指定设备。

排查第 3 项：所有 HackRF 是否共享同一个时钟

症状特征：各设备频率与采样率存在微小偏差，无法完全对齐。

排查动作：如果各设备使用各自内部晶振，频率与采样率不可能精确一致。必须让所有设备共享同一个 10 MHz 参考时钟。

HackRF One 的时钟接口规格

HackRF One 的时钟特性（详见 external_clock_interface.rst）：

• CLKOUT SMA 端口：输出 3.3 V、10 MHz 方波，面向高阻抗负载设计；
• CLKIN SMA 端口：高阻抗输入，期望 3.3 V、10 MHz 方波。不要超过 3.3 V、不要低于 0 V；不要接入非 10 MHz 频率的时钟（除非自行修改固件支持）；
• 可以将一台 HackRF One 的 CLKOUT 直接连接另一台的 CLKIN（直连即满足电气规格）；
• HackRF One 检测到 CLKIN 信号后，会用外部时钟替代内部晶振，且切换动作仅在收发操作开始时发生；
• P22 排针注意：CLKIN 信号同时连接到板内 P22 排针的 pin 2。HackRF One 只有一个CLKIN 信号，由 CLKIN 端口与 P22 pin 2 共享，因此不要同时在 CLKIN 与 P22 pin 2 上接入输入信号。

HackRF Pro 的时钟接口差异

HackRF Pro 有两个可配置的 SMA 端口 P1 与 P2：

• 默认 P1 配置为 CLKIN、P2 配置为 CLKOUT；
• 第二个 CLKIN 信号位于 P22 排针 pin 2，且P22_CLKIN 与 P1_CLKIN 是相互独立的信号（与 HackRF One 不同）。改用 P22 作为时钟输入：

hackrf_clock -c p22

• 也可以把其他内部信号连接到 P1 或 P2，替代默认的 CLKIN/CLKOUT：

hackrf_clock -1 <signal> # 配置 P1 hackrf_clock -2 <signal> # 配置 P2

从 hackrf_clock.c 的解析逻辑可以看到，P1 可选的信号包括clkin、trigger_in、trigger_out、p22_clkin、pps_out、aux_clk1、aux_clk2、off；P2 可选clkout、trigger_in、trigger_out。这意味着在 HackRF Pro 上，P1/P2 可以同时承担时钟与触发两种角色（这也是 hardware_triggering.rst 提到的"P1/P2 可同时提供时钟同步与触发"）。

时钟共享的额外收益

在触发场景中，先让两台设备共享时钟还有一个额外好处：将两台设备的参考地互连，从而省去硬件触发所需地线中的一根（详见 hardware_triggering.rst）。无论哪台设备作为触发源，都可以由任意一台为另一台提供时钟。

排查第 4 项：时钟输入是否被正确检测

症状特征：CLKIN 已经接入 10 MHz 信号，但设备仍在使用内部晶振。

排查动作：使用hackrf_clock -i检查时钟输入状态，务必用-d指定序列号：

hackrf_clock -i -d <serial number>

预期输出（源码 hackrf_clock.c 中的打印逻辑）：

• 检测到时钟：CLKIN status: clock signal detected
• 未检测到时钟：CLKIN status: no clock signal detected

注意事项：

• 该功能要求2022.09.1 或更新主机软件；
• 文档特别警告：旧式做法——用hackrf_debug检查时钟输入——在部分硬件版本上结果不可靠，请勿继续使用。底层实现上，hackrf_clock -i调用 libhackrf 的hackrf_get_clkin_status()，经由厂商 USB 请求读取时钟芯片状态（见 hackrf.c）。

排查第 5 项：CLKOUT 是否已经启用

症状特征：用另一台 HackRF 作为时钟源（CLKOUT 接 CLKIN），但接收方始终检测不到时钟。

排查动作：HackRF 的 CLKOUT 默认是关闭的，必须显式启用：

hackrf_clock -o 1 -d <serial number> # 启用 CLKOUT hackrf_clock -o 0 -d <serial number> # 关闭 CLKOUT

同样建议配合-d明确指定作为时钟源的那台设备，避免误操作。

排查第 6 项：CLKIN 波形是否符合规格

症状特征：检测结果时有时无，或设备虽"检测到"时钟但相位噪声明显偏大。

规格要求与常见问题（官方文档明确列出）：

• 理想波形：0 V 至 3.0~3.3 V 之间的10 MHz 方波；
• 正弦波可用但相位噪声更大：如果必须用正弦波（例如来自信号发生器的 10 MHz 参考），功能上可行，但会恶化相噪指标；
• 未缓冲的 TCXO 输出可能电压不足：某些板载温补晶振（TCXO）的直接输出未经缓冲，驱动能力与电平不足以满足 CLKIN 高阻抗输入的阈值要求；
• 部分硬件版本对超规格时钟输入的容忍度更低：同一套时钟源在不同批次/版本硬件上的表现可能不同。

如果波形达标但检测仍失败，可借助hackrf_clock -r <clock_num>或hackrf_clock -a读取 SI5351C 时钟芯片的寄存器和 multisynth 配置，确认时钟源选择（XTAL/CLKIN）是否按预期切换（相关读取逻辑见 hackrf_clock.c）。

排查第 7 项：硬件本身是否存在故障

症状特征：接线与配置完全正确，CLKIN 检测仍失败。

重要提醒：市面上部分 HackRF 克隆产品存在 CLKIN 端口不可用（non-functional）的批次。若排除了软件与接线问题，应怀疑硬件故障。官方文档明确记录了这一点，因此选购与排查时都需留意。

排查第 8 项：所有设备是否通过硬件触发同时启动

症状特征：各设备频率一致，但采样起始时刻仍有毫秒级偏差。

排查动作：如果不用硬件触发，各设备的启动时刻无法精确对齐。必须按 hardware_triggering.rst 的说明连接触发信号，并用hackrf_transfer -H让设备等待触发输入。

触发信号规格

• 触发信号是3.3 V 的脉冲，在上升沿触发；
• 触发输入/输出也可以连接非 HackRF 的外部设备；
• 多设备场景下，确保所有设备共享地线后，把一台设备的触发输出接到其余各设备的触发输入（例如通过面包板跳线）。

操作示例（两台 HackRF One 同步接收）

第一步：用hackrf_info获取两台设备的序列号。

第二步：在终端一，用被触发设备的序列号启动带-H的接收，命令会打印Waiting for trigger...并等待触发信号（对应源码 hackrf_transfer.c 中的输出逻辑）：

hackrf_transfer -H -d <serial number A> -a 0 -l 32 -g 32 -r rx1.cs8

第三步：在另一终端，用触发设备的序列号启动接收——不需要任何特殊参数即可激活触发输出（hw_sync关闭时设备默认处于触发输出模式）：

hackrf_transfer -d <serial number B> -a 0 -l 32 -g 32 -r rx2.cs8

两条命令将在同一时刻开始采样，时间同步误差小于一个采样周期。

关键细节：如果同时启动多个带-H的hackrf_transfer实例，必须先让它们都进入Waiting for trigger...状态，再发送触发信号，否则尚未就绪的实例会错过触发。

底层实现：硬件同步模式

-H选项在 hackrf_transfer.c 中被解析为hw_sync = true，随后调用hackrf_set_hw_sync_mode(HW_SYNC_MODE_ON)（见 hackrf_transfer.c）。在固件侧，该请求由 usb_api_transceiver.c 的usb_vendor_request_set_hw_sync_mode处理，最终写入 radio 的RADIO_TRIGGER寄存器——也就是说，"等待触发"并非主机侧轮询，而是设备硬件/固件层面的门控，这正是能够达到亚采样周期精度的原因。

HackRF One 触发接线的硬件操作

HackRF One 的硬件触发需要打开外壳访问板内排针（HackRF Pro 则可通过 P1/P2 SMA 端口实现，无需开盖）：

1. 开盖：每个外壳由小型塑料卡扣固定，开盖时卡扣可能损坏，但通常不影响继续使用；
2. 找到 P28 排针：HackRF One 有 4 个常规焊接的排针，其中 3 个呈 C 形排列，板上标记为 P28、P22、P20；P28 是其中最靠近板中央的排针；
3. 定位触发引脚：P28 排针的pin 15 = 触发输出（trigger output），pin 16 = 触发输入（trigger input）。接线前可参照下图确认引脚位置：

4. 共地：先确保两台设备共地——推荐将一台的 CLKIN 接到另一台的 CLKOUT（如前文"时钟共享"所述，顺带完成共地），或者用跳线连接两台设备 P28 的 pin 2；
5. 连接触发线：用一根跳线，把一台设备的P28 pin 15（触发输出）接到另一台设备的P28 pin 16（触发输入）。

所需器材：一根 0.1" 排针公对公跳线，以及一根用于时钟同步的 SMA 线缆（或第二根跳线）。

GNU Radio 的限制

目前 GNU Radio 的 Osmocom 与 Soapy 模块均不支持硬件触发。Osmocom 模块的界面看起来支持相关选项，但实际上这些选项不产生任何效果（官方文档明确说明）。需要硬件触发同步时，请使用hackrf_transfer -H或基于 libhackrf 自研的调用hackrf_set_hw_sync_mode()的程序。

排查第 9 项：USB 吞吐是否存在丢样（shortfall）

症状特征：同步采集的数据后期处理时发现两路信号相位漂移或偶发错位。

原理：如果 RX 采样被丢弃（overrun）或 TX 采样被延迟（underrun），流中会出现缺失/迟到的样本，直接导致多路信号失去同步。

排查动作：在软件运行完毕后，对每台设备执行：

hackrf_debug -S -d <serial number>

该命令打印设备的 M0 状态（对应 hackrf_debug.c 的print_state），重点关注：

• Number of shortfalls：若非零，说明 RX 有丢弃或 TX 有迟到，信号必然失步；
• Longest shortfall：单次最长的欠载字节数；
• 相关字段还包括Requested mode、Active mode、M0 count、M4 count、Shortfall limit、Mode change threshold、Error等（错误码定义见 hackrf_debug.c，包括RX_TIMEOUT、TX_TIMEOUT、MISSED_DEADLINE）。

hackrf_debug -S依赖 M0 状态读取，同样要求 2022.09.1 或更新主机软件。

强制止损：若希望"只要出现 shortfall 就让设备停止"以便及时发现问题，可设置零容忍：

hackrf_debug -T 0 -R 0 -d <serial number>

其中-T为 TX underrun 限制（字节数）、-R为 RX overrun 限制（字节数），置 0 表示对任何字节的 shortfall 都零容忍。底层通过 libhackrf 的hackrf_set_tx_underrun_limit()/hackrf_set_rx_overrun_limit()下发（见 hackrf.c），固件侧由 usb_api_transceiver.c 写入_tx_underrun_limit/_rx_overrun_limit，供 M0 在流传输中实时判决。

排查第 10 项：各设备是否共享 USB 总线

症状特征：低采样率下同步正常，高采样率下 shortfall 频发。

结论：单台 HackRF One 在 20 MHz 采样率下几乎占满一整条 USB 2.0 总线的带宽。因此，除非采样率很低，否则每台 HackRF 应连接到各自独立的 USB 总线（例如独立根端口或独立 USB 控制器）。将多台设备串联在同一个 USB Hub 上，几乎必然导致带宽不足与丢样，进而破坏同步。

这一限制在源码中同样可以印证：hackrf_transfer的采样率上限为 20 MHz（hackrf_transfer.c 中SAMPLE_RATE_MAX_HZ = 20000000），20 MHz、8 bit 双通道 IQ 数据流对应的 USB 传输速率已经逼近 USB 2.0 高速模式的实际吞吐上限。

快速自查对照表

进一步阅读

• 同步排查清单原文
• 外部时钟接口详解
• 硬件触发详解
• 工具源码：hackrf_clock、hackrf_debug、hackrf_transfer
• 底层库与固件：libhackrf、固件 USB 收发请求

• 嵌入式
• 硬件开发
• 固件
• 通信