Guided Tutorial GNU Radio in C++

= Tutorial: Working with GNU Radio in C++ =

Objectives

 * Extend our knowledge to program GNU Radio using C++.
 * An introduction to GNU Radio's C++ API, in particular:
 * types
 * generic functions
 * GNU Radio blocks
 * Learn to manage and write our own OOT modules in C++.
 * We follow our discussions based on a working example by continuing to work on our OOT module.
 * Within the tutorial module, we will build our QPSK demodulator called as My QPSK Demodulator in C++.
 * Understand the nuances of developing an OOT module.
 * The tutorial considers some advance topics that are also part of GNU Radio framework.
 * These topics find their usage for some specific implementations of the OOT module.

Prerequisites

 * Knowledge of C++
 * Previous tutorials recommended:
 * Tutorials Introductions
 * GRC Tutorial
 * Programming GR in Python

-

= 4.1 C++ or Python? =

This is a standard question that every one of us needs to consider before starting our own OOT module. Tutorial 3 already addressed ways to select the programming language of choice for the blocks in OOT module using

$ gr_modtool add -t sync -l python or

$ gr_modtool add -t sync -l cpp # This is the default

Apart from the compiler and interpreter, there are many differences out there. To decide upon the choice of the programming language, it is important that we limit the differences from the GNU Radio perspective. Primarily, it depends more on the objective of the OOT module. As far as the performance is concerned, implementing the blocks in C++ makes more sense, and if the performance of the OOT module is the not main issue Python would be a good choice, as it is concise yet simple. Moreover, Python allows faster prototyping as we don't have to compile to test the modules.

= 4.2 Maneuvering our OOT module =

Introduced in tutorial 3, we will now extend the usage of gr_modtool to create an OOT module and write our blocks in C++.

For a detailed explanation of  commands, go here, or have a quick peek at the cheat sheet.

4.2.1 Objective
When this tutorial is complete, we will be able to build this flow graph:

https://raw.githubusercontent.com/gnuradio/gr-tutorial/master/examples/tutorial4/figs/Tut4_My_QPSK_demod_flowgraph.png

The flowgraph demonstrates a QPSK transceiver chain with the block My QPSK Demodulator block module under the OOT tutorial. We will be building this block using C++. All other blocks are standard GNU Radio blocks.

As in the previous tutorial, My QPSK Demodulator consumes QPSK symbols which are complex valued floats at the input and produces the alphabets as bytes at output. We will plot the binary values (from 0 through 3) as well as the transmitted complex symbols during operation.

Alright, lets get started.

4.2.2 Step 1: Create an OOT module
xyz@comp:mydir$ gr_modtool nm tutorial Creating out-of-tree module in ./gr-tutorial... Done. Use 'gr_modtool add' to add a new block to this currently empty module. xyz@comp:mydir$ ls xyz@comp:mydir$ gr-tutorial

Have a look into the dir structure of our

xyz@comp:mydir$ cd gr-tutorial xyz@comp:mydir/gr-tutorial$ ls apps cmake  CMakeLists.txt  docs  examples  grc  include  lib  python  swig

4.2.3 Step 2: Insert My QPSK Demodulator block into the OOT module
Again using, inside  , we create our   block:

xyz@comp:mydir/gr-tutorial$ gr_modtool add my_qpsk_demod_cb GNU Radio module name identified: tutorial Enter code type: general Language: C++ Block/code identifier: my_qpsk_demod_cb Enter valid argument list, including default arguments: bool gray_code Add Python QA code? [Y/n] Add C++ QA code? [y/N] Y Adding file 'my_qpsk_demod_cb_impl.h'... Adding file 'my_qpsk_demod_cb_impl.cc'... Adding file 'my_qpsk_demod_cb.h'... Editing swig/qpsk_demod_swig.i... Adding file 'qa_my_qpsk_demod_cb.py'... Editing python/CMakeLists.txt... Adding file 'qpsk_demod_my_qpsk_demod_cb.xml'... Editing grc/CMakeLists.txt...

Unlike when creating an OOT module, creating a block using  demand inputs from the user. To follow the command line user interaction, let's decompose the information above.

xyz@comp:mydir/gr-tutorial$ gr_modtool add my_qpsk_demod_cb

represents class name of the block, where the suffix, 'cb' is added to the block name, which conform to the GNU Radio nomenclature. 'cb' states the block established that takes complex data as input and spits byte as output.

Enter code type: general

In GNU Radio, there exist different kinds of blocks: general, sync, interpolator/decimator, source/sink, Hierarchical, etc. Depending on the choice of our block,  adds the corresponding code and functions. As illustrated, for  block, we opt for a general block. The following section will discuss the purpose of the specific blocks in detail.

In many cases, the block demands a user interface. For, gray_code is selected to be "default arguments".

Enter valid argument list, including default arguments: bool gray_code

Moreover, GNU Radio provides an option of writing test cases. This provides quality assurance to the code written. If selected, the  adds the quality assurance files corresponding to python and C++.

Add Python QA code? [Y/n] Add C++ QA code? [y/N] y

With this, we have already established the GNU Radio semantics for our block coupled with the OOT module. In the following sections, we will focus on the implementation of our block.

The detailed description of coding structure for the block can be found here

4.2.4 Step 3: Fleshing out the code
The next step is to implement the logic for our block. This is done inside the work function which is defined in the source file  inside the   folder. The skeleton of the  has the following structure:


 * is the constructor of the block .   calls the constructor of the base class block   defined here.


 * The arguments inside  represents the block name and a call to the make function.


 * The make function  and   is a member function of the class   that signifies the input and output port/s.


 *  and  represents the maximum and number of ports.


 *  and  indicates the datatypes for the input and output port/s which needs to be filled out manually.

Next, we need to modify the constructor. After modification, it looks like this:

The option  is copied to the class attribute. Note that we need

to declare this a private member of the class in the header file ,

Also inside this class is the method, which is pure virtual in  , so we definitely need to override that. After running ,

the skeleton version of this function will look something like this:

There is one pointer to the input- and one pointer to the output buffer, respectively, and a for-loop which processes the items in the input buffer and copies them to the output buffer. Once the demodulation logic is implemented, the structure of the work function has the form

This work function calls another function, which we also need to add:

Note the function declaration also needs to be added to the class header.

The function  is a maximum likelihood decoder for the QPSK demodulater. Theoretically, the function should compute the distance from each ideal QPSK symbol to the received symbol (It is mathematically equivalent to determining the Voronoi regions of the received sample). For a QPSK signal, these Voronoi regions are simply four quadrants in the complex plane. Hence, to decode the sample into bits, it makes sense to map the received sample to these quadrants.

Now, let's consider the  function. The system needs to know how much data is required to ensure validity in each of the input arrays. As stated before, the  method provides this information, and you must therefore override it anytime you write a   derivative (for sync blocks, this is implicit).

The default implementation of  says there is a 1:1 relationship between noutput_items and the requirements for each input stream. The size of the items is defined by  in the constructor of. The sizes of the input and output items can of course differ; this still qualifies as a 1:1 relationship. Of course, if you had this relationship, you wouldn't want to use a !

Although the 1:1 implementation worked for, it wouldn't be appropriate for interpolators, decimators, or blocks with a more complicated relationship between   and the input requirements. That said, by deriving your classes from,   or   instead of  , you can often avoid implementing.

Refilling the private constructor and overriding the  and   will suffice the coding structure of our block. However, in the  class there exists more specific functions. These functions are covered under advanced topics section

4.2.5 Step 4: Flesh out the XML file
The .xml provides the user interface between the OOT module displayed in the GRC and the source code. Moreover, the XML file defines an interface to pass the parameters specific for the module. Hence, to access the module inside GRC, it is important to modify the .xml files manually. The XML file for our block is named as  inside the   folder. Presently, the 's version looks like:

Default version:  my_qpsk_demod_cb tutorial_my_qpsk_demod_cb tutorial import tutorial tutorial.my_qpsk_demod_cb($gray_code) ...    ...     ...

in

The parameter  can be put under the   tag.

Adding parameter tag:

 Gray Code gray_code True bool Yes True No      False

Like the work function, the datatypes for the input and output ports represented by  and   tags should be modified.

Modifying source and sink tag:

in    complex

After all the necessary modification the "tutorial_my_qpsk_demod_cb.xml" looks like this:

Modified version:

 My QPSK Demodulator tutorial_my_qpsk_demod_cb tutorial import tutorial tutorial.my_qpsk_demod_cb($gray_code) Gray Code gray_code True bool Yes True No      False in    complex

4.2.6 Step 5: Install my_qpsk_demod in grc
We have finished the implementation of our block, now it's important use its functionality under GRC. So we build our OOT and install the underlying blocks. To do so, we need to execute the following commands:

sequence: xyz@comp:mydir/gr-tutorial$ mkdir build xyz@comp:mydir/gr-tutorial$ cd build xyz@comp:mydir/gr-tutorial/build$ cmake .. -- Build type not specified: defaulting to release. Checking for GNU Radio Module: RUNTIME * INCLUDES=/usr/local/include * LIBS=/usr/local/lib/libgnuradio-runtime.so;/usr/local/lib/libgnuradio-pmt.so GNURADIO_RUNTIME_FOUND = TRUE -- Configuring done -- Generating done -- Build files have been written to: pathtomyhomefolder/mydir/gr-qpsk_demod/build xyz@comp:mydir/gr-demod/build$make [ 7%] Built target gnuradio-tutorial [ 23%] Built target test-tutorial [ 23%] Built target tutorial_swig_swig_doc [ 30%] Built target _tutorial_swig_swig_tag [ 38%] Swig source Scanning dependencies of target _tutorial_swig [ 46%] Building CXX object swig/CMakeFiles/_tutorial_swig.dir/tutorial_swigPYTHON_wrap.cxx.o Linking CXX shared module _tutorial_swig.so [ 53%] Built target _tutorial_swig [ 61%] Generating tutorial_swig.pyc [ 69%] Generating tutorial_swig.pyo [ 84%] Built target pygen_swig_2598c [100%] Built target pygen_python_6ab2e [100%] Built target pygen_apps_9a6dd

xyz@comp:mydir/gr-qpsk_demod/build$ sudo make install [ 7%] Built target gnuradio-tutorial [ 23%] Built target test-tutorial [ 23%] Built target tutorial_swig_swig_doc [ 30%] Built target _tutorial_swig_swig_tag [ 53%] Built target _tutorial_swig [ 84%] Built target pygen_swig_2598c [100%] Built target pygen_python_6ab2e [100%] Built target pygen_apps_9a6dd Install the project... -- Install configuration: "Release" -- Up-to-date: /usr/local/lib/cmake/tutorial/demodConfig.cmake -- Up-to-date: /usr/local/include/tutorial/api.h -- Up-to-date: /usr/local/include/tutorial/my_qpsk_demod_cb.h -- Up-to-date: /usr/local/lib/libgnuradio-tutorial.so -- Installing: /usr/local/lib/python2.7/dist-packages/tutorial/_tutorial_swig.so -- Removed runtime path from "/usr/local/lib/python2.7/dist-packages/tutorial/_tutorial_swig.so" -- Installing: /usr/local/lib/python2.7/dist-packages/tutorial/tutorial_swig.py -- Installing: /usr/local/lib/python2.7/dist-packages/tutorial/tutorial_swig.pyc -- Installing: /usr/local/lib/python2.7/dist-packages/tutorial/tutorial_swig.pyo -- Up-to-date: /usr/local/include/tutorial/tutorial/swig/tutorial_swig.i -- Installing: /usr/local/include/tutorial/tutorial/swig/tutorial_swig_doc.i -- Up-to-date: /usr/local/lib/python2.7/dist-packages/tutorial/__init__.py -- Up-to-date: /usr/local/lib/python2.7/dist-packages/tutorial/__init__.pyc -- Up-to-date: /usr/local/lib/python2.7/dist-packages/tutorial/__init__.pyo -- Up-to-date: /usr/local/share/gnuradio/grc/blocks/tutorial_my_qpsk_cb.xml

xyz@comp:mydir/gr-qpsk_demod/build$ sudo ldconfig

4.2.7 Step 6: Quality Assurance (Unit Testing)
https://raw.githubusercontent.com/gnuradio/gr-tutorial/master/examples/tutorial4/figs/Constellation_diagram.png

Figure above represents the constellation diagram (displayed in accordance to the Qt GUI Constellation Sink) of the QPSK modulated input fed to out OOT module. The task of our QPSK demodulator is to demodulate this complex valued input stream and to produce stream of quaternary alphabets (0,1,2,3) or simply bytes as output.

By following the steps of writing the OOT module, we did manage to produce the byte stream at the output of QPSK demodulator, still, it doesn't guarantee the correct working of our block. In this situation, it becomes significant to write unit test for our module that certifies the clean implementation of the QPSK demodulator.

Below we see the source of code of the  can be found under

Full QA code

It can be easily noticed that the  is implemented in python, in spite of we opted C++ in the first case for writing our blocks. This is because, GNU Radio inherits the python unittest framework to support quality assurance. And, if you remember it correctly from previous tutorials, swig as part of GNU Radio framework, provides python bindings for the C++ code. Hence, we are able to write the unit test for our block  in python.

So lets gather a bit of know how on how to write test cases for the block. Okay, lets consider the header part first:

and  are the standard lines that includes gr, gr_unittest functionality in the   file. import the python bidden version of our module, which provides an access our block. Finally,  includes array.

The  file execution start by calling this function. The  automatically calls the functions in a specific order   for creating the top block at the start,   for deleting the top block at the end. In between the  and   the test cases defined are executed. The methods starting with prefix  are recognized as test cases by. We have defined two test cases  and. The usual structure of a test cases comprises of a known input data and the expected output. A flowgraph is created to include the source (input data), block to be tested (processor) and sink (resulted output data). In the end the expected output is compared with the resulted output data.

Finally, the statements in the test cases

determine the result of test cases as passed or failed. The test cases are executed before installation of the module by running :

Output xyz@comp:mydir/gr-tutorial/build$ make test Running tests... Test project /home/kaushik/src/gr-tutorial/build Start 1: test_tutorial 1/3 Test #1: test_tutorial .................... Passed   0.11 sec Start 2: qa_chat_sanitizer 2/3 Test #2: qa_chat_sanitizer ................***Failed   0.04 sec Start 3: qa_qpsk_demod 3/3 Test #3: qa_qpsk_demod .................... Passed   2.00 sec 67% tests passed, 1 tests failed out of 3 Total Test time (real) =  2.34 sec The following tests FAILED: 2 - qa_chat_sanitizer (Failed) Errors while running CTest make: *** [test] Fehler 8

In the output above, one of the test failed, however, Test 3 belonging to the, claims to have passed the test cases.

Congratulations, we have just finished writing our OOT module  and a C++ block.

= 4.3 Advanced topics =

The topics discussed until now have laid the foundation for designing the OOT module independently. However, the GNU Radio jargon extends further beyond these. Therefore, under this section, we drift from the QPSK demodulator and focus on the features that are rarely used or are more specific to the implementation.

To add physical meaning to the discussion, we have taken assistance of the existing modules. The source code excerpts are included thereof. Enthusiastic readers are suggested to open the source code in parallel and play around with their functionalities.

4.3.1 Specific functions related to block
In the last section, we managed out implementation of our block by defining functions like  and. But sometimes special functions need to be defined for the implementation. The list is long, but we try to discuss same of these functions in the following subsections.

4.3.1.1 set_history
If your block needs a history (i.e., something like an FIR filter), call this in the constructor.

Here is an example

GNU Radio then makes sure you have the given number of 'old' items available.

The smallest history you can have is 1, i.e., for every output item, you need 1 input item. If you choose a larger value, N, this means your output item is calculated from the current input item and from the N-1 previous input items.

The scheduler takes care of this for you. If you set the history to length N, the first N items in the input buffer include the N-1 previous ones (even though you've already consumed them).

The history is stored in the variable.

The  is defined in

4.3.1.2 set_output_multiple
When implementing your  routine, it's occasionally convenient to have the run time system ensure that you are only asked to produce a number of output items that is a multiple of some particular value. This might occur if your algorithm naturally applies to a fixed sized block of data. Call  in your constructor to specify this requirement,

by invoking, we set the value variable to. The default value of  is 1.

Lets consider an example, say we want to generate outputs only in a 64 elements chunk, by setting d_output_multiple to 64 we can achieve this, but note that we can also get multiples of 64 i.e. 128, 256 etc

The definition of  can be found in gnuradio/gnuradio-runtime/block.cc

4.3.2 Specific block categories
Again the implementation of the  was done using a general block. However, GNU Radio includes some blocks with special functionality. A brief overview of these blocks is described in the table.

In the next subsections we discuss these blocks in detail. Again, enthusiastic readers can find these blocks in the GNU Radio source code.

Source
An example of source block in C++

Some observations:


 * sets the input items to 0, in indicates there are no input streams.
 * Because it connected with the hardware USRP, the  is a sub class of.

Sink
An example of the sink block in C++

Some observations:


 * sets the output items to 0, in indicates there are no output streams.
 * Because it connected with the hardware USRP, the  is a sub class of.

4.3.2.3 Sync
The sync block allows users to write blocks that consume and produce an equal number of items per port. A sync block may have any number of inputs or outputs. When a sync block has zero inputs, its called a source. When a sync block has zero outputs, its called a sink.

An example sync block in C++:

Some observations:


 * noutput_items is the length in items of all input and output buffers
 * an input signature of gr::io_signature::make(0, 0, 0) makes this a source block
 * an output signature of gr::io_signature::make(0, 0, 0) makes this a sink block

Decimators
The decimation block is another type of fixed rate block where the number of input items is a fixed multiple of the number of output items.

An example decimation block in c++

Some observations:


 * The gr_sync_decimator constructor takes a 4th parameter, the decimation factor
 * The user must assume that the number of input items = noutput_items*decimation. The value  is therefore implicit.

Interpolation
The interpolation block is another type of fixed rate block where the number of output items is a fixed multiple of the number of input items.

An example interpolation block in c++

Some observations:


 * The gr_sync_interpolator constructor takes a 4th parameter, the interpolation factor
 * The user must assume that the number of input items = noutput_items/interpolation

4.3.2.5 Hierarchical blocks
Hierarchical blocks are blocks that are made up of other blocks. They instantiate the other GNU Radio blocks (or other hierarchical blocks) and connect them together. A hierarchical block has a "connect" function for this purpose.

When to use hierarchical blocks?

Hierarchical blocks provides us modularity in our flowgraphs by abstracting simple blocks, that is hierarchical block helps us define our specific blocks at the same time provide us the flexibility to change it, example, we would like to test effect of different modulation schemes for a given channel model. However our synchronization algorithms are specific or newly published. We define our hier block as gr-my_sync that does synchronization followed equalizer and demodulation. We start with BPSK, the flowgraph looks like

gr-tx ---> gr-channel --> gr-my_sync --> gr-equalizer --> gr-bpsk_demod

Now, our flowgraph looks decent. Secondly, we abstracted the complex functionality of our synchronization. Shifting to QPSK, where the synchronization algorithm remains the same, we just replace the gr-bpsk_demod with gr-qpsk_demod

gr-tx ---> gr-channel --> gr-my_sync --> gr-equalizer --> gr-qpsk_demod

How to build hierarchical blocks in GNU Radio?

Hierarchical blocks define an input and output stream much like normal blocks. To connect input i to a hierarchical block, the source is (in Python):

Similarly, to send the signal out of the block on output stream o:

An typical example of a hierarchical block is OFDM Receiver implemented in python under gnuradio/gr-digital/python/digital

The class is defined as:

and instantiated as

Some main tasks performed by the OFDM receiver include channel filtering, synchronization and IFFT tasks. The individual tasks are defined inside the hierarchical block.


 * Channel filtering


 * Synchronization


 * ODFM demodulation

Finally, the individual blocks along with hierarchical are connected among each to form a flow graph.

Connection between the hierarchical block OFDM receiver to channel filter block

Connection between the channel filter block to the OFDM synchronization block.

and so forth.

Hierarchical blocks can also be nested, that is blocks defined in hierarchical blocks could also be hierarchical blocks. For example, OFDM sync block is also an hierarchical block. In this particular case it is implemented in. Lets have a look into it.

Underneath is instant of the hierarchical block. Don't panic by looking at its size, we just need to grab the concept behind creating hierarchical blocks.

OFDM impl

Let's understand the code piece wise. The hierarchical block is C++ is instantiated as follows:

where  is the constructor with parameters   and   is the base class. The block name  is defined following the GNU Radio block naming style.

defines my input items and the output items are either

or

depending on the preprocessor directive.

The individual blocks inside the  block are defined as follows:

Finally the individual blocks are connected using:

= 4.4 Closing note =

At this point, we are qualified enough to write our own OOT module and include blocks within (either in Python or C++ depending on what we choose). To strengthen the things we learned in this tutorial, its time to go through a small quiz in the following section.

= 4.5 Quiz =


 * What will change if we decide to shift our modulation scheme form QPSK to 8 PSK/4-QAM/16-QAM?
 * If we think of porting the QPSK demodulator to a generic demodulator, does the usage of hierarchical block makes sense?
 * How does noise affect our system?

-

[1] http://radioware.nd.edu/documentation/advanced-gnuradio/writing-a-signal-processing-block-for-gnu-radio-part-i