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  and. If you're using Linux and installed GNU Radio from source (e.g. by using the build-gnuradio script), these programs get installed into  or.

The most commonly used tools include


 * - 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.
 * - 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.
 * - Receive and listen to incoming signals on your audio device. This tool can demodulate AM and FM signals.
 * - Simple signal generator, can create the most common signals (sine, sweep, square, noise).
 * - 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 &quot;-h&quot; switch which will display a help screen. With the  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. 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++.