The GNU Radio (GR) Project

B.1 The GNU Radio (GR) Project

B.1.1 For those willing to stop reading and run code

Running GR on Windows is easier nowadays than when GR started, as discussed at [ urlagrw]. But if it is an option, using GR on Linux is advised.¹

Figure B.1: GNU Radio Companion interface highlighting the icons to execute the simulation.

The easiest way to explore GNU Radio (GR) is to execute gnuradio-companion.py, the GNU Radio Companion (or GRC). The GRC is a GUI for GR that aims to make easier to get started with GR. On Windows, it is often located at c:\Program Files\gnuradio\bin and assuming this folder is part of your PATH and Python is properly installed, the script can be invoked with:

1python gnuradio-companion.py

from a command prompt. An alternative is to use Windows Explorer to navigate to its folder and double-click the script icon. Figure B.1 illustrates GRC after loading a file (with extension grc).²

For those who are serious about using GR, the official web site is [ urlagro]. A great source of information and cool projects is the Comprehensive GR Archive Network [ urlagra].

B.1.2 Basic facts about GR

GR is a free software development toolkit that provides the signal processing runtime and processing blocks to implement software radios. It supports, Linux, Mac OS and Windows.

GR applications are primarily written using the Python programming language, while the supplied, performance-critical signal processing path is implemented in C++.

As used in this text, GR supports the development of signal processing algorithms using pre-recorded or generated data, avoiding the need for actual RF hardware.

A block in GR is actually a class implemented in C++. For example, a block called gr.quadrature_demod_cf corresponds to the class gr_quadrature_demod_cf implemented in C++. SWIG (Simplified Wrapper and Interface Generator) is a software layer that creates an interface between C++ and Python.

GR uses the following conventions for files:

.h file for class declaration
.cc file for class definition
.i file defining how SWIG generates glue code binding the C++ class into Python

and for variables names:

f - IEEE 754 single precision number in floating points (or floats)
c - complex (pair of 32-bit floats)
i - integer (32-bit signed integer)
s - short (16-bit signed integer)
b - byte (8-bit signed integer)

Much more information about code conventions is available at [ urlagrc].

A very important aspect of GR is that it has a Scheduler that controls the flow of information. The user connects the blocks using a graph and the Scheduler takes care of sending information from a block to the next block(s) in the graph.

Blocks are connected together using the connect() method of the flow graph. The connect() method takes two parameters, the source endpoint and the destination endpoint, and creates a connection from the source to the destination. An endpoint has two components: a signal processing block and a port number. The port number specifies which input or output port of the specified block is to be connected. In the general form, an endpoint is represented as a Python tuple like this: (block, port_number). When port_number is zero, the block may be used alone. For instance the following two expressions are equivalent:

1fg.connect ((src1, 0), (dst, 1)) 
2fg.connect (src1, (dst, 1))

The start() method forks one or more threads to run the computation described by the graph and returns control immediately to the caller.

Among other tasks, the Scheduler has to allocate buffers to accommodate the data that flows among the blocks. When developing simple applications, which rely only on existing blocks, most of the times the user does not need to understand much about the Scheduler. However, when developing new blocks in C++ or sophisticated applications, it is important to study the Scheduler and related tasks.

¹ In case you need (or want) to run GR on Windows, the main difficulty during the installation process is to keep the dependencies (Python libraries, etc.) compatible among themselves. For example, assume that you have Python version 2.7 installed, then you cannot use a library for Python version 3.3. The problem is that it is sometimes hard to find the file you are looking for on the Web. Try, for example, finding PyQwt-5.2.1-py2.7-x32-pyqt4.9.6-numpy1.6.2-1.exe, which is suggested at the Ettus Windows install page. If not found, you may end up going for PyQwt-5.2.1-py2.7-x32-pyqt4.9.6-numpy1.7.1.exe instead. But then, you must use the NumPy version 1.7.1 (numpy-1.7.1-win32-superpack-python2.7.exe) instead of the originally suggested 1.6.2. Pay attention on how the versions are encoded in the file names to be installed and make sure they match.

² One interesting thing is that, as indicated in Figure B.1, the icon to execute the flow graph has a gray color that sometimes leads novice users to consider it is disabled.