HowToUse

How do I use GNU Radio?

Even after successfully installing GNU Radio, it might not be clear what exactly GNU Radio is capable of and what it can be used for. This article will give an overview of what you can do with GNU Radio and how to do it.

Using the included tools and utility programs

GNU Radio comes with a large variety of tools and programs which can be used out of the box. If you installed from source, you can find most of the source files in gr-utils/src/python and gr-uhd/apps. If you're using Linux and installed GNU Radio from source (e.g. by using the build-gnuradio script), these programs get installed into /usr/local/bin.

The most commonly used tools include

• uhd_fft - A very simple spectrum analyzer tool which uses a connected UHD device (i.e., a USRP) to display the spectrum at a given frequency. This can be also used for a waterfall plot or as an oscilloscope.
• uhd_rx_cfile - Record an I/Q sample stream using a connected UHD device. Samples are written to a file and can be analysed off-line at a later time, using either GNU Radio or other tools such as Octave or Matlab.
• uhd_rx_nogui - Receive and listen to incoming signals on your audio device. This tool can demodulate AM and FM signals.
• uhd_siggen{_gui}.py - Simple signal generator, can create the most common signals (sine, sweep, square, noise).
• gr_plot* - This is an entire suite of apps which can display pre-recorded samples saved to a file. You can plot the spectra, PSD and time-domain representations of these signals.

If you're using Linux, you can call all these apps from the command line. All apps include a "-h" switch which will display a help screen. With the uhd_fft.py tool, this would look like this:

$ uhd_fft --help                                                                                                 
linux; GNU C++ version 4.5.2; Boost_104200; UHD_003.003.000-d5d448e

Usage: uhd_fft.py [options]

Options:
  -h, --help            show this help message and exit
  -a ADDRESS, --address=ADDRESS
                        Address of UHD device, [default=addr=192.168.10.2]
  -A ANTENNA, --antenna=ANTENNA
                        select Rx Antenna where appropriate
  -s SAMP_RATE, --samp-rate=SAMP_RATE
                        set sample rate (bandwidth) [default=1000000.0]
  -f FREQ, --freq=FREQ  set frequency to FREQ
  -g GAIN, --gain=GAIN  set gain in dB (default is midpoint)
  -W, --waterfall       Enable waterfall display
  -S, --oscilloscope    Enable oscilloscope display
  --avg-alpha=AVG_ALPHA
                        Set fftsink averaging factor, default=[0.1]
  --ref-scale=REF_SCALE
                        Set dBFS=0dB input value, default=[1.0]
  --fft-size=FFT_SIZE   Set number of FFT bins [default=1024]

This is what it looks when used with a USRP1 and a DBSRx daughterboard observing a GSM downlink:

$ uhd_fft.py -a type=usrp1 -f 935M -s 2M

Graphical signal processing development: The GNU Radio Companion (GRC)

Digital signal processing (DSP) is where GNU Radio shines; this is what it was originally made for. GRC is a Simulink-like graphical tool to design signal processing flow graphs. If you're comfortable dealing with FIR filters, digital modulators and other DSP concepts, using GRC should be simple and straightforward for you.

On Linux systems, GRC is invoked by calling the gnuradio-companion command. If your installation was fine, GRC will pop up in its own window. On the right hand side, you can find all the available blocks (good news: adding new blocks is not terribly difficult!), which can be dragged into the main window and connected by clicking the edges. GRC has it's own wiki page.

Here's an example of a narrowband FM receiver, which filters a signal, FM demodulates it and passes it to the sound card (this and other examples can be found on www.oz9aec.net.

Using Python to write powerful signal processing and radio applications

Sometimes GRC cannot provide all the flexibility required for your application. Anything that can be clicked together in GRC can also be written in Python, and while it is more of an effort to code everything yourself, it also provides you with the entire power and functionality of Python and its libraries, such as SciPy or NumPy for Python-centric processing of your signals or your favorite widget library to create any GUI you wish.

Have a look at the Python apps tutorial to find out how to go ahead here. The tutorial also includes an introduction to the main GNU Radio concepts, such as flow graphs.

The C++ domain: Extending GNU Radio

GNU Radio is extremely powerful and includes many kinds of signal processing blocks. However, if you're developing something particular, chances are high that sooner or later you'll be running into some component which is lacking; be it a specific channel code, a segmentation algorithm or whatever. In this case, you will want to write your own blocks to add them into GNU Radio. This is usually done in C++, in order to keep GNU Radio as fast as it is. If this is what you need, check out the tutorial on how to write a new block.

Figuring out how stuff is done: read the examples

Starting to develop stuff using GNU Radio may seem daunting at first. GNU Radio is a powerful but scary beast, but has a steep learning curve.
The best way to start to understand how GNU Radio works is to look at examples. Under Linux, they usually get installed /usr/local/share/gnuradio/examples. There are literally several hundred example files to discover, sorted by topic.

In the source tree, the examples are in the sub-directory they belong to. All examples to do with digital modulation are in 'gr-digital/examples', all examples concerning filters (that includes resampling etc.) are in 'gr-filter/examples' etc. GNU Radio provides examples for Python, GNU Radio companion and C++.