XML GRC: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
(Created page with "=== Creating the XML Block Definition === The best way to learn how to create the xml file is to learn by example. See the block definitions (source:grc/blocks) packaged with...")
 
(Reinserted XML tags)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== Creating the XML Block Definition ===
=== Creating the XML Block Definition ===


The best way to learn how to create the xml file is to learn by example. See the block definitions (source:grc/blocks) packaged with GRC, and read through a few files. Essentially, all block definitions are structured as follows:
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:


<pre>
<pre>
    My Block Name
&lt;?xml version="1.0"?&gt;
    my_package_my_block_ff
&lt;block&gt;
        Filters
  &lt;name&gt;My Block Name&lt;/name&gt;
    from gnuradio import my_package
  &lt;key&gt;my_package_my_block_ff&lt;/key&gt;
    my_package.my_block_ff($param1, $param2)
  &lt;category&gt;Filters&lt;/category&gt;
        set_param1($param1)
  &lt;import&gt;from gnuradio import my_package&lt;/import&gt;
  &lt;make&gt;my_package.my_block_ff($param1, $param2)&lt;/make&gt;
  &lt;callback&gt;set_param1($param1)&lt;/callback&gt;
 
 
  &lt;param&gt;
    &lt;name&gt;Parameter 1&lt;/name&gt;
    &lt;key&gt;param1&lt;/key&gt;
    &lt;type&gt;real&lt;/type&gt;
  &lt;param&gt;
 
 
  &lt;param&gt;
    &lt;name&gt;Parameter 2&lt;/name&gt;
    &lt;key&gt;param2&lt;/key&gt;
    &lt;value&gt;1&lt;/value&gt;
    &lt;type&gt;int&lt;/type&gt;
  &lt;param&gt;
 
 
  &lt;sink&gt;
    &lt;name&gt;in&lt;/name&gt;
    &lt;type&gt;float&lt;/name&gt;
  &lt;/sink&gt;
 
      
      
        Parameter 1
  &lt;source&gt;
        param1
    &lt;name&gt;out&lt;/name&gt;
        real
    &lt;type&gt;float&lt;/type&gt;
  &lt;/source&gt;
      
      
   
 
        Parameter 2
  &lt;source&gt;
        param2
     &lt;name&gt;out&lt;/name&gt;
        1
     &lt;type&gt;float&lt;/type&gt;
        int
  &lt;/source&gt;
      
&lt;/block&gt;
      
        in
        float
                part
   
   
        out
        float
   
       
        out
        float
</pre>
</pre>


* The example above will make a block with 2 parameters, 1 input, and 2 outputs.
* 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. See [https://github.com/gnuradio/gnuradio/blob/master/grc/core/block.dtd block.dtd] for specifics.
* 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 '''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 '''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.
Line 44: Line 57:
* 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.  
* 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.
* 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 '''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.
* 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.
* 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.
Line 50: Line 63:
=== Some Example Definitions ===
=== Some Example Definitions ===


* Simple Example: "Complex to Real" source:[https://github.com/gnuradio/gnuradio/blob/master/gr-blocks/grc/blocks_complex_to_real.xml|gr-blocks/grc/blocks_complex_to_real.xml]
* Simple Example: "Complex to Real" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-blocks/grc/blocks_complex_to_real.xml gr-blocks/grc/blocks_complex_to_real.xml]
* Multiple Callbacks: "Costas Loop" source:[https://github.com/gnuradio/gnuradio/blob/master/gr-digital/grc/digital_costas_loop_cc.xml|gr-digital/grc/digital_costas_loop_cc.xml]
* Multiple Callbacks: "Costas Loop" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-digital/grc/digital_costas_loop_cc.xml gr-digital/grc/digital_costas_loop_cc.xml]
* Vlen Example: "Throttle" source:[https://github.com/gnuradio/gnuradio/blob/master/gr-digital/grc/blocks_throttle.xml|gr-digital/grc/blocks_throttle.xml]
* Vlen Example: "Throttle" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-blocks/grc/blocks_throttle.xml gr-digital/grc/blocks_throttle.xml]
* Advanced Make: "FFT" source:[https://github.com/gnuradio/gnuradio/blob/master/gr-fft/grc/fft_fft_vxx.xml|gr-fft/grc/fft_fft_vxx.xml]
* Advanced Make: "FFT" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-fft/grc/fft_fft_vxx.xml gr-fft/grc/fft_fft_vxx.xml]

Latest revision as of 10:53, 14 May 2020

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