Frequently Asked Questions

A series of questions commonly asked (and answered). Gathered from the mailing list archives and various experts. Please, please consult this file before asking on the mailing list. Also, if you feel a relevant question is missing, consider writing a Q&A here.


General

Who/what/when/where/why/how (not necessarily in that order)?

What is GNU Radio?

GNU Radio is a collection of software that when combined with minimal hardware, allows the construction of radios where the actual waveforms transmitted and received are defined by software. What this means is that the digital modulation schemes used in today's high performance wireless devices are now software problems.

To be more precise, GNU Radio is a software library. This means you can use GNU Radio to develop complete applications for radio engineering and signal processing.

Where can I download GNU Radio?

Check the download page on the wiki then go over to the build guide for instructions on how to build and what dependencies GNU Radio has. For the most popular Linux distributions, there is a build script available which automates the downloading, dependency-checking and building for you.

How can I get involved?

For any kind of involvement (not necessarily meaning lots of work), go read how to get involved.

If you'd like to contribute code, also read the development page very carefully.

What can I do to help contribute to GNU Radio?

There are currently some outstanding tasks that need to be accomplished as well as an endless supply of bugs that need to be fixed. Please feel free to enhance GNU Radio, but make sure you read the development page first before we can accept nontrivial contributions.

"How to get involved" might also be of interest.

How can I post on this wiki / use the bug tracker?

Due to spamming issues, you will have to go through a two-step process:
  1. Create an account on this page (top right)
  2. Write an email to the mailing list and request being added as a contributor.

Which operating systems are supported?

First of all: If you have no external forces restricting your choice, go with an up-to-date Linux distribution. Setting up GNU Radio on Linux simply creates the smallest amount of friction. Ubuntu and Fedora are the most common among the GNU Radio community.

However, if you have no other, choice, Windows and Mac are also supported.

Who is part of GNU Radio?

GNU Radio is maintained by Tom Rondeau. It was founded and formerly maintained by Eric Blossom, with regular contributions by Johnathan Corgan, Matt Ettus and others.

For a more complete list of contributors, please visit the [source:gnuradio/trunk/AUTHORS AUTHORS] file in the subversion repository.

Why did GNU Radio get started?

While GNU has been extremely successful in creating free software suites for exploration and hacking by the everyday user, there is still a large void when it comes to hardware hacking especially within the radio frequency spectrum. GNU Radio helps fill this void by supplying a suite of signal processing software blocks along with some tangible hardware to the general public at a modest price (free software, reasonably priced hardware).

Where can I ask other questions about GNU Radio not answered here?

You should feel free to join the mailing lists and actively participate or just read the different threads.

Flying Blind

Learning about a new system is hard. Please don't make it any harder.

The hardest way to learn about a new system - aka flying blind:
  1. Receive samples to a .dat file
  2. Post-process file -> failure
  3. Tweak parameters and repeat

The recommended approach:

Use Gnuradio Companion to generate a graphical application:
  • generate data - live!
  • observe spectrum - live!
  • tweak parameters - live!

Before using hardware, start by using simulation to better understand the flowgraph. Signal sources, noise sources, channel model, file source and sink, signal plotters... etc. See also the tutorial on debugging GNU Radio flow graphs.


GNU Radio Companion

The GNU Radio Companion is graphical UI to develop GNU Radio applications.

I executed the command "grc" and <something bad happened>!

The command "grc" was renamed to "gnuradio-companion" as to not conflict with the Generic Colouriser package, also with a grc executable.

I executed the command "gnuradio-companion" and <something bad happened>!

Ignore GRC for a moment. The error is probably happening at a lower level. Open a terminal and run:

python -c "from gnuradio import gr" 

Does this yield an error? If so, see the section on Python import problems.

Otherwise, see the section on [[FAQ#|The-problem-of-multiple-installs|multiple installs]].

How do I debug a GRC program?

The easiest way is to connect graphical sinks to various points in your flow graph; often, this will give you enough information if the signal has the expected value. If you need more fine-grained debugging features, you can run all your debuggers on the generated Python file (see this).


Build, Install or Runtime Issues

If you have already tried looking at the BuildGuide page, and still seem to have build or runtime issues, read on!

I have problems installing! Please help!

99% of installation troubles are caused by people not installing the correct dependencies and not properly reading the build guide. If you are no expert, go this way:
  • Use Ubuntu or Fedora and
  • Use the build-gnuradio script.

This should take care of all your troubles. Building GNU Radio is not difficult, unless perhaps when you're trying some bleeding edge branch.

How come not all the components are getting installed?

When you run cmake, it might say that some components are not being installed. It might look like this:

-- ######################################################
-- # Gnuradio disabled components                        
-- ######################################################
--   * gr-comedi
--   * gr-shd

Don't worry. It is not usual to install all the components of GNU Radio. However, if a component is listed here which you actually need, you're probably lacking some dependencies. Check the build guide again, or try the automatic build script.

How come it doesn't compile?

Have you read the build guide for your platform and made sure you have all the dependencies installed properly?

If, after following the guide, nothing seems to work, ask the mailing list as a last resort. Make sure to paste the output of cmake.

The compiler doesn't seem to find QWT?

Try adding this to your cmake call: -DQWT_INCLUDE_DIRS=/usr/include/qwt5 (change the path appropriately).

It compiled and installed, but now I can't activate the Python modules?

Perhaps you need to set the PYTHONPATH environment variable, e.g.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

Make sure you identify the correct path first.

The problem of multiple installs

Users like to install multiple versions of gnuradio in multiple parts of their system. Most often, the user installs a very old gnuradio from the package manager into /usr and a new version of gnuradio into /usr/local. This is very bad, the versions of the executable files will not match the library files, will not match the python files.

Solution:

Remove all installed gnuradio files from the system:
  • If you installed from the package manager, then use the package manager to uninstall the files.
  • If you installed from source, use make uninstall, or manually delete all gnuradio files.
  • Purge all gnuradio and gruel files in /usr/bin, /usr/lib(64), /usr/share, /usr/local/bin, /usr/local/lib(64), /usr/local/share

Now install the desired version of gnuradio on your system.

Experts only: How can I deliberately install GNU Radio multiple times (different versions)?

If you like hacking around with GNU Radio, you might want to install both master and next (and possibly other versions) on your machine and switch between these versions without uninstalling.

The following solution is a modified version of "Johnathan Corgans setup": https://lists.gnu.org/archive/html/discuss-gnuradio/2009-02/msg00521.html:

  • Using -DCMAKE_INSTALL_PREFIX, install every version into a separate directory beneath your home dir (e.g. ~/.usrlocal-grnext, ~/.usrlocal-grmaster).
  • Select the active installation by creating a symlink (e.g. .sys -> .sys-next), and run ldconfig.
  • Set your paths appropriately, e.g.:
    # Put this in .bashrc, or whereever your shell reads startup commands from
    GRPREFIX=~/.usrlocal
    if [ -z `echo $PATH | grep "$GRPREFIX"` ]; then 
    export PATH=/usr/lib/ccache:$PATH:~/bin:$GRPREFIX/bin
    export LD_LOAD_LIBRARY=$LD_LOAD_LIBRARY:$GRPREFIX/lib
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GRPREFIX/lib
    export PYTHONPATH=$PYTHONPATH:$GRPREFIX/lib/python2.7/dist-packages
    export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$GRPREFIX/lib/pkgconfig
    export GRC_BLOCKS_PATH=$GRC_BLOCKS_PATH:$GRPREFIX/share/gnuradio/grc/blocks
    fi
    # for ZSH users (watch paths, those are for fedora): ~/.zshenv is attached
    

If you're feeling really adventurous, you can even add a post-checkout hook (.git/hooks/post-checkout):

#!/bin/bash
# $1 - old SHA
# $2 - new SHA
# $3 == 1 if a branch was switched
if [ $3 = "1" ]; then
        BRANCH=`git branch --no-color --contains=$2 |  sed -n 's/\* \(.*\)$/\1/p'`
        if [ "$BRANCH"='(no branch)' ];
        then
                exit
        fi
        test -d $HOME/.usrlocal-gr$BRANCH || exit
        rm $HOME/.usrlocal
        ln -s $HOME/.usrlocal-gr$BRANCH $HOME/.usrlocal
        sudo ldconfig
fi

This will do the switching for you every time you git checkout another branch, so you'll never forget!
Note this will slow 'git checkout' down a bit.

I get an error when importing from Python: _gnuradio_swig_py_runtime.so: undefined symbol: ... what do I do?

$ cat /etc/ld.so.conf
$ cp /etc/ld.so.conf /tmp/ld.so.conf
$ echo /usr/local/lib >> /tmp/ld.so.conf
$ sudo mv /tmp/ld.so.conf /etc/ld.so.conf

... then finally:

$ sudo ldconfig

Now try running those GNU Radio scripts again.

I get an error: "ImportError: libgnuradio-ofdm.so: cannot open shared object file: No such file or directory". What now?

That's a very common message when developing on Linux machines; the reason is directly after installing a library, the dynamic linker doesn't necessarily know about it.
Running

$ sudo ldconfig

usually solves this problem (this command never hurts, you can run it as often as you like).


GNU Radio Processing Blocks

Everything dealing with the creation, implementation and usage of the GNU Radio core signal processing blocks.

What are the building blocks of GNU Radio at my disposal?

GNU Radio uses doxygen to help document all the different modules as well as the API for the core processing blocks.

Do you support BPSK/D-BPSK/QPSK/M-QAM/OFDM/etc.

Sure, have a look at the examples in gnuradio-examples. The information can be found here. If it hasn't been implemented, try it yourself! You'll be surprised what you'll learn.

Why bother with Python? I just want to code in C++!

Sure, that's not a problem. You can write C++-only applications with GNU Radio. However, using Python is great asset and can speed up the development process immensely, even without prior experience with Python.

Isn't Python slow? My application requires blazing speed.

Python is only used to setup the flow graph. Once setup, most of the work is done in C++.

That said, you can write signal processing code with Python and if you use libraries such as Numpy, Python is actually pretty quick.

How do I write a block?

Here's a tutorial on how to do that. This tutorial explores the use of gr_modtool for creating out-of-tree (OOT) projects and adding and removing blocks from the. The gr_modtool utility is distributed as part of GNU Radio.

What is the file format of a gr_file_sink?

The file sink writes the samples to a file in binary format (little-endian). The data format will only depend on the data type used in the file sink block. The following explains the data types and gives the Python Scipy command to read data from the file.

  • gr.sizeof_char: 1 byte per sample
    • f = scipy.fromfile(open("filename"), dtype=scipy.int8)
  • gr.sizeof_short: 2 bytes per sample
    • f = scipy.fromfile(open("filename"), dtype=scipy.int16)
  • gr.sizeof_int: 4 bytes per sample
    • f = scipy.fromfile(open("filename"), dtype=scipy.int32)
  • gr.sizeof_float: 4 bytes per sample (IEEE 754 single-precision floats)
    • f = scipy.fromfile(open("filename"), dtype=scipy.float32)
  • gr.sizeof_gr_complex: 4 bytes per sample as floating point real and imaginary
    • f = scipy.fromfile(open("filename"), dtype=scipy.complex64)

Python related questions

Python import problems: from gnuradio import <foo> is giving me errors!

There are two kind of errors that can happen:

1) <foo> was not found, causing the import to fail.

  • Was <foo> a configured component in your gnuradio build?
  • Did you install <foo>?
  • Can you locate the python files for <foo>?
  • Are the files in your python path?
python -c "import sys; print sys.path" 

If the files are not in your python path, you need to edit the PYTHONPATH environment variable

2) There was a library symbol mismatch.

See the section on multiple-installs.

How can I access the samples in Python?

The easiest way is to write a Python block (see the tutorial). You can then access the content of the input_items vector just like any other Numpy array.

How do I debug GNU Radio in Python?

There are many ways to debug a signal processing application, and it depends on the nature of the bug. For signal processing errors, it's best to develop your own methods. For pesky errors like segmentation faults, it's more straight-forward.

Check out the debugging tutorial for more information on debugging.


Universal Software Radio Peripheral (USRP) and the Universal Hardware Driver (UHD)

Questions specific to the USRP and daughterboards, their functionality, and role within GNU Radio as well as UHD. Note that USRP devices are best accessed by UHD; if you're using legacy drivers don't expect stuff to work or any support on the GNU Radio mailing list.

What are the Universal Software Radio Peripherals?

The [trac:USRP Universal Software Radio Peripheral (USRP)] is a general purpose motherboard which hosts a wide range of daughterboards which can be used with the signal processing blocks found in the GNU Radio software package to give access to the radio frequency spectrum.

Can multiple USRPs be installed on one single host?

Sure, simply create a UHD source for every USRP connected.

If you still use legacy code, you can use the following Python code:

src1 = usrp.source_c( which=0 )
src2 = usrp.source_c( which=1 )

Now which USRP gets assigned #0 and #1 is dependent on the order they enumerate on the USB, first by bus, then by device. This may be affected by which one is plugged in first or turned on first.

The other caveat is that most motherboards share a single USB controller for all their ports. So you're sharing the same 32 MB/s bandwidth across two USRPs now, effectively halving the maximum RF bandwidth you can work with if both USRPs are using the USB equally.

How can I record data from different daughterboards on the same USRP?

You'll need to write a small bit of code. The RX side of a USRP can only be opened once. Thus, you need a single program that reads input from both daughterboards at the same time.

Take a look at [source:gnuradio/trunk/gnuradio-examples/python/multi-antenna/multi_file.py multi_file.py]. It handles 4 simultaneous inputs.

Lastly, when using 2 inputs, there's no need to load special FPGA firmware. The standard file works fine.

What is inband signaling and how can I use it?

Inband signaling is receiving and transmitting control, status and data packets to a USRP to perform specific actions at specific times. This will allow for tight tolerances for TDMA style Media Access Controllers (MACs).

GNU Radio supports inband signaling through a mechanism called stream tags.

Can I run 802.11a/b/g/n/? with a USRP?

Some code has been released which can send and receive 802.11b at 1 Mbps. However, USB 2.0 is too slow to support two way 802.11 interactions, so this is not possible with the USRP1 and USRP B100. In theory, it should be possible with the Gigabit-capable USRP devices such as the N200 series.

The other problem is latency: round trip delay plus processing time would probably not work in our favour here.

What frequency ranges are covered that I can use with the USRP?

Daughterboards are available which cover ranges from DC to 5.9 GHz.

Which sampling rates do the USRPs support?

The signals streamed to and from the USRPs have to be integer fractions of the clock rates, i.e. 64Msps/N for USRP1s and 100Msps/N for anything else. N cannot be any number, though. For most applications, this involves resampling on the host as well.

Can I transmit and receive from the same USRP?

Yes, but there are some caveats that you must take into consideration. First, if using a cabled setup, be sure there is some attenuation between the transmitter and receiver. Second, realize that there is not much isolation on the board itself and signal can leak through even without an antenna.

How does the USRP decide where to allocate requested receive gain?

The current ADC chip (AD9862) on the main board can support 0-20 dB of gain, and various daughtercards can have different gain ranges of their own. Matt Ettus: "In general, we put as much gain as close to the antenna as possible. So the ADC gain is only added in if you request a very high gain."

Can I stream digital data to or from the I/O pins on the USRP?

Yes, check out CompGrGpio.

My USRP2 with the raw Ethernet driver doesn't work with a switch!

The raw Ethernet interface the gr-usrp2 driver uses doesn't route across switches. Time to upgrade to UHD!

My USRP N210 doesn't work with [usrp2_xxx, gr-usrp2]!

The USRP N210 is incompatible with the old gr-usrp2 driver. You must install UHD and convert your applications to gr-uhd sources/sinks to use the N210.

I have two USRPs, and when I transmit on one and receive on the other at the same frequency I get an offset!

USRPs are real-world devices, and as such they are subject to real-world tolerances. There will always be an unavoidable frequency offset between transmitter and receiver, just like in any radio. Coping with frequency offset is the subject of many, many dissertations and papers, and any good book in the literature will tackle the subject of frequency offset estimation and compensation. The exact scheme suitable for your application will depend heavily on the application itself, and could include a Costas loop, simple frequency-tracking PLL, data-aided estimation, etc.

There are a bunch of ways to get around the problem.

  1. Lock the oscillators of your USRPs. See http://files.ettus.com/uhd_docs/manual/html/sync.html for more information.
  2. Use a GPS-disciplined oscillator reference for both USRPs. This is really expensive and only necessary if you need a geographically-distributed absolute time reference.
  3. Use Gnuradio's built-in blocks for frequency locking. These include PLLs, DLLs, FLLs, Costas loops, etc.
  4. Write a custom frequency synchronization algorithm. This can be as simple as the squared-FFT method or as complex as data-aided preamble synchronization. See the OFDM example's Schmidl and Cox synchronization algorithm included with Gnuradio as an example of one method used for OFDM.
  5. Don't use real hardware, and simulate entirely within Gnuradio. You don't always need USRPs to do your simulation.
For a Quick N' Dirty Fix (tm):
  1. Look at a frequency domain plot
  2. Measure the frequency offset
  3. Adjust tuning to compensate

I have a question regarding the USRP1 specifically which is not answered here!

A comprehensive USRP1 FAQ can be found at the USRP-FAQ page.

I upgraded to UHD and now usrp2_fft.py doesn't work!

The UHD driver uses a different GNU Radio source block. Use uhd_fft.py instead.

I upgraded to UHD and now [benchmark_rx.py, tunnel.py, <other Gnuradio example>] doesn't work!

The "classic" gnuradio examples have been ported to uhd in the 3.5 release.

I upgraded to UHD and now [usrp2_find_devices, usrp2_probe] doesn't work!

Use uhd_find_devices and uhd_usrp_probe for all your finding and probing needs.


Signal Processing related

Here are some common DSP related questions. Note that this web site is not meant to teach DSP; you will need a firm grasp of it before you can really attempt to develop GNU Radio applications.

What is this "complex baseband" everyone is talking about?

Well this is awkward... if you're seriously asking this question, you don't have the basic knowledge to do SDR. Complex baseband is the most basic concept (unfortunately, not something that can be answered with one sentence in this FAQ). Just grab a book or read wikipedia, it's not that difficult.

Why is there always a frequency offset when transmitting from one USRP to another?

It's the law of physics. There is no way to eliminate this. Digital receivers must be able to cope with this kind of error.

How do I know the exact voltage/power of my received input signal?

This is extremely difficult. Remember that the USRP (or whatever device you're using) has several analog stages (AGC, amplifiers etc.) which all affect the power before it is passed to the A/D converter. Once you're in the digital domain, all you have is numbers.

The only way to get the exact received power is by calibrating your signal manually.

I'm running uhd_fft.py (or a graphical FFT sink) and there's always a peak in the middle of my spectrum!

It's called DC offset. If it's ruining your DSP, there are blocks to kill it (DC blockers).


Anything Else

I'd like to cite GNU Radio in a scientific paper, are there any rules?

Not really, but make sure you're citing the correct thing -- e.g., are you referencing GNU Radio, or a separate project on CGRAN? Also, make sure you have a timestamp in your citation. Here's an example for a BibTeX markup:

@misc{url:gnu-radio,
  author = "{GNU Radio Website}",
  year = "{accessed February 2012}",
  url = {http://www.gnuradio.org}
}

.zshenv - .zshenv for multiple GNU Radio installations (495 Bytes) Marcus Müller, 05/07/2013 06:58 pm