XML GRC

Creating the XML Block Definition

The best way to learn how to create the xml file is to learn by example. Look at the .grc file of a few blocks packaged with GNU Radio as examples. Essentially, all block definitions are structured as follows:

<?xml version="1.0"?>
<block>
  <name>My Block Name</name>
  <key>my_package_my_block_ff</key>
  <category>Filters</category>
  <import>from gnuradio import my_package</import>
  <make>my_package.my_block_ff($param1, $param2)</make>
  <callback>set_param1($param1)</callback>


  <param>
    <name>Parameter 1</name>
    <key>param1</key>
    <type>real</type>
  <param>


  <param>
    <name>Parameter 2</name>
    <key>param2</key>
    <value>1</value>
    <type>int</type>
  <param>


  <sink>
    <name>in</name>
    <type>float</name>
  </sink>

    
  <source>
    <name>out</name>
    <type>float</type>
  </source>
    

  <source>
    <name>out</name>
    <type>float</type>
  </source>
</block>

• The example above will make a block with 2 parameters, 1 input, and 2 outputs.
• The ordering of the tags is important, if tags are not ordered properly, the block will fail validation. For now just try to follow the ordering other blocks use (e.g. params then sources/sinks)
• The name tags dictate the label text for the block, parameters, and ports.
• The key tags are unique identifiers, they may not contain spaces. The block key must be globally unique among all blocks in GRC. The parameter keys must be unique only within the block.
• The category tag is a unix-style path that represents the location of the block inside the block selection window. The path can be a new category (Custom), or represent a sub-category (Filters/Custom). To put a block into the root category, just use a single slash (/) for the root path.
• The import tag (there can be multiple) must be a valid python import statement to the module containing your block.
• The make tag contains the code necessary to construct your block. This code is essentially a cheetah template nested inside an xml tag. Upon code generation, the template performs a text substitution on the "$" parameters. For more advanced capabilities, see the cheetah template documentation.
• The callback tag registers a set-method from your custom block. Once the set-method is registered, the set-method can be called at runtime when a variable is changed. There can be any number of callback tags, one for each set-method of your block. Or no callback tags if this is not applicable.
• For the param tags, the commonly used values for the type tags are: complex, real, int, complex_vector, real_vector, int_vector, string, and raw. The raw type allows any value to be used without performing type checking. The real type should be used for single and double precision floating point numbers. The int type should be used for longs, ints, shorts, and chars.
• The hide tag controls how the parameter is displayed in GRC. It's either none, part (show in the prop dialog, not in the block on the canvas) or all.
• The sink tag represents an input port, and the source tag represents an output port. The allowed values for the type tags are: complex, float, int, short, and byte. For ports with a vector length, specify a vlen tag after the type tag.
• In case you want to create a block definition as done for the FECAPI, the key tag has to start with variable_ in order to work correctly in GRC.

Some Example Definitions

• Simple Example: "Complex to Real" source:gr-blocks/grc/blocks_complex_to_real.xml
• Multiple Callbacks: "Costas Loop" source:gr-digital/grc/digital_costas_loop_cc.xml
• Vlen Example: "Throttle" source:gr-digital/grc/blocks_throttle.xml
• Advanced Make: "FFT" source:gr-fft/grc/fft_fft_vxx.xml