Merge pull request #1540 from miek/docs-improvements

docs: Rename FAQ to troubleshooting, reorganise, and add info on troubleshooting undetected hardware

docs/source/faq.rst

@@ -1,166 +0,0 @@
-.. _faq:
-
-================================================
-FAQ
-================================================
-
-
-What is the Transmit Power of HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF One's absolute maximum TX power varies by operating frequency:
-
-    * 1 MHz to 10 MHz: 5 dBm to 15 dBm, generally increasing as frequency increases (see this `blog post <https://greatscottgadgets.com/2015/05-15-hackrf-one-at-1-mhz/>`__)
-    * 10 MHz to 2170 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases
-    * 2170 MHz to 2740 MHz: 13 dBm to 15 dBm
-    * 2740 MHz to 4000 MHz: 0 dBm to 5 dBm, decreasing as frequency increases
-    * 4000 MHz to 6000 MHz: -10 dBm to 0 dBm, generally decreasing as frequency increases
-
-Through most of the frequency range up to 4 GHz, the maximum TX power is between 0 and 10 dBm. The frequency range with best performance is 2170 MHz to 2740 MHz.
-
-Overall, the output power is enough to perform over-the-air experiments at close range or to drive an external amplifier. If you connect an external amplifier, you should also use an external bandpass filter for your operating frequency.
-
-Before you transmit, know your laws. HackRF One has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your HackRF One legally.
-
-
-----
-
-
-What is the Receive Power of HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The maximum RX power of HackRF One is -5 dBm. Exceeding -5 dBm can result in permanent damage!
-
-In theory, HackRF One can safely accept up to 10 dBm with the front-end RX amplifier disabled. However, a simple software or user error could enable the amplifier, resulting in permanent damage. It is better to use an external attenuator than to risk damage.
-
-
-----
-
-
-What is the minimum signal power level that can be detected by HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This isn't a question that can be answered for a general purpose SDR platform such as HackRF. Any answer would be very specific to a particular application. For example, an answerable question might be: What is the minimum power level in dBm of modulation M at frequency F that can be detected by HackRF One with software S under configuration C at a bit error rate of no more than E%? Changing any of those variables (M, F, S, C, or E) would change the answer to the question. Even a seemingly minor software update might result in a significantly different answer. To learn the exact answer for a specific application, you would have to measure it yourself.
-
-HackRF's concrete specifications include operating frequency range, maximum sample rate, and dynamic range in bits. These specifications can be used to roughly determine the suitability of HackRF for a given application. Testing is required to finely measure performance in an application. Performance can typically be enhanced significantly by selecting an appropriate antenna, external amplifier, and/or external filter for the application.
-
-
-----
-
-
-Is HackRF full-duplex?
-~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF One is a half-duplex transceiver. This means that it can transmit or receive but not both at the same time.
-
-
-----
-
-
-Why isn't HackRF One full-duplex?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF One is designed to support the widest possible range of SDR applications in a single, low cost, portable device. Many applications do not require full-duplex operation. Full-duplex support would have made HackRF larger and more expensive, and it would have required an external power supply. Since full-duplex needs can be met by simply using a second HackRF One, it made sense to keep the device small, portable, and low cost for everyone who does not require full-duplex operation.
-
-
-----
-
-
-How could the HackRF One design be changed to make it full-duplex?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The HackRF One hardware design is actually full-duplex (at lower sample rates) from the USB connection through the ADC/DAC. The RF section is the only part of the design that cannot support full-duplex operation. The easiest way to make HackRF One full-duplex would be to create an add-on board that duplicates the RF section and also provides an external power input (from a wall wart, for example) for the additional power required. This would also require software effort; the firmware, CPLD, libhackrf, and other host software would all need work to support full-duplex operation.
-
-If you were to try to redesign the RF section on HackRF One to support full-duplex, the main thing to focus on would be the MAX2837 (intermediate frequency transceiver). This part is half-duplex, so you would either need two of them or you would have to redesign the RF section to use something other than the MAX2837, likely resulting in a radically different design. If you used two MAX2837s you might be able to use one RFFC5071 instead of two RFFC5072s.
-
-
-----
-
-
-.. _bigspike:
-
-What is the big spike in the center of my received spectrum?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you see a large spike in the center of your FFT display regardless of the frequenecy you are tuned to, you are seeing a DC offset (or component or bias). The term "DC" comes from "Direct Current" in electronics. It is the unchanging aspect of a signal as opposed to the "alternating" part of the signal (AC) that changes over time. Take, for example, the signal represented by the digital sequence:
-
-.. code-block:: sh
-
-	-2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1
-
-This periodic signal contains a strong sinusoidal component spanning from -2 to 9. If you were to plot the spectrum of this signal, you would see one spike at the frequency of this sinusoid and a second spike at 0 Hz (DC). If the signal spanned from values -2 to 2 (centered around zero), there would be no DC offset. Since it is centered around 3.5 (the number midway between -2 and 9), there is a DC component.
-
-Samples produced by HackRF are measurements of radio waveforms, but the measurement method is prone to a DC bias introduced by HackRF. It's an artifact of the measurement system, not an indication of a received radio signal. DC offset is not unique to HackRF; it is common to all quadrature sampling systems.
-
-There was a bug in the HackRF firmware (through release 2013.06.1) that made the DC offset worse than it should have been. In the worst cases, certain Jawbreakers experienced a DC offset that drifted to a great extreme over several seconds of operation. This bug has been fixed. The fix reduces DC offset but does not do away with it entirely. It is something you have to live with when using any quadrature sampling system like HackRF.
-
-A high DC offset is also one of a few symptoms that can be caused by a software version mismatch. A common problem is that people run an old version of gr-osmosdr with newer firmware.
-
-
-
-----
-
-
-
-How do I deal with the big spike in the middle of my spectrum?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Start by reading :ref:`our FAQ Response on the DC Spike <bigspike>`. After that, there are a few options:
-
-    #. Ignore it. For many applications it isn't a problem. You'll learn to ignore it.
-
-    #. Avoid it. The best way to handle DC offset for most applications is to use offset tuning; instead of tuning to your exact frequency of interest, tune to a nearby frequency so that the entire signal you are interested in is shifted away from 0 Hz but still within the received bandwidth. If your algorithm works best with your signal centered at 0 Hz (many do), you can shift the frequency in the digital domain, moving your signal of interest to 0 Hz and your DC offset away from 0 Hz. HackRF's high maximum sampling rate can be a big help as it allows you to use offset tuning even for relatively wideband signals.
-
-    #. Correct it. There are various ways of removing the DC offset in software. However, these techniques may degrade parts of the signal that are close to 0 Hz. It may look better, but that doesn't necessarily mean that it is better from the standpoint of a demodulator algorithm, for example. Still, correcting the DC offset is often a good choice.
-
-
-
----
-
-
-
-What gain controls are provided by HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF (both Jawbreaker and One) provides three different analog gain controls on RX and two on TX.
-
-The three RX gain controls are at these stages:
-
-- RF ("amp", 0 or ~11 dB)
-- IF ("lna", 0 to 40 dB in 8 dB steps)
-- baseband ("vga", 0 to 62 dB in 2 dB steps)
- 
-The two TX gain controls are at these stages:
-
-- RF (0 or ~11 dB)
-- IF (0 to 47 dB in 1 dB steps)
-
-Note: in some documents, the RF gain was erroneously quoted to be 14 dB. The confusion was based on the fact that the MGA-81563 amplifier is advertised as a "14 dBm" amplifier, but that specifies its output power, not its amplification. See `Martin Ling's comment on issue #1059 <https://github.com/greatscottgadgets/hackrf/issues/1059#issuecomment-1060038293>`__ for some details!
-
-----
-
-
-Why is the RF gain setting restricted to two values?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF has two RF amplifiers close to the antenna port, one for TX and one for RX. These amplifiers have two settings: on or off. In the off state, the amps are completely bypassed. They nominally provide around 11 dB of gain when on, but the actual amount of gain varies by frequency. In general, expect less gain at higher frequencies. For fine control of gain, use the IF and/or baseband gain options.
-
-
-----
-
-
-Why are the LEDs on HackRF different colours?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each LED is a single color. There are no multi-colored LEDs on HackRF One. Adjacent LEDs are different colors in order to make them easier to distinguish from one another. The colors do not mean anything.
-
-
-----
-
-
-Where can I purchase HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF is designed and manufactured by Great Scott Gadgets. We do not sell low volumes of HackRFs to people individually; instead we have agreements with specific resellers. Please see our reseller list on the Great Scott Gadgets website for availability: `http://greatscottgadgets.com/hackrf/ <http://greatscottgadgets.com/hackrf/>`__. 
-
-HackRF is open source hardware, so you can also build your own.

docs/source/getting_help.rst

@@ -2,7 +2,7 @@
 Getting Help
 ============
 
-Before asking for help with HackRF, check to see if your question is answered in this documentation, listed in the :ref:`FAQ <faq>`, or addressed in the `HackRF GitHub repository issues <https://github.com/greatscottgadgets/hackrf/issues>`__.
+Before asking for help with HackRF, check to see if your question is answered in this documentation, listed in the :ref:`Troubleshooting <troubleshooting>` page, or addressed in the `HackRF GitHub repository issues <https://github.com/greatscottgadgets/hackrf/issues>`__.
 
 For assistance with HackRF general use or development, please look at the `issues on the GitHub project <https://github.com/greatscottgadgets/hackrf/issues>`__. This is the preferred place to ask questions so that others may locate the answer to your question in the future.
 

docs/source/hackrf_one.rst

@@ -7,7 +7,8 @@ HackRF One
 
 HackRF One is the current hardware platform for the HackRF project. It is a Software Defined Radio peripheral capable of transmission or reception of radio signals from 1 MHz to 6 GHz. Designed to enable test and development of modern and next generation radio technologies, HackRF One is an open source hardware platform that can be used as a USB peripheral or programmed for stand-alone operation.
 
-
+| `Product page <https://greatscottgadgets.com/hackrf/one/>`_
+| `Where to buy <https://greatscottgadgets.com/hackrf/one/#purchasing>`_
 
 Features
 ~~~~~~~~
@@ -27,3 +28,35 @@ Features
     * open source
 
 
+Maximum input power
+~~~~~~~~~~~~~~~~~~~
+
+The maximum input power of HackRF One is -5 dBm. Exceeding -5 dBm can result in permanent damage!
+
+In theory, HackRF One can safely accept up to 10 dBm with the front-end RX amplifier disabled. However, a simple software or user error could enable the amplifier, resulting in permanent damage. It is better to use an external attenuator than to risk damage.
+
+
+Minimum detectable input power
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This isn't a question that can be answered for a general purpose SDR platform such as HackRF. Any answer would be very specific to a particular application. For example, an answerable question might be: What is the minimum power level in dBm of modulation M at frequency F that can be detected by HackRF One with software S under configuration C at a bit error rate of no more than E%? Changing any of those variables (M, F, S, C, or E) would change the answer to the question. Even a seemingly minor software update might result in a significantly different answer. To learn the exact answer for a specific application, you would have to measure it yourself.
+
+HackRF's concrete specifications include operating frequency range, maximum sample rate, and dynamic range in bits. These specifications can be used to roughly determine the suitability of HackRF for a given application. Testing is required to finely measure performance in an application. Performance can typically be enhanced significantly by selecting an appropriate antenna, external amplifier, and/or external filter for the application.
+
+
+Typical maximum transmit power
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HackRF One's maximum TX power varies by operating frequency:
+
+    * 1 MHz to 10 MHz: 5 dBm to 15 dBm, generally increasing as frequency increases (see this `blog post <https://greatscottgadgets.com/2015/05-15-hackrf-one-at-1-mhz/>`__)
+    * 10 MHz to 2170 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases
+    * 2170 MHz to 2740 MHz: 13 dBm to 15 dBm
+    * 2740 MHz to 4000 MHz: 0 dBm to 5 dBm, decreasing as frequency increases
+    * 4000 MHz to 6000 MHz: -10 dBm to 0 dBm, generally decreasing as frequency increases
+
+Through most of the frequency range up to 4 GHz, the maximum TX power is between 0 and 10 dBm. The frequency range with best performance is 2170 MHz to 2740 MHz.
+
+Overall, the output power is enough to perform over-the-air experiments at close range or to drive an external amplifier. If you connect an external amplifier, you should also use an external bandpass filter for your operating frequency.
+
+Before you transmit, know your laws. HackRF One has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your HackRF One legally.

docs/source/index.rst

@@ -7,7 +7,7 @@ Welcome to HackRF's documentation!
    :caption: User Documentation
 
    getting_help
-   faq
+   troubleshooting
    synchronization_checklist
    hackrf_projects_mentions
 

docs/source/leds.rst

@@ -2,7 +2,8 @@
 LEDs
 ====
 
-
 When HackRF One is plugged in to a USB host, four LEDs should turn on: 3V3, 1V8, RF, and USB. The 3V3 LED indicates that the primary internal power supply is working properly. The 1V8 and RF LEDs indicate that firmware is running and has switched on additional internal power supplies. The USB LED indicates that the HackRF One is communicating with the host over USB.
 
 The RX and TX LEDs indicate that a receive or transmit operation is currently in progress.
+
+Each LED is a single color. There are no multi-colored LEDs on HackRF One. Adjacent LEDs are different colors in order to make them easier to distinguish from one another. The colors do not mean anything.

docs/source/setting_gain.rst

@@ -2,4 +2,24 @@
 Setting Gain Controls for RX
 ============================
 
+Gain controls
+~~~~~~~~~~~~~
+
+HackRF One provides three different analog gain controls on RX and two on TX.
+
+The three RX gain controls are at these stages:
+
+- RF ("amp", 0 or ~11 dB)
+- IF ("lna", 0 to 40 dB in 8 dB steps)
+- baseband ("vga", 0 to 62 dB in 2 dB steps)
+ 
+The two TX gain controls are at these stages:
+
+- RF (0 or ~11 dB)
+- IF (0 to 47 dB in 1 dB steps)
+
+Note: in some documents, the RF gain was erroneously quoted to be 14 dB. The confusion was based on the fact that the MGA-81563 amplifier is advertised as a "14 dBm" amplifier, but that specifies its output power, not its amplification. See `Martin Ling's comment on issue #1059 <https://github.com/greatscottgadgets/hackrf/issues/1059#issuecomment-1060038293>`__ for some details!
+
+The TX and RX RF amplifiers have two settings: on or off. In the off state, the amps are completely bypassed. They nominally provide around 11 dB of gain when on, but the actual amount of gain varies by frequency. In general, expect less gain at higher frequencies. For fine control of gain, use the IF and/or baseband gain options.
+
 A good default setting to start with is RF=0 (off), IF=16, baseband=16. Increase or decrease the IF and baseband gain controls roughly equally to find the best settings for your situation. Turn on the RF amp if you need help picking up weak signals. If your gain settings are too low, your signal may be buried in the noise. If one or more of your gain settings is too high, you may see distortion (look for unexpected frequencies that pop up when you increase the gain) or the noise floor may be amplified more than your signal is.

docs/source/troubleshooting.rst

@@ -0,0 +1,74 @@
+.. _troubleshooting:
+
+================================================
+Troubleshooting
+================================================
+
+HackRF not detected / "No HackRF boards found."
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the software you're using is unable to detect the HackRF hardware and/or `hackrf_info` returns "No HackRF boards found.", this can be caused by a number of different software or hardware issues.
+
+Solution
+--------
+
+    #. If you are using a PortaPack addon, make sure to select "HackRF" mode from the main menu.
+
+    #. If you are using a virtual machine or Windows Subsystem for Linux (WSL), make sure that it is configured to pass through the USB device.
+
+    #. Check whether the device appears in ``lsusb`` (Linux), Device Manager (Windows), or System Report (macOS). If it doesn't not appear, it could either be a firmware issue, an issue with the cable, or another hardware issue.
+
+    #. Try booting the HackRF in DFU mode by holding the "DFU" button when plugging in the device. It should now appear as `NXP Semiconductors LPC4330FET180 [ARM Cortex M4 + M0] (device firmware upgrade mode)` in the locations listed above. If it does appear, then it was likely a firmware issue and you can follow the instructions to :ref:`recover the SPI flash firmware <recovering_firmware>`.
+
+    #. If the device does not appear in DFU mode then it is likely to be an issue with the USB cable. Charge-only cables (which do not include the data lines) have become very common and will cause this symptom. Ideally, test the cable you're using with another device that does some sort of data transfer to be sure that it works, or just try other cables.
+
+    #. If the device still does not appear, it may be a less common issue or possibly a fault with the hardware. See :doc:`Getting Help <getting_help>` for information on where to ask for more support, and please include as much detail as you can about what you've already tried.
+
+.. _bigspike:
+
+There is a big spike in the center of the received spectrum
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you see a large spike in the center of your FFT display regardless of the frequenecy you are tuned to, you are seeing a DC offset (or component or bias). The term "DC" comes from "Direct Current" in electronics. It is the unchanging aspect of a signal as opposed to the "alternating" part of the signal (AC) that changes over time.
+
+.. figure:: ../images/dc_spike_grc.png
+   :align: center
+
+   DC spike
+
+
+Take, for example, the signal represented by the digital sequence:
+
+.. code-block:: sh
+
+	-2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1
+
+.. figure:: ../images/dc_spike_example_plot.png
+   :align: center
+
+   Example signal
+
+This periodic signal contains a strong sinusoidal component spanning from -2 to 9. If we plot the spectrum of this signal, you can see one spike at the frequency of this sinusoid and a second spike at 0 Hz (DC).
+
+
+.. figure:: ../images/dc_spike_example_spectrum.png
+   :align: center
+
+   Spectrum of example signal
+
+If the signal spanned from values -2 to 2 (centered around zero), there would be no DC offset. Since it is centered around 3.5 (the number midway between -2 and 9), there is a DC component.
+
+Samples produced by HackRF are measurements of radio waveforms, but the measurement method is prone to a DC bias introduced by HackRF. It's an artifact of the measurement system, not an indication of a received radio signal. DC offset is not unique to HackRF; it is common to all quadrature sampling systems.
+
+A high DC offset is also one of a few symptoms that can be caused by a software version mismatch. A common problem is that people run an old version of gr-osmosdr with newer firmware.
+
+Solution
+--------
+
+There are a few options:
+
+    #. Ignore it. For many applications it isn't a problem. You'll learn to ignore it.
+
+    #. Avoid it. The best way to handle DC offset for most applications is to use offset tuning; instead of tuning to your exact frequency of interest, tune to a nearby frequency so that the entire signal you are interested in is shifted away from 0 Hz but still within the received bandwidth. If your algorithm works best with your signal centered at 0 Hz (many do), you can shift the frequency in the digital domain, moving your signal of interest to 0 Hz and your DC offset away from 0 Hz. HackRF's high maximum sampling rate can be a big help as it allows you to use offset tuning even for relatively wideband signals.
+
+    #. Correct it. There are various ways of removing the DC offset in software. However, these techniques may degrade parts of the signal that are close to 0 Hz. It may look better, but that doesn't necessarily mean that it is better from the standpoint of a demodulator algorithm, for example. Still, correcting the DC offset is often a good choice.

docs/source/updating_firmware.rst

@@ -29,7 +29,7 @@ After writing the firmware to SPI flash, you may need to reset the HackRF device
 
 If you get an error that mentions HACKRF_ERROR_NOT_FOUND, it is often a permissions problem on your OS.
 
-
+.. _recovering_firmware:
 
 Only if Necessary: Recovering the SPI Flash Firmware
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~