Installation

Note: Since most distributions include an out-dated version GNU Radio, we recommend to use any of the following methods to install GNU Radio and our modules.

PyBombs is the official GNU Radio installer. It offers an app store, which supports installation of out of tree modules, like our WiFi and ZigBee transceivers. They are listed as gr-ieee-80211 and gr-ieee-802154.

macOS

If you are a Mac user, you can install our module through MacPorts. You will have to search for gr-ieee802-11 and gr-ieee802-15-4. If you compile the modules manually, you have to be careful to link against the correct Python library. This is most likely the one from MacPorts or Homebrew and not the system library.

From Source

Note: Like GNU Radio, our modules use master and next branches for development, which are supposed to be used with the corresponding GNU Radio branches. We recommend staying up-to-date by using the next branch.

Some non project-specific blocks (like the Wireshark connector) are in separate module (gr-foo). This module has to be installed first.

git clone https://github.com/bastibl/gr-foo.git
cd gr-foo
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig

Then, gr-ieee802-11 or gr-ieee802-15-4 are installed similarly.

git clone git://github.com/bastibl/gr-ieee802-11.git
cd gr-ieee802-11
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig

Adjust Maximum Shared Memory

The transceivers use GNU Radio’s tagged stream blocks, which buffer complete frames in shared memory before processing them. Since maximum-sized frames comprise many samples, the shared memory size might have to be adapted. On Linux this can be done with:

sudo sysctl -w kernel.shmmax=2147483648

Hierarchical Blocks

The physical layers are encapsulated in hierarchical blocks, which allows for a clearer transceiver structure in GNU Radio Companion. Since GNU Radio does not yet support the inclusion of hierarchical blocks in the installation process, you will have to build the blocks manually. This can be done by opening the blocks in GNU Radio Companion and executing the build command. The hierarchical blocks will be installed to ~/.grc_gnuradio/.

Check message port connections

With updates to GNU Radio Companion, the connections between the blocks in the flow graphs might break. If this is the case, just reconnect the blocks in GNU Radio Companion.

Python OpenGL

If the graphical outputs don’t look like on the screenshots (the plot with the subcarrier constellations, for example), please assert that you have python-opengl installed.

Run volk_profile

To support real-timer operation on a normal PC, the blocks make heavy use of SIMD instruction through the VOLK library. To assert that you use the best implementation for your architecture, please run volk_profile, which comes as part of GNU Radio.

Calibrate your daughterboard

If you have a WBX, SBX, or CBX daughterboard you should calibrate it to minimize IQ imbalance and TX DC offsets. See the application notes for more details.

Adapt Environment Variables

If you installed the GNU Radio modules to an uncommon location, you might have to adapt your environment variables accordingly. Assuming that you installed the module to ~/usr/, this can be done with:

export PATH=~/usr/bin:${PATH}
export LD_LIBRARY_PATH=~/usr/lib:${LD_LIBRARY_PATH}
export PYTHONPATH=~/usr/lib/python2.7/site-packages:${PYTHONPATH}

If GNU Radio Companion doesn’t find the blocks it will output error messages like:

>>> Error: Block key "ieee802_11_ofdm_mac" not found in Platform - grc(GNU Radio Companion)
>>> Error: Block key "foo_packet_pad" not found in Platform - grc(GNU Radio Companion)

In that case you have to adapt your ~/.gnuradio/config.conf to include something like:

[grc]
global_blocks_path = /opt/local/share/gnuradio/grc/blocks
local_blocks_path = ~/usr/share/gnuradio/grc/blocks

Overruns and Underruns

If you have problems with overruns or underruns, try connecting the SDR directly to your PC (without using a switch, for example). Furthermore, do not run it in a VM, but use a native installation.

Testing your Installation

To test the installation, please run the loopback flow graphs in the example directory. This flow graph does not need any hardware and allows you to ensure that the software part is installed correctly. If everything works as intended you should see decoded frames in the console.

Troubleshooting

  • Check compile and installation logs for warnings or errors.
  • Run the transceiver on a native installation (no VM).
  • Connect directly to the SDR (no switch, for example).
  • If you use an SDR from Ettus, apply the recommended sysconfig changes.
  • If you use an WBX, SBX, or CBX daugtherbord, try calibrating it.
  • Run volk_profile.
  • Try different gain settings on sender and receiver.
  • Close the cases of the devices and don’t place them directly beside each other.
  • Run the flow graph with real-time priority.
  • Compile GNU Radio and our modules in release mode.
  • If you use an SDR from Ettus, try different LO offsets.

Asking for help

If you went through this tutorial and still face problems that you cannot solve on your own, please post your questions to the GNU Radio mailing list. In order to help you, we need as much information as possible. Please be very verbose about what’s going wrong and what you are actually trying to do. You should include at least the following information:

  • OS (Ubuntu, macOS…)
  • Version of GNU Radio and the modules you are using
  • Hardware (SDR and daughterboard)
  • Used bandwidth and frequency
  • What are you trying to do
  • What you already did to debug the problem
  • Where exactly your experiment breaks