Getting Started: Linux

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.

Ubuntu users: 14.04 LTS (Trusty) is highly recommended. Use the bladeRF PPA (instructions below) for maximum freshness.

Table of Contents Easy installation for Ubuntu: The bladeRF PPA Installing dependencies Debian-based distros (e.g., Ubuntu) Redhat-based distros (e.g., Fedora, CentOS) Building bladeRF libraries and tools from source Clone the bladeRF git repository Configure the build Perform the build and installation Uninstalling later Checking basic device operation Building GNU Radio and gr-osmosdr Using build-gnuradio to fetch dependencies and checkout source via Git Compile GNU Radio Add GNU Radio to linker path and executable path Build and install gr-osmosdr Simple test applications to verify device operation

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

Compatible firmware and FPGA images can be installed as well. You'll need to manually update the firmware using bladeRF-cli --flash-firmware /usr/share/Nuand/bladeRF/bladeRF_fw.img, but the FPGA image should be automatically loaded each time your bladeRF is plugged in.

$ sudo apt-get install bladerf-firmware-fx3
$ sudo apt-get install bladerf-fpga-hostedx40   # for the 40 kLE hardware
$ sudo apt-get install bladerf-fpga-hostedx115  # for the 115 kLE hardware

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.

If your distribution does not provide a libtecla package (e.g., Fedora), it's recommended that you build it from source, as it makes the bladeRF-cli interactive mode much nicer to use!

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 libtecla1-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 

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

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

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 https://github.com/Nuand/bladeRF.git ./bladeRF
$ cd ./bladeRF
$ ls  

The directory contents will look something like this:

CHANGELOG       CONTRIBUTORS  debian           fx3_firmware  host   README.md
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 Debug build
• 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.

$ cmake -DCMAKE_BUILD_TYPE=Debug -DINSTALL_UDEV_RULES=ON ../

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 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 (such as gr-iqbal).

A "sandbox" directory will be used to do the build. Change this to whatever your preferred build directory is in the relevant commands.

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

$ mkdir -p ~/sandbox/gnuradio-builds
$ cd ~/sandbox/gnuradio-builds
$ wget http://www.sbrac.org/files/build-gnuradio
$ chmod +x ./build-gnuradio
$ ./build-gnuradio -m prereqs gitfetch

Note that this takes quite 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 ~/sandbox/gnuradio-builds/gnuradio/
$ git checkout -b gnuradio-v3.7.5.1 v3.7.5.1
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio-3.7.5.1  ../
$ make && sudo make install

Add GNU Radio to linker path and executable path

Create a new file called /etc/profile.d/gnuradio.sh

sudo vi /etc/profile.d/gnuradio.sh

Put the following into it:

#!/bin/bash
# Add GNU Radio binaries to the search path
export PATH=$PATH:/opt/gnuradio-3.7.5.1/bin
# Add GNU Radio python libraries to python search path
if [ $PYTHONPATH ]; then
        export PYTHONPATH=$PYTHONPATH:/opt/gnuradio-3.7.5.1/lib/python2.7/dist-packages
else
        export PYTHONPATH=/opt/gnuradio-3.7.5.1/lib/python2.7/dist-packages
fi

Note: update the path above if you deviated from gnuradio-3.7.5.1

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 call /etc/ld.so.conf.d/gnuradio.conf you will need sudo for this again.. (one line file)

sudo vi /etc/ld.so.conf.d/gnuradio.conf

Put this in the new file:

/opt/gnuradio-3.7.5.1/lib

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-3.7.5.1/lib:
	libgnuradio-iqbalance.so -> libgnuradio-iqbalance.so
	libgnuradio-qtgui-3.7.5.1.so.0.0.0 -> libgnuradio-qtgui.so
	libgnuradio-zeromq-3.7.5.1.so.0.0.0 -> libgnuradio-zeromq.so
	libgnuradio-dtv-3.7.5.1.so.0.0.0 -> libgnuradio-dtv.so
	libgnuradio-audio-3.7.5.1.so.0.0.0 -> libgnuradio-audio.so
	libgnuradio-wxgui-3.7.5.1.so.0.0.0 -> libgnuradio-wxgui.so
	libgnuradio-fcd-3.7.5.1.so.0.0.0 -> libgnuradio-fcd.so
	libgnuradio-trellis-3.7.5.1.so.0.0.0 -> libgnuradio-trellis.so
	libgnuradio-fosphor-3.7.0git.so.0.0.0 -> libgnuradio-fosphor.so
	libgnuradio-noaa-3.7.5.1.so.0.0.0 -> libgnuradio-noaa.so
	libgnuradio-channels-3.7.5.1.so.0.0.0 -> libgnuradio-channels.so
	libgnuradio-osmosdr-0.1.5git.so.0.0.0 -> libgnuradio-osmosdr.so
	libgnuradio-pmt-3.7.5.1.so.0.0.0 -> libgnuradio-pmt.so
	libgnuradio-wavelet-3.7.5.1.so.0.0.0 -> libgnuradio-wavelet.so
	libgnuradio-digital-3.7.5.1.so.0.0.0 -> libgnuradio-digital.so
	libgnuradio-analog-3.7.5.1.so.0.0.0 -> libgnuradio-analog.so
	libgnuradio-video-sdl-3.7.5.1.so.0.0.0 -> libgnuradio-video-sdl.so
	libgnuradio-fec-3.7.5.1.so.0.0.0 -> libgnuradio-fec.so
	libgnuradio-pager-3.7.5.1.so.0.0.0 -> libgnuradio-pager.so
	libgnuradio-runtime-3.7.5.1.so.0.0.0 -> libgnuradio-runtime.so
	libgnuradio-blocks-3.7.5.1.so.0.0.0 -> libgnuradio-blocks.so
	libgnuradio-filter-3.7.5.1.so.0.0.0 -> libgnuradio-filter.so
	libgnuradio-atsc-3.7.5.1.so.0.0.0 -> libgnuradio-atsc.so
	libgnuradio-fft-3.7.5.1.so.0.0.0 -> libgnuradio-fft.so
	libgnuradio-vocoder-3.7.5.1.so.0.0.0 -> libgnuradio-vocoder.so

If so, you're all set!

For the profile.d changes to take effect, either:

• Log out and log back in
• Run $ source /etc/profile.d/gnuradio.sh to update the environment in your current termunal

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-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 ~/sandbox/gnuradio-builds/gr-osmosdr
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio-3.7.5.1 ../
$ make && 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,fpga=<your FPGA image> -s 2000000 -f 446000000

Test Transmit: (446 MHz + 25 KHz )

osmocom_siggen -a bladerf=0,fpga=<your FPGA image> -s 2000000 -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.