Skip to content

Getting Started: Linux

Jump to bottom Edit New page
frank8371 edited this page Feb 21, 2014 · 58 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.

Ubuntu users: 13.04 or later is recommended (due to its 3.8 kernel and a more recent libusb version). Note that 12.04 contains libusb-1.0.9. However, libusb-1.0.10 or higher is required to build and use libbladeRF.

Table of Contents

Easy installation for Ubuntu 13.04 and later

If you're running Ubuntu 13.04 (Raring Ringtail) or later, a PPA is available at ppa:bladerf/bladerf-snapshots. New builds will appear occasionally, built from the master.

To activate this PPA, 

$ sudo apt-add-repository ppa:bladerf/bladerf-snapshots
$ 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

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

Note: This PPA replaces ppa:rtucker/bladerf-daily, which is now deprecated.

Installing dependencies

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.

While it is possible to use >= libusb-1.0.12, the bladeRF-flash utility will not be available due to hotplug support not being added until libusb-1.0.16. Versions earlier than libusb-1.0.12 are not supported.

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

(Optional) For Ubuntu users, the libusb-1.0.16 can be fetched from the upstream sources at http://packages.ubuntu.com/saucy/libusb-1.0-0 and http://packages.ubuntu.com/saucy/libusb-1.0-0-dev via: 

$ wget http://de.archive.ubuntu.com/ubuntu/pool/main/libu/libusbx/libusb-1.0-0_1.0.16-3_amd64.deb && sudo dpkg -i libusb-1.0-0_1.0.16-3_amd64.deb
$ wget http://de.archive.ubuntu.com/ubuntu/pool/main/libu/libusbx/libusb-1.0-0-dev_1.0.16-3_amd64.deb && sudo dpkg -i libusb-1.0-0-dev_1.0.16-3_amd64.deb

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

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: 

CMakeLists.txt  COPYING          fx3_firmware  host
CONTRIBUTORS    firmware_common  hdl           README.md

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 grant members of the plugdev group read-write access to bladeRF devices. This group can can be changed via -DBLADERF_GROUP. The remainder of this guide assumes the default.
  • 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 (plugdev, by default). Check the output of the groups command: 

$ groups                                                       ~
jon adm cdrom sudo dip plugdev lpadmin sambashare

In the above case (an Ubuntu 13.10 system), the user is already in the plugdev group, so we can skip ahead to the next subsection.

However, on a Fedora 19 system, the user will not be in many groups. Furthermore, this distro doesn't have normally create and use a plugdev group. We can create one as follows: 

$ groups                                                       ~
jon wheel
$ sudo groupadd plugdev
$ sudo usermod -a -G plugdev jon

# Now log out and log back in...

$ groups
jon wheel plugdev

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

Detecting the bladeRF

With the libraries and tools installed, we can now use the bladeRF-cli (command line interface) to probe for devices attached to the system.

First, take a look at the command-line options: 

$ bladeRF-cli --help
  • If you see the help text, you can skip ahead to the invocation with the -p option.
  • If you receive error about not being able to find libbladeRF.so.0, then we must create an ldconfig entry to ensure that library path in which libbladeRF was installed is searched. Follow the next few steps.
    • As root (i.e., use sudo) create an /etc/ld.so.conf.d/bladeRF.conf and open it with your favorite editor
    • Add a single line containing /usr/local/lib to the file. If you specified something other than /usr/local for CMAKE_INSTALL_PREFIX (the default), adjust this line accordingly.
    • Run sudo ldconfig and then try running bladeRF-cli --help again. The library search issue should now be resolved.
Note that the -p option may be used to probe for device. Plug in your device, and run the following command. You should see similar output. 
$ bladeRF-cli -p
    Backend:        libusb
    Serial:         f12ce1037830a1b27f3ceeba1f521413
    USB Bus:        4
    USB Address:    8

If you do not see any device listed:

  • Verify that your user is in the plugdev group
  • Double check dmesg and lsusb output
    • The bladeRF's VID=1d50 and PID=6066
    • If you see a Cypress device with VID=04b4 PID=00f3, then the bladeRF is running in the bootloader mode. No worries! Follow the instructions at this page to reflash your device.
  • See the Troubleshooting page before continuing.

Viewing additional device information

More information about the attached device can be viewed while running bladeRF-cli in interactive mode. Enter this mode and issue the help command to see a list of available command. Use the info command to print information about the device, and version to view version information, most notably, the firmware: 

$ bladeRF-cli -i

bladeRF> help

... (Help text shown here ) ...

bladeRF> info

  Serial #:                 f12ce1037830a1b27f3ceeba1f521413                          
  VCTCXO DAC calibration:   0x894e
  FPGA size:                40 KLE
  FPGA loaded:              no
  USB bus:                  2
  USB address:              3
  USB speed:                Hi-Speed
  Backend:                  libusb
  Instance:                 0

bladeRF> version
  bladeRF-cli version:        0.6.0-git-f1f1c25
  libbladeRF version:         0.7.0-git-f1f1c25

  Firmware version:           1.0.0
  FPGA version:               Unknown (FPGA not loaded)

Here we see the device's serial number, DAC calibration, FPGA information, and USB connection information. Take note of the FPGA size, as this will help determine which FPGA file to load.

Note: If you see the following message, it is required that you update the firmware before continuing to the next section. See this wiki page for more information on updating your firmware. 

********************************************************************************
* ENTERING LEGACY MODE, PLEASE UPGRADE TO THE LATEST FIRMWARE BY RUNNING:
* wget http://nuand.com/fx3/latest.img ; bladeRF-cli -f latest.img
********************************************************************************

Loading the FPGA

Support for loading the FPGA from flash automatically is currently supported and undergoing further testing. See the bladeRF-cli --help text for information on how to write an FPGA image to flash for autoloading.

For simplicity, this guide shows how to load the FPGA without storing it into flash for autoloading. (As a result, you'll have to load the FPGA each time the device is reset or plugged in.)

FPGA images can be obtained from the Nuand website or from a nightly build of "bleeding edge" images.

To load an image from the command line. 

$ bladeRF-cli -l <path/to/fpga/file>

Or to load an image while in interactive mode: 

bladeRF> load fpga <path/to/fpga/file>

After the FPGA loads, you should see LEDs on the board begin blinking. At this point, you're ready to start using your device!

Building GNU Radio and gr-osmosdr

The following procedure uses gnuradio-build 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 gnuradio-build 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 git-v3.7.1 v3.7.1
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio-3.7.1git  ../
$ 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.1git/bin
# Add GNU Radio python libraries to python search path
if [ $PYTHONPATH ]; then
        export PYTHONPATH=$PYTHONPATH:/opt/gnuradio-3.7.1git/lib/python2.7/dist-packages
else
        export PYTHONPATH=/opt/gnuradio-3.7.1git/lib/python2.7/dist-packages
fi
Note: update the path above if you deviated from gnuradio-3.7.1git

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.1git/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.1git/lib:
        libgnuradio-atsc-3.7.1git.so.0.0.0 -> libgnuradio-atsc.so
        libgnuradio-trellis-3.7.1git.so.0.0.0 -> libgnuradio-trellis.so
        libgnuradio-analog-3.7.1git.so.0.0.0 -> libgnuradio-analog.so
        libgnuradio-pager-3.7.1git.so.0.0.0 -> libgnuradio-pager.so
        libgnuradio-vocoder-3.7.1git.so.0.0.0 -> libgnuradio-vocoder.so
        libgnuradio-video-sdl-3.7.1git.so.0.0.0 -> libgnuradio-video-sdl.so
        libgnuradio-pmt-3.7.1git.so.0.0.0 -> libgnuradio-pmt.so
        libgnuradio-noaa-3.7.1git.so.0.0.0 -> libgnuradio-noaa.so
        libgnuradio-filter-3.7.1git.so.0.0.0 -> libgnuradio-filter.so
        libgnuradio-digital-3.7.1git.so.0.0.0 -> libgnuradio-digital.so
        libgnuradio-channels-3.7.1git.so.0.0.0 -> libgnuradio-channels.so
        libgnuradio-qtgui-3.7.1git.so.0.0.0 -> libgnuradio-qtgui.so
        libgnuradio-wxgui-3.7.1git.so.0.0.0 -> libgnuradio-wxgui.so
        libgnuradio-fec-3.7.1git.so.0.0.0 -> libgnuradio-fec.so
        libgnuradio-wavelet-3.7.1git.so.0.0.0 -> libgnuradio-wavelet.so
        libgnuradio-fcd-3.7.1git.so.0.0.0 -> libgnuradio-fcd.so
        libgnuradio-blocks-3.7.1git.so.0.0.0 -> libgnuradio-blocks.so
        libgnuradio-fft-3.7.1git.so.0.0.0 -> libgnuradio-fft.so
        libgnuradio-runtime-3.7.1git.so.0.0.0 -> libgnuradio-runtime.so
        libgnuradio-audio-3.7.1git.so.0.0.0 -> libgnuradio-audio.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.1git ../
$ 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 8000000 -f 446000000

Test Transmit: (446 MHz + 25 KHz ) 

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

Add a custom footer
Add a custom sidebar
Clone this wiki locally