document hardware triggering

This replaces outdated documentation of an older trigger mechanism.

docs/source/expansion_interface.rst

@@ -215,9 +215,9 @@ SDIO, GPIO, clocks, and CPLD.
   * - 14  
     - GCK1
   * - 15  
-    - B1AUX14
+    - B1AUX14 (trigger output)
   * - 16  
-    - B1AUX13
+    - B1AUX13 (trigger input)
   * - 17  
     - CPLD_TCK
   * - 18  
@@ -233,4 +233,4 @@ SDIO, GPIO, clocks, and CPLD.
 
 Additional unpopulated headers and test points are available for test and development, but they may be incompatible with some enclosure or expansion options.
 
-Refer to the schematics and component documentation for more information.
+Refer to the schematics and component documentation for more information.

docs/source/external_clock_interface.rst

@@ -2,10 +2,14 @@
 External Clock Interface (CLKIN and CLKOUT)
 ===========================================
 
-HackRF One produces a 10 MHz clock signal on CLKOUT. The signal is a 10 MHz square wave from 0 V to 3 V intended for a high impedance load.
+.. _external_clock_interface:
 
-The CLKIN port on HackRF One is a high impedance input that expects a 0 V to 3 V square wave at 10 MHz. Do not exceed 3.3 V or drop below 0 V on this input. Do not connect a clock signal at a frequency other than 10 MHz (unless you modify the firmware to support this). You may directly connect the CLKOUT port of one HackRF One to the CLKIN port of another HackRF One.
+HackRF One produces a 10 MHz clock signal on CLKOUT. The signal is a 3.3 V, 10 MHz square wave intended for a high impedance load.
+
+The CLKIN port on HackRF One is a high impedance input that expects 3.3 V square wave at 10 MHz. Do not exceed 3.3 V or drop below 0 V on this input. Do not connect a clock signal at a frequency other than 10 MHz (unless you modify the firmware to support this). You may directly connect the CLKOUT port of one HackRF One to the CLKIN port of another HackRF One.
 
 HackRF One uses CLKIN instead of the internal crystal when a clock signal is detected on CLKIN. The switch to or from CLKIN only happens when a transmit or receive operation begins.
 
 To verify that a signal has been detected on CLKIN, use ``hackrf_clock -i``. The expected output with a clock detected is `CLKIN status: clock signal detected`. The expected output with no clock detected is `CLKIN status: no clock signal detected`.
+
+To activate CLKOUT, use ``hackrf_clock -o 1``. To switch it off, use ``hackrf_clock -o 0``.

docs/source/hardware_triggering.rst

@@ -0,0 +1,81 @@
+===================
+Hardware Triggering
+===================
+
+HackRF One transmit and receive operations can be synchronized with another HackRF One or with other external equipment by using the trigger input and output on pin header P28. Triggering provides time synchronization with error of less than one sample period.
+
+
+Clock Synchronization
+~~~~~~~~~~~~~~~~~~~~~
+
+When triggering one HackRF One from another, it is often desirable to first ensure that the two devices share a common frequency reference. This has an added benefit of grounding the HackRFs to each other, eliminating one of the wires required for triggering. See :ref:`External Clock Interface <external_clock_interface>` for instructions.
+
+Either HackRF One may serve as the clock source for the other regardless of which is providing the trigger output.
+
+
+Requirements
+~~~~~~~~~~~~
+
+To connect two HackRF Ones for triggering you will need:
+
+    * a male-to-male jumper wire for 0.1" pin headers
+    * an SMA cable for clock synchronization or a second jumper wire
+
+
+.. _open_your_hackrf_one:
+
+Open Your HackRF One
+~~~~~~~~~~~~~~~~~~~~
+
+The HackRF One case has small plastic clips holding it together. These may be damaged when the case is opened, but typically the case can still be used after such damage. Please follow the instructions in `this video <https://www.youtube.com/watch?v=zuXJtpTSEJM>`__ by `Jared Boone <https://twitter.com/sharebrained>`__.
+
+Open the enclosures of both HackRF Ones to access their pin headers.
+
+
+Identify the Trigger Pins
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HackRF One has four normally-populated pin headers, three of which are arranged in a 'C' shape. On the circuit board these are marked P28, P22, and P20. P28 is the header nearest to the center of the board. Locate pins 15 (trigger output) and 16 (trigger input) on header P28.
+
+.. image:: ../images/trigger-pins.png
+	:align: center
+
+
+Connect the Trigger Output to the Trigger Input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First ensure that the two devices share a common ground. This may be accomplished by connecting one's CLKIN to the other's CLKOUT as recommended above. Alternatively, connect a jumper wire from P28 pin 2 on one HackRF One to P28 pin 2 on the other HackRF One.
+
+Next use a jumper wire to connect P28 pin 15 (trigger output) on one HackRF One to P28 pin 16 (trigger input) on the other HackRF One.
+
+
+Usage
+~~~~~
+
+Use ``hackrf_info`` to discover the serial numbers of both HackRF Ones. Using the serial number of the HackRF One to be triggered, use ``hackrf_transfer -H`` to set up a triggered operation. For example:
+
+* ``hackrf_transfer -H -d <serial number> -a 0 -l 32 -g 32 -r rx1.cs8``
+
+The command will print "Waiting for trigger..." until a trigger signal is detected on the device's trigger input.
+
+In another terminal, use the serial number of the triggering HackRF One to initiate an operation to take place at the same time as the triggered operation. For example:
+
+* ``hackrf_transfer -d <serial number> -a 0 -l 32 -g 32 -r rx2.cs8``
+
+Note that no special argument is required to activate the trigger output.
+
+Both ``hackrf_transfer`` commands will start sampling RF signals at the same time, accurate to less than one sample period.
+
+
+Additional Devices
+~~~~~~~~~~~~~~~~~~
+
+Multiple HackRF Ones may be triggered by a single HackRF One. Ensure that all the devices share a common ground and then connect one device's trigger output to the trigger inputs of the other devices (with jumpers connected via a breadboard, for example).
+
+Equipment other than a HackRF One may be connected to a HackRF One's trigger input or output. The trigger signal is a 3.3 V pulse that triggers on the rising edge.
+
+
+References
+~~~~~~~~~~
+
+HackRF's trigger mechanism was contributed by the authors of `Synchronisation of Low-Cost Open Source SDRs for Navigation Applications <http://spcomnav.uab.es/docs/conferences/Bartolucci_NAVITEC_2016.pdf>`__ which provides details about the implementation and background.

docs/source/index.rst

@@ -43,7 +43,7 @@ Welcome to HackRF's documentation!
    hackrfs_buttons
    external_clock_interface
    expansion_interface
-   multiple_device_hardware_synch
+   hardware_triggering
    rf_shield_installation
 
 .. toctree::

docs/source/multiple_device_hardware_synch.rst

@@ -1,147 +0,0 @@
-================================================
-Multiple Device Hardware Level Synchronization
-================================================
-
-Purpose
-~~~~~~~
-
-This page describes the modifications required to get multiple HackRF hardware-level synchronisation working. Synchronisation is required for many applications where a single HackRF isn't sufficient:
-
-    * phase correlation
-    * oversampling using multiple devices
-    * 40MHz (or more) protocols such as WiFi
-
-The HackRFs will start transmitting USB packets at the same time, which results in an inter-device offset of ~50 samples at a sample rate of 20MSps. Without this synchronisation, the offset is in the range of thousands to tens of thousands of samples. This is due to the USB start command being called sequentially for each device, along with USB buffering, OS-level timing etc.
-
-
-
-**BE WARNED** you will have to open your HackRFs, which is most likely going to destroy the plastic case it comes in. You will also be electrically connecting them together. If you do this incorrectly, there is a good chance one or all of the devices will be permanently destroyed.
-
-
-
-Related work
-~~~~~~~~~~~~
-
-\"bardi\_\" on the #hackrf channel pointed out his paper on synchronising HackRFs. This uses the HackRF CPLD to synchronise multiple devices.
-
-
-
-Requirements
-~~~~~~~~~~~~
-
-For this to work you will need:
-
-    * at least two devices
-    * a clock sync cable
-    * some connecting cables (pin header-type)
-    * a breadboard
-
-
-.. _opening_your_hackrf:
-
-Opening your HackRF
-~~~~~~~~~~~~~~~~~~~
-
-The HackRF case has small plastic clips holding it together. These are usually destroyed when the case is opened. Please follow the instructions in `this video <https://www.youtube.com/watch?v=zuXJtpTSEJM>`__ by `Jared Boone <https://twitter.com/sharebrained>`__.
-
-
-
-Connect the clocks
-~~~~~~~~~~~~~~~~~~
-
-Connecting the HackRF clocks together will force them to sample at precisely the same rate. The individual samples will most likely be sampled at slightly different times due to phase offsets in the clock ICs, but for most purposes this is acceptable.
-
-Choose a **primary** HackRF, and connect the clock sync cable from the clock out connector to the clock in connector of the **second** HackRF. If you're using another HackRF, connect the second HackRF's clock out to the **third** HackRF's clock in.
-
-Your HackRFs should look like this: 
-
-.. image:: ../images/hackrf-clock-sync.jpg
-	:align: center
-
-
-
-Identify the pin headers
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Firstly, this has only been tested on official HackRF Ones. If you have a jawbreaker, HackRF blue or another HackRF-inspired device, you will have to figure out how to connect the devices correctly, using the schematics.
-
-The hackrf has four pin headers, three of which are arranged in a 'C' shape. On the board these are marked as *P28*, *P22* and *P20*. *P20* is the header closest to the *clock in/clock out* connectors. For this exercise we will only be discussing *P20*. The `hackrf schematics <https://github.com/mossmann/hackrf/tree/master/hardware/hackrf-one>`__ are a very good reference for this activity. The relevant part can been seen in the following image:
-
-.. image:: ../images/hackrf-pin-headers.jpg
-	:align: center
-
-This is the P20 schematic diagram: 
-
-.. image:: ../images/hackrf-pin-headers-p20.png
-	:align: center
-
-
-
-Wire up the pin headers
-~~~~~~~~~~~~~~~~~~~~~~~
-
-As mentioned before **BE WARNED**, this step could easily result in **one or all** of your HackRFs being **permanently damaged**.
-
-Now that's out of the way, let me describe what we're doing here. The first part of this exercise is to give both devices a common ground. This is really important for any inter-device electrical connections, as it prevents ICs from seeing slight differences in the respective GND levels as legitimate signals. As shown on the schematic, many of the pins in P20 are GND pins. We use P20-PIN19 on both devices and connect them together like so: 
-
-.. image:: ../images/hackrf-pin-headers-p20-19-gnd.jpg
-	:align: center
-
-.. image:: ../images/hackrfs-gnd-connection.jpg
-	:align: center
-
-We then need a *positive* (+5v) connection to 'fake' the *third* hackrf if it's not present. We use *P20-PIN3* from the **primary** hackrf for this, and bring it down to the breadboard. *primary:P20-PIN8* and *secondary:P20-PIN8* are ready input GPIO pins for the missing third HackRF. Connect these to the breadboard *positive* line. After this your setup should look like so: 
-
-.. image:: ../images/hackrf-pin-headers-p20-3-positive.jpg
-	:align: center
-
-.. image:: ../images/hackrf-pin-headers-p20-3-8-3rd.png
-	:align: center
-
-Next we connect the *primary:P20-PIN7 ready* GPIO pin input to the *secondary:P20-PIN5 ready* GPIO pin output, and the *primary:P20-PIN5 ack* GPIO pin output to the *secondary:P20-PIN7* ack GPIO pin input. This is the final step, and should look as follows:
-
-.. image:: ../images/hackrf-pin-headers-ack-ready-colours.jpg
-	:align: center
-
-.. image:: ../images/hackrf-pin-headers-ack-ready.jpg
-	:align: center
-
-
-
-Upgrade
-~~~~~~~
-
-Now that the hardware is setup, you need to upgrade your HackRFs' firmware, and your *libhackrf* to at least `v2017.02.1 <https://github.com/mossmann/hackrf/releases/tag/v2017.02.1>`__ as per :ref:`this documentation page <updating_firmware>`.
-
-
-
-Testing with hackrf_transfer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The latest version of *hackrf_transfer* includes the '-H' flag, which will activate hardware synchronisation (via libhackrf via the firmware). Testing this way is a little tricky because neither HackRF will start sending data until they are synched, and *hackrf_transfer* will time out if it hasn't received any data within one second. So the test requires that **two** copies of _hackrf_transfer are started within 1 second of each other. My approach is to have two terminal windows with the relevant commands waiting, and quickly run them.
-
-This test will fail if:
-
-    * your hackrf firmware or libhackrf are out of date
-    * your connectors are incorrectly set up
-    * your timing is too slow when running hackrf_transfer
-
-Run the following command:
-
-    * hackrf_transfer -d <device A> -r <filename-A> -H &; hackrf_transfer -d <device B> -r <filename-B> -H
-
-If the test runs correctly, you have successfully streamed synchronised data from two HackRFs!
-
-The two streams can be merged into one using GnuRadio, and then viewed using `this hacky piece of PyQt <https://github.com/dodgymike/direction-finding/blob/master/decode_remote_dual_stream.py>`__.
-
-
-
-What next?
-~~~~~~~~~~
-
-Obviously the method of wiring up multiple HackRFs described above is fragile and prone to error. Perhaps a PCB could be designed that will connect up to four HackRFs together by plugging into the 'C-shape' pin headers.
-
-Usually the *Osmocom source* can be used for multi-device streaming, as it can be configured to pull from more than one device. Unfortunately the current version does not have hardware synchronisation built in. Work is being done to make the *Osmocom source* compatible with these changes.
-
-.. image:: ../images/grc-hw-sync-streaming.png
-	:align: center

docs/source/rf_shield_installation.rst

@@ -10,7 +10,7 @@ Official Great Scott Gadgets HackRF Ones do not come from the factory with an RF
 
   **BE WARNED: Opening the plastic case of your HackRF One will most likely destroy the tabs that hold it together.**  
 
-  Instructions for removing a HackRF One from it's case can be found :ref:`here <opening_your_hackrf>`.
+  Instructions for removing a HackRF One from its case can be found :ref:`here <open_your_hackrf_one>`.