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.
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.
Before compiling on Ubuntu systems, ensure the following packages are installed.
$ sudo apt-get install python3-six python3-mako python3-lxml python3-lxml python3-numpy python3-numpy python3-pip git python3-pybind11 libsndfile1-dev
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
Install PyBOMBS (using pip, but other methods are listed on the PyBOMBS README.md), apply the default configuration, and add the default recipes:
$ pip3 install --upgrade git+https://github.com/gnuradio/pybombs.git $ pybombs auto-config $ pybombs recipes add-defaults
To use Nuand's experimental gr-osmo, consider running the following:
$ sed -i 's/gitea.osmocom.org.sdr/github.com\/Nuand/g' ~/.pybombs/recipes/gr-recipes/gr-osmosdr.lwr
$ sed -i '/- gr.\{7,\}/d' ~/.pybombs/recipes/gr-recipes/gr-osmosdr.lwr
$ sed -i '/- gr.iqbal/d' ~/.pybombs/recipes/gr-recipes/gr-osmosdr.lwr
Optionally to enable gr-video-sdl, try:
$ sudo apt-get install libsdl1.2-dev $ sed -i 's/-DENABLE_VOLK=ON/-DENABLE_VOLK=ON -DENABLE_GR_VIDEO_SDL=ON/g' ~/.pybombs/recipes/gr-recipes/gnuradio.lwr ~/.pybombs/recipes/gr-recipes/gnuradio38.lwr
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/
Optionally, to set GNURadio to dev branch 3.9 run the following two commands:
$ pybombs config --package gnuradio gitrev maint-3.9 $ pybombs config --package gr-osmosdr gitrev dev-gr-3.9
Then continue compiling GNURadio.
$ 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/setup_env.sh $ bladeRF-cli -i $ gqrx
If any PYTHONPATH warning or errors appear while launching gnuradio-companion, ensure all of the Python package library paths in ~/pybombs/bladeRF/lib/ are present in $PYTHONPATH.
To have setup_env.sh try to fix missing PYTHONPATH paths, first backup the setup_env.sh then try:
$ echo "export PYTHONPATH=$(echo ~/pybombs/bladeRF/lib/*/*-packages | sed 's/ /:/g')":'$PYTHONPATH' >> ~/pybombs/bladeRF/setup_env.sh
If everything went correctly, something similar should appear:
$ tail -n 1 ~/pybombs/bladeRF/setup_env.sh export PYTHONPATH=/home/user/pybombs/bladeRF/lib/python3.8/site-packages:/home/user/pybombs/bladeRF/lib/python3/dist-packages:$PYTHONPATHNote: the paths should be absolute paths, and they should appear on the very last line of the
setup_env.sh file. If things match, try sourcing the file again source ~/pybombs/bladeRF/setup_env.sh
If these outputs do not appear or do not match, it might be good to restore the backup of the setup_env.sh file and manually add the missing Python package paths to the file.
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.
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
If you're running Ubuntu 20.04 (focal) or later, a PPA is available at ppa:nuand/bladerf. New builds will appear occasionally as bladeRF releases (and release candidates) are tagged.
To activate the PPA, simply:
$ sudo add-apt-repository ppa:nuandllc/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.
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.
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
$ 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
If you already installed the bladeRF software using apt-get above, you can skip this section.
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
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
Debugfor a debug build, orRelWithDebInfofor a release build with debug symbols
- Change to
- 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.
- By default, this grants members of the plugdev group read-write access to bladeRF devices. This group can can be changed via
- Specify that files should be installed into /usr/local
- You can install into a different location via the
-DCMAKE_INSTALL_PREFIX=/some/desired/pathoption. 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.
- You can install into a different location via the
$ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -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
The following commands:
- Perform the build
- Install files to /usr/local or the location specified by
CMAKE_INSTALL_PREFIX - Updated share library paths, so that libbladeRF can be found
$ make && sudo make install && sudo ldconfig
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.
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.
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.
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.
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.
$ mkdir -p ~/software/gnuradio-build $ cd ~/software/gnuradio-build $ wget http://www.sbrac.org/files/build-gnuradio $ chmod +x ./build-gnuradio $ ./build-gnuradio -m prereqs gitfetchThe
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.
$ 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-3.7.13.4 ../ $ make -j8 && sudo make install
If you would like GNU Radio to be available in PATH for all uses, create a new file called /etc/profile.d/gnuradio.sh:
sudo vi /etc/profile.d/gnuradio.sh
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:
#!/bin/bash
# Add GNU Radio binaries to the search path
GNURADIO_PATH=/opt/gnuradio-3.7.13.4
export PATH=$PATH:$GNURADIO_PATH/bin
# Add GNU Radio python libraries to python search path
if [ $PYTHONPATH ]; then
export PYTHONPATH=$PYTHONPATH:$GNURADIO_PATH/lib/python2.7/dist-packages
else
export PYTHONPATH=$GNURADIO_PATH/lib/python2.7/dist-packages
fi
Note: Be sure to update GNURADIO_PATH if you deviated from gnuradio-3.7.13.4
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/ld.so.conf.d/gnuradio.conf`:
sudo vi /etc/ld.so.conf.d/gnuradio.conf
Put this in the new file:
/opt/gnuradio-3.7.13.4/libNote: 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.13.4/lib:
libgnuradio-analog-3.7.13.4.so.0.0.0 -> libgnuradio-analog.so
libgnuradio-trellis-3.7.13.4.so.0.0.0 -> libgnuradio-trellis.so
libgnuradio-fft-3.7.13.4.so.0.0.0 -> libgnuradio-fft.so
libgnuradio-fec-3.7.13.4.so.0.0.0 -> libgnuradio-fec.so
libgnuradio-qtgui-3.7.13.4.so.0.0.0 -> libgnuradio-qtgui.so
libgnuradio-channels-3.7.13.4.so.0.0.0 -> libgnuradio-channels.so
libgnuradio-wavelet-3.7.13.4.so.0.0.0 -> libgnuradio-wavelet.so
libgnuradio-pmt-3.7.13.4.so.0.0.0 -> libgnuradio-pmt.so
libgnuradio-atsc-3.7.13.4.so.0.0.0 -> libgnuradio-atsc.so
libgnuradio-video-sdl-3.7.13.4.so.0.0.0 -> libgnuradio-video-sdl.so
libgnuradio-vocoder-3.7.13.4.so.0.0.0 -> libgnuradio-vocoder.so
libgnuradio-fcd-3.7.13.4.so.0.0.0 -> libgnuradio-fcd.so
libgnuradio-zeromq-3.7.13.4.so.0.0.0 -> libgnuradio-zeromq.so
libgnuradio-blocks-3.7.13.4.so.0.0.0 -> libgnuradio-blocks.so
libgnuradio-audio-3.7.13.4.so.0.0.0 -> libgnuradio-audio.so
libgnuradio-dtv-3.7.13.4.so.0.0.0 -> libgnuradio-dtv.so
libgnuradio-pager-3.7.13.4.so.0.0.0 -> libgnuradio-pager.so
libgnuradio-noaa-3.7.13.4.so.0.0.0 -> libgnuradio-noaa.so
libgnuradio-filter-3.7.13.4.so.0.0.0 -> libgnuradio-filter.so
libgnuradio-digital-3.7.13.4.so.0.0.0 -> libgnuradio-digital.so
libgnuradio-runtime-3.7.13.4.so.0.0.0 -> libgnuradio-runtime.so
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/gnuradio.shorsource ~/.bashrc, depending which file you added the PATH definition to, in order to update the environment in your current terminal
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.
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-3.7.13.4 ../ $ make -j8 && sudo make install && sudo ldconfig
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-3.7.13.4 ../ $ make -j8 && sudo make install && sudo ldconfig
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.
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 https://github.com/csete/gqrx.git $ cd gqrx $ mkdir build $ cd build $ cmake -DCMAKE_INSTALL_PREFIX=/opt/gnuradio-3.7.13.4 ../ $ 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.