Editing Guided Tutorial GNU Radio in C++

Jump to: navigation, search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 2: Line 2:
  
 
= Tutorial: Working with GNU Radio in C++ =
 
= Tutorial: Working with GNU Radio in C++ =
 +
<br>
 +
<b>NOTE:</b> This tutorial applies only to GR Release 3.7
  
 
== Objectives ==
 
== Objectives ==
Line 32: Line 34:
 
When this tutorial is complete, we will be able to build this flow graph:
 
When this tutorial is complete, we will be able to build this flow graph:
  
[[File:Tutorial4_fg.png]]
+
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.
 
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.
  
'''My QPSK Demodulator''' consumes QPSK symbols which are complex values at the input and produces the alphabets as bytes at output. The output screen looks like this:
+
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.
 
 
[[File:Tutorial4_out.png|700px]]
 
  
 
== Step 1: Create an OOT module <code>gr-tutorial</code> ==
 
== Step 1: Create an OOT module <code>gr-tutorial</code> ==
  
  xyz@comp:mydir$ gr_modtool newmod tutorial
+
  xyz@comp:mydir$ gr_modtool nm tutorial
 
  Creating out-of-tree module in ./gr-tutorial... Done.
 
  Creating out-of-tree module in ./gr-tutorial... Done.
 
  Use 'gr_modtool add' to add a new block to this currently empty module.
 
  Use 'gr_modtool add' to add a new block to this currently empty module.
Line 50: Line 50:
 
  xyz@comp:mydir$ cd ~/gr-tutorial
 
  xyz@comp:mydir$ cd ~/gr-tutorial
 
  xyz@comp:mydir/gr-tutorial$ ls
 
  xyz@comp:mydir/gr-tutorial$ ls
  apps  cmake  CMakeLists.txt  docs  examples  grc  include  lib MANIFEST.md python  swig
+
  apps  cmake  CMakeLists.txt  docs  examples  grc  include  lib  python  swig
 
 
Note: The file MANIFEST.md was not added prior to GR 3.8.
 
  
 
== Step 2: Insert My QPSK Demodulator block into the OOT module ==
 
== Step 2: Insert My QPSK Demodulator block into the OOT module ==
Line 60: Line 58:
 
  xyz@comp:mydir/gr-tutorial$ gr_modtool add my_qpsk_demod_cb
 
  xyz@comp:mydir/gr-tutorial$ gr_modtool add my_qpsk_demod_cb
 
  GNU Radio module name identified: tutorial
 
  GNU Radio module name identified: tutorial
('sink', 'source', 'sync', 'decimator', 'interpolator', 'general', 'tagged_stream', 'hier', 'noblock')
+
  Enter code type: general
  Enter block type: general
 
Language (python/cpp): cpp
 
 
  Language: C++
 
  Language: C++
 
  Block/code identifier: my_qpsk_demod_cb
 
  Block/code identifier: my_qpsk_demod_cb
Please specify the copyright holder: gnuradio.org
+
  Enter valid argument list, including default arguments:  bool gray_code
  Enter valid argument list, including default arguments:  
+
  Add Python QA code? [Y/n]  
  bool gray_code
+
  Add C++ QA code? [y/N] Y
  Add Python QA code? [Y/n] Y
+
  Adding file 'my_qpsk_demod_cb_impl.h'...
  Add C++ QA code? [y/N] N
+
  Adding file 'my_qpsk_demod_cb_impl.cc'...
  Adding file 'lib/my_qpsk_demod_cb_impl.h'...
+
  Adding file 'my_qpsk_demod_cb.h'...
  Adding file 'lib/my_qpsk_demod_cb_impl.cc'...
+
  Editing swig/qpsk_demod_swig.i...
  Adding file 'include/tutorial/my_qpsk_demod_cb.h'...
+
  Adding file 'qa_my_qpsk_demod_cb.py'...
  Editing swig/tutorial_swig.i...
 
  Adding file 'python/qa_my_qpsk_demod_cb.py'...
 
 
  Editing python/CMakeLists.txt...
 
  Editing python/CMakeLists.txt...
  Adding file 'grc/tutorial_my_qpsk_demod_cb.block.yml'...
+
  Adding file 'qpsk_demod_my_qpsk_demod_cb.xml'...
 
  Editing grc/CMakeLists.txt...
 
  Editing grc/CMakeLists.txt...
  
Line 87: Line 81:
 
  Enter code type: general
 
  Enter code type: general
  
In GNU Radio, there exist different kinds of blocks with the different possibilities listed above (since 3.8). Depending on the choice of our block, <code>gr_modtool</code> adds the corresponding code and functions. As illustrated, for <code>my_qpsk_demod_cb</code> block, we opt for a general block.
+
In GNU Radio, there exist different kinds of blocks: general, sync, interpolator/decimator, source/sink, Hierarchical, etc. Depending on the choice of our block, <code>gr_modtool</code> adds the corresponding code and functions. As illustrated, for <code>my_qpsk_demod_cb</code> block, we opt for a general block.
 
 
Please specify the copyright holder:
 
 
 
Since version 3.8, the tool asks for a copyright holder for the code you are about to write. The implications of what you write in that line are legal and not computational.
 
  
 
For <code>my_qpsk_demod_cb</code>, gray_code is selected to be "default arguments".
 
For <code>my_qpsk_demod_cb</code>, gray_code is selected to be "default arguments".
Line 104: Line 94:
 
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.
 
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 [[BlocksCodingGuide|here]].
+
The detailed description of coding structure for the block can be found [http://gnuradio.org/redmine/projects/gnuradio/wiki/BlocksCodingGuide#Public-Header-Files here]
  
 
== Step 3: Fleshing out the code ==
 
== Step 3: Fleshing out the code ==
Line 129: Line 119:
 
* The arguments inside <code>gr::block(...)</code> represents the block name and a call to the make function.
 
* The arguments inside <code>gr::block(...)</code> represents the block name and a call to the make function.
  
* The make function <code>gr::io_signature::make(<+MIN_IN+>, <+MAX_IN+>, sizeof(<+ITYPE+>))</code> and <code>gr::io_signature::make(<+MIN_OUT+>, <+MAX_OUT+>, sizeof(<+OTYPE+>))</code> is a member function of the class <code>gr::io_signature</code> that signifies the input and output port/s.
+
* The make function <code>gr::io_signature::make(<+MIN_IN+>, <+MAX_IN+>, sizeof(<+ITYPE+>))</code> and <code>gr::io_signature::make(<+MIN_OUT+>, <+MAX_OUT+>, sizeof(<+OTYPE+>)</code> is a member function of the class <code>gr::io_signature</code> that signifies the input and output port/s.
  
 
* <''MIN_OUT''> and <''MAX_OUT''> represents the maximum and number of ports.
 
* <''MIN_OUT''> and <''MAX_OUT''> represents the maximum and number of ports.
Line 447: Line 437:
 
== Step 4: Flesh out the XML file ==
 
== Step 4: Flesh out the XML file ==
  
In GNU Radio 3.7 the .xml provides the user interface between the OOT module displayed in the GRC and the source code. For GNU Radio 3.8 and newer, see the next section which describes the YAML format. 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 <code>demod_my_qpsk_demod_cb.xml</code> inside the <code>grc/</code> folder. Presently, the <code>gr_modtool</code>'s version looks like:
+
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 <code>demod_my_qpsk_demod_cb.xml</code> inside the <code>grc/</code> folder. Presently, the <code>gr_modtool</code>'s version looks like:
  
 
Default version:
 
Default version:
Line 570: Line 560:
 
</block>
 
</block>
  
</pre>
 
 
== Step 4 bis: Flesh out the YAML file ==
 
 
Since version 3.8, GNU Radio has replaced the XML files by YAML. They work the same but with a different syntax.
 
 
The .yml provides the user interface between the OOT module displayed in the GRC and the source code. Moreover, the YAML 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 .yml files manually. The YAML file for our block is named as <code>tutorial_my_qpsk_demod_cb.block.yml</code> inside the <code>grc/</code> folder. Presently, the <code>gr_modtool</code>'s version looks like:
 
 
Default version:
 
<pre>
 
id: tutorial_my_qpsk_demod_cb
 
label: my_qpsk_demod_cb
 
category: '[tutorial]'
 
 
templates:
 
  imports: import tutorial
 
  make: tutorial.my_qpsk_demod_cb(${gray_code})
 
 
#  Make one 'parameters' list entry for every parameter you want settable from the GUI.
 
#    Keys include:
 
#    * id (makes the value accessible as \$keyname, e.g. in the make entry)
 
#    * label (label shown in the GUI)
 
#    * dtype (e.g. int, float, complex, byte, short, xxx_vector, ...)
 
parameters:
 
- id: ...
 
  label: ...
 
  dtype: ...
 
- id: ...
 
  label: ...
 
  dtype: ...
 
 
#  Make one 'inputs' list entry per input and one 'outputs' list entry per output.
 
#  Keys include:
 
#      * label (an identifier for the GUI)
 
#      * domain (optional - stream or message. Default is stream)
 
#      * dtype (e.g. int, float, complex, byte, short, xxx_vector, ...)
 
#      * vlen (optional - data stream vector length. Default is 1)
 
#      * optional (optional - set to 1 for optional inputs. Default is 0)
 
inputs:
 
- label: ...
 
  domain: ...
 
  dtype: ...
 
  vlen: ...
 
  optional: ...
 
 
outputs:
 
- label: ...
 
  domain: ...
 
  dtype: ...
 
  vlen: ...
 
  optional: ...
 
 
#  'file_format' specifies the version of the GRC yml format used in the file
 
#  and should usually not be changed.
 
file_format: 1
 
</pre>
 
 
 
The parameter <code>gray_code</code> can be put under the <code>parameters</code> tag.
 
 
Adding parameter tag:
 
 
<pre>
 
parameters:
 
- id: gray_code
 
  label: Gray Code
 
  dtype: bool
 
  default: 'True'
 
</pre>
 
 
 
Like the work function, the datatypes for the input and output ports represented by <code>input</code> and <code><nowiki>output</nowiki></code> tags should be modified.
 
 
Modifying source and sink tag:
 
 
<pre> 
 
inputs:
 
- label: in
 
  dtype: complex
 
</pre>
 
<pre> 
 
outputs:
 
- label: out
 
  dtype: byte
 
</pre>
 
 
 
After all the necessary modification the "tutorial_my_qpsk_demod_cb.block.yml" looks like this:
 
 
Modified version:
 
 
<pre>
 
id: tutorial_my_qpsk_demod_cb
 
label: My QPSK Demodulator
 
category: '[tutorial]'
 
 
templates:
 
  imports: import tutorial
 
  make: tutorial.my_qpsk_demod_cb(${gray_code})
 
 
parameters:
 
- id: gray_code
 
  label: Gray Code
 
  dtype: bool
 
  default: 'True'
 
 
inputs:
 
- label: in
 
  dtype: complex
 
outputs:
 
- label: out
 
  dtype: byte
 
 
file_format: 1
 
 
</pre>
 
</pre>
  
Line 1,130: Line 1,006:
 
How to build hierarchical blocks in GNU Radio?
 
How to build hierarchical blocks in GNU Radio?
  
Hierarchical blocks define an input and output stream much like normal blocks. For '''I''' input streams, let '''i''' be a value between 0 and '''I'''-1. To connect input '''i''' to a hierarchical block, the source is (in Python):
+
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):
  
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
self.connect((self, <i>), <block>)
+
self.connect((self, i), <block>)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 1,139: Line 1,015:
  
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
self.connect(<block>, (self, <o>))
+
self.connect(<block>, (self, o))
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 1,302: Line 1,178:
 
connect(normalizer_magsquare, 0, normalizer_ma, 0);
 
connect(normalizer_magsquare, 0, normalizer_ma, 0);
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
-----
 +
 +
[1] http://radioware.nd.edu/documentation/advanced-gnuradio/writing-a-signal-processing-block-for-gnu-radio-part-i

Please note that all contributions to GNU Radio are considered to be released under the Creative Commons Attribution-ShareAlike (see GNU Radio:Copyrights for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel | Editing help (opens in new window)