Add a checklist for synchronised operation of multiple HackRFs.

[martinling]

What would you like us to add to or change about the HackRF One documentation?

The discussion in #1340 made me think it would be useful to have a checklist in the documentation for troubleshooting setups that require synchronisation of multiple HackRFs.

Points to include:

• Are you running the latest firmware and host software versions?
  • There have been many bug fixes, so please use the latest release for both.
• Are you applying settings to the right target devices?
  • With more than one HackRF device connected, you always need to specify which one to talk to.
  • Use the -d option with a serial number on the command line to specify which device to target.
  • Check the documentation for GNU Radio blocks for how to select devices by serial number.
• Are all HackRFs sharing a clock via the external clock interface?
  • If not, frequencies and sample rates will not match exactly.
  • Is the clock input being detected? Check with hackrf_clock -i.
    • This requires 2022.09.1 or later host software.
    • The older way of checking using hackrf_debug will not work correctly on all hardware revisions.
  • If the clock input is not being detected:
    • If the clock source is CLKOUT of another HackRF, has it been enabled? Do this with hackrf_clock -o
    • Is the CLKIN waveform correct?
      • It should be a 10MHz square wave between 0V and 3-3.3V.
      • A sine wave is OK but may give greater phase noise.
      • An unbuffered TCXO output may not have sufficient voltage.
      • Some hardware revisions are less tolerant of out-of-spec clock input than others.
    • Is your hardware faulty? Some HackRF clones were sold with a non-functional CLKIN port.
• Are all HackRFs being started together using hardware triggering?.
  • If not, start times will not match exactly.
  • There is currently no support for hardware triggering via the Osmocom or Soapy blocks in GNU Radio.
    • The Osmocom block may look like it supports this but these options do nothing!
  • Use hackrf_transfer with the -H option to enable hardware triggering.
• Are any samples being lost due to USB throughput problems?
  • If RX samples are dropped or TX samples delayed, signals will become out of sync.
  • Are your HackRFs sharing a USB bus?
    • A single HackRF One at 20MHz sample rate uses practically all the bandwidth of a single USB 2.0 bus.
    • Unless using very low sample rates, each HackRF should be connected to its own bus.
  • Use hackrf_debug -S after running your software to check if there were throughput problems.
    • This requires 2022.09.1 or later host software.
    • If the shortfall count for a device is non-zero, some samples were dropped on RX or late for TX.
    • To force shortfalls to stop the device at runtime, use hackrf_debug -T 0 -R 0 to set zero tolerance for shortfalls.