From 4002fb2f8b97b03b061aba240909f16bf56fd8f9 Mon Sep 17 00:00:00 2001 From: straithe Date: Tue, 14 Dec 2021 00:29:31 -0500 Subject: [PATCH 1/2] Update docs --- .gitignore | 3 ++ docs/source/clocking.rst | 2 +- docs/source/external_clock_interface.rst | 11 +++++ docs/source/faq.rst | 41 ++++++++++++++++ docs/source/hackrf_one.rst | 62 +----------------------- docs/source/hackrfs_buttons.rst | 11 +++++ docs/source/index.rst | 4 +- docs/source/opera_cake.rst | 8 +-- docs/source/software_support.rst | 4 +- 9 files changed, 77 insertions(+), 69 deletions(-) create mode 100644 docs/source/external_clock_interface.rst create mode 100644 docs/source/hackrfs_buttons.rst diff --git a/.gitignore b/.gitignore index d26a771d..2abfd070 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,9 @@ Thumbs.db *.sublime-workspace .vscode* +# Documentation Stuff +docs/build/ + # Xilinx tools create an enormous amount of poop: firmware/cpld/**/isim/ firmware/cpld/**/_ngo/ diff --git a/docs/source/clocking.rst b/docs/source/clocking.rst index 93ad2a9b..53f1d960 100644 --- a/docs/source/clocking.rst +++ b/docs/source/clocking.rst @@ -1,5 +1,5 @@ ================================================ -Clocking +Clocking Signals ================================================ diff --git a/docs/source/external_clock_interface.rst b/docs/source/external_clock_interface.rst new file mode 100644 index 00000000..64a6c409 --- /dev/null +++ b/docs/source/external_clock_interface.rst @@ -0,0 +1,11 @@ +=========================================== +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. + +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 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_debug --si5351c -n 0 -r``. The expected output with a clock detected is `[ 0] -> 0x01`. The expected output with no clock detected is `[ 0] -> 0x51`. diff --git a/docs/source/faq.rst b/docs/source/faq.rst index d0cb2438..6ffb89e5 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -5,6 +5,38 @@ 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 `__) + * 10 MHz to 2150 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases + * 2150 MHz to 2750 MHz: 13 dBm to 15 dBm + * 2750 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 2150 MHz to 2750 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -45,6 +77,15 @@ If you were to try to redesign the RF section on HackRF One to support full-dupl ---- +Are those connectors SMA or RP-SMA? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some connectors that appear to be SMA are actually RP-SMA. If you connect an RP-SMA antenna to HackRF One, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. RP-SMA connectors are most common on 2.4 GHz antennas and are popular on Wi-Fi equipment. Adapters are available. + + +---- + + .. _bigspike: What is the big spike in the center of my received spectrum? diff --git a/docs/source/hackrf_one.rst b/docs/source/hackrf_one.rst index 695865a5..90555af8 100644 --- a/docs/source/hackrf_one.rst +++ b/docs/source/hackrf_one.rst @@ -22,64 +22,4 @@ Features * pin headers for expansion * portable * open source - - - -Using HackRF One's Buttons -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The RESET button resets the microcontroller. This is a reboot that should result in a USB re-enumeration. - -The DFU button invokes a USB DFU bootloader located in the microcontroller's ROM. This bootloader makes it possible to unbrick a HackRF One with damaged firmware because the ROM cannot be overwritten. - -To invoke DFU mode: Press and hold the DFU button. While holding the DFU button, reset the HackRF One either by pressing and releasing the RESET button or by powering on the HackRF One. Release the DFU button. - -The DFU button only invokes the bootloader during reset. This means that it can be used for other functions by custom firmware. - - - -SMA, not RP-SMA -~~~~~~~~~~~~~~~ - -Some connectors that appear to be SMA are actually RP-SMA. If you connect an RP-SMA antenna to HackRF One, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. RP-SMA connectors are most common on 2.4 GHz antennas and are popular on Wi-Fi equipment. Adapters are available. - - - -Transmit Power -~~~~~~~~~~~~~~ - -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 `__) - * 10 MHz to 2150 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases - * 2150 MHz to 2750 MHz: 13 dBm to 15 dBm - * 2750 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 2150 MHz to 2750 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. - - - -Receive Power -~~~~~~~~~~~~~ - -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. - - - -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. - -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 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_debug --si5351c -n 0 -r``. The expected output with a clock detected is `[ 0] -> 0x01`. The expected output with no clock detected is `[ 0] -> 0x51`. + \ No newline at end of file diff --git a/docs/source/hackrfs_buttons.rst b/docs/source/hackrfs_buttons.rst new file mode 100644 index 00000000..05120372 --- /dev/null +++ b/docs/source/hackrfs_buttons.rst @@ -0,0 +1,11 @@ +==================== +HackRF One's Buttons +==================== + +The RESET button resets the microcontroller. This is a reboot that should result in a USB re-enumeration. + +The DFU button invokes a USB DFU bootloader located in the microcontroller's ROM. This bootloader makes it possible to unbrick a HackRF One with damaged firmware because the ROM cannot be overwritten. + +To invoke DFU mode: Press and hold the DFU button. While holding the DFU button, reset the HackRF One either by pressing and releasing the RESET button or by powering on the HackRF One. Release the DFU button. + +The DFU button only invokes the bootloader during reset. This means that it can be used for other functions by custom firmware. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 2fda8185..dc77b106 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,8 +39,10 @@ Welcome to HackRF's documentation! list_of_hardware_revisions hardware_components + enclosure_options + hackrfs_buttons + external_clock_interface clocking - enclosure_options expansion_interface multiple_device_hardware_synch diff --git a/docs/source/opera_cake.rst b/docs/source/opera_cake.rst index 2b066c17..b1b60eed 100644 --- a/docs/source/opera_cake.rst +++ b/docs/source/opera_cake.rst @@ -24,13 +24,13 @@ Port connections may be configured manually. For example, to connect A0 to A2 an .. code-block :: sh - hackrf_operacake -a A2 -b B3 + hackrf_operacake -a A2 -b B3 To connect A0 to B2 and B0 to A4: .. code-block :: sh - hackrf_operacake -a B2 -b A4 + hackrf_operacake -a B2 -b A4 If only one primary port is configured, the other primary port will be connected to the first secondary port on the opposite side. For example, after the next two commands B0 will be connected to A1: @@ -147,13 +147,13 @@ In time mode, the A0 port connection switches automatically over time, counted i To cycle through four ports, one port every 1000 samples: -.. code-block :: +.. code-block :: sh hackrf_operacake -m time -t A1:1000 -t A2:1000 -t A3:1000 -t A4:1000 When the duration on multiple ports is the same, the ``-w`` option can be used to set the default dwell time: -.. code-block :: +.. code-block :: sh hackrf_operacake --mode time -w 1000 -t A1 -t A2 -t A3 -t A4 diff --git a/docs/source/software_support.rst b/docs/source/software_support.rst index 2aaed2de..2436f8ab 100644 --- a/docs/source/software_support.rst +++ b/docs/source/software_support.rst @@ -1,11 +1,11 @@ ================================================ -Software Support +HackRF Compatible Software ================================================ Software with HackRF Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is intended to be a list of software known to work with the HackRF. There are three sections, GNU Radio Based software, those that have support directly, and those that can work with data from the HackRF. +This is intended to be a list of software known to work with the HackRF. There are three sections, GNU Radio Based software, those that have direct support, and those that can work with data from the HackRF. From 471defd545283313565bebcd8f212f122ff0306f Mon Sep 17 00:00:00 2001 From: Michael Ossmann Date: Wed, 29 Dec 2021 15:09:40 -0700 Subject: [PATCH 2/2] avoid incorrect syntax highlighting also remove spaces before '::'s --- docs/source/opera_cake.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/opera_cake.rst b/docs/source/opera_cake.rst index b1b60eed..e647c9aa 100644 --- a/docs/source/opera_cake.rst +++ b/docs/source/opera_cake.rst @@ -22,19 +22,19 @@ Opera Cake has two primary ports, A0 and B0, each of which can be switched to an Port connections may be configured manually. For example, to connect A0 to A2 and B0 to B3: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -a A2 -b B3 To connect A0 to B2 and B0 to A4: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -a B2 -b A4 If only one primary port is configured, the other primary port will be connected to the first secondary port on the opposite side. For example, after the next two commands B0 will be connected to A1: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -a A2 -b B3 hackrf_operacake -a B2 @@ -49,13 +49,13 @@ Board Address Each Opera Cake has a numeric address set by optional jumpers installed on header P1. The default address (without jumpers) is 0. The ``--list`` or ``-l`` option can be used to list the address(es) of one or more Opera Cakes installed on a HackRF One: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -l The address may be set to any number from 0 to 7 by installing jumpers across the A0, A1, and/or A2 pins of header P1. -.. list-table :: +.. list-table:: :header-rows: 1 :widths: 1 1 1 1 @@ -98,7 +98,7 @@ The address may be set to any number from 0 to 7 by installing jumpers across th When configuring an Opera Cake, the address may be specified with the ``--address`` or ``-o`` option: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -o 1 -a A1 -b B2 @@ -115,7 +115,7 @@ Manual Mode The default mode of operation is ``manual``. In manual mode, fixed port connections are configured with the ``-a`` and ``-b`` options as in the port configuration examples above. If the operating mode has been changed, it can be changed back to manual mode with: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -m manual @@ -128,7 +128,7 @@ The bands are specified in priority order. The final band specified will be used To assign frequency bands to ports you must use the ``-f `` option for each band, with the minimum and maximum frequencies specified in MHz. For example, to use port A1 for 100 MHz to 600 MHz, A3 for 600 MHz to 1200 MHz, and B2 for 0 MHz to 4 GHz: -.. code-block :: sh +.. code-block:: sh hackrf_operacake -m frequency -f A1:100:600 -f A3:600:1200 -f B2:0:4000 @@ -147,13 +147,13 @@ In time mode, the A0 port connection switches automatically over time, counted i To cycle through four ports, one port every 1000 samples: -.. code-block :: sh +.. code-block:: none hackrf_operacake -m time -t A1:1000 -t A2:1000 -t A3:1000 -t A4:1000 When the duration on multiple ports is the same, the ``-w`` option can be used to set the default dwell time: -.. code-block :: sh +.. code-block:: none hackrf_operacake --mode time -w 1000 -t A1 -t A2 -t A3 -t A4