Skip to content

Getting Started: Linux

Robert Ghilduta edited this page Aug 21, 2019 · 132 revisions

This guide describes the process of building and installing the bladeRF host libraries and tool for a Linux system, and quickly getting a device up and running using pre-built firmware and FPGA images.

Table of Contents

Easy installation: PyBOMBS

PyBOMBS is essentially a package manager and build system for GNU Radio. It handles the fetching, building, and installation of GNU Radio and dependencies, and is largely system independent. The installation steps are listed on the PyBOMBS GitHub page, but the following is a list of steps and basic packages needed to get up and running with the bladeRF.

Install PyBOMBS (using pip, but other methods are listed on the PyBOMBS, apply the default configuration, and add the default recipes:

$ pip3 install --upgrade git+
$ pybombs auto-config
$ pybombs recipes add-defaults

NB: If the pybombs command is not found after pip install ensure that ~/.local/bin is part of your path. If it is not, run (and also add the following command to your .bashrc):

export PATH=$PATH:$HOME/.local/bin

To use Nuand's experimental gr-osmo, consider running the following:

$ sed -i 's/\/Nuand/g' ~/.pybombs/recipes/gr-recipes/gr-osmosdr.lwr

Before compiling on Ubuntu systems, ensure the following packages are installed.

$ sudo apt-get install python3-six python-six python-mako python3-lxml python-lxml python-numpy python3-numpy

Now, let's create a prefix, or a directory in which to install all the GNU Radio components. In this case, we set the prefix directory to ~/pybombs/bladeRF. We also specify the alias, bladeRF, for easy reference later, and install the default GNU Radio setup.

$ mkdir ~/pybombs/
$ pybombs prefix init ~/pybombs/bladeRF -a bladeRF -R gnuradio-default

At this point, GNU Radio has been installed into ~/pybombs/bladeRF. Now, install useful applications such as bladeRF and gqrx:

$ pybombs -p bladeRF install bladeRF gr-iqbal gr-osmosdr gqrx

Once each component has been successfully built, they may be run using pybombs -p bladeRF run <command>, some examples follow:

$ pybombs -p bladeRF run bladeRF-cli -- -i
$ pybombs -p bladeRF run gqrx

Alternatively, the GNU Radio environment may be "sourced" into the active console, allowing applications to be run directly.

$ source ~/pybombs/bladeRF/
$ bladeRF-cli -i
$ gqrx

PyBOMBS udev rules

You may get a permissions error when trying to access the bladeRF. This is typically from lack of, or incorrect, udev rule(s) and may be remedied by following the udev installation instructions.

PyBOMBS and gr-fosphor

On recent Ubuntu systems, try the following steps to install gr-fosphor. This assumes the appropriate GPU drivers are already installed.

$ sudo apt install ocl-icd-opencl-dev
$ sudo apt-get install libfreetype6 libfreetype6-dev
$ pybombs -p bladeRF install bladeRF gr-fosphor

Easy installation for Ubuntu: The bladeRF PPA

If you're running Ubuntu 14.04 (trusty) or later, a release PPA is available at ppa:bladerf/bladerf. New builds will appear occasionally as bladeRF releases (and release candidates) are tagged. (Package signing key is 1024R/2FB21B35.)

Want something fresher? There is also a ppa:bladerf/bladerf-snapshots PPA for more frequent, bleeding-edge builds from the master branch. Same process, just change the ppa: target below.

To activate the release PPA, simply:

$ sudo add-apt-repository ppa:bladerf/bladerf
$ sudo apt-get update
$ sudo apt-get install bladerf

If you plan to build gnuradio, gr-osmosdr, etc, you will also need the header files:

$ sudo apt-get install libbladerf-dev

Firmware and FPGA images can be installed from this PPA as well. Firmware should be manually updated using bladeRF-cli --flash-firmware /usr/share/Nuand/bladeRF/bladeRF_fw.img, but the FPGA image will be automatically loaded by libbladeRF when you open your device.

$ sudo apt-get install bladerf-firmware-fx3     # firmware for all models of bladeRF
$ sudo apt-get install bladerf-fpga-hostedx40   # for bladeRF x40
$ sudo apt-get install bladerf-fpga-hostedx115  # for bladeRF x115
$ sudo apt-get install bladerf-fpga-hostedxa4   # for bladeRF 2.0 Micro A4
$ sudo apt-get install bladerf-fpga-hostedxa9   # for bladeRF 2.0 Micro A9

Note: All of the FPGA images can be installed simultaneously without issue.

Then, skip down to the Checking basic device operation section, bypassing the compilation steps.

Note: Ubuntu's repositories have an older version of the bladeRF libraries and tools, with the bladeRF-cli tool provided by a package named bladerf-host, instead of bladerf. If you've previously installed the Ubuntu repository version, the apt-get install bladerf step will remove/upgrade the older packages as appropriate.

Skip down to "Checking Basic Device Operation" after performing these steps.

Installing dependencies

If you already installed the bladeRF software using apt-get above, you can skip this section.

NOTE: If your distribution provides libusb-1.0 packages earlier than 1.0.16, you may want to consider to manually installing libusb >= 1.0.16, either from source or from upstream packages. Issues have been reported with earlier versions.

Debian-based distros (e.g., Ubuntu)

Install dependent packages for the build:

$ sudo apt-get install libusb-1.0-0-dev libusb-1.0-0 build-essential cmake libncurses5-dev libtecla1 libtecla-dev pkg-config git wget

You can check the libusb and libusb-dev versions installed on your system via:

$ dpkg -s libusb-1.0-0 libusb-1.0-0-dev 

Optional: If you wish to build libbladeRF documentation and the bladeRF-cli man page, you'll need the following:

$ sudo apt-get install doxygen help2man pandoc

Redhat-based distros (e.g., Fedora, CentOS)

$ sudo yum groupinstall "Development Tools" "Development Libraries"
$ sudo yum install libusbx libusbx-devel cmake wget gcc-c++ libedit libedit-devel

Optional: If you wish to build libbladeRF documentation and the bladeRF-cli man page, you'll need the following:

$ sudo yum install doxygen help2man pandoc

Building bladeRF libraries and tools from source

If you already installed the bladeRF software using apt-get above, you can skip this section.

Clone the bladeRF git repository

To obtain the latest source code for the first time, clone the Nuand git repository via:

$ git clone ./bladeRF
$ cd ./bladeRF
$ ls  

The directory contents will look something like this:

CHANGELOG       CONTRIBUTORS  debian           fx3_firmware  host
CMakeLists.txt  COPYING       firmware_common  hdl           legal

In the future, you can update the repository via:

$ git pull

Configure the build

First enter the directory containing the host source. Then create and enter a directory to perform the build in. By working out of the a 'build' directory, it's easy to later clean up, by simply removing 'build/'.

$ cd host/
$ mkdir build
$ cd build

Next, configure the build. In the below example, we:

  • Set up a Release build
    • Change to Debug for a debug build, or RelWithDebInfo for a release build with debug symbols
  • Enable the installation of udev rules.
    • By default, this grants members of the plugdev group read-write access to bladeRF devices. This group can can be changed via -DBLADERF_GROUP=desired_group.
  • Specify that files should be installed into /usr/local
    • You can install into a different location via the -DCMAKE_INSTALL_PREFIX=/some/desired/path option. Note that you'll need to need to configure binary and library search paths if you install elsewhere. If you're unsure how to do this, simply follow the steps below to use the default install location.

Ensure that your user is in the group specified by BLADERF_GROUP. Check the output of the groups command:

$ groups
jon adm cdrom sudo dip plugdev lpadmin sambashare

In the above case, the user is already in the plugdev group, so we can skip ahead to the next subsection.

However, on other systems, the user may not already be in the required group. Furthermore, some distributions may not use the plugdev group. In these cases, you can either add a user to a more appropriate group or create a new group (and configure the build with -DBLADERF_GROUP=desired_group. For example, to create a bladerf group and add the user jon to it:

$ groups
jon wheel
$ sudo groupadd bladerf
$ sudo usermod -a -G bladerf jon

# Now log out and log back in...

$ groups
jon wheel bladerf

Perform the build and installation

The following commands:

  1. Perform the build
  2. Install files to /usr/local or the location specified by CMAKE_INSTALL_PREFIX
  3. Updated share library paths, so that libbladeRF can be found
$ make && sudo make install && sudo ldconfig

Uninstalling later

Note that from this same directory, you can run the following to uninstall the files place on your system in the previous step.

sudo make uninstall

The install_manifest.txt file, created after running the install step successfully, lists all the files installed. It is a good idea to back up this file if you plan on removing this build directory later.

Checking basic device operation

Before continuing, see the Getting Started: Verifying Basic Device Operation guide to test basic functionality.

If you encounter any issues or warnings, be sure to check the Troubleshooting guide before continuing on with this article.

Building GNU Radio, gr-iqbal, and gr-osmosdr

The following procedure uses build-gnuradio to fetch dependencies and checkout some useful tools. However, it only covers installing GNU Radio and gr-osmosdr. A similar procedure maybe used to install the other tools.

See the GNU-Radio wiki for more information, including the use of PyBOMBS, which is now the installation method preferred by many users.

If you're not comfortable with the instructions presented below, please consider following the PyBOMBS instructions on the GNU Radio wiki instead.

GNU Radio >= 3.7.7 and VOLK

As of GNU Radio v3.7.7, VOLK is now a separate project pulled in via a git submodule. This implies that one must use the --recursive flag when cloning the repository. (build-gnuradio and PyBOMBS do this for you.) If you are manually cloning the GNU Radio and forget to use the --recursive flag, you'll need to run git submodule init volk followed by git submodule update to initialize the VOLK subrepo.

Multiple GNU Radio Installations

Having multiple GNU Radio installations on your system is highly discouraged, unless you're aware of how to avoid mixups between library search paths and binary paths between the different installations.

If you are building GNU Radio from source, as shown below, ensure you do not have GNU Radio installed from your distribution's package manager or from a previous build. If you do, remove it before continuing.

Using build-gnuradio to fetch dependencies and checkout source via Git

$ mkdir -p ~/software/gnuradio-build
$ cd ~/software/gnuradio-build
$ wget
$ chmod +x ./build-gnuradio
$ ./build-gnuradio -m prereqs gitfetch
The build-gnuradio script will prompt you a few times before proceeding; type 'y' and press enter to continue. Note that this script takes a bit of time, depending on how many dependencies you need to have installed. Run top periodically to see what's currently going on.

Compile GNU Radio

$ cd ~/software/gnuradio-build/gnuradio/
$ git checkout -b gnuradio-v3.7.13.4 v3.7.13.4
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio- ../
$ make -j8 && sudo make install

Add GNU Radio to linker path and executable path

If you would like GNU Radio to be available in PATH for all uses, create a new file called /etc/profile.d/

sudo vi /etc/profile.d/

Otherwise, if you would like GNU Radio executables to only be in your path, update your shell's runtime-config file, such as ~/.bashrc.

Put the following into it:


# Add GNU Radio binaries to the search path

# Add GNU Radio python libraries to python search path
if [ $PYTHONPATH ]; then
        export PYTHONPATH=$PYTHONPATH:$GNURADIO_PATH/lib/python2.7/dist-packages
        export PYTHONPATH=$GNURADIO_PATH/lib/python2.7/dist-packages

Note: Be sure to update GNURADIO_PATH if you deviated from gnuradio-

Note: If you're on a non-Debian based distro, you might need to replace "dist-packages" with "site-packages".

Again, with your favorite text editor, create a new file called `/etc/`:

sudo vi /etc/

Put this in the new file:

Note: on some 64 bit systems, you might need a lib64 directory in this file as well.
  • Update your library cache again
$ sudo ldconfig -v | grep gnuradio

You should see something akin to the following:

/opt/gnuradio- -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> ->

If so, you're all set!

For the changes to your PATH take effect, either:

  • Log out and log back in
  • Run $ source /etc/profile.d/ or source ~/.bashrc, depending which file you added the PATH definition to, in order to update the environment in your current terminal
Once you have logged back in to your desktop, you should be able to run gnuradio-companion.

If you get a pop-up with errors about PYTHONPATH or LD_LIBRARY_PATH, check the output of the env command to see how these environment variables are currently set.

Build and install gr-iqbal

This step is optional, but will make additional IQ balance functionality available for gr-osmosdr.

$ cd ~/software/gnuradio-build/gr-iqbal
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio- ../
$ make -j8 && sudo make install && sudo ldconfig

Build and install gr-osmosdr

gr-osmosdr was checked out during the build-gnuradio execution. This provides GNU Radio support for a number of devices, including the bladeRF.

$ cd ~/software/gnuradio-build/gr-osmosdr
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio- ../
$ make -j8 && sudo make install && sudo ldconfig

Simple test applications to verify device operation

The osmocom programs may be used to quickly view an FFT and generate a tone.

Test Receive: (446 MHz)

osmocom_fft -a bladerf=0 -s 2500000 -f 446000000

Test Transmit: (446 MHz + 25 KHz )

osmocom_siggen -a bladerf=0 -s 2500000 -f 446000000 -g 4 --sine -x 25000

Note that only one program can have the bladeRF opened at a time.

If you'd like to run a quick test in a full-duplex configuration, consider creating a GRC flowgraph.

Do not connect the bladeRF TX output to the RX input without an attenuator. If you do not have an attenuator, consider using the bladeRF's (technically, the LMS6002D's) internal baseband and RF loopback modes, via the loopback= argument to the osmocom sink/source block.

Build and install GQRX

GQRX is a software defined radio receiver powered by GNU Radio and Qt. The bladeRF is supported via gr-osmosdr. The latest and greatest of GQRX can be built from source as follows, assuming you have Qt5 libraries (and development headers) already installed: (Note: On Debian-based distros, you will need to sudo apt-get install libqt5svg5-dev if you don't already have it. On Ubuntu you may need to sudo apt-get install qt5-default for QT5 libraries, if you don't already have them. Ensure that you have qt5-qmake installed.)

$ cd ~/software/gnuradio-build/
$ git clone
$ cd gqrx
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio- ../ 
$ make -j8 && sudo make install && sudo ldconfig

When first running gqrx (or after running gqrx -e), you will be presented with a dialog to configure a device. Below are some suggested settings to start:

Device String: bladerf=0,buffers=128,buflen=8192,transfers=32

This selects the first available bladeRF, and adds some additional buffering.

Sample rate: 5000000

5Msps is a good starting point, as this should work on both USB 2.0 and USB 3.0 connections.

Bandwidth: 3.84 MHz

The bandwidth should always be set less than the sample rate to minimize aliases and prevent noise from folding in. See Figure 6 in LMS6002D datasheet to determine how low to set the bandwidth to ensure you get maximal rejection at the bandwidth limits governed by your sample rate. (Note that the plots' X axes are from 0 to Fs/2, not -Fs/2 to Fs/2).


  • Note that the Receive Options tab allows you to enable various demodulators
  • Use the Squelch under Receiver Options to mute auto below a certain threshold
  • The FFT settings tab allows you to increase the FFT size and speed up the FFT and waterfall
  • If audio is choppy, try reducing your sample rate and bandwidth, the FFT size or rate, or all of these.
You can’t perform that action at this time.