Great Scott Gadgets HackRF User manual

HackRF
Great Scott Gadgets
Jul 15, 2021

USER DOCUMENTATION
1 Getting Started with HackRF and GNU Radio 1
1.1 Try Your HackRF with Pentoo Linux .................................. 1
1.2 Software Setup .............................................. 2
1.3 Examples ................................................. 2
2 hackrf_sweep 3
2.1 Usage ................................................... 3
2.2 Output fields ............................................... 3
3 Operating System Tips 5
3.1 Package managers ............................................ 5
3.2 Building from source ........................................... 6
4 HackRF One 9
4.1 Features .................................................. 9
4.2 Differences between Jawbreaker and HackRF One ........................... 9
4.3 Enclosure Options ............................................ 10
4.4 Using HackRF One’s Buttons ...................................... 10
4.5 SMA, not RP-SMA ............................................ 10
4.6 Transmit Power .............................................. 11
4.7 Receive Power .............................................. 11
4.8 External Clock Interface (CLKIN and CLKOUT) ............................ 11
4.9 Hardware Documentation ........................................ 12
4.10 Expansion Interface ........................................... 12
5 Opera Cake 17
5.1 Using Opera Cake ............................................ 17
5.2 Opera Glasses .............................................. 18
6 Updating Firmware 19
6.1 Updating the SPI Flash Firmware .................................... 19
6.2 Updating the CPLD ........................................... 19
6.3 Only if Necessary: DFU Boot ...................................... 20
6.4 Only if Necessary: Recovering the SPI Flash Firmware ......................... 20
6.5 Obtaining DFU-Util ........................................... 20
7 FAQ 23
7.1 I can’t seem to access my HackRF under Linux ............................. 23
7.2 hackrf_set_sample_rate fails ....................................... 25
7.3 What is the big spike in the center of my received spectrum? ...................... 25
7.4 How do I deal with the DC offset? .................................... 26
i

7.5 Purchasing HackRF ........................................... 26
7.6 Making sense of gain settings ...................................... 26
7.7 System Requirements .......................................... 27
7.8 LEDs ................................................... 27
7.9 Half-Duplex, Full-Duplex ........................................ 27
7.10 What is the receive sensibility of HackRF? ............................... 28
7.11 Troubleshooting ............................................. 28
8 HackRF Hacks 29
9 Getting Help 31
10 Tips and Tricks 33
10.1 USB Cables (and why to use a noise reducing one) ........................... 33
10.2 Sampling Rate and Baseband Filters ................................... 33
11 Firmware Development Setup 35
12 LPC43xx Debugging 37
12.1 Black Magic Probe ............................................ 37
12.2 LPC-Link ................................................. 37
12.3 ST-LINK/V2 ............................................... 37
12.4 Run ARM GDB ............................................. 39
13 LPC43xx SGPIO Configuration 41
13.1 Frequently Asked Questions ....................................... 41
14 LPC43xx USB DFU Notes 43
14.1 Setup ................................................... 43
14.2 Usage Notes ............................................... 43
14.3 Jellybean Notes .............................................. 44
15 LPC43xx USB Implementation 45
15.1 Initial Experimentation and Discovery .................................. 45
16 Hardware Components 47
16.1 Block Diagrams ............................................. 48
17 Clocking 51
18 Multiple device hardware level synchronization 53
18.1 Purpose .................................................. 53
18.2 Related work ............................................... 53
18.3 Requirements ............................................... 53
18.4 Opening your HackRF .......................................... 54
18.5 Connect the clocks ............................................ 54
18.6 Identify the pin headers ......................................... 55
18.7 Wire up the pin headers ......................................... 57
18.8 Upgrade ................................................. 59
18.9 Testing with hackrf_transfer ....................................... 59
18.10 What next? ................................................ 60
19 Software Support 63
19.1 Software with HackRF Support ..................................... 63
19.2 GNU Radio Based ............................................ 63
19.3 Direct Support .............................................. 63
ii

19.4 Can use HackRF data .......................................... 63
19.5 HackRF Tools .............................................. 64
19.6 Handling HackRF data .......................................... 64
20 libhackRF API 65
20.1 Setup, Initialization and Shutdown .................................... 65
20.2 Using the Radio ............................................. 67
20.3 Reading and Writing Registers ...................................... 68
20.4 Updating Firmware ............................................ 69
20.5 Board Identifiers ............................................. 70
20.6 Miscellaneous .............................................. 71
20.7 Data Structures .............................................. 71
20.8 Enumerations ............................................... 72
21 Jawbreaker 75
21.1 Features .................................................. 75
21.2 Set your Jawbreaker Free! ........................................ 75
21.3 SMA, not RP-SMA ............................................ 76
21.4 Transmit Power .............................................. 76
21.5 Hardware Documentation ........................................ 76
21.6 Expansion Interface ........................................... 76
22 Design Goals 83
23 Future Hardware Modifications 85
23.1 Antenna .................................................. 85
23.2 Baseband ................................................. 85
23.3 CPLD ................................................... 85
23.4 Clocking ................................................. 85
23.5 USB ................................................... 86
23.6 Power Management ........................................... 86
23.7 Regulators ................................................ 86
23.8 Buttons .................................................. 86
23.9 Shielding ................................................. 86
23.10 Footprints ................................................. 86
23.11 Shield Support .............................................. 87
24 Lemondrop Bring Up 89
24.1 Si5351 I2C ................................................ 89
25 LPC4350 SGPIO Experimentation 95
25.1 SGPIO Examples ............................................. 95
iii

iv

CHAPTER
ONE
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.
1.1 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 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.
1

HackRF
1.2 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 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.
1.3 Examples
A great way to get started with HackRF is the SDR with HackRF video series. Additional examples follow:
Testing the HackRF
1. Plug in the HackRF
2. run the hackrf_info command $ hackrf_info
If everything is OK, you should see something similar to the following:
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
1. Download the FM Radio Receiver python file here
2. Run the file $ python ./fm_radio_rx.py
3. You can find the GNU Radio Companion source file here
2 Chapter 1. Getting Started with HackRF and GNU Radio

CHAPTER
TWO
HACKRF_SWEEP
2.1 Usage
[-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
[-n num_samples]# Number of samples per frequency, 8192-4294967296
[-w bin_width]# FFT bin width (frequency resolution) in Hz
[-1]# one shot mode
[-B]# binary output
[-I]# binary inverse FFT output
-r filename # output file
2.2 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:
Date Time Hz
Low
Hz
High
Hz bin
width
Num
Sam-
ples
dB dB dB dB dB
2019-
01-03
11:57:34.967805240000000024050000001000000.0020 -64.72 -63.36 -60.91 -61.74 -58.58
2019-
01-03
11:57:34.967805241000000024150000001000000.0020 -69.22 -60.67 -59.50 -61.81 -58.16
2019-
01-03
11:57:34.967805240500000024100000001000000.0020 -61.19 -70.14 -60.10 -57.91 -61.97
2019-
01-03
11:57:34.967805241500000024200000001000000.0020 -72.93 -79.14 -68.79 -70.71 -82.78
2019-
01-03
11:57:34.967805242000000024250000001000000.0020 -67.57 -61.61 -57.29 -61.90 -70.19
2019-
01-03
11:57:34.967805243000000024350000001000000.0020 -56.04 -59.58 -66.24 -66.02 -62.12
3

HackRF
Two ranges of 5 MHz are analyzed at once from the same set of samples, so a single timestamp applies to the whole
range.
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.
4 Chapter 2. hackrf_sweep

CHAPTER
THREE
OPERATING SYSTEM TIPS
Here are some software setup tips for particular Operating Systems and Linux distributions.
3.1 Package managers
We highly recommend that, unless developing or testing new features of HackRF, most users use build systems or
package management provided for their operating system.
3.1.1 Linux
Ubuntu / Debian
sudo apt install gqrx-sdr
Fedora / Red Hat
sudo dnf install gnuradio gr-osmosdr hackrf gqrx -y
Gentoo Linux
emerge -a net-wireless/hackrf-tools
USE="hackrf" emerge -a net-wireless/gr-osmosdr
Arch Linux
pacman -S gnuradio gnuradio-osmosdr
pacman -S gnuradio-companion
5

HackRF
3.1.2 OS X (10.5+)
MacPorts
sudo port install gr-osmosdr
Homebrew
brew install gr-osmosdr
3.1.3 Windows
Binaries are provided as part of the PothosSDR project, they can be downloaded here.
3.1.4 FreeBSD
You can use the binary package: # pkg install hackrf
You can build and install from ports:
# cd /usr/ports/comms/hackrf
# make install
3.2 Building from source
3.2.1 Linux / OS X / *BSD
Preparing Your System
First of all, make sure that your system is up to date using your operating system provided update method.
3.2.2 Installing using PyBOMBS
The GNU Radio project has a build system that covers the core libraries, drivers for SDR hardware, and many out of
tree modules. PyBOMBs will take care of installing dependencies for you.
3.2.3 Building HackRF tools from source
Acquire the source for the HackRF tools from either a release archive or git: git clone https://github.com/
mossmann/hackrf.git
Once you have the source downloaded, the host tools can be built as follows:
cd hackrf/host
mkdir build
cd build
cmake ..
(continues on next page)
6 Chapter 3. Operating System Tips

HackRF
(continued from previous page)
make
sudo make install
sudo ldconfig
If you have HackRF hardware, you may need to update the firmware to match the host tools versions.
3.2.4 Windows
Prerequisites for Cygwin, MinGW, or Visual Studio
•cmake-2.8.12.1 or later from http://www.cmake.org/cmake/resources/software.html
•libusbx-1.0.18 or later from http://sourceforge.net/projects/libusbx/files/latest/download?source=files
•fftw-3.3.5 or later from http://www.fftw.org/install/windows.html
•Install Windows driver for HackRF hardware or use Zadig see http://sourceforge.net/projects/libwdi/files/zadig
–If you want to use Zadig select HackRF USB device and just install/replace it with WinUSB driver.
Note for Windows build: You shall always execute hackrf-tools from Windows command shell and not from Cygwin
or MinGW shell because on Cygwin/MinGW Ctrl+C is not managed correctly and especially for hackrf_transfer the
Ctrl+C (abort) will not stop correctly and will corrupt the file.
For Visual Studio 2015 x64
Create library definition for MSVC to link to C:\fftw-3.3.5-dll64> lib /machine:x64 /def:libfftw3f-3.
def
c:\hackrf\host\build> cmake ../ -G "Visual Studio 14 2015 Win64" \
-DLIBUSB_INCLUDE_DIR=c:\libusb-1.0.21\libusb \
-DLIBUSB_LIBRARIES=c:\libusb-1.0.21\MS64\dll\lib\libusb-1.0.lib \
-DTHREADS_PTHREADS_INCLUDE_DIR=c:\pthreads-w32-2-9-1-release\Pre-built.2\include \
-DTHREADS_PTHREADS_WIN32_LIBRARY=c:\pthreads-w32-2-9-1-release\Pre-built.2\lib\x64\
˓→pthreadVC2.lib \
-DFFTW_INCLUDES=C:\fftw-3.3.5-dll64 \
-DFFTW_LIBRARIES=C:\fftw-3.3.5-dll64\libfftw3f-3.lib
CMake will produce a solution file named HackRF.sln and a series of project files which can be built with msbuild
as follows: c:\hackrf\host\build> msbuild HackRF.sln
Cygwin
mkdir host/build
cd host/build
cmake ../ -G "Unix Makefiles" -DCMAKE_LEGACY_CYGWIN_WIN32=1-DLIBUSB_INCLUDE_DIR=/usr/
˓→local/include/libusb-1.0/
make
make install
3.2. Building from source 7

HackRF
MinGW
mkdir host/build
cd host/build
cmake ../ -G "MSYS Makefiles" -DLIBUSB_INCLUDE_DIR=/usr/local/include/libusb-1.0/
make
make install
8 Chapter 3. Operating System Tips

CHAPTER
FOUR
HACKRF ONE
HackRF One is the current hardware platform for the HackRF project. It is a Software Defined Radio peripheral capable
of transmission or reception of radio signals from 1 MHz to 6 GHz. Designed to enable test and development of modern
and next generation radio technologies, HackRF One is an open source hardware platform that can be used as a USB
peripheral or programmed for stand-alone operation.
4.1 Features
•half-duplex transceiver
•operating freq: 1 MHz to 6 GHz
•supported sample rates: 2 Msps to 20 Msps (quadrature)
•resolution: 8 bits
•interface: High Speed USB (with USB Micro-B connector)
•power supply: USB bus power
•software-controlled antenna port power (max 50 mA at 3.3 V)
•SMA female antenna connector (50 ohms)
•SMA female clock input and output for synchronization
•convenient buttons for programming
•pin headers for expansion
•portable
•open source
4.2 Differences between Jawbreaker and HackRF One
Jawbreaker was the beta platform that preceded HackRF One. HackRF One incorporates the following changes and
enhancements:
•Antenna port: No modification is necessary to use the SMA antenna port on HackRF One.
•PCB antenna: Removed.
•Size: HackRF One is smaller at 120 mm x 75 mm (PCB size).
•Enclosure: The commercial version of HackRF One from Great Scott Gadgets ships with an injection molded
plastic enclosure. HackRF One is also designed to fit other enclosure options.
9

HackRF
•Buttons: HackRF One has a RESET button and a DFU button for easy programming.
•Clock input and output: Installed and functional without modification.
•USB connector: HackRF One features a new USB connector and improved USB layout.
•Expansion interface: More pins are available for expansion, and pin headers are installed on HackRF One.
•Real-Time Clock: An RTC is installed on HackRF One.
•LPC4320 microcontroller: Jawbreaker had an LPC4330.
•RF shield footprint: An optional shield may be installed over HackRF One’s RF section.
•Antenna port power: HackRF One can supply up to 50 mA at 3.3 V DC on the antenna port for compatibility
with powered antennas and other low power amplifiers.
•Enhanced frequency range: The RF performance of HackRF One is better than Jawbreaker, particularly at the
high and low ends of the operating frequency range. HackRF One can operate at 1 MHz or even lower.
4.3 Enclosure Options
The commercial version of HackRF One from Great Scott Gadgets ships with an injection molded plastic enclosure,
but it is designed to fit two optional enclosures:
•Hammond 1455J1201: HackRF One fits this extruded aluminum enclosure and other similar models from Ham-
mond 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.
4.4 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.
4.5 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.
10 Chapter 4. HackRF One

HackRF
4.6 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.
4.7 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.
4.8 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.
4.6. Transmit Power 11

HackRF
4.9 Hardware Documentation
Schematic diagram, assembly diagram,and bill of materials can be found at https://github.com/mossmann/hackrf/tree/
master/doc/hardware
4.10 Expansion Interface
The HackRF One expansion interface consists of headers P9, P20, P22, and P28. These four headers are installed on
the commercial HackRF One from Great Scott Gadgets.
4.10.1 P9 Baseband
A direct analog interface to the high speed dual ADC and dual DAC.
Pin Function
1 GND
2 GND
3 GND
4 RXBBQ-
5 RXBBI-
6 RXBBQ+
7 RXBBI+
8 GND
9 GND
10 TXBBI-
11 TXBBQ+
12 TXBBI+
13 TXBBQ-
14 GND
15 GND
16 GND
12 Chapter 4. HackRF One

HackRF
4.10.2 P20 GPIO
Providing access to GPIO, ADC, RTC, and power.
Pin Function
1 VBAT
2 RTC_ALARM
3 VCC
4 WAKEUP
5 GPIO3_8
6 GPIO3_0
7 GPIO3_10
8 GPIO3_11
9 GPIO3_12
10 GPIO3_13
11 GPIO3_14
12 GPIO3_15
13 GND
14 ADC0_6
15 GND
16 ADC0_2
17 VBUSCTRL
18 ADC0_5
19 GND
20 ADC0_0
21 VBUS
22 VIN
4.10.3 P22 I2S
I2S, SPI, I2C, UART, GPIO, and clocks.
4.10. Expansion Interface 13

HackRF
Pin Function
1 CLKOUT
2 CLKIN
3 RESET
4 GND
5 I2C1_SCL
6 I2C1_SDA
7 SPIFI_MISO
8 SPIFI_SCK
9 SPIFI_MOSI
10 GND
11 VCC
12 I2S0_RX_SCK
13 I2S_RX_SDA
14 I2S0_RX_MCLK
15 I2S0_RX_WS
16 I2S0_TX_SCK
17 I2S0_TX_MCLK
18 GND
19 U0_RXD
20 U0_TXD
21 P2_9
22 P2_13
23 P2_8
24 SDA
25 CLK6
26 SCL
4.10.4 P28 SD
SDIO, GPIO, clocks, and CPLD.
14 Chapter 4. HackRF One