Difference between revisions of "Embedded Python Block"

From GNU Radio
Jump to navigation Jump to search
(First round of revisions: add Initial code section; add User notes.)
Line 1: Line 1:
[[Category:Block Docs]]
[[Category:Block Docs]]
Allows you to create a new (custom) block, in Python, without needing to make and install an Out of Tree Module (OOT).  The example block (pre-populated code when you add the block to your flowgraph) simply takes the input stream and multiplies it by a constant.  Note that the structure of this Python block matches the structure of an Out of Tree Module (OOT) Python block, it's essentially a Python OOT block built into a grc flowgraph.  
Allows you to create a new (custom) block in Python without needing to make and install an Out of Tree Module (OOT).  When you add the block to your flowgraph,  the pre-populated code simply takes the input stream and multiplies it by a constant.  Note that the structure of this Python block matches the structure of an Out of Tree Module (OOT) Python block. It's essentially a Python OOT block built into a grc flowgraph.  


For some platforms the open with Default Text Editor button may do nothing, in which case you have to manually choose the text editor.
== Initial code in the Python block ==
Here is the pre-populated code:
<pre>
"""
Embedded Python Blocks:


When you update the Python code, as long as there are no errors the block will automatically update. If you are adding new code and it seems like nothing is changing, there is probably an error in your code.
Each time this file is saved, GRC will instantiate the first class it finds
to get ports and parameters of your block. The arguments to __init__  will
be the parameters. All of them are required to have default values!
"""


Note that every parameter needs a default argument, due to the way your code gets parsed, and if you have a vector length equal to a variable, the default value must be "hardcoded".
import numpy as np
from gnuradio import gr
 
 
class blk(gr.sync_block):  # other base classes are basic_block, decim_block, interp_block
    """Embedded Python Block example - a simple multiply const"""
 
    def __init__(self, example_param=1.0):  # only default arguments here
        """arguments to this function show up as parameters in GRC"""
        gr.sync_block.__init__(
            self,
            name='Embedded Python Block',  # will show up in GRC
            in_sig=[np.complex64],
            out_sig=[np.complex64]
        )
        # if an attribute with the same name as a parameter is found,
        # a callback is registered (properties work, too).
        self.example_param = example_param
 
    def work(self, input_items, output_items):
        """example: multiply with constant"""
        output_items[0][:] = input_items[0] * self.example_param
        return len(output_items[0])
</pre>


== Parameters ==
== Parameters ==
You decide the parameters of your custom block =)
On line 16 of the code above <pre>def __init__(self, example_param=1.0):  # only default arguments here</pre> every parameter needs a default value. If you have a vector length equal to a variable, the default value must be "hardcoded".  If you don't have any parameters, change that line of code to <pre>def __init__(self):</pre>
 
== User notes ==
 
* To revise the Python code:
** right click on the Embedded Python block
** select <q>Properties</q>
** select <q>Open in Editor</q>
** select <q>Use Default</q> or <q>Choose Editor</q>
** For some platforms the <q>Use Default</q> button may do nothing, in which case you have to choose the text editor manually.
** if you select <q>Choose Editor</q>, the /usr/bin folder will open for you to pick one.
<p><b>Important:</b> It is highly recommended that any flowgraph using an Embedded Python Block be placed in a separate directory (folder); particularly so if more than one Embedded Python Block is used. This is because the generation process creates a file <q>epy_block_0.py</q> from that flowgraph. If you generate a different flowgraph in the same directory, its Embedded Python Block will overwrite the file.</p>
<p><b>Warning:</b> To make changes to the Python code, you <u>must</u> follow the steps above. If you edit the <q>epy_block_0.py</q> file directly and then generate the flowgraph again, your changes will be wiped out! (The most recent edited code is actually stored in the .grc file.)</p>


== Example Flowgraph ==
== Example Flowgraph ==


Insert description of flowgraph here, then show a screenshot of the flowgraph and the output if there is an interesting GUI.  Currently we have no standard method of uploading the actual flowgraph to the wiki or git repo, unfortunately.  The plan is to have an example flowgraph showing how the block might be used, for every block, and the flowgraphs will live in the git repo.
Insert description of flowgraph here, then show a screenshot of the flowgraph and the output if there is an interesting GUI.  Currently we have no standard method of uploading the actual flowgraph to the wiki or git repo, unfortunately.  The plan is to have an example flowgraph showing how the block might be used, for every block, and the flowgraphs will live in the git repo.

Revision as of 18:48, 17 October 2019

Allows you to create a new (custom) block in Python without needing to make and install an Out of Tree Module (OOT). When you add the block to your flowgraph, the pre-populated code simply takes the input stream and multiplies it by a constant. Note that the structure of this Python block matches the structure of an Out of Tree Module (OOT) Python block. It's essentially a Python OOT block built into a grc flowgraph.

Initial code in the Python block

Here is the pre-populated code:

"""
Embedded Python Blocks:

Each time this file is saved, GRC will instantiate the first class it finds
to get ports and parameters of your block. The arguments to __init__  will
be the parameters. All of them are required to have default values!
"""

import numpy as np
from gnuradio import gr


class blk(gr.sync_block):  # other base classes are basic_block, decim_block, interp_block
    """Embedded Python Block example - a simple multiply const"""

    def __init__(self, example_param=1.0):  # only default arguments here
        """arguments to this function show up as parameters in GRC"""
        gr.sync_block.__init__(
            self,
            name='Embedded Python Block',   # will show up in GRC
            in_sig=[np.complex64],
            out_sig=[np.complex64]
        )
        # if an attribute with the same name as a parameter is found,
        # a callback is registered (properties work, too).
        self.example_param = example_param

    def work(self, input_items, output_items):
        """example: multiply with constant"""
        output_items[0][:] = input_items[0] * self.example_param
        return len(output_items[0])

Parameters

On line 16 of the code above

def __init__(self, example_param=1.0):  # only default arguments here

every parameter needs a default value. If you have a vector length equal to a variable, the default value must be "hardcoded". If you don't have any parameters, change that line of code to

def __init__(self):

User notes

  • To revise the Python code:
    • right click on the Embedded Python block
    • select Properties
    • select Open in Editor
    • select Use Default or Choose Editor
    • For some platforms the Use Default button may do nothing, in which case you have to choose the text editor manually.
    • if you select Choose Editor, the /usr/bin folder will open for you to pick one.

Important: It is highly recommended that any flowgraph using an Embedded Python Block be placed in a separate directory (folder); particularly so if more than one Embedded Python Block is used. This is because the generation process creates a file epy_block_0.py from that flowgraph. If you generate a different flowgraph in the same directory, its Embedded Python Block will overwrite the file.

Warning: To make changes to the Python code, you must follow the steps above. If you edit the epy_block_0.py file directly and then generate the flowgraph again, your changes will be wiped out! (The most recent edited code is actually stored in the .grc file.)

Example Flowgraph

Insert description of flowgraph here, then show a screenshot of the flowgraph and the output if there is an interesting GUI. Currently we have no standard method of uploading the actual flowgraph to the wiki or git repo, unfortunately. The plan is to have an example flowgraph showing how the block might be used, for every block, and the flowgraphs will live in the git repo.