Merge pull request greatscottgadgets#1540 from miek/docs-improvements

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

Author: antoinevg

docs/images/dc_spike_example_plot.png

@@ -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/images/dc_spike_example_spectrum.png

@@ -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/images/dc_spike_grc.png

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

docs/source/faq.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/getting_help.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.