Dinah Bronson—4 May 2022
In GNU Radio, Embedded Python Blocks are one of the easiest ways to customize blocks for your flowchart. They allow you to access and modify the input and output vectors using python instead of forcing you to create and compile an official out-of-tree module in C++. While they are one of the easiest ways to create new blocks, they still have many nuances that can be difficult to navigate at first.
This tutorial is intended to help reduce some of the frustration that comes with trying to navigate a new system and integrate into it by going through the steps of implementing one of these blocks and discussing some of the nuances. Assuming that you already have a basic understanding of GNU Radio, we will only be specifically discussing the Embedded Python Block.
To start, you will need to create a flowchart in GNU Radio Companion and bring a Python Block into the flowchart.
Where to find the Python Block option
After bringing the block in, you should see something like this when you double-click on it:
Properties window for default Embedded Python Block
The default settings and code in the Embedded Python Block essentially create a Gain block, where you type a value into Example_Param and the block outputs a replica of the input scaled by that value. To change the code, click on the button that says ‘Open in Editor’. After selecting ‘Open in Editor’, you will be prompted to either select an editor or to use the default editor. In this tutorial, we will use the default.
The code for the block is saved internally in the .grc file. If you want to make changes to the code, you will need to change it in the .grc file (either in GNU Radio Companion, or by editing the .grc file code), even though the python code is technically saved to a different file as well (in /tmp/epy_block_0_ner2l4lr.py for this example).
The default code in the default editor looks like this:
Code for default Embedded Python Block
In the code, you have a lot of freedom. You can change the input and output signal types and how many of each you want, you can change any of the docstrings, and you can add and subscribe or publish to message ports. You can add filters and logic to create and change your outputs. You can also import other python modules to further expand the possibilities.
Make sure that you have an init function and a work function. When you run your flowchart, GNU Radio will call the work function passing in an input and an output, so you will put the main body of your code there, and you need to make sure the work function expects those two arrays as input parameters. To work properly, the work function should also return a non-zero value. Returning the length of the output_items[0] vector or the length of the input_items[0] vector both seem to work well and seem to be used most commonly.
The input and output vector lengths vary each time the function is run and can be anywhere from 0 to 10 or more samples long. In order to access individual elements (i.e. the next sample in the input), the best way to make sure it is done properly is to simply iterate over the vector.
Here is an example of some potentially useful changes to this code to make a block that may or may not be particularly useful overall. It simply outputs a message when the magnitude of the float input is less than the magnitude of the complex input divided by one of the parameters:
Examples of changes you can make in the Embedded Python Block code