Software Setup

In most instances, there are two pieces of software that you will be needing: UHD and GNU Radio. Most package managers have a version of libUHD that is compiled by Ettus for their radio products. At Per Vices, we maintain our own fork of libUHD. This allows for easy interfacing with software devices, and provides some compatibility with USRP devices. For more on these differences, check out our application note on use and operations. While you are unlikely to notice these differences when using the software, you will have to take some care to make sure that the correct (Per vices) version of UHD is what gets installed.

Table 1: Supported Operating Systems
Operating System Note on Performance
Arch Linux We use this for internal development and recommend it for high performance (high sample rates, etc.)
Ubuntu 20.04LTS Packages are provided but performance may be negatively affected at higher sample rates, etc.
Ubuntu 22.04LTS Packages are provided but performance may be negatively affected at higher sample rates, etc.
Centos 8/Redhat 8.5 Packages are provided but performance may be negatively affected at higher sample rates, etc.

Note

All performance measurements listed on our support site are carried out on an Arch Linux system.

Note

While other operating system’s may work (Windows, other Linux distributions), we highly recommend using one in the above table.

In most instances, there are two pieces of software that you will be needing: libUHD and GNU Radio. Most package managers have a version of libUHD that is compiled by Ettus for their radio products. At Per Vices, we maintain our own fork of UHD that looks and operates similarly with one main exception: it supports the Crimson TNG and Cyan radios that we manufacture. While you likely won’t notice the differences when using the software, you will have to take some care to make sure the correct (Per vices) version is what gets installed.

At run-time, GNU Radio compares the version of the UHD library used during compilation with the presently installed version. If there is a difference, it generates an error message. This is most often caused when using a distribution provided version of GNU Radio that has been compiled with the Ettus UHD version. Ensuring that you have correctly installed the Per Vices UHD version, and then recompiling gnuradio ensures consistency in the library versions and fixes any errors.

Figure 8: Overview of libUHD installation process

If you already have GNU Radio installed on your host computer, you need to first uninstall it (also uninstall the Ettus libUHD library, if applicable). Next, ensure the Per Vices libUHD version is correctly installed and reboot the computer. Finally, compile and install GNU Radio from source.

We use archlinux internally for development and testing. Installing uhd and GNU Radio on other distributions may be slightly more challenging.

Note

While the required procedure isn’t complicated, it definitely assumes familiarity with the Linux environment and build flow. If you run into difficulty, please contact us.

1. Installing from Binaries

Note

When installing from source, the packaged binaries for each distribution are created using the dockerfiles specified in the pvpkg repository.

Note

Ensure you do not have any other versions of UHD or GNU Radio installed! Remove all versions of UHD or GNU Radio if you are doing a fresh install.

1.1. Archlinux Binaries

To install Per Vices UHD and GNU Radio on Archlinux, follow these instructions:

  1. Download the pre-compiled binaries for GNU Radio and Per Vices UHD:

    GNU Radio

    UHD

    Note

    If the host is running headless, use these two commands to download the GNU Radio and UHD files.

    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" http://files.pervices.com/latest/sw/archlinux/gnuradio/
    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" https://files.pervices.com/latest/sw/archlinux/uhd/

  2. Use this command to install the tar file first for UHD, and then for GNURadio.

    $ sudo pacman -U --noconfirm <package name>

1.2. Ubuntu 20.04 Binaries

To install Per Vices UHD and GNU Radio on Ubuntu 20.04, follow these instructions:

  1. Ensure the proper packages are installed to allow for building Debian packages on the host system:

    $ sudo apt-get -y install dpkg-dev sudo apt-utils dh-make bzr-builddeb equivs xz-utils iputils-ping net-tools software-properties-common cmake git coreutils build-essential

  2. Add a repo to allow for gcc-11 install:

    $ sudo add-apt-repository ppa:ubuntu-toolchain-r/test

  3. Install gcc-11:

    $ sudo apt update && apt install -y gcc-11 g++-11

  4. After installing gcc, determine the currently running compiler of GNU Radio with the following:

    $ gcc --version

  5. If the currently active gcc in step 5 is anything other than gcc 11, run these commands to ensure gcc-11 is used by default:

    $ sudo update-alternatives --remove-all cpp && \
    sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90 --slave /usr/bin/g++ g++ /usr/bin/g++-9 --slave /usr/bin/gcov gcov /usr/bin/gcov-9 --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-9 --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-9  --slave /usr/bin/cpp cpp /usr/bin/cpp-9 && \
    sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 --slave /usr/bin/g++ g++ /usr/bin/g++-11 --slave /usr/bin/gcov gcov /usr/bin/gcov-11 --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-11 --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-11  --slave /usr/bin/cpp cpp /usr/bin/cpp-11

  6. Install pip to allow installation of necessary python module pygccxml:

    $ sudo apt-get -y install python3-pip

  7. Install the latest version of pygccxml to allow for C++17 Python compatibility (needed for gr-modtool):

    $ sudo pip3 install pygccxml

  8. Download the latest deb files (package) for UHD and GNU Radio here (Download UHD first then GNU Radio):

    UHD

    GNU Radio

    Note

    If the host is running headless, use these two commands to download the GNU Radio and UHD files.

    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" http://files.pervices.com/latest/sw/ubuntu20.04/uhd/
    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" http://files.pervices.com/latest/sw/ubuntu20.04/gnuradio/

  9. Navigate to where you downloaded the UHD deb files above and untar the build files:

    $ sudo tar -xvzf <archive_name_ending_in .tar.gz>

  10. Install UHD in the directory you untared the files using dpkg:

    $ sudo dpkg -i uhd*.deb

  11. The above command will most likely fail with missing dependencies, but the install will work by subsequently running the following command to retrieve these:

    $ sudo apt --fix-broken install

  12. Install volk 2.4.1 (this is the mimimum version required). Note that you will need to run this after installing UHD and before installing the GNU Radio Debian package.

    $ git clone --branch v2.4.1 --recursive https://github.com/gnuradio/volk.git && cd volk && mkdir build && cd build && cmake -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/usr/bin/python3 ../ && make && sudo make install

  13. Untar and install the GNU Radio deb packages as was done for UHD in steps 9 to 11.

    $ sudo dpkg -i libgnuradio*.deb
    $ sudo apt --fix-broken install
    $ sudo dpkg -i gnuradio*.deb
    $ sudo apt --fix-broken install

1.3. Ubuntu 22.04 Binaries

To install Per Vices UHD and GNU Radio on Ubuntu 22.04, follow these instructions:

  1. Ensure the proper packages are installed to allow for building Debian packages on the host system:

    $ sudo apt-get -y install dpkg-dev sudo apt-utils dh-make bzr-builddeb equivs xz-utils iputils-ping net-tools software-properties-common cmake git coreutils build-essential

  2. Install pip to allow installation of necessary python module pygccxml:

    $ sudo apt-get -y install python3-pip

  3. Install the latest version of pygccxml to allow for C++17 Python compatibility (needed for gr-modtool):

    $ sudo pip3 install pygccxml

  4. Download the latest deb files (package) for UHD and GNU Radio here (Download UHD first then GNU Radio):

    UHD

    GNU Radio

    Note

    If the host is running headless, use these two commands to download the GNU Radio and UHD files.

    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" http://files.pervices.com/latest/sw/ubuntu22.04/uhd/
    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" http://files.pervices.com/latest/sw/ubuntu22.04/gnuradio/

  5. Navigate to where you downloaded the UHD deb files above and untar the build files:

    $ sudo tar -xvzf <archive_name_ending_in .tar.gz>

  6. Install UHD in the directory you untared the files using dpkg:

    $ sudo dpkg -i uhd*.deb

  7. The above command will most likely fail with missing dependencies, but the install will work by subsequently running the following command to retrieve these:

    $ sudo apt --fix-broken install

  8. Install volk 2.5.1 (this is the mimimum version required). Note that you will need to run this after installing UHD and before installing the GNU Radio Debian package.

    $ git clone --branch v2.5.1 --recursive https://github.com/gnuradio/volk.git && cd volk && mkdir build && cd build && cmake -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/usr/bin/python3 ../ && make && sudo make install

  9. Untar and install the GNU Radio deb packages as was done for UHD in steps 5 to 7.

    $ sudo dpkg -i libgnuradio*.deb
    $ sudo apt --fix-broken install
    $ sudo dpkg -i gnuradio*.deb
    $ sudo apt --fix-broken install

1.4. Oracle 8/Centos 8/Redhat 8.5 Binaries

To install Per Vices UHD and GNU Radio on Oracle8, follow these instructions:

  1. Ensure that you have packages installed that are required before beginning the UHD/Volk/Gnuradio install:

    $ sudo yum -y install dnf-plugins-core oracle-epel-release-el8 make gcc rpm-build git rpmdevtools wget cmake python3-pip

  2. Add a repository necessary for some of the dependencies

    $ sudo dnf config-manager --set-enabled ol8_codeready_builder

  3. To ensure C++17 Pyton compatibility, you need to move local install from pip to rpm site-packages to use in GNU Radio install or else it will not be located. Run the following to do this:

    $ sudo pip3 install retrying==1.3.3 pygccxml==2.2.1 pyqtgraph==0.11.1 && \
    cd /usr/local/lib/python3.6/site-packages/ && \
    mv pygccxml  pygccxml-2.2.1.dist-info  pyqtgraph  pyqtgraph-0.11.1.dist-info  retrying-1.3.3-py3.6.egg-info  retrying.py /usr/lib/python3.6/site-packages

  4. Get the latest version of Per Vices UHD and GNU Radio build files:

    GNU Radio

    UHD

    Note

    If the host is running headless, use these two commands to download the GNU Radio and UHD files.

    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" https://www.files.pervices.com/latest/sw/oracle8/gnuradio/
    $ wget -r -np -nH --cut-dirs=3 -R "*index.html*" https://www.files.pervices.com/latest/sw/oracle8/uhd/

  5. Untar the the build files:

    $ sudo tar -xvzf <archive_name_ending_in .tar.gz>

  6. From directory where the UHD build files are extracted, run this command to install all the necessary UHD dependencies:

    $ sudo dnf builddep -y uhd.spec

  7. To install UHD, run the following command in the directory with the UHD RPM files (package):

    $ sudo rpm -i uhd*.rpm

  8. Ensure gcc-11 is set as compiler for application runtime (adjust path if gcc-toolset-11 is installed at different location).

    $ sudo source /opt/rh/gcc-toolset-11/enable

  9. Install all dependencies necessary for GNU Radio (these commands are run in the directory that the gnuradio tar file is extracted to):

    $ sudo dnf builddep -y gnuradio.spec

  10. From directory where GNU Radio files are extracted, run the following commands to install:

    $ sudo rpm -i volk*.rpm && rpm -i libgnuradio*.rpm && rpm -i python3*.rpm && rpm -i gnuradio*.rpm

2. Compiling from Source (Using a Package Manager)

We automatically compile the UHD and GNU Radio binaries used with our product using dockerfiles found in the pvpkg repo, for specific distributions, including ArchLinux, Ubuntu, and Centos.

We encourage you to clone this repo, as it includes a number of patches and dependencies required to make the installation easier, and it also allows you to use your package manager for installation. You can clone the repo as follows;

$ git clone https://github.com/pervices/pvpkg
To build the package, we use a Jenkinsfile. Instructions on how to install Jenkins is found in the README.md file within the above repo. You may also create the required binaries yourself, using the dockerfiles associated with each distribution.

2.1. Archlinux

To compile the current UHD binaries from source, you can use the dockerfile to help determine the required dependencies necessary to compile UHD and Gnuradio from your own distribution. This dockerfile assumes a clean installation of archlinux, and presents you with a guide on how to install it.

We suggest cloning the pvpkg repo, and then entering the arch subdirectory. This includes the required dependencies, along with a dockerfile that may be used to help guide installation.

In particular, you’ll first need to install the required dependencies for archlinux. You can find these dependencies in the archlinux dockerfile, which specifies all the steps we use to automatically build the archlinux binaries we post.

To download the latest UHD library from git hub, and install all the required dependencies, here is the command

sudo wget https://raw.githubusercontent.com/pervices/pvpkg/master/Arch/UHD/PKGBUILD && \
yay -Sy --noconfirm  \
    $(pacman --deptest $(source ./PKGBUILD && echo ${depends[@]} ${makedepends[@]})) && \
 makepkg --noconfirm --syncdeps --install --needed

You may also find the above command in the archlinux UHD PKGBUILD script

2.2 Ubuntu

We suggest first cloning the pvpkg repo:

$ git clone https://github.com/pervices/pvpkg
Then, you can use the dockerfile for ubuntu20.04 as a guide, as shown here.

When following the dockerfile, note that we require a libboost dependency of 1.67. If you’ve update your boost library, you will need to uninstall the older versions of boost, and install the 1.67 version. This may be a bit tricky, but running apt-get remove, along with apt-get autoremove, will help.

This is especially true if you’re not able to successfully run the mk-build-deps command. In this case, running the following may help;

$ apt-get install libboost1.67-all-dev

You may need to manually install the unmet dependencies if this is the case. Otherwise, you can follow the dockerfile commands, substituting the notroot directory for your own home directory.

3.1. Compiling from Source Manually

Provided you’re prepared to resolve your own dependencies, you can easily compile UHD and Gnuradio from source. The specific commands and flags used to compile the sources, are most easily found within the Archlinux PKGBUILD associated with each application.

3.2. Manual Compilation Tips

If you are committed to using another operating system, then you will want to build GNU Radio and UHD from source. However, your package manager can be useful for obtaining the necessary dependencies. We suggest installing all GNU Radio and UHD dependencies using your distribution package management system, and then actually installing GNU Radio and UHD from source.

  1. Install all GNU Radio and UHD dependencies, but do NOT actually install GNU Radio or UHD.

    • You need to ensure that you have all the required install dependencies.
    • Though you will try to avoid installing GNU Radio or UHD
  2. After installing the required dependencies, confirm that you do NOT have any of the following installed;

    • gnuradio
    • libgnuradio
    • libvolk
    • libuhd
    • uhd-host
  3. If you have previously attempted to install GNU Radio or UHD from source, confirm that you do not have any residual files.

    • Ideally, if you still have the original source directory, you can run ?make uninstall? as root, to delete all the installed files.
    • The default installation settings see gnuradio installed in /usr/local/{bin,lib…}. Check each of the subdirectories in /usr/src to see whether you have old installation files. The presence of these files WILL cause problems down the road; either move them somewhere else, or delete them.
  4. Download the Per Vices UHD driver sources code, and compile and install it.

    • For compatability, you may want to use the -DCMAKE_INSTALL_PREFIX=/usr cmake flag to install binaries to /usr (this is consistent with most linux distributions).
    • In order to successfully install the remaining components, you will need to have successfully installed the Per Vices UHD driver.
    • We recommend confirming that you have installed the correct uhd version, by typing; uhd_find_devices -v and confirming that the version number matches what you expect.
  5. Download the gnuradio source code, compile and install it.

    • The gnuradio application needs to use the systems python interpreter and some accompanying python libraries to run. To ensure that our system can locate these tools, we will need to ensure that the PYTHONPATH and LD_LIBRARY_PATH are properly set.
    • You can verify that the LD_LIBRARY_PATH is set correctly using sudo ldconfig
echo 'export PYTHONPATH=/usr/local/lib/python3/dist-packages:usr/local/lib/python2.7/site-packages:$PYTHONPATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/user/local/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
echo 'export PYTHONPATH=/usr/local/lib/python3/dist-packages:usr/local/lib/python2.7/site-packages:$PYTHONPATH' >> ~/.profile
echo 'export LD_LIBRARY_PATH=/user/local/lib:$LD_LIBRARY_PATH' >> ~/.profile

4. After installation

Confirm your installation by testing successful set up and operation.

You can also learn more about how to use our software by looking at our tutorials.