Installing GNU Radio Companion for the HackRF One
Overview
Every sector of today’s society is entirely dependent on connectivity. As a result, communication systems engineering has evolved into an essential profession where practitioners are required to master a diverse set of skills and tools in order to solve the latest technical challenges. This was not the case several decades ago as various engineers would individually handle tasks such as algorithmic development for the transceiver, theoretical performance analysis of the end-to-end communication system, implementation of the digital signal processing, and development of the radio frequency front-end for a single communication system. In this era, these silos overlap leading to the need for an engineer to know how to provide solutions across these silos on the same project such as designing a communication system algorithm and masterfully implementing it on a field programmable gate array (FPGA) or an embedded processing device. At the heart of this, is a technology referred to as Software Defined Radio (SDR).
Modern advances in computing technologies, digital signal processing (DSP) and digital communication algorithms, artificial intelligence, radio frequency (RF) hardware design, networking topologies and many other elements have evolved modern communication systems into complex, intelligent, high-performance platforms that can adapt to operational environments and deliver large amounts of information in real-time, error-free. SDR, the latest step in communication systems technology adopts the most recent advances in all these fields to yield the ultimate transmitter and receiver.
In the next upcoming posts, I will be sharing different experiments, findings and project developments on SDRs, particularly aligning to Dynamic Spectrum Access (DSA), which is one of the latest opportunities that can provide access to unutilised or underutilised spectrum for new services, particularly broadband access. My focus will therefore feature findings on the RF bands already identified across the globe for spectrum sharing — some are already licensed and approved in some countries while some are still under study (particularly the IMT and satellite ones) although I must mention it will also depend with the frequency range the SDR I am using is covering. I am currently in possession of a Hack RF One and two RTL-SDRs (the Nano and the Mini). I intend to expand my Lab with others in the near future. I also have some FPGA equipment that I will get to explore as well and get to share my knowledge both from the hardware and the software side. Of course, as an enthusiast of IoT, time to time I will also share my spectrum measurements on the various frequencies for Low Power Wide Area Networks exploitation (both unlicensed and licensed). The detailed contents I will get to share will be a highlight of my publications together with other people’s work that I have also found amazing to study and try out. I will be doing this through links to my published papers or the other peoples’ works.
As a kickstart, in this post, I begin by sharing how one can install the GNU radio companion for the Hack RF One on a Linux system (in my case, I am using Pop!_OS 21.04). GNU radio is a framework that enables users to design, simulate and deploy highly capable real-world radio systems. There exists a huge community of GNU radio and a lot of content and instruction about GNU radio can be found on this link of the GNU radio academy. While this installation has been covered in different blog posts as well as a series of amazing videos here and the Great Scott Gadgets website, I just want to contribute to that by trying to make everything under one roof based on my first-hand experience and notably my own deviations.
About SDR
For over 2 decades now, Software Defined Radio (SDR) has been a topic of great interest and extensive research and development with makers, students, hobbyists, engineers, researchers and computer scientists doing different amazing stuff under this topic. Moreover, SDRs can be used to implement FM receivers, spectral viewing designs and even construct systems to decode the ID of a nearby cellular base station.
In a nutshell, an SDR can be defined as simply a radio that can be programmed through a software platform in order to implement multiple radio functions. A radio on the other hand is defined as a communication system employing wireless transmission of information by means of electromagnetic waves propagated through space. While radio became an amazing reality due to earlier brilliant theorists and experimentalists, the convergence of micro-electronics with it has spun into an amazing evolution of SDRs.
There exists a number or different families of SDRs with the cheapest and most affordable being the RTL-SDR but in this post, I am only covering the Hack RF One. Figure 1 shows an architectural diagram of SDR implementation with a Mini RTL-SDR and a Nano RTL-SDR connected to a windows PC and a raspberry Pi respectively. I have listed other notable SDRs in table 1 which could come with improvements like front-end filters, larger ADCs, wider bandwidths, wider frequency ranges and possibly transmit capabilities (like the Hack RF One).
Figure 1: Architectural diagram with a Mini RTL-SDR and a Nano RTL-SDR
Table 1: A list of notable SDRs
The Hack RF One is the current hardware platform for the HackRF project. This SDR peripheral is capable of transmission or reception (in a half-duplex fashion) of radio signals from 1 MHz to 6 GHz. It has a bandwidth of 20 MHz with an ADC of 8-bits. More information on it can be found on this link. The HackRF One antenna is an ANT500 from Great Scott Gadgets designed to operate from 75 MHz to 1 GHz. Its total length is configurable from 20cm to 88cm. ANT500 is constructed of stainless steel and features an SMA male connector, rotating shaft and adjustable elbow. Figure 2 shows the Hack RF One connected to my PC while Figure 3 shows the ANT500.
Figure 2: HackRF One connected to my PC
Figure 3: The ANT500 HackRF One Antenna
The Operating System
Although the greatscottgadgets.com suggests setting up the Hack RF on the Pentoo Linux, I share my setup here on the Pop!_OS. I am guessing one would have a great experience with the Pentoo Linux, especially if their focus is on Cybersecurity — predominantly penetration testing and security assessment but for my case (focused on the Telecommunications Engineering concepts), I am choosing to set this up on the Pop!_OS_21.04. In addition, I do not have a free PC to try set up the Pentoo as I have a plethora of embedded developments running on my Pop!_OS since the best full experience of Pentoo requires setting up a full Linux environment.
Pop!_OS, similar to Ubuntu and Fedora, ships with the GNOME desktop so there is largely no much of a difference between it and Ubuntu. In fact, Ubuntu 20.04 pushed me an upgrade to Pop!_OS 21.04 a few months back although the Pop!_OS is based on Cosmic desktop. If you would like to learn more about Pop!_OS_21.04, I suggest you look at these videos — video_1 and video 2 as well as this link to the Pop!_OS website.
Setting up the GNU Radio
In my set up, I have obediently followed instructions provided through this link so that I do not break anything in my setup. If you already have the HackRF One hardware, run the following command to install it on Pop!_OS_21.04.
$sudo apt install hackrf
then check if the hackrf is installed and detected by running the following command
$ hackrf_info
If your output appears as shown in figure 4, then your Hack RF hardware is correctly installed and detectable on the Pop!_OS.
Figure 4: Output of the terminal command for HackRF information
Ensure you make Python3 the default python by editing the .bashrc (I have used VIM but feel free to use your favourite IDE). Python3 is the most up-to-date version of the Python language with many improvements made to increase the efficiency and simplicity of the code that you write.
$ vim ~/.bashrc
Add the following line to the bashrc file:
alias python=python3 the run the below command to permanently select python3
$source ~/.bashrc
Next, install the Python Bundles Overlay Managed Build System (PyBOMBS). PyBOMBS is a meta-package manager that can install packages from source or using the local package managers. It was mainly designed by users of the GNU Radio project, which is extended by a large number of out-of-tree (OOT) modules. The installation link is found here on Github. If you find these instructions unclear, you can skip to the last section where I list the commands of successfully setting up PyBombs.
Next, update the firmware of the HackRF. Download the latest firmware from this link — https://github.com/mossmann/hackrf/releases/tag/v2021.03.1. This downloads the firmware version released on 1st March of 2021 (2021.03.1). At the time of the release of this post, this is the latest firmware version for the HackRF One. Unzip the file and change into the directory — firmware-bin (This is located in the folder of the latest firmware you have downloaded and unzipped)
$ cd hackrf-2021.03.1/firmware-bin
Then run the following command
$ hackrf_spiflash -w hackrf_one_usb.bin
The successful execution of this command should give you the following output shown in figure 5.
Figure 5: Successful firmware upgrade of the HackRF One
Next, you might need to also update the Complex Programmable Logic Device (CPLD). The CPLD is the interface handler to the quadrature ADC. Many CPLDs and FPGAs have integrated phase locked loops (PLLs) for generating stable, phase-aligned clocks for other peripherals. The CPLD essentially plays the following role:
- Generate the ADC sample clock from the internal PLL.
- Distribute the clock to the ADC and the Cortex.
- Handle bus deskew on the ADC parallel bus
- Offer in-line buffering of the ADC to allow the Cortex chip to service interrupts without breaking sample sequence in the role of a very small stream FIFO.
Therefore, to update the CPLD, use the following commands
$ cd hackrf-2021.03.1/firmware/cpld/sgpio_if
then run the next command.
$ hackrf_cpldjtag -x sgpio_if/default.xsvf
You can then check if the firmware has been upgraded by re-running the command
$ hackrf_info
If your output appears as below, then your firmware has been successfully upgraded.
Figure 6: HackRF interface with upgraded firmware
If the firmware is not working properly, you can run the following command
$ sudo apt install dfu-util
The LPC4330 microcontroller of the HackRF is capable of booting from several code sources. By default, HackRF boots from SPI flash memory (SPIFI). It can also boot HackRF in DFU (USB) boot mode. In this mode, the SDR will enumerate over USB, wait for code to be delivered using the DFU (Device Firmware Update)standard over USB and then executes that code from RAM. SPIFI is normally unused and unaltered in DFU mode. Please note, this mode is only relevant if the firmware installed in SPI flash has been damaged or when programming a home-made HackRF for the first time. More details on this can be found in the HackRF documentation.
Installing GNU Radio
First, run the following command to include the repository of the GNU radio to the Pop!_OS hirsuite’s Personal Package Archive (PPA). Installing via PPA allows you to easily get newer GNU software version that may not be available in the official repositories.
$ sudo add-apt-repository ppa:gnuradio/gnuradio-releases
Then update the OS
$ sudo apt update
and run the following command to install GNU Radio version 3.8.x with Python3 support
$ sudo apt-install git cmake g++ libboost-all-dev libgmp-dev swig python3-numpy python3-mako python3-sphinx python3-lxml doxygen libfftw3-dev libsdl1.2-dev libgsl-dev libqwt-qt5-dev libqt5opengl5-dev python3-pyqt5 liblog4cpp5-dev libzmq3-dev python3-yaml python3-click python3-click-plugins python3-zmq python3-scipy python3-gi python3-gi-cairo gir1.2-gtk-3.0 libcodec2-dev libgsm1-dev
Then run the following commands
$ git clone — recursive https://github.com/gnuradio/gnuradio.git (remember two dashes after “clone”)
$ cd gnuradio
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/usr/bin/python3 ../
$make -j3 (This is based on the specs of my Pop!_OS PC)
$make test
$sudo make install
$sudo ldconfig
Setting up PyBOMBS
Run the following set of commands:
$ sudo apt install python3-pip (This command installs PIP — Package Installer for Python).
$ sudo pip3 install pybombs
$ pybombs auto-config
$ pybombs recipes add-defaults
$ pybombs prefix init ~/prefix-3.8 -R gnuradio-default
$ source ~/prefix-3.8/setup_env.sh
Sometimes gnu-radio companion starts having issues with the PYTHONPATH. In such a case, follow the guide on this link to resolve it.
If everything is okay, when you run the below command:
$ gnuradio-companion
the following welcome prompt should appear as shown in Figure 7 with the interface for the GNU Radio Companion launching to appear as shown in Figure 8.
Figure 7: GNU Radio Companion Welcome prompt
Figure 8: GNU Radio Companion Interface
This should successfully setup GNU Radio Companion for HackRF One on your Linux PC (Pop!_OS_21.04 or any Ubuntu version. I have not been able to set this up on Pentoo Linux but I think the setup should be quite similar and straightforward.
Conclusions
An SDR is a combination of hardware and software technologies that enable reconfigurable system architectures for wireless networks and user terminals. SDR provides an efficient and comparatively inexpensive solution to the problem of building multi-mode, multi-band and multi-functional wireless devices that can be enhanced using software upgrades. I can’t wait to share more on this topic with more practical examples in the future posts.
