diff --git a/docs/source/LPC43XX_SGPIO_Configuration.rst b/docs/source/LPC43XX_SGPIO_Configuration.rst index a1102c9f..fe5a472d 100644 --- a/docs/source/LPC43XX_SGPIO_Configuration.rst +++ b/docs/source/LPC43XX_SGPIO_Configuration.rst @@ -13,11 +13,8 @@ In the current HackRF design, there is a CPLD which manages the interface betwee -Frequently Asked Questions -~~~~~~~~~~~~~~~~~~~~~~~~~~ - Why not use GPDMA to transfer samples through SGPIO? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It would be great if we could, as that would free up lots of processor time. Unfortunately, the GPDMA scheme in the LPC43xx does not seem to support peripheral-to-memory and memory-to-peripheral transfers with the SGPIO peripheral. diff --git a/docs/source/enclosure_options.rst b/docs/source/enclosure_options.rst index 07b6a9fa..51d3c5ff 100644 --- a/docs/source/enclosure_options.rst +++ b/docs/source/enclosure_options.rst @@ -5,4 +5,4 @@ The commercial version of HackRF One from Great Scott Gadgets ships with an inje * Hammond 1455J1201: HackRF One fits this extruded aluminum enclosure and other similar models from Hammond Manufacturing. In order to use the enclosure's end plates, you will have to drill them. An end plate template can be found in the HackRF One KiCad layout. - * Acrylic sandwich: You can also use a laser cut acrylic enclosure with HackRF One. This is a good option for access to the expansion headers. A design can be found in the HackRF One hardware directory. Use any laser cutting service or purchase from a `reseller `__. \ No newline at end of file + * Acrylic sandwich: You can also use a laser cut acrylic enclosure with HackRF One. This is a good option for access to the expansion headers. A design can be found in the HackRF One hardware directory. Use any laser cutting service or purchase from a `reseller `__. \ No newline at end of file diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 010cf89d..f393514e 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -106,9 +106,28 @@ There was a bug in the HackRF firmware (through release 2013.06.1) that made the 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 `. 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/getting_help.rst b/docs/source/getting_help.rst index fe7be870..83418c4e 100644 --- a/docs/source/getting_help.rst +++ b/docs/source/getting_help.rst @@ -1,9 +1,11 @@ -================================================ +============ Getting Help -================================================ +============ -Before asking for help with HackRF, check to see if your question is listed in the :ref:`FAQ ` or has already been answered in `GitHub issues `__ or the `mailing list archives `__. +Before asking for help with HackRF, check to see if your question is answered in this documentation, listed in the :ref:`FAQ `, or addressed in the `HackRF GitHub repository issues `__. -For assistance with HackRF use or development, please look at the `issues on the GitHub project `__. This is the preferred place to ask questions so that others may locate the answer to your question in the future. +For assistance with HackRF general use or development, please look at the `issues on the GitHub project `__. This is the preferred place to ask questions so that others may locate the answer to your question in the future. -Many users spend time in the `#hackrf channel on Discord `__. +We invite you to join our community discussions on `Discord `__. Note that while technical support requests are welcome here, we do not have support staff on duty at all times. Be sure to also submit an issue on GitHub if you’ve found a bug or if you want to ensure that your request will be tracked and not overlooked. + +If you wish to see past discussions and questions about HackRF, you may also view the `mailing list archives `__. diff --git a/docs/source/getting_started_hackrf_gnuradio.rst b/docs/source/getting_started_hackrf_gnuradio.rst deleted file mode 100644 index 7603409c..00000000 --- a/docs/source/getting_started_hackrf_gnuradio.rst +++ /dev/null @@ -1,69 +0,0 @@ -================================================ -Getting Started with HackRF and GNU Radio -================================================ - -We recommend getting started by watching the `Software Defined Radio with HackRF `__ video series. This series will introduce you to HackRF One, software including GNU Radio, and teach you the fundamentals of Digital Signal Processing (DSP) needed to take full advantage of the power of Software Defined Radio (SDR). Additional helpful information follows. - -.. _try_pentoo: - -Try Your HackRF with Pentoo Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The easiest way to get started with your HackRF and ensure that it works is to use Pentoo, a Linux distribution with full support for HackRF and GNU Radio. Download the latest Pentoo .iso image from one of the mirrors listed at `http://pentoo.ch/downloads/ `__. Then burn the .iso to a DVD or use `UNetbootin `__ to install the .iso on a USB flash drive. Boot your computer using the DVD or USB flash drive to run Pentoo. Do this natively, not in a virtual machine. (Unfortunately high speed USB operation invariably fails when people try to run HackRF from a virtual machine.) - -Once Pentoo is running, you can immediately use it to :ref:`update firmware ` on your HackRF or use other HackRF command line tools. For a walkthrough, watch `SDR with HackRF, Lesson 5: HackRF One `__. - -To verify that your HackRF is detected, type ``hackrf_info`` at the command line. It should produce a few lines of output including "Found HackRF board." The 3V3, 1V8, RF, and USB LEDs should all be illuminated and are various colors. - -You can type ``startx`` at the command line to launch a desktop environment. Accept the "default config" in the first dialog box. The desktop environment is useful for GNU Radio Companion and other graphical applications but is not required for basic operations such as firmware updates. - -Now you can use programs such as gnuradio-companion or gqrx to start experimenting with your HackRF. Try the Examples below. If you are new to GNU Radio, an excellent place to start is with the `SDR with HackRF `__ video series or with the `GNU Radio guided tutorials `__. - -**Alternative: GNU Radio Live SDR Environment** - -The `GNU Radio Live SDR Environment `__ is another nice bootable Linux .iso with support for HackRF and, of course, GNU Radio. - -Software Setup -~~~~~~~~~~~~~~ - -As mentioned above, the best way to get started with HackRF is to use Pentoo Linux. Eventually you may want to install software to use HackRF with your favorite operating system. - -If your package manager includes the most recent release of libhackrf and gr-osmosdr, then use it to install those packages in addition to GNU Radio. Otherwise, the recommended way to install these tools is by using `PyBOMBS `__. - -See the :ref:`Operating System Tips ` page for information on setting up HackRF software on particular Operating Systems and Linux distributions. - -If you have any trouble, make sure that things work when booted to Pentoo. This will allow you to easily determine if your problem is being caused by hardware or software, and it will give you a way to see how the software is supposed to function. - -Examples -~~~~~~~~ - -A great way to get started with HackRF is the `SDR with HackRF `__ video series. Additional examples follow: - -Testing the HackRF - - #. Plug in the HackRF - #. run the hackrf_info command ``$ hackrf_info`` - -If everything is OK, you should see something similar to the following: - -.. code-block:: sh - - hackrf_info version: 2017.02.1 - libhackrf version: 2017.02.1 (0.5) - Found HackRF - Index: 0 - Serial number: 0000000000000000################ - Board ID Number: 2 (HackRF One) - Firmware Version: 2017.02.1 (API:1.02) - Part ID Number: 0x######## 0x######## - -**FM Radio Example** - -This Example was derived from the following works: - - * `RTL-SDR FM radio receiver with GNU Radio Companion `__ - * `How To Build an FM Receiver with the USRP in Less Than 10 Minutes `__ - - #. Download the FM Radio Receiver python file `here `__ - #. Run the file ``$ python ./fm_radio_rx.py`` - #. You can find the GNU Radio Companion source file `here `__ diff --git a/docs/source/hackrf_minimum_requirements.rst b/docs/source/hackrf_minimum_requirements.rst new file mode 100644 index 00000000..4be16afc --- /dev/null +++ b/docs/source/hackrf_minimum_requirements.rst @@ -0,0 +1,9 @@ +============================================ +Minimum Host System Requirements for HackRF +============================================ + +HackRF requires you to supply 500 mA at 5 V DC to your HackRF via the USB port. If your host computer has difficulty meeting this requirement, you may need to use a powered USB hub. + +There is no specific minimum CPU requirement for the host computer when using a HackRF, but SDR is generally a CPU-intensive application. If you have a slower CPU, you may be unable to run certain SDR software or you may only be able to operate at lower sample rates. + +Most users will want to stream data to or from the HackRF at high speeds. This requires that the host computer supports Hi-Speed USB. Some Hi-Speed USB hosts are better than others, and you may have multiple host controllers on your computer. If you have difficulty operating your HackRF at high sample rates (10 Msps to 20 Msps), try using a different USB port on your computer. If possible, arrange things so that the HackRF is the only device on the bus. \ No newline at end of file diff --git a/docs/source/hackrf_one.rst b/docs/source/hackrf_one.rst index 4fdc0e34..7abddf2d 100644 --- a/docs/source/hackrf_one.rst +++ b/docs/source/hackrf_one.rst @@ -25,4 +25,5 @@ Features * pin headers for expansion * portable * open source - + + diff --git a/docs/source/hackrf_sweep.rst b/docs/source/hackrf_sweep.rst deleted file mode 100644 index 6b85fdb8..00000000 --- a/docs/source/hackrf_sweep.rst +++ /dev/null @@ -1,119 +0,0 @@ -================================================ -hackrf_sweep -================================================ - -Usage -~~~~~ - -.. code-block:: sh - - [-h] # this help - [-d serial_number] # Serial number of desired HackRF - [-a amp_enable] # RX RF amplifier 1=Enable, 0=Disable - [-f freq_min:freq_max] # minimum and maximum frequencies in MHz - [-p antenna_enable] # Antenna port power, 1=Enable, 0=Disable - [-l gain_db] # RX LNA (IF) gain, 0-40dB, 8dB steps - [-g gain_db] # RX VGA (baseband) gain, 0-62dB, 2dB steps - [-w bin_width] # FFT bin width (frequency resolution) in Hz, 2445-5000000 - [-1] # one shot mode - [-N num_sweeps] # Number of sweeps to perform - [-B] # binary output - [-I] # binary inverse FFT output - -r filename # output file - - - -Output fields -~~~~~~~~~~~~~ - -``date, time, hz_low, hz_high, hz_bin_width, num_samples, dB, dB, ...`` - -Running ``hackrf_sweep -f 2400:2490`` gives the following example results: - -.. list-table :: - :header-rows: 1 - :widths: 1 1 1 1 1 1 1 1 1 1 1 - - * - Date - - Time - - Hz Low - - Hz High - - Hz bin width - - Num Samples - - dB - - dB - - dB - - dB - - dB - * - 2019-01-03 - - 11:57:34.967805 - - 2400000000 - - 2405000000 - - 1000000.00 - - 20 - - -64.72 - - -63.36 - - -60.91 - - -61.74 - - -58.58 - * - 2019-01-03 - - 11:57:34.967805 - - 2410000000 - - 2415000000 - - 1000000.00 - - 20 - - -69.22 - - -60.67 - - -59.50 - - -61.81 - - -58.16 - * - 2019-01-03 - - 11:57:34.967805 - - 2405000000 - - 2410000000 - - 1000000.00 - - 20 - - -61.19 - - -70.14 - - -60.10 - - -57.91 - - -61.97 - * - 2019-01-03 - - 11:57:34.967805 - - 2415000000 - - 2420000000 - - 1000000.00 - - 20 - - -72.93 - - -79.14 - - -68.79 - - -70.71 - - -82.78 - * - 2019-01-03 - - 11:57:34.967805 - - 2420000000 - - 2425000000 - - 1000000.00 - - 20 - - -67.57 - - -61.61 - - -57.29 - - -61.90 - - -70.19 - * - 2019-01-03 - - 11:57:34.967805 - - 2430000000 - - 2435000000 - - 1000000.00 - - 20 - - -56.04 - - -59.58 - - -66.24 - - -66.02 - - -62.12 - -Each sweep across the entire specified frequency range is given a single time stamp. - -The fifth column tells you the width in Hz (1 MHz in this case) of each frequency bin, which you can set with ``-w``. The sixth column is the number of samples analyzed to produce that row of data. - -Each of the remaining columns shows the power detected in each of several frequency bins. In this case there are five bins, the first from 2400 to 2401 MHz, the second from 2401 to 2402 MHz, and so forth. diff --git a/docs/source/hackrf_tools.rst b/docs/source/hackrf_tools.rst new file mode 100644 index 00000000..54f38392 --- /dev/null +++ b/docs/source/hackrf_tools.rst @@ -0,0 +1,139 @@ +============ +HackRF Tools +============ + +Great Scott Gadgets provides some commandline tools for interacting with HackRF. + * **hackrf_info** Read device information from HackRF such as serial number and firmware version. + + * **hackrf_transfer** Send and receive signals using HackRF. Input/output files are 8-bit signed quadrature samples. + + * **hackrf_sweep**, a command-line spectrum analyzer. + + * **hackrf_clock** Read and write clock input and output configuration. + + * **hackrf_operacake** Configure Opera Cake antenna switch connected to HackRF. + + * **hackrf_spiflash** A tool to write new firmware to HackRF. See: :ref:`Updating Firmware `. + + * **hackrf_debug** Read and write registers and other low-level configuration for debugging. + + + +hackrf_sweep +~~~~~~~~~~~~ + +Usage +^^^^^ + +.. code-block:: sh + + [-h] # this help + [-d serial_number] # Serial number of desired HackRF + [-a amp_enable] # RX RF amplifier 1=Enable, 0=Disable + [-f freq_min:freq_max] # minimum and maximum frequencies in MHz + [-p antenna_enable] # Antenna port power, 1=Enable, 0=Disable + [-l gain_db] # RX LNA (IF) gain, 0-40dB, 8dB steps + [-g gain_db] # RX VGA (baseband) gain, 0-62dB, 2dB steps + [-w bin_width] # FFT bin width (frequency resolution) in Hz, 2445-5000000 + [-1] # one shot mode + [-N num_sweeps] # Number of sweeps to perform + [-B] # binary output + [-I] # binary inverse FFT output + -r filename # output file + + + +Output fields +^^^^^^^^^^^^^ + +``date, time, hz_low, hz_high, hz_bin_width, num_samples, dB, dB, ...`` + +Running ``hackrf_sweep -f 2400:2490`` gives the following example results: + +.. list-table :: + :header-rows: 1 + :widths: 1 1 1 1 1 1 1 1 1 1 1 + + * - Date + - Time + - Hz Low + - Hz High + - Hz bin width + - Num Samples + - dB + - dB + - dB + - dB + - dB + * - 2019-01-03 + - 11:57:34.967805 + - 2400000000 + - 2405000000 + - 1000000.00 + - 20 + - -64.72 + - -63.36 + - -60.91 + - -61.74 + - -58.58 + * - 2019-01-03 + - 11:57:34.967805 + - 2410000000 + - 2415000000 + - 1000000.00 + - 20 + - -69.22 + - -60.67 + - -59.50 + - -61.81 + - -58.16 + * - 2019-01-03 + - 11:57:34.967805 + - 2405000000 + - 2410000000 + - 1000000.00 + - 20 + - -61.19 + - -70.14 + - -60.10 + - -57.91 + - -61.97 + * - 2019-01-03 + - 11:57:34.967805 + - 2415000000 + - 2420000000 + - 1000000.00 + - 20 + - -72.93 + - -79.14 + - -68.79 + - -70.71 + - -82.78 + * - 2019-01-03 + - 11:57:34.967805 + - 2420000000 + - 2425000000 + - 1000000.00 + - 20 + - -67.57 + - -61.61 + - -57.29 + - -61.90 + - -70.19 + * - 2019-01-03 + - 11:57:34.967805 + - 2430000000 + - 2435000000 + - 1000000.00 + - 20 + - -56.04 + - -59.58 + - -66.24 + - -66.02 + - -62.12 + +Each sweep across the entire specified frequency range is given a single time stamp. + +The fifth column tells you the width in Hz (1 MHz in this case) of each frequency bin, which you can set with ``-w``. The sixth column is the number of samples analyzed to produce that row of data. + +Each of the remaining columns shows the power detected in each of several frequency bins. In this case there are five bins, the first from 2400 to 2401 MHz, the second from 2401 to 2402 MHz, and so forth. diff --git a/docs/source/hackrfs_buttons.rst b/docs/source/hackrfs_buttons.rst index 05120372..d2a6a690 100644 --- a/docs/source/hackrfs_buttons.rst +++ b/docs/source/hackrfs_buttons.rst @@ -1,11 +1,11 @@ -==================== -HackRF One's Buttons -==================== +======= +Buttons +======= -The RESET button resets the microcontroller. This is a reboot that should result in a USB re-enumeration. +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. +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. + +The DFU button only invokes the bootloader during reset. This means that it can be used for other functions by custom firmware. 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/hardware_triggering.rst b/docs/source/hardware_triggering.rst index 3f8a6dfa..38d4ed17 100644 --- a/docs/source/hardware_triggering.rst +++ b/docs/source/hardware_triggering.rst @@ -27,9 +27,7 @@ To connect two HackRF Ones for triggering you will need: 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 `__ by `Jared Boone `__. - -Open the enclosures of both HackRF Ones to access their pin headers. +If your HackRF Ones are not bare boards, you will need to open up their cases to access the pin headers on the HackRF Ones. Each HackRF One case has small plastic clips holding it together. These clips 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 `__ by `Jared Boone `__ to open your HackRF One cases. Identify the Trigger Pins diff --git a/docs/source/index.rst b/docs/source/index.rst index 707647b1..4ab40fa6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,23 +6,33 @@ Welcome to HackRF's documentation! :maxdepth: 2 :caption: User Documentation - hackrf_one - jawbreaker - faq - troubleshooting getting_help - tips_tricks + faq hackrf_projects_mentions .. toctree:: :maxdepth: 2 - :caption: Software + :caption: HackRF One Hardware + + hackrf_one + hackrf_minimum_requirements + list_of_hardware_revisions + hardware_components + leds + hackrfs_buttons + external_clock_interface + expansion_interface + hardware_triggering + enclosure_options + usb_cables + rf_shield_installation + +.. toctree:: + :maxdepth: 2 + :caption: Jawbreaker Hardware + + jawbreaker - installing_hackrf_software - getting_started_hackrf_gnuradio - software_support - libhackrf_api - hackrf_sweep .. toctree:: :maxdepth: 2 @@ -35,16 +45,14 @@ Welcome to HackRF's documentation! .. toctree:: :maxdepth: 2 - :caption: Hardware + :caption: Software - list_of_hardware_revisions - hardware_components - enclosure_options - hackrfs_buttons - external_clock_interface - expansion_interface - hardware_triggering - rf_shield_installation + installing_hackrf_software + hackrf_tools + software_support + sampling_rate + setting_gain + virtual_machines .. toctree:: :maxdepth: 2 @@ -56,4 +64,5 @@ Welcome to HackRF's documentation! opera_cake_board_addressing opera_cake_port_configuration opera_cake_modes_of_operation - \ No newline at end of file + + diff --git a/docs/source/installing_hackrf_software.rst b/docs/source/installing_hackrf_software.rst index db293dcc..dc4cc181 100644 --- a/docs/source/installing_hackrf_software.rst +++ b/docs/source/installing_hackrf_software.rst @@ -1,8 +1,12 @@ .. _operating_system_tips: -================================================ +========================== Installing HackRF Software -================================================ +========================== + +HackRF software includes HackRF Tools and libhackrf. HackRF Tools are the commandline utilities that let you interact with your HackRF. libhackrf is a low level library that enables software on your computer to operate with HackRF. + + Install Using Package Managers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,8 +64,12 @@ Windows: Binaries Binaries are provided as part of the PothosSDR project, they can be downloaded `here `__. + + ----------- + + Installing From Source ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/jawbreaker.rst b/docs/source/jawbreaker.rst index ef1f4b3f..9852a474 100644 --- a/docs/source/jawbreaker.rst +++ b/docs/source/jawbreaker.rst @@ -1,6 +1,6 @@ -================================================ +========== Jawbreaker -================================================ +========== HackRF Jawbreaker is the beta test hardware platform for the HackRF project. @@ -20,53 +20,48 @@ Features -Set your Jawbreaker Free! -~~~~~~~~~~~~~~~~~~~~~~~~~ +Hardware Documentation +~~~~~~~~~~~~~~~~~~~~~~ -Jawbreaker has an SMA antenna connector but also includes a built-in PCB antenna intended for operation near 900 MHz. It isn't a very good antenna. Seriously. A paperclip stuck into the SMA connector would probably be better. You can free your Jawbreaker to operate with better antennas by cutting the PCB trace to the PCB antenna with a knife. This enables the SMA connector to be used without interference from the PCB antenna. - -A video that demonstrates the antenna modification is on YouTube: `HackRF Antenna Modification `__ - -The trace to be cut is between the two solder pads inside a box labeled R44 in the `assembly diagram `__. There is an arrow pointing to it printed on the board. - -Due to a manufacturing error, there is solder on R44. R44 may appear as a single solder blob. If you have a soldering iron and solder wick/braid, use a soldering iron and fine solder wick to remove as much solder as you can from the two R44 pads. Then, use a pen knife to gently cut away the area between the two R44 pads. Make multiple, gentle cuts, instead of one or two forceful cuts. As you cut, you'll break through the black solder mask, then the copper trace between the pads, and stop when you reach fiberglass. Remove the copper trace completely, so just the two R44 pads remain. Use a multimeter or continuity tester to verify that the two R44 pads are no longer connected. - -If you don't have a soldering iron, you can cut through the copper trace and the solder blob all at once, but it requires a bit more effort. - -The only reason not to do this is if you want to try Jawbreaker but don't have any antenna with an SMA connector (or adapter). - -If you want to restore the PCB antenna for some reason, you can install a 10 nF capacitor or a 0 ohm resistor on the R44 pads or you may be able to simply create a solder bridge. - - - -SMA, not RP-SMA -~~~~~~~~~~~~~~~ - -Some connectors that appear to be SMA are actually RP-SMA. If you connect an RP-SMA antenna to Jawbreaker, 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. +Schematic diagram, assembly diagram, and bill of materials can be found at `https://github.com/greatscottgadgets/hackrf/tree/master/hardware `__ Transmit Power ~~~~~~~~~~~~~~ -The maximum TX power varies by operating frequency: +The maximum TX power for Jawbreaker varies by operating frequency: * 30 MHz to 100 MHz: 5 dBm to 15 dBm, increasing as frequency decreases * 100 MHz to 2300 MHz: 0 dBm to 10 dBm, increasing as frequency decreases - * 2300 MHz to 2700 MHz: 10 dBm to 15 dBm + * 2170 MHz to 2740 MHz: 10 dBm to 15 dBm * 2700 MHz to 4000 MHz: -5 dBm to 5 dBm, increasing as frequency decreases * 4000 MHz to 6000 MHz: -15 dBm to 0 dBm, increasing as frequency decreases 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. Jawbreaker has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your Jawbreaker legally. +Before you transmit, know the laws for the region you are transmitting in. Jawbreaker has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your Jawbreaker legally. -Hardware Documentation -~~~~~~~~~~~~~~~~~~~~~~ +SMA, not RP-SMA +~~~~~~~~~~~~~~~ -Schematic diagram, assembly diagram,and bill of materials can be found at `https://github.com/mossmann/hackrf/tree/master/doc/hardware `__ +The connectors on Jawbreaker are SMA, not RP-SMA. SMA connectors and RP-SMA connectors look extremely similar, the difference is that SMA connectors have a center pin. RP-SMA connectors are common on 2.4 GHz antennas and are popular on Wi-Fi equipment. If you connect an RP-SMA antenna to Jawbreaker, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. + + + +Recommended PCB and Antenna Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Jawbreaker has an SMA antenna connector and it also includes a built-in PCB antenna intended for operation near 900 MHz. The built-in PCB antenna isn't a very good antenna. A paperclip stuck into the SMA connector of the Jawbreaker is likely to be better. We recommend that you free your Jawbreaker to operate with better antennas by cutting the PCB trace to the PCB antenna with a knife. This enables the SMA connector to be used without interference from the PCB antenna. + + +The trace to be cut is between the two solder pads inside a box labeled R44. There is an arrow printed on the board that points to the R44 box. A video that demonstrates the antenna modification is on YouTube: `HackRF Antenna Modification `__. + +Due to a manufacturing error, there is solder on the pads in box R44 that you should try to remove before you cut the trace. R44 may appear as a single solder blob. If you have a soldering iron and solder wick/braid, use a soldering iron and fine solder wick to remove as much solder as you can from the two R44 pads. Then, use a pen knife to gently cut away the area between the two R44 pads. Make multiple, gentle cuts, instead of one or two forceful cuts. As you cut, you'll break through the black solder mask, then the copper trace between the pads, and stop when you reach fiberglass. Remove the copper trace completely, so just the two R44 pads remain. Use a multimeter or continuity tester to verify that the two R44 pads are no longer connected. If you don't have a soldering iron, you can cut through the copper trace and the solder blob all at once, but it requires a bit more effort. The only reason not to cut the PCB trace is if you want to try Jawbreaker but don't have any antenna with an SMA connector (or adapter). + +If you want to restore the PCB antenna for some reason, you can install a 10 nF capacitor or a 0 ohm resistor on the R44 pads or you may be able to simply create a solder bridge. @@ -536,14 +531,14 @@ Cut P17 short (trace) to enable external clock input. If short is cut, a jumper More ^^^^ -Additional headers are available. See the `board files `__ for additional details. +Additional headers are available. See the `board files `__ for additional details. Differences between Jawbreaker and HackRF One ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Jawbreaker was the beta platform that preceded HackRF One. HackRF One incorporates the following changes and enhancements: +Jawbreaker was the beta platform that preceded HackRF One. HackRF One incorporates the following changes and enhancements (at minimum): * Antenna port: No modification is necessary to use the SMA antenna port on HackRF One. * PCB antenna: Removed. diff --git a/docs/source/leds.rst b/docs/source/leds.rst new file mode 100644 index 00000000..519e0abd --- /dev/null +++ b/docs/source/leds.rst @@ -0,0 +1,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. diff --git a/docs/source/libhackrf_api.rst b/docs/source/libhackrf_api.rst deleted file mode 100644 index 9e25fa12..00000000 --- a/docs/source/libhackrf_api.rst +++ /dev/null @@ -1,575 +0,0 @@ -================================================ -libhackRF API -================================================ - - - -This document describes the functions, data structures and constants that libHackRF provides. It should be used as a reference for using libHackRF and the HackRF hardware. - -If you are writing a generic SDR application, i.e. not tied to the HackRF hardware, we strongly recommend that you use either gr-osmosdr or SoapySDR to provide support for the broadest possible range of software defined radio hardware. - -For example usage of many of these functions, see the `hackrf_transfer `__ tool. - - - -Setup, Initialization and Shutdown -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -HackRF Init -^^^^^^^^^^^ - -Initialize libHackRF, including global libUSB context to support multiple HackRF hardware devices. - -**Syntax:** ``int hackrf_init()`` - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Open -^^^^^^^^^^^ - -**Syntax:** ``int hackrf_open(hackrf_device** device)`` - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Device List -^^^^^^^^^^^^^^^^^^ - -Retrieve a list of HackRF devices attached to the system. This function finds all devices, regardless of permissions or availability of the hardware. - -**Syntax:** ``hackrf_device_list_t* hackrf_device_list()`` - -**Returns:** A pointer to a hackrf_device_list_t struct, a list of HackRF devices attached to the system. The contents of the hackrf_device_list_t struct are decribed in the data structures section below. - - - - -HackRF Device List Open -^^^^^^^^^^^^^^^^^^^^^^^ - -Open and acquire a handle on a device from the hackrf_device_list_t struct. - -**Syntax:** ``int hackrf_device_list_open(hackrf_device_list_t* list, int idx, hackrf_device** device)`` - -**Params:** - -``list`` - A pointer to a hackrf_device_list_t returned by ``hackrf_device_list()`` - -``idx`` - The list index of the HackRF device to open - -``device`` - Output location for hackrf_device pointer. Only valid when return value is HACKRF_SUCCESS. - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Device List Free -^^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``void hackrf_device_list_free(hackrf_device_list_t* list)`` - -**Params:** - -``list`` - A pointer to a hackrf_device_list_t returned by ``hackrf_device_list()`` - - - - -HackRF Open By Serial -^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_open_by_serial(const char* const desired_serial_number, hackrf_device** device)`` - -**Returns:** - - - -HackRF Close -^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_close(hackrf_device* device)`` - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Exit -^^^^^^^^^^^ - -Cleanly shutdown libHackRF and the underlying USB context. This does not stop in progress transfers or close the HackRF hardware. ``hackrf_close()`` should be called before this to cleanly close the connection to the hardware. - -**Syntax:** ``int hackrf_exit()`` - -**Returns:** A value from the hackrf_error constants listed below. - - - -Using the Radio -~~~~~~~~~~~~~~~ - -HackRF Start Rx -^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_start_rx(hackrf_device*, hackrf_sample_block_cb_fn, void* rx_ctx)`` - -**Params:** - -**Returns:** A value from the hackrf_error constants listed below. - - - - -HackRF Stop Rx -^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_stop_rx(hackrf_device*)`` - -**Params:** - -**Returns:** A value from the hackrf_error constants listed below. - - - - -HackRF Start Tx -^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_start_tx(hackrf_device*, hackrf_sample_block_cb_fn, void* tx_ctx)`` - -**Params:** - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Stop Tx -^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_stop_tx(hackrf_device*)`` - -**Params:** - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Set Baseband Filter Bandwidth -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_set_baseband_filter_bandwidth(hackrf_device*, const uint32_t bandwidth_hz)`` - -**Params:** - -**Returns:** A value from the hackrf_error constants listed below. - - - -HackRF Compute Baseband Filter BW -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Compute best default value depending on sample rate (auto filter). - -**Syntax:** ``uint32_t hackrf_compute_baseband_filter_bw(const uint32_t bandwidth_hz)`` - -**Params:** - -**Returns:** A valid baseband filter width available from the Maxim MAX2837 frontend used by the radio. - - - - -HackRF Compute Baseband Filter BW Round Down LT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Compute nearest freq for bw filter (manual filter) - -**Syntax:** ``uint32_t hackrf_compute_baseband_filter_bw_round_down_lt(const uint32_t bandwidth_hz)`` - -**Params:** - -**Returns:** A valid baseband filter width available from the Maxim MAX2837 frontend used by the radio. - - - -Reading and Writing Registers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These low level functions are intended for debugging purposes only. - - -HackRF MAX2837 Read -^^^^^^^^^^^^^^^^^^^ - -Read register values from the MAX2837 Baseband IC. - -**Syntax:** ``int hackrf_max2837_read(hackrf_device* device, uint8_t register_number, uint16_t* value)`` - -**Params:** - -**Returns:** - - - -HackRF MAX2837 Write -^^^^^^^^^^^^^^^^^^^^ - -Write register values to the MAX2837 Baseband IC. - -**Syntax:** ``int hackrf_max2837_write(hackrf_device* device, uint8_t register_number, uint16_t value)`` - -**Params:** - -**Returns:** - - - -HackRF Si5351C Read -^^^^^^^^^^^^^^^^^^^ - -Read register values from the Si5351C clock generator IC. - -**Syntax:** ``int hackrf_si5351c_read(hackrf_device* device, uint16_t register_number, uint16_t* value)`` - -**Params:** - -**Returns:** - - - -HackRF Si5351C Write -^^^^^^^^^^^^^^^^^^^^ - -Write register values to the Si5351C clock generator IC. - -**Syntax:** ``int hackrf_si5351c_write(hackrf_device* device, uint16_t register_number, uint16_t value)`` - -**Params:** - -**Returns:** - - - -HackRF RFFC5071 Read -^^^^^^^^^^^^^^^^^^^^ - -Read register values from the RFFC5071 mixer IC. - -**Syntax:** ``int hackrf_rffc5071_read(hackrf_device* device, uint8_t register_number, uint16_t* value)`` - -**Params:** - -**Returns:** - - - -HackRF RFFC5071 Write -^^^^^^^^^^^^^^^^^^^^^ - -Write register values to the RFFC5071 mixer IC. - -**Syntax:** ``int hackrf_rffc5071_write(hackrf_device* device, uint8_t register_number, uint16_t value)`` - -**Params:** - -**Returns:** - - - -Updating Firmware -~~~~~~~~~~~~~~~~~ - -HackRF CPLD Write -^^^^^^^^^^^^^^^^^ - -A bitstream is written to the CPLD by the firmware during normal operation (since release 2021.03.1). This function writes a bitstream to the CPLD's flash which is not necessary for normal use. The device will need to be reset by physically pressing the reset button after hackrf_cpld_write. - -**Syntax:** ``int hackrf_cpld_write(hackrf_device* device, unsigned char* const data, const unsigned int total_length)`` - -**Params:** - -**Returns:** - - - - -HackRF SPI Flash Erase -^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_spiflash_erase(hackrf_device* device)`` - -**Params:** - -**Returns:** - - - -HackRF SPI Flash Write -^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_spiflash_write(hackrf_device* device, const uint32_t address, const uint16_t length, unsigned char* const data)`` - -**Params:** - -**Returns:** - - - -HackRF SPI Flash Read -^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_spiflash_read(hackrf_device* device, const uint32_t address, const uint16_t length, unsigned char* data)`` - -**Params:** - -**Returns:** - - - -Board Identifiers -~~~~~~~~~~~~~~~~~ - -HackRF Board ID Read -^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_board_id_read(hackrf_device* device, uint8_t* value)`` - -**Params:** - -**Returns:** - - - -HackRF Version String Read -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_version_string_read(hackrf_device* device, char* version, uint8_t length)`` - -**Params:** - -**Returns:** - - - -HackRF Board Part ID Serial Number Read -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``int hackrf_board_partid_serialno_read(hackrf_device* device, read_partid_serialno_t* read_partid_serialno)`` - -**Params:** - -**Returns:** - - - -Miscellaneous -~~~~~~~~~~~~~ - -HackRF Error Name -^^^^^^^^^^^^^^^^^ - -**Syntax:** ``const char* hackrf_error_name(enum hackrf_error errcode)`` - -**Params:** - -**Returns:** - - - -HackRF Board ID Name -^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``const char* hackrf_board_id_name(enum hackrf_board_id board_id)`` - -**Params:** - -**Returns:** - - - -HackRF USB Board ID Name -^^^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``const char* hackrf_usb_board_id_name(enum hackrf_usb_board_id usb_board_id)`` - -**Params:** - -**Returns:** - - - -HackRF Filter Path Name -^^^^^^^^^^^^^^^^^^^^^^^ - -**Syntax:** ``const char* hackrf_filter_path_name(const enum rf_path_filter path)`` - -**Params:** - -**Returns:** - - - -Data Structures -~~~~~~~~~~~~~~~ - -``typedef struct hackrf_device hackrf_device`` - -.. code-block :: sh - - typedef struct { - hackrf_device* device; - uint8_t* buffer; - int buffer_length; - int valid_length; - void* rx_ctx; - void* tx_ctx; - } hackrf_transfer; - -.. code-block :: sh - - typedef struct { - uint32_t part_id[2]; - uint32_t serial_no[4]; - } read_partid_serialno_t; - -.. code-block :: sh - - typedef struct { - char **serial_numbers; - enum hackrf_usb_board_id *usb_board_ids; - int *usb_device_index; - int devicecount; - - void **usb_devices; - int usb_devicecount; - } hackrf_device_list_t; - -``typedef int (*hackrf_sample_block_cb_fn)(hackrf_transfer* transfer)`` - - - -Enumerations -~~~~~~~~~~~~ - -Supported board versions -^^^^^^^^^^^^^^^^^^^^^^^^ - -These values identify the board type of the connected hardware. This value can be used as an indicator of capabilities, such as frequency range, bandwidth or antenna port power. - -.. list-table :: - :header-rows: 1 - :widths: 1 1 1 1 - - * - Board - - Frequency range - - Sample Rate - - Antenna port power - * - HackRF One - - 1 MHz–6 GHz - - 20 Msps - - Yes - * - Jawbreaker - - 10 MHz–6 GHz - - 20 Msps - - No - * - rad1o - - 50 MHz–4 GHz - - 20 Msps - - No - * - Jellybean - - N/A - - 20 Msps - - No - -Most boards will identify as HackRF One, Jawbreaker, or rad1o. Jellybean was a pre-production revision of HackRF that is no longer supported. No hardware device should intentionally report itself with an unrecognized or undetected board ID. - -.. code-block :: sh - - enum hackrf_board_id { - BOARD_ID_JELLYBEAN = 0, - BOARD_ID_JAWBREAKER = 1, - BOARD_ID_HACKRF1_OG = 2, - BOARD_ID_RAD1O = 3, - BOARD_ID_HACKRF1_R9 = 4, - BOARD_ID_UNRECOGNIZED = 0xFE, - BOARD_ID_UNDETECTED = 0xFF, - }; - - - -USB Product IDs -^^^^^^^^^^^^^^^ - -.. code-block :: sh - - enum hackrf_usb_board_id { - USB_BOARD_ID_JAWBREAKER = 0x604B, - USB_BOARD_ID_HACKRF_ONE = 0x6089, - USB_BOARD_ID_RAD1O = 0xCC15, - USB_BOARD_ID_INVALID = 0xFFFF, - }; - - - -Transceiver Mode -^^^^^^^^^^^^^^^^ - -HackRF can operate in four main transceiver modes: Receive, Transmit, Signal Source, and Sweep. There is also a CPLD update mode which is used to write firmware images to the CPLD flash. - -The transceiver mode can be changed with ``hackrf_set_transceiver_mode`` with the value parameter set to one of the following: - -.. code-block:: sh - - enum transceiver_mode_t { - HACKRF_TRANSCEIVER_MODE_OFF = 0, - HACKRF_TRANSCEIVER_MODE_RECEIVE = 1, - HACKRF_TRANSCEIVER_MODE_TRANSMIT = 2, - HACKRF_TRANSCEIVER_MODE_SS = 3, - TRANSCEIVER_MODE_CPLD_UPDATE = 4, - TRANSCEIVER_MODE_RX_SWEEP = 5, - }; - -Receive mode (TRANSCEIVER_MODE_RX) is used to stream samples from the radio to the host system. Use ``hackrf_set_freq`` to set the center frequency of receiver and ``hackrf_set_sample_rate`` to set the sample rate (effective bandwidth). - -Transmit mode (TRANSCEIVER_MODE_TX) is used to stream samples from the host to the radio. - -See `hackrf_transfer `__ for an example of setting transmit and receive mode and transferring data over USB. - - - -Function return values -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block::sh - - enum hackrf_error { - HACKRF_SUCCESS = 0, - HACKRF_TRUE = 1, - HACKRF_ERROR_INVALID_PARAM = -2, - HACKRF_ERROR_NOT_FOUND = -5, - HACKRF_ERROR_BUSY = -6, - HACKRF_ERROR_NO_MEM = -11, - HACKRF_ERROR_LIBUSB = -1000, - HACKRF_ERROR_THREAD = -1001, - HACKRF_ERROR_STREAMING_THREAD_ERR = -1002, - HACKRF_ERROR_STREAMING_STOPPED = -1003, - HACKRF_ERROR_STREAMING_EXIT_CALLED = -1004, - HACKRF_ERROR_USB_API_VERSION = -1005, - HACKRF_ERROR_NOT_LAST_DEVICE = -2000, - HACKRF_ERROR_OTHER = -9999, - }; - - - -RF Filter Path -^^^^^^^^^^^^^^ - -.. code-block:: sh - - enum rf_path_filter { - RF_PATH_FILTER_BYPASS = 0, - RF_PATH_FILTER_LOW_PASS = 1, - RF_PATH_FILTER_HIGH_PASS = 2, - }; diff --git a/docs/source/sampling_rate.rst b/docs/source/sampling_rate.rst new file mode 100644 index 00000000..eab21496 --- /dev/null +++ b/docs/source/sampling_rate.rst @@ -0,0 +1,14 @@ +Sampling Rate and Baseband Filters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using a sampling rate of less than 8MHz is not recommended. Partly, this is because the MAX5864 (ADC/DAC chip) isn't specified to operate at less than 8MHz, and therefore, no promises are made by Maxim about how it performs. But more importantly, the baseband filter in the MAX2837 has a minimum bandwidth of 1.75MHz. It can't provide enough filtering at 2MHz sampling rate to remove substantial signal energy in adjacent spectrum (more than +/-1MHz from the tuned frequency). The MAX2837 datasheet suggests that at +/-1MHz, the filter provides only 4dB attenuation, and at +/-2MHz (where a signal would alias right into the center of your 2MHz spectrum), it attenuates about 33dB. That's significant. Here's a picture: + +.. image:: ../images/max2837-1m75bw-at-2m.png + :align: center + +At 8MHz sampling rate, and using the minimum 1.75MHz bandwidth filter, this is the response: + +.. image:: ../images/max2837-1m75bw-at-8m.png + :align: center + +You can see that the attenuation is more than 60dB at +/-2.8MHz, which is more than sufficient to remove significant adjacent spectrum interference before the ADC digitizes the baseband. If using this configuration to get a 2MHz sampling rate, use a GNU Radio block after the 8MHz source that performs a 4:1 decimation with a decently sharp low pass filter (complex filter with a cut-off of <1MHz). \ No newline at end of file diff --git a/docs/source/setting_gain.rst b/docs/source/setting_gain.rst new file mode 100644 index 00000000..eae8bfd3 --- /dev/null +++ b/docs/source/setting_gain.rst @@ -0,0 +1,5 @@ +============================ +Setting Gain Controls for RX +============================ + +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. diff --git a/docs/source/software_support.rst b/docs/source/software_support.rst index c21ba9bc..e8487652 100644 --- a/docs/source/software_support.rst +++ b/docs/source/software_support.rst @@ -1,82 +1,77 @@ -================================================ -HackRF Compatible Software -================================================ +=========================================== +Third-Party Software Compatible With HackRF +=========================================== -Software with HackRF Support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Software That Has Direct Support For 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. +* GQRX + + * `http://gqrx.dk/ `__ + +* GNU Radio + + * https://www.gnuradio.org/ + +* GNU Radio Mode-S/ADS-B + + * `https://github.com/bistromath/gr-air-modes `__ + +* QSpectrumAnalyzer + + * `https://github.com/xmikos/qspectrumanalyzer `__ + +* SDR# + + * `https://airspy.com/download/ `__ + * Windows OS only + * Only nightly builds currently support HackRF One + +* SDR Console + + * https://www.sdr-radio.com/Console + +* Spectrum Analyzer GUI for hackrf_sweep for Windows + + * `https://github.com/pavsa/hackrf-spectrum-analyzer `__ + +* Universal Radio Hacker (Windows/Linux) + + * `https://github.com/jopohl/urh `__ + +* Web-based APRS tracker + + * `https://xakcop.com/aprs-sdr `__ -GNU Radio Based -~~~~~~~~~~~~~~~ +Software That Can Use Data From HackRF +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Baudline -GNU Radio Mode-S/ADS-B - `https://github.com/bistromath/gr-air-modes `__ + * `http://www.baudline.com/ `__ + * Can view/process HackRF data, e.g. hackrf_transfer -GQRX - `http://gqrx.dk/ `__ - - - -Direct Support -~~~~~~~~~~~~~~ - -SDR# (Windows only) - `https://airspy.com/download/ `__ - - * Only nightly builds currently support HackRF One - `http://sdrsharp.com/downloads/sdr-nightly.zip `__ - -SDR_Radio.com V2 - `http://v2.sdr-radio.com/Radios/HackRF.aspx `__ - -Universal Radio Hacker (Windows/Linux) - `https://github.com/jopohl/urh `__ - -QSpectrumAnalyzer - `https://github.com/xmikos/qspectrumanalyzer `__ - -Spectrum Analyzer GUI for hackrf_sweep for Windows - `https://github.com/pavsa/hackrf-spectrum-analyzer `__ - -Web-based APRS tracker `https://xakcop.com/aprs-sdr `__ - - -Can use HackRF data -~~~~~~~~~~~~~~~~~~~ - -Inspectrum `https://github.com/miek/inspectrum `__ +* Inspectrum + * `https://github.com/miek/inspectrum `__ * Capture analysis tool with advanced features -Baudline `http://www.baudline.com/ `__ (Can view/process HackRF data, e.g. hackrf_transfer) +* Matlab + + .. code-block :: sh + + fid = open('samples.bin', 'r'); + len = 1000; % 1000 samples + y = fread(fid, 2*len, 'int8'); + y = y(1:2:end) + 1j*y(2:2:end); + fclose(fid) -HackRF Tools -~~~~~~~~~~~~ +Troubleshooting Recommendations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In addition to third party tools that support HackRF, we provide some commandline tools for interacting with HackRF. For information on how to use each tool look at the help information provided (e.g. ``hackrf_transfer -h``) or the `manual pages `__. +Many of these tools require libhackrf and at times HackRF Tools. It may help you to have updated libhackrf and HackRF Tools when troubleshooting these applications. - * **hackrf_info** Read device information from HackRF such as serial number and firmware version. - - * **hackrf_transfer** Send and receive signals using HackRF. Input/output files are 8-bit signed quadrature samples. - - * **hackrf_sweep**, a command-line spectrum analyzer. - - * **hackrf_clock** Read and write clock input and output configuration. - - * **hackrf_operacake** Configure Opera Cake antenna switch connected to HackRF. - - * **hackrf_spiflash** A tool to write new firmware to HackRF. See: :ref:`Updating Firmware `. - - * **hackrf_debug** Read and write registers and other low-level configuration for debugging. - - -Handling HackRF data -~~~~~~~~~~~~~~~~~~~~ - -Matlab -^^^^^^ - -.. code-block :: sh - - fid = open('samples.bin', 'r'); - len = 1000; % 1000 samples - y = fread(fid, 2*len, 'int8'); - y = y(1:2:end) + 1j*y(2:2:end); - fclose(fid) +It is also strongly suggested, and usually required, that your HackRF Tools and HackRF firmware match. \ No newline at end of file diff --git a/docs/source/tips_tricks.rst b/docs/source/tips_tricks.rst deleted file mode 100644 index ef55b473..00000000 --- a/docs/source/tips_tricks.rst +++ /dev/null @@ -1,40 +0,0 @@ -================================================ -Tips and Tricks -================================================ - -USB Cables (and why to use a noise reducing one) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The USB cable you choose can make a big difference in what you see when using your HackRF and especially when using it around between 120 and 480 MHz where USB is doing all its work. - - #. Use a shielded USB cable. The best way to guarantee RF interference from USB is to use an unshielded cable. You can test that your cable is shielded by using a continuity tester to verify that the shield on one connector has continuity to the shield on the connector at the other end of the cable. - - #. Use a short USB cable. Trying anything larger than a 6ft cable may yield poor results. The longer the cable, the more loss you can expect and when making this post a 15ft cable was tried and the result was the HackRF would only power up half way. - - #. For best results, select a cable with a ferrite core. These cables are usually advertised to be noise reducing and are recognizable from the plastic block towards one end. - -Screenshot before and after changing to a noise reducing cable (`view full size image `__): - -.. image:: ../images/noisereducingcablescreenshot.jpeg - :align: center - -A shielded cable with ferrite core was used in the right-hand image. - -The before and after images were both taken with the preamp on and the LNA and VGA both set to 24db. - - - -Sampling Rate and Baseband Filters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Using a sampling rate of less than 8MHz is not recommended. Partly, this is because the MAX5864 (ADC/DAC chip) isn't specified to operate at less than 8MHz, and therefore, no promises are made by Maxim about how it performs. But more importantly, the baseband filter in the MAX2837 has a minimum bandwidth of 1.75MHz. It can't provide enough filtering at 2MHz sampling rate to remove substantial signal energy in adjacent spectrum (more than +/-1MHz from the tuned frequency). The MAX2837 datasheet suggests that at +/-1MHz, the filter provides only 4dB attenuation, and at +/-2MHz (where a signal would alias right into the center of your 2MHz spectrum), it attenuates about 33dB. That's significant. Here's a picture: - -.. image:: ../images/max2837-1m75bw-at-2m.png - :align: center - -At 8MHz sampling rate, and using the minimum 1.75MHz bandwidth filter, this is the response: - -.. image:: ../images/max2837-1m75bw-at-8m.png - :align: center - -You can see that the attenuation is more than 60dB at +/-2.8MHz, which is more than sufficient to remove significant adjacent spectrum interference before the ADC digitizes the baseband. If using this configuration to get a 2MHz sampling rate, use a GNU Radio block after the 8MHz source that performs a 4:1 decimation with a decently sharp low pass filter (complex filter with a cut-off of <1MHz). \ No newline at end of file diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst deleted file mode 100644 index 0a88d98d..00000000 --- a/docs/source/troubleshooting.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _troubleshooting: - -=============== -Troubleshooting -=============== - -Why isn't my HackRF One detectable after I plug it into my computer? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If your HackRF One isn't immediately detectable it is very possible that your Micro USB cable is not meeting HackRF One's requirements. HackRF One requires quite a bit of supply current and solid USB 2.0 high speed communications to operate. It is common for HackRF One to reveal cables with deficiencies such as carrying power but not data, carrying data but not enough power, etc. Please try multiple cables to resolve this issue. More than once people have gotten their HackRF One to work after trying their fifth cable. - - ----- - - -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 `. 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. - - ----- - - -How should I set the gain controls for RX? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - - ----- - - -What are the minimum system requirements for using HackRF? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most important requirement is that you supply 500 mA at 5 V DC to your HackRF via the USB port. If your host computer has difficulty meeting this requirement, you may need to use a powered USB hub. - -Most users will want to stream data to or from the HackRF at high speeds. This requires that the host computer supports Hi-Speed USB. Some Hi-Speed USB hosts are better than others, and you may have multiple host controllers on your computer. If you have difficulty operating your HackRF at high sample rates (10 Msps to 20 Msps), try using a different USB port on your computer. If possible, arrange things so that the HackRF is the only device on the bus. - -There is no specific minimum CPU requirement for the host computer, but SDR is generally a CPU-intensive application. If you have a slower CPU, you may be unable to run certain SDR software or you may only be able to operate at lower sample rates. - - ----- - - -Why isn't HackRF working with my virtual machine (VM)? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -HackRF requires the ability to stream data at very high rates over USB. Unfortunately VM software typically has problems with continuous high speed USB transfers. - -There are some known bugs with the HackRF firmware's USB implementation. It is possible that fixing these bugs will improve the ability to operate HackRF with a VM, but there is a very good chance that operation at higher sample rates will still be limited. - - ----- - - -What LEDs should be illuminated on the HackRF? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. diff --git a/docs/source/updating_firmware.rst b/docs/source/updating_firmware.rst index b696d37f..39d2b2d7 100644 --- a/docs/source/updating_firmware.rst +++ b/docs/source/updating_firmware.rst @@ -4,12 +4,10 @@ Updating Firmware ================================================ -HackRF devices ship with firmware on the SPI flash memory. The firmware can be updated with nothing more than a USB cable and host computer. +HackRF devices ship with firmware on the SPI flash memory. The firmware can be updated with a USB cable and host computer. These instructions allow you to upgrade the firmware in order to take advantage of new features or bug fixes. -If you have any difficulty making this process work from your native operating system, you can :ref:`use Pentoo or the GNU Radio Live DVD ` to perform the updates. - Updating the SPI Flash Firmware @@ -29,22 +27,18 @@ When writing a firmware image to SPI flash, be sure to select firmware with a fi After writing the firmware to SPI flash, you may need to reset the HackRF device by pressing the RESET button or by unplugging it and plugging it back in. -If you get an error that mentions HACKRF_ERROR_NOT_FOUND, check out the :ref:`FAQ `. It's often a permissions problem that can be quickly solved. +If you get an error that mentions HACKRF_ERROR_NOT_FOUND, it is often a permissions problem on your OS. -Updating the CPLD -~~~~~~~~~~~~~~~~~ +Only if Necessary: Recovering the SPI Flash Firmware +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Older versions of HackRF firmware (prior to release 2021.03.1) require an additional step to program a bitstream into the CPLD. +If the firmware installed in SPI flash has been damaged or if you are programming a home-made HackRF for the first time, you will not be able to immediately use the hackrf_spiflash program as listed in the above procedure. Follow these steps instead: -To update the CPLD image, first update the SPI flash firmware, libhackrf, and hackrf-tools to the version you are installing. Then: - -.. code-block :: sh - - hackrf_cpldjtag -x firmware/cpld/sgpio_if/default.xsvf - -After a few seconds, three LEDs should start blinking. This indicates that the CPLD has been programmed successfully. Reset the HackRF device by pressing the RESET button or by unplugging it and plugging it back in. + #. Follow the DFU Boot instructions to start the HackRF in DFU boot mode. + #. Type ``dfu-util --device 1fc9:000c --alt 0 --download hackrf_one_usb.dfu`` to load firmware from a release package into RAM. If you have a Jawbreaker, use hackrf_jawbreaker_usb.dfu instead. Alternatively, use ``make -e BOARD=HACKRF_ONE RUN_FROM=RAM program`` to load the firmware into RAM and start it. + #. Follow the SPI flash firmware update procedure above to write the ".bin" firmware image to SPI flash. @@ -63,17 +57,6 @@ You should only use a firmware image with a filename ending in ".dfu" over DFU, -Only if Necessary: Recovering the SPI Flash Firmware -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If the firmware installed in SPI flash has been damaged or if you are programming a home-made HackRF for the first time, you will not be able to immediately use the hackrf_spiflash program as listed in the above procedure. Follow these steps instead: - - #. Follow the DFU Boot instructions to start the HackRF in DFU boot mode. - #. Type ``dfu-util --device 1fc9:000c --alt 0 --download hackrf_one_usb.dfu`` to load firmware from a release package into RAM. If you have a Jawbreaker, use hackrf_jawbreaker_usb.dfu instead. Alternatively, use ``make -e BOARD=HACKRF_ONE RUN_FROM=RAM program`` to load the firmware into RAM and start it. - #. Follow the SPI flash firmware update procedure above to write the ".bin" firmware image to SPI flash. - - - Obtaining DFU-Util ~~~~~~~~~~~~~~~~~~ @@ -97,4 +80,19 @@ If you are using a platform without a dfu-util package, build instruction can be make sudo make install -Now you will have the current version of DFU Util installed on your system. \ No newline at end of file +Now you will have the current version of DFU Util installed on your system. + + + +Updating the CPLD +~~~~~~~~~~~~~~~~~ + +Older versions of HackRF firmware (prior to release 2021.03.1) require an additional step to program a bitstream into the CPLD. + +To update the CPLD image, first update the SPI flash firmware, libhackrf, and hackrf-tools to the version you are installing. Then: + +.. code-block :: sh + + hackrf_cpldjtag -x firmware/cpld/sgpio_if/default.xsvf + +After a few seconds, three LEDs should start blinking. This indicates that the CPLD has been programmed successfully. Reset the HackRF device by pressing the RESET button or by unplugging it and plugging it back in. \ No newline at end of file diff --git a/docs/source/usb_cables.rst b/docs/source/usb_cables.rst new file mode 100644 index 00000000..c947ce88 --- /dev/null +++ b/docs/source/usb_cables.rst @@ -0,0 +1,27 @@ +========== +USB Cables +========== + +The USB cable you choose can make a big difference in what you see when using your HackRF and especially when using it around between 120 and 480 MHz where USB is doing all its work. + + #. Use a shielded USB cable. The best way to guarantee RF interference from USB is to use an unshielded cable. You can test that your cable is shielded by using a continuity tester to verify that the shield on one connector has continuity to the shield on the connector at the other end of the cable. + + #. Use a short USB cable. Trying anything larger than a 6ft cable may yield poor results. The longer the cable, the more loss you can expect and when making this post a 15ft cable was tried and the result was the HackRF would only power up half way. + + #. For best results, select a cable with a ferrite core. These cables are usually advertised to be noise reducing and are recognizable from the plastic block towards one end. + +Screenshot before and after changing to a noise reducing cable (`view full size image `__): + +.. image:: ../images/noisereducingcablescreenshot.jpeg + :align: center + +A shielded cable with ferrite core was used in the right-hand image. + +The before and after images were both taken with the preamp on and the LNA and VGA both set to 24db. + + + +Why isn't my HackRF One detectable after I plug it into my computer? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your HackRF One isn't immediately detectable it is very possible that your Micro USB cable is not meeting HackRF One's requirements. HackRF One requires quite a bit of supply current and solid USB 2.0 high speed communications to operate. It is common for HackRF One to reveal cables with deficiencies such as carrying power but not data, carrying data but not enough power, etc. Please try multiple cables to resolve this issue. More than once people have gotten their HackRF One to work after trying their fifth cable. \ No newline at end of file diff --git a/docs/source/virtual_machines.rst b/docs/source/virtual_machines.rst new file mode 100644 index 00000000..a93973e2 --- /dev/null +++ b/docs/source/virtual_machines.rst @@ -0,0 +1,5 @@ +================ +Virtual Machines +================ + +HackRF requires the ability to stream data at very high rates over USB. Unfortunately VM software typically has problems with USB passthrough; especially continuous high speed USB transfers. It is recommended to not use a HackRF with a VM. \ No newline at end of file