Draft-AN-445

Application Note Number
AN-445

Abstract
This Application Note provides a comprehensive guide for building and installing the open-source toolchain for the USRP (UHD and GNU Radio) from source code on a Linux platform. The Ubuntu distribution is specifically discussed.

UHD on Linux
UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

Devices
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, and N210 devices. The E310 and E312 devices are embedded devices which are fundamentally different from the other non-embedded devices. They are not addressed in this document.

Install Linux
If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 22.04, Ubuntu 20.04, or Debian Bullseye with a 64-bit architecture. There are several variants of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should work. For the purposes of this document, these variants can be considered equivalent.

Download and install Ubuntu or Debian from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.


 * Ubuntu download page
 * Xubuntu download page
 * Debian download page

There are many tools for writing an ISO image to a USB flash drive. On most Ubuntu systems, there is the Startup Disk Creator utility. For other Linux OSs, MacOS, or Windows you can use Balena Etcher, UNetbootin, or many others. See 6 Best Bootable USB Creators for Linux for example.


 * Balena Etcher github page
 * UNetbootin github page

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

Update and Install dependencies
Before building UHD and GNU Radio, you need to make sure that all the dependencies are installed.

The following commands will install all the required dependencies. Before running them, you should ensure that the "Main" and "Universe" repositories are enabled in &quot;Software Sources&quot;.

Next, on a terminal screen, run:

sudo apt-get update

Once the system has been updated, then install the required dependencies below.

Focal Fossa (20.04) through Kinetic Kudu (22.10)
GNU Radio version 3.8.x with Python 3 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 libusb-1.0-0 libusb-1.0-0-dev libudev-dev

GNU Radio version 3.9.x in addition to above requires:

sudo apt install pybind11-dev python3-matplotlib libsndfile1-dev \ python3-pip libsoapysdr-dev soapysdr-tools

pip install pygccxml pip install pyqtgraph

GNU Radio version 3.10.x and the 'main' branch in addition to above require:

sudo apt install libiio-dev libad9361-dev libspdlog-dev python3-packaging python3-jsonschema

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

Building and installing UHD from source code
UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below.


 * UHD repository on GitHub

If you want to use GNU Radio with a USRP, install the UHD package from source using the following instructions. UHD sits at the same level as GNU Radio as an independent driver, which gr-uhd references. So if you want gr-uhd enabled, you FIRST must clone and install UHD.

For this example, we will start in the home directory to parallel the steps for installing GNU Radio from source.

cd ~/

Clone the code into your home directory:

git clone https://github.com/EttusResearch/uhd.git cd ~/uhd

Note: In the following command, change  to some other branch or tag if you want to build a different version. git checkout v4.4.0.0

Note: Unlike most GNU Radio build processes, UHD builds under the  directory. cd host mkdir build cd build

Note: In the following command, we will use  to install UHD into the same prefix as GNU Radio.

cmake -DCMAKE_INSTALL_PREFIX=/usr/local ../

Note: In the following command, if your computer's CPU has multiple cores, you can use the argument  to speed compilation; e.g.,   will use 3 threads in the build. Specify at most one less than the number of CPU cores so the system does not appear to 'freeze' during the build. If not specified, then a single thread is used for the build.

make -j3 make test sudo make install

Finally, make sure that the  environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your  file:

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running. You should see something similar to the following.

[INFO] [UHD] linux; GNU C++ version 12.2.0; Boost_107400; UHD_4.4.0.HEAD-0-g5fac246b No UHD Devices Found

You can now download the UHD FPGA Images for this installation. sudo uhd_images_downloader

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. cd ~/uhd/host/utils sudo cp uhd-usrp.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger

The installation of UHD is now complete. At this point, connect the USRP to the host computer and run: uhd_usrp_probe

Building and installing GNU Radio from source code
GNU Radio is open-source, and is hosted on GitHub. You can browse the code online at the link below.


 * GNU Radio repository on GitHub

The development of GNU Radio is very fast-paced, but the GNU Radio Wiki is kept up to date with all changes. Therefore the best place to get build instructions is here for versions 3.9+ and here for version 3.8.

Configuring USB
On Linux, 'udev' handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. cd ~/uhd/host/utils sudo cp uhd-usrp.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger

Configuring Ethernet
For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with, Network Manager will probably overwrite these settings.

Connect the USRP
The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run " ". You should see the USRP listed on the USB bus with a VID of  and PID of ,  ,  , for B200, B210, B200mini, respectively.

Also try running " " and " ".

Thread priority scheduling
When UHD spawns a new thread, it may try to boost the thread's scheduling priority. If setting the new priority fails, the UHD software prints a warning to the console, as shown below. This warning is harmless; it simply means that the thread will retain a normal or default scheduling priority.

UHD Warning: Unable to set the thread priority. Performance may be negatively affected. Please see the general application notes in the manual for instructions. EnvironmentError: OSError: error in pthread_setschedparam

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. This can be enabled by creating a group, adding your user to it, and then appending the line   to the file.

sudo groupadd usrp sudo usermod -aG usrp $USER

Then add the line below to end of the file :

@usrp - rtprio 99

You must log out and log back into the account for the settings to take effect. In most Linux distributions, a list of groups and group members can be found in the  file.

There is further documentation about this in the User Manual at the link below.


 * Threading Notes section of the User Manual