Difference between revisions of "Instructions for System Setup and Configuration"

Latest revision as of 11:49, 25 January 2026

Author

Neel Pandeya

Introduction

This document provides instructions for attendees to setup and configure their laptop or desktop computer system for use with the hands-on exercises and labs for the "USRP Open-Source Toolchain: UHD and GNU Radio" workshop/tutorial.

This document assumes that you are using a USRP B200/B210 radio, although the USRP X300/X310, N300, N310, N320, N321, X410 may also be used as well.

In some sessions, the radio will be provided to you, but in other sessions you will need to provide your own radio. Check this with the organizer of your session.

Your laptop or desktop computer should be no more than about six or seven years old, with an Intel i5, i7, or i9 CPU, or AMD equivalent, running at a 3.5 GHz clock speed or higher, with 8 GB memory, and at least one USB 3.0 port (for USRP B200/B210 radios) and one RJ-45 Ethernet port (for other USRP radios). You will need about 30 GB of free disk space for the Linux installation. You will need to have internet access during the entire installation, set-up, and configuration process.

Also note that all of this is optional. You only have to do this if you want to use the USRP in the workshop to do the hands-on exercises, and actually use the USRP radio. If you do not want to do this, and if you simply want to sit back and watch the instructor's presentation, then you can skip all of this, and just come to the workshop with a cup of coffee.

Step 1: Install Xubuntu 24.04.3

Install Xubuntu 24.04.3. You may also install Ubuntu itself, or any other Ubuntu flavor, such as Kubuntu, Lubuntu, Cinnamon, MATE, or Linux Mint. We recommend using Xubuntu because it is very light-weight, and the user interface is easy-to-use and intuitive, and it runs fast on older or resource-constrained hardware.

https://ubuntu.com/desktop/flavors

Please install on-the-metal, not in a Virtual Machine (VM). Please install specifically version 24.04.3.

If you already have an existing Windows or Linux installation on your computer, then you can install Ubuntu or Xubuntu alongside your already-existing operating system, in a dual-boot configuration. The installer will ask you about this, and it supports installing in a dual-boot configuration. However, note that there can be some challenges when dual-booting with Windows 11, and this may not be easy to set up and may not work well.

You can download the ISO images for Xubuntu from the links below. Write the ISO image to a USB 3.0 drive, and boot from it, and install Xubuntu. The USB drive capacity should be a minimum of 16 GB.

https://xubuntu.org/download/

https://cdimage.ubuntu.com/xubuntu/releases/noble/release/

Step 2: Installation Settings

During the Xubuntu installation process, set the username to be "ettus". This is not strictly necessary, but if you do this, then it will make all the commands in the installation instructions and in the exercises work more easily. The hostname does not matter. Do not use any disk encryption. Do not enable any volume management.

Step 3: Apply Updates

Once the installation is complete, boot into it, and open a terminal window, and apply updates. Run the commands listed below, in a terminal window.

   sudo apt update
   sudo apt upgrade

Step 4: Install Dependencies

Install the package dependencies for UHD, GNU Radio, and other tools. Run the commands listed below, in a terminal window.

   sudo apt-get install openssh-server htop tree lshw meld git libfftw3-bin ncurses-bin libncurses6 libncursesw6 net-tools ethtool aptitude screen hwloc inxi wireshark wireshark-doc wireshark-dev tshark build-essential ntp doxygen gnome-disk-utility cpufrequtils libsndfile1-dev

   sudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool g++ git inetutils-tools libboost-all-dev libncurses6 libncurses-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev python3-dev python3-mako python3-numpy python3-requests python3-scipy python3-setuptools python3-ruamel.yaml

   sudo apt-get 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 python3-setuptools python3-pygccxml python3-thrift libqwt-qt5-6 libqwt-qt5-dev python3-pyqt5.qwt python3-qwt3d-qt5 libspdlog-dev libspdlog1.12 pybind11-dev python3-cppimport python3-pybind11 python3-pybindgen

Step 5: Create a folder for GIT repositories

Create a folder to hold all the GIT repositories. Run the commands listed below, in a terminal window.

   mkdir $HOME/git

Step 6: Create a work area folder

Create a folder to hold workshop materials and for running exercises. Run the commands listed below, in a terminal window.

   mkdir $HOME/workarea

Step 7: Download the slides and materials

Download the slides and materials for the workshop from the Ettus Knowledge Base (KB). Run the commands listed below, in a terminal window.

   wget -P $HOME/workarea https://kb.ettus.com/images/a/ab/Workshop_GnuRadio_Materials_20171212.tar.gz
   wget -P $HOME/workarea https://kb.ettus.com/images/f/fd/Workshop_GnuRadio_Slides_20250802.pdf

Step 8: Unzip the materials

Unzip the workshop materials file. Run the commands listed below, in a terminal window.

   cd $HOME/workarea
   tar zxvf Workshop_GnuRadio_Materials_20171212.tar.gz

Step 9: Install UHD 4.9

Install UHD version 4.9, and download all the USRP FPGA image files. Run the commands listed below, in a terminal window.

   cd $HOME/git
   git clone http://github.com/EttusResearch/uhd.git
   cd uhd/host
   mkdir build
   cd build
   git checkout v4.9.0.0
   cmake ../
   make -j4
   sudo make install
   sudo ldconfig
   sudo uhd_images_downloader

Step 10: Install VOLK

Install the VOLK library. This used to be bundled with GNU Radio, but now it's broken out as a separate library. Run the commands listed below, in a terminal window.

   git clone --recursive https://github.com/gnuradio/volk.git
   cd volk
   mkdir build
   cd build
   git checkout v3.2.0
   cmake -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/usr/bin/python3 ../
   make -j4
   sudo make install
   sudo ldconfig

Step 11: Install GNU Radio 3.10.12

Install GNU Radio version 3.10.12. Run the commands listed below, in a terminal window.

   cd $HOME/git
   git clone http://github.com/gnuradio/gnuradio.git
   cd gnuradio
   mkdir build
   cd build
   git checkout v3.10.12.0
   cmake ../
   make -j4
   sudo make install
   sudo ldconfig

Step 12: Update the Bash shell file

Add the following lines the end of your $HOME/.bashrc file. You can use a graphical text editor such as Gedit or Mousepad.

First, open the file using either the Gedit or Mousepad text editor.

   mousepad $HOME/.bashrc
   gedit $HOME/.bashrc

Next, add the two lines listed below to the very end of the file, and save it.

   export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
   export PYTHONPATH=/usr/local/lib/python3.12/dist-packages:/usr/local/lib/python3.12/site-packages:$PYTHONPATH

Then, exit and close the text editor, and exit and close the terminal window, and open a brand-new terminal window.

Step 13: Apply the USB udev rules

Apply the USB udev rules for the USRP B200/B210. If you are not using a USRP B200/B210, but some other Ethernet-based radio, then you can skip this step, although it is still good to do. Run the commands listed below, in a terminal window.

   cd /usr/local/lib/uhd/utils
   sudo cp uhd-usrp.rules /etc/udev/rules.d/
   sudo udevadm control --reload-rules
   sudo udevadm trigger

Step 14: Install gr-osmosdr

Install the gr-osmosdr Out-Of-Tree (OOT) module. Run the commands listed below, in a terminal window.

   cd $HOME/git
   git clone https://github.com/osmocom/gr-osmosdr
   cd gr-osmosdr
   mkdir build
   cd build
   cmake ../
   make -j4
   sudo make install
   sudo ldconfig

Step 15: Install gr-rds

Install the gr-rds Out-Of-Tree (OOT) module. Run the commands listed below, in a terminal window.

   cd $HOME/git
   git clone https://github.com/bastibl/gr-rds
   cd gr-rds
   mkdir build
   cd build
   git checkout maint-3.10
   cmake ../
   make -j4
   sudo make install
   sudo ldconfig

Step 16: Install GQRX

Install GQRX. You will also need to install two more package dependencies. Run the commands listed below, in a terminal window.

   sudo apt-get install libqt5svg5 libqt5svg5-dev
   cd $HOME/git
   git clone https://github.com/gqrx-sdr/gqrx
   cd gqrx
   mkdir build
   cd build
   git checkout v2.17.7
   cmake ../
   make -j4
   sudo make install
   sudo ldconfig

Step 17: Install gr-paint

Install gr-paint. Run the commands listed below, in a terminal window.

   cd $HOME/git
   git clone https://github.com/drmpeg/gr-paint
   cd gr-paint
   mkdir build
   cd build
   cmake ../
   make -j4
   sudo make install
   sudo ldconfig

Test the Installation

If you did not see any errors in any of the previous steps, then your installation and configuration should now be complete. You can run a few simple and quick tests to verify that your system is running correctly and is ready for the workshop/tutorial.

First, run the commands below, even if you do not have any USRP radio connected to your computer.

   uhd_find_devices
   uhd_usrp_probe

You should see output similar to what is listed below when there is no USRP device connected.

   ettus@lenovo-t480s:~$ uhd_find_devices 
   [INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
   No UHD Devices Found
   ettus@lenovo-t480s:~$ uhd_usrp_probe 
   [INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
   Error: LookupError: KeyError: No devices found for ----->
   Empty Device Address
   ettus@lenovo-t480s:~$ 

You should see output similar to what is listed below when there is one USRP B200 device connected.

   ettus@lenovo-t480s:~$ uhd_find_devices 
   [INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
   [INFO] [B200] Loading firmware image: /usr/local/share/uhd/images/usrp_b200_fw.hex...
   --------------------------------------------------
   -- UHD Device 0
   --------------------------------------------------
   Device Address:
       serial: 3304B90
       name: 4B200
       product: B200
       type: b200
   
   
   ettus@lenovo-t480s:~$ uhd_usrp_probe 
   [INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
   [INFO] [B200] Detected Device: B200
   [INFO] [B200] Loading FPGA image: /usr/local/share/uhd/images/usrp_b200_fpga.bin...
   [INFO] [B200] Operating over USB 3.
   [INFO] [B200] Detecting internal GPSDO.... 
   [INFO] [GPS] No GPSDO found
   [INFO] [B200] Initialize CODEC control...
   [INFO] [B200] Initialize Radio control...
   [INFO] [B200] Performing register loopback test... 
   [INFO] [B200] Register loopback test passed
   [INFO] [B200] Setting master clock rate selection to 'automatic'.
   [INFO] [B200] Asking for clock rate 16.000000 MHz... 
   [INFO] [B200] Actually got clock rate 16.000000 MHz.
     _____________________________________________________
    /
   |       Device: B-Series Device
   |     _____________________________________________________
   |    /
   |   |       Mboard: B200
   |   |   serial: 3304B90
   |   |   name: 4B200
   |   |   product: 1
   |   |   revision: 5
   |   |   FW Version: 8.0
   |   |   FPGA Version: 16.0
   |   |   
   |   |   Time sources:  none, internal, external, gpsdo
   |   |   Clock sources: internal, external, gpsdo
   |   |   Sensors: ref_locked
   |   |     _____________________________________________________
   |   |    /
   |   |   |       RX DSP: 0
   |   |   |   
   |   |   |   Freq range: -8.000 to 8.000 MHz
   |   |     _____________________________________________________
   |   |    /
   |   |   |       RX Dboard: A
   |   |   |     _____________________________________________________
   |   |   |    /
   |   |   |   |       RX Frontend: A
   |   |   |   |   Name: FE-RX1
   |   |   |   |   Antennas: TX/RX, RX2
   |   |   |   |   Sensors: temp, rssi, lo_locked
   |   |   |   |   Freq range: 50.000 to 6000.000 MHz
   |   |   |   |   Gain range PGA: 0.0 to 76.0 step 1.0 dB
   |   |   |   |   Bandwidth range: 200000.0 to 56000000.0 step 0.0 Hz
   |   |   |   |   Connection Type: IQ
   |   |   |   |   Uses LO offset: No
   |   |   |     _____________________________________________________
   |   |   |    /
   |   |   |   |       RX Codec: A
   |   |   |   |   Name: B200 RX dual ADC
   |   |   |   |   Gain Elements: None
   |   |     _____________________________________________________
   |   |    /
   |   |   |       TX DSP: 0
   |   |   |   
   |   |   |   Freq range: -8.000 to 8.000 MHz
   |   |     _____________________________________________________
   |   |    /
   |   |   |       TX Dboard: A
   |   |   |     _____________________________________________________
   |   |   |    /
   |   |   |   |       TX Frontend: A
   |   |   |   |   Name: FE-TX1
   |   |   |   |   Antennas: TX/RX
   |   |   |   |   Sensors: temp, lo_locked
   |   |   |   |   Freq range: 50.000 to 6000.000 MHz
   |   |   |   |   Gain range PGA: 0.0 to 89.8 step 0.2 dB
   |   |   |   |   Bandwidth range: 200000.0 to 56000000.0 step 0.0 Hz
   |   |   |   |   Connection Type: IQ
   |   |   |   |   Uses LO offset: No
   |   |   |     _____________________________________________________
   |   |   |    /
   |   |   |   |       TX Codec: A
   |   |   |   |   Name: B200 TX dual DAC
   |   |   |   |   Gain Elements: None
   
   ettus@lenovo-t480s:~$

Second, you can run the GNU Radio Companion (GRC) tool. Run the commands below, and verify that the GRC window appears.

   gnuradio-companion

Third, you can connect the USRP B200/B210 to the computer, and then run the command listed below.

   lsusb

You should see the USRP listed in the output, as shown below.

   ettus@lenovo-t480s:~$ lsusb
   Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
   Bus 001 Device 004: ID 03f0:6a41 HP, Inc HP USB Optical Mouse
   Bus 001 Device 005: ID 2500:0020 Ettus Research LLC USRP B210
   Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
   Bus 002 Device 002: ID 0bda:0316 Realtek Semiconductor Corp. Card Reader
   Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
   Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
   ettus@lenovo-t480s:~$ 

Fourth, you can run the command below, to confirm that GNU Radio is configured correctly, and that you are running the correct version.

   ettus@lenovo-t480s:~$ gnuradio-config-info --print-all
   /usr/local/
   /usr/local/etc
   /usr/local/etc/gnuradio/conf.d
   /home/ettus/.config/gnuradio
   /home/ettus/.local/state/gnuradio
   Fri, 09 Jan 2026 14:37:15Z
   testing-support;python-support;post-install;doxygen;man-pages;gnuradio-runtime;common-precompiled-headers;gr-ctrlport;gnuradio-companion;JSON/YAML config blocks;gr-blocks;gr-fec;gr-fft;gr-filter;gr-analog;gr-digital;gr-dtv;gr-audio;* alsa;* oss;gr-channels;gr-pdu;gr-qtgui;gr-trellis;gr-uhd;gr-uhd UHD 4.0 RFNoC;gr-utils;gr_modtool;gr_blocktool;gr-video-sdl;gr-vocoder;* codec2;* freedv;* gsm;gr-wavelet;gr-zeromq;gr-network
   3.10.12.0
   cc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0 
   Copyright (C) 2023 Free Software Foundation, Inc. 
   This is free software see the source for copying conditions.  There is NO 
   warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   c++ (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0 
   Copyright (C) 2023 Free Software Foundation, Inc. 
   This is free software see the source for copying conditions.  There is NO 
   warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   /usr/bin/cc:::-O3 -DNDEBUG  -fvisibility=hidden -Wsign-compare -Wall -Wno-uninitialized -Wignored-qualifiers -Wcast-qual 
   /usr/bin/c++:::-O3 -DNDEBUG  -fvisibility=hidden -Wsign-compare -Wall -Wno-uninitialized -Wignored-qualifiers -Wcast-qual
   2.11.1
   ettus@lenovo-t480s:~$

Conclusion

If the simple tests of the installation listed above worked without any errors, then you are now finished, and you are now ready for the workshop/tutorial.

If you have any questions or problems, you can contact the author via email at [email protected]

We look forward to seeing you in the workshop/tutorial.