Sojus07/hackrf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #1025 from straithe/updateDocs

Browse Source 
Update docs
This commit is contained in:
Michael Ossmann
2021-12-29 15:18:11 -07:00
committed by GitHub
parent 0002e2d391 471defd545
commit bf84a3a9ba
9 changed files with 85 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@ -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/

2
docs/source/clocking.rst
View File

@ -1,5 +1,5 @@
================================================
Clocking
Clocking Signals
================================================

11
docs/source/external_clock_interface.rst Normal file
View File

@ -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`.

41
docs/source/faq.rst
View File

@ -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 <https://greatscottgadgets.com/2015/05-15-hackrf-one-at-1-mhz/>`__)
* 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?

60
docs/source/hackrf_one.rst
View File

@ -23,63 +23,3 @@ Features
* 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 <https://greatscottgadgets.com/2015/05-15-hackrf-one-at-1-mhz/>`__)
* 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`.

11
docs/source/hackrfs_buttons.rst Normal file
View File

@ -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.

4
docs/source/index.rst
View File

@ -39,8 +39,10 @@ Welcome to HackRF's documentation!
list_of_hardware_revisions
hardware_components
clocking
enclosure_options
hackrfs_buttons
external_clock_interface
clocking
expansion_interface
multiple_device_hardware_synch

24
docs/source/opera_cake.rst
View File

@ -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
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
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 <port:min:max>`` 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 ::
.. 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 ::
.. code-block:: none
hackrf_operacake --mode time -w 1000 -t A1 -t A2 -t A3 -t A4

4
docs/source/software_support.rst
View File

@ -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.