Creating Python OOT with gr-modtool

Beginner Tutorials Introducing GNU Radio What is GNU Radio? Installing GNU Radio Your First Flowgraph Flowgraph Fundamentals Python Variables in GRC Variables in Flowgraphs Runtime Updating Variables Signal Data Types Converting Data Types Packing Bits Streams and Vectors Hier Blocks and Parameters Creating and Modifying Python Blocks Creating Your First Block Python Block With Vectors Python Block Message Passing Python Block Tags DSP Blocks Low Pass Filter Example Designing Filter Taps Sample Rate Change Frequency Shifting Reading and Writing Binary Files SDR Hardware RTL-SDR FM Receiver B200-B205mini FM Receiver

TODO: fill out some introductory info TODO: add this tutorial to the nav bar

This tutorial was written using GNU Radio v3.10.1.1.

Creating an OOT Module

Open a terminal and navigate to an appropriate directory for writing software, such as the home directory:

$ cd $HOME

GNU Radio comes packaged with gr_modtool, software used to create out-of-tree (OOT) modules. An OOT module can be thought of as a collection of custom GNU Radio blocks. Create an OOT module named customModule using gr_modtool:

$ gr_modtool newmod customModule

The directory gr-customModule is created which contains all of the skeleton code for an OOT module, however it does not yet have any blocks. Move into the gr-customModule directory:

$ cd gr-customModule

List all of the files and directories within the OOT module:

$ ls

The directory listing will be as follows:

apps/  cmake/  CMakeLists.txt  docs/  examples/  grc/  include/  lib/  MANIFEST.md  python/

Creating an OOT Block

Now a block needs to be created within gr-customModule. The custom block will either add or subtract based on an input parameter, so the block is named addSubSelect:

$ gr_modtool add addSubSelect

The command will start a questionnaire about how to the block is to be defined: what block type, language and parameters:

GNU Radio module name identified: customModule
('sink', 'source', 'sync', 'decimator', 'interpolator', 'general', 'tagged_stream', 'hier', 'noblock')

Select the sync block, which produces an output for every input:

Enter block type: sync

Enter python as the language:

Language (python/cpp): python
Language: Python
Block/code identifier: addSubSelect

Enter the name or organization of the copyright holder:

Please specify the copyright holder: YourName

Now enter the argument list:

Enter valid argument list, including default arguments:

Enter the argument list as if writing the Python code directly. In this case the selector will determine whether or not the block performs addition or subtraction. A default argument of True is given:

selector=True

Determine whether or not you want the Python quality assurance (QA) code:

Add Python QA code? [Y/n] n

New files will be generated:

Adding file 'python/customModule/addSubSelect.py'...
Adding file 'grc/customModule_addSubSelect.block.yml'...
Editing grc/CMakeLists.txt...

Two new files were created, addSubSelect.py which defines the operation of the block and customModule_addSubSelect.block.yml which defines the interface of the block for GNU Radio Companion (GRC). The CMakeLists.txt file was modified so the two files will be installed when the module is compiled and installed.

Modifying Python File

Open the python file with a text editor:

gedit python/customModule/addSubSelect.py &

The following code will be listed: ‎

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright 2022 YourName.
#
# SPDX-License-Identifier: GPL-3.0-or-later
#


import numpy
from gnuradio import gr

class addSubSelect(gr.sync_block):
    """
    docstring for block addSubSelect
    """
    def __init__(self, selector=True):
        gr.sync_block.__init__(self,
            name="addSubSelect",
            in_sig=[<+numpy.float32+>, ],
            out_sig=[<+numpy.float32+>, ])


    def work(self, input_items, output_items):
        in0 = input_items[0]
        out = output_items[0]
        # <+signal processing here+>
        out[:] = in0
        return len(output_items[0])‎

Change the import statement:

import numpy as np

Both the __init__() function and work() function need to be modified. The __init__() function is modified to define the input type. The addSubSelect block will accept two complex inputs and produce a complex output, therefore the in_sig and out_sig parameters need to be changed. The selector parameter also needs to be saved as a member variable:

    def __init__(self, selector=True):
        gr.sync_block.__init__(self,
            name="addSubSelect",
            in_sig=[np.complex64,np.complex64],
            out_sig=[np.complex64])
        self.selector = selector

The work() function is modified to either add or subtract the two inputs based on the selector parameter:

    def work(self, input_items, output_items):
        in0 = input_items[0]
        in1 = input_items[1]

        if (self.selector):
            output_items[0] = in0 + in1
        else:
            output_items[0] = in0 - in1

        return len(output_items[0])

Save the file.

Modifying YAML File

Open the .yml file with a text editor:

gedit grc/customModule_addSubSelect.block.yml &

The following YAML is displayed: ‎

id: customModule_addSubSelect
label: addSubSelect
category: '[customModule]'

templates:
  imports: from gnuradio import customModule
  make: customModule.addSubSelect(${selector})

#  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, ...)
#     * default
parameters:
- id: parametername_replace_me
  label: FIX ME:
  dtype: string
  default: You need to fill in your grc/customModule_addSubSelect.block.yaml
#- 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‎

The YAML file needs to be updated to match the addSubSelector.py file that was just modified. There is a single parameter, selector. Enter the parameter values according to:

‎

parameters:
- id: selector
  label: Add (True) or Subtract (False) Selector
  dtype: bool
  default: True‎

The two inputs need to be defined in the YAML:

‎

inputs:
- label: in0
  domain: stream
  dtype: complex
- label: in1
  domain: stream
  dtype: complex
‎

The single output needs to be defined:

‎

outputs:
- label: out0
  domain: stream
  dtype: complex
‎

Save the file.

Install the Block

In the top level directory of gr_customModule, create a build directory:

$ mkdir build

The directory should look like the following:

apps/  build/  cmake/  CMakeLists.txt  docs/  examples/  grc/  include/  lib/  MANIFEST.md  python/

Move into the build directory,

$ cd build

Then run CMake which will prepare the makefiles:

cmake ..

Compile the module:

$ make

Install the module with sudo:

sudo make install

Multiple files will now be installed:

[  0%] Built target pygen_apps_9a6dd
[  0%] Built target copy_module_for_tests
[100%] Built target pygen_python_customModule_f524f
Install the project...
-- Install configuration: "Release"
-- Installing: /usr/local/lib/cmake/gnuradio-customModule/gnuradio-customModuleConfig.cmake
-- Installing: /usr/local/include/gnuradio/customModule/api.h
-- Installing: /usr/local/lib/python3.9/dist-packages/gnuradio/customModule/__init__.py
-- Installing: /usr/local/lib/python3.9/dist-packages/gnuradio/customModule/addSubSelect.py
-- Installing: /usr/local/lib/python3.9/dist-packages/gnuradio/customModule/__init__.pyc
-- Installing: /usr/local/lib/python3.9/dist-packages/gnuradio/customModule/addSubSelect.pyc
-- Installing: /usr/local/lib/python3.9/dist-packages/gnuradio/customModule/__init__.pyo
-- Installing: /usr/local/lib/python3.9/dist-packages/gnuradio/customModule/addSubSelect.pyo
-- Installing: /usr/local/share/gnuradio/grc/blocks/customModule_addSubSelect.block.yml

Using the Custom Block in a Flowgraph

Start GNU Radio Companion (GRC):

$ gnuradio-companion &

The addSubSelect block will be available under the customModule drop down in the block library:

Drag the block into the workspace: