Editing YAML GRC

Jump to: navigation, search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 1: Line 1:
[[Category:3.8]]
+
Starting with release 3.8, XML replaces YAML as the file format for GNU Radio Companion. This is triggered by switching from Cheetah to Mako as the templating engine, since Cheetah does not support Python 3. Specifically, this will impact .grc files, block descriptions and block tree files. This article won’t focus on the .grc files, because they aren’t meant for manual editing.
Starting with release 3.8, YAML replaces XML as the file format for GNU Radio Companion. This is triggered by switching from Cheetah to Mako as the templating engine, since Cheetah does not support Python 3. Specifically, this will impact .grc files, block descriptions and block tree files. This article won’t focus on the .grc files, because they aren’t meant for manual editing.
 
  
 
The most notable change is of course the absence of XML’s angle brackets in favour of YAML’s colon-separated keys and values, and the change in file names for blocks. The latter is important for GRC to recognise the file. Namely, the “.xml” ending has been replaced with “.block.yml” for block descriptions and the underscore in block tree files has been replaced with a dot. (For example, “qtgui_tree.xml” becomes “qtgui.tree.yml”)
 
The most notable change is of course the absence of XML’s angle brackets in favour of YAML’s colon-separated keys and values, and the change in file names for blocks. The latter is important for GRC to recognise the file. Namely, the “.xml” ending has been replaced with “.block.yml” for block descriptions and the underscore in block tree files has been replaced with a dot. (For example, “qtgui_tree.xml” becomes “qtgui.tree.yml”)
Line 10: Line 9:
 
=== ID ===
 
=== ID ===
  
<syntaxhighlight lang="yaml" line="line" highlight="1">
+
<syntaxhighlight lang="python" line="line" highlight="1">
 
id: blocks_multiply_const_vxx
 
id: blocks_multiply_const_vxx
 
label: Multiply Const
 
label: Multiply Const
Line 16: Line 15:
 
parameters:
 
parameters:
 
-  id: type
 
-  id: type
    label: IO Type
+
label: IO Type
 
(...)
 
(...)
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 24: Line 23:
 
=== Label ===
 
=== Label ===
  
<syntaxhighlight lang="yaml" line="line" highlight="2">
+
<syntaxhighlight lang="python" line="line" highlight="2">
 
id: blocks_multiply_const_vxx
 
id: blocks_multiply_const_vxx
 
label: Multiply Const
 
label: Multiply Const
Line 30: Line 29:
 
parameters:
 
parameters:
 
-  id: type
 
-  id: type
    label: IO Type
+
label: IO Type
 
(...)
 
(...)
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 38: Line 37:
 
=== Flags (optional) ===
 
=== Flags (optional) ===
  
<syntaxhighlight lang="yaml" line="line" highlight="3">
+
<syntaxhighlight lang="python" line="line" highlight="3">
 
id: blocks_throttle
 
id: blocks_throttle
 
label: Throttle
 
label: Throttle
Line 45: Line 44:
 
parameters:
 
parameters:
 
-  id: type
 
-  id: type
    label: Type
+
label: Type
 
(...)
 
(...)
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 53: Line 52:
 
=== Parameters ===
 
=== Parameters ===
  
<syntaxhighlight lang="yaml" line="line" >
+
=== Inputs ===
parameters:
 
-  id: tr_chan
 
    label: Trigger Channel
 
    category: Trigger
 
    dtype: int
 
    default: '0'
 
    hide: part
 
-  id: tr_type
 
    label: Trigger Type
 
    category: Trigger
 
    dtype: enum
 
    options: [TRIGGER_FREE, TRIGGER_AUTO]
 
    option_labels: ["Free", "Auto"]
 
</syntaxhighlight>
 
 
 
This part describes the parameters to display to the user. A number of keywords is used there:
 
; id
 
: A unique name for the parameter, it is not displayed to the user but can be used to reference the parameter inside this file: ${<id>}
 
; label
 
: Human readable name to display to the user.
 
; dtype
 
: [[Datatypes|Type]] of the data handled by the parameter
 
: This can have many values
 
:; Numbers
 
:: raw, complex, real, float, int, hex, bool
 
:; Vectors of numbers
 
:: complex_vector, real_vector, float_vector, int_vector
 
:; Strings
 
:: string, file_open, file_save, _multiline _mutiline_python_external
 
:; Other special types
 
:: gui_hint, import, id, stream_id, name and enum
 
 
 
; default
 
: A default value for the parameter
 
; category
 
: Used to organise a large number of parameters. If set, a new tab will be created and named as the value of the keyword with the parameter inside.
 
; hide
 
: If the value is part, the parameter will not be shown on the block representation inside GRC.
 
: If it's all, it will not be shown at all, even inside the properties window.
 
: If it's none, it will never be hidden.
 
; base_key
 
: Inherit properties from another parameter. The value given is the id of that parameter.
 
 
 
=== Inputs and Outputs (optional) ===
 
 
 
<syntaxhighlight lang="yaml" line="line" highlight="6-14">
 
id: qtgui_freq_sink_x
 
(...)
 
    default: '1.0'
 
    hide: ${ ('part' if int(nconnections) >= 10 else 'all') }
 
  
inputs:
+
=== Outputs ===
-  domain: stream
 
    dtype: ${ type.t }
 
    multiplicity: ${ (0 if (type == 'msg_complex' or type == 'msg_float') else nconnections) }
 
    optional: true
 
-  domain: message
 
    id: freq
 
    optional: true
 
    hide: ${ showports }
 
 
 
outputs:
 
-  domain: message
 
(...)
 
</syntaxhighlight>
 
 
 
This describes the input ports. '''domain''' can be either '''stream''' or '''message'''. Stream ports need a type, which usually is specified as a parameter. This is true for our example, the type is specified in '''type.t'''. The '''multiplicity''' tells us how many "copies" of this port we want. (Yes, this can be zero!) Finally, the '''optional''' flag tells us whether this port ''must'' be connected or not. (GRC won't generate the flowgraph if a non-optional port isn't connected)
 
 
 
Message ports[https://wiki.gnuradio.org/index.php/Guided_Tutorial_Programming_Topics#5.3_Message_Passing] don't have a specified type here, but they have IDs. This message port can also be hidden, using the "Show message ports" option in the parameters.
 
 
 
 
 
The output ports work similarly.
 
  
 
=== Asserts (optional) ===
 
=== Asserts (optional) ===
  
<syntaxhighlight lang="yaml" line="line" highlight="6-7">
+
<syntaxhighlight lang="python" line="line" highlight="5-6">
id: blocks_throttle
 
 
(...)     
 
(...)     
 
     dtype: ${ type }
 
     dtype: ${ type }
Line 144: Line 72:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Asserts (previously known as "checks" for the XML blocks) are expressions that ''need'' to be true, otherwise GRC won't let you generate the flowgraph. Asserts are Python statements that should eval() to 'True' when correct, wrapped with Mako template designators '${' and '}'.
+
Asserts (previously known as "checks" for the XML blocks) are expressions that ''need'' to be true, otherwise GRC won't let you generate the flowgraph.
  
 
=== Templates ===
 
=== Templates ===
  
<syntaxhighlight lang="yaml" line="line" highlight="5-12">
+
==== Imports ====
id: blocks_message_strobe_random
 
(...)
 
    optional: true
 
  
templates:
+
==== Make ====
    imports: |-
 
        from gnuradio import blocks
 
        import pmt
 
    make: blocks.message_strobe_random(${msg}, ${dist}, ${mean}, ${std})
 
    callbacks:
 
    - set_msg(${msg})
 
    - set_dist(${dist})
 
(...)
 
</syntaxhighlight>
 
  
The templates describe the code that is created when GRC generates the flowgraph. This part consists of the imports, the make/initialization statements and the callbacks. The values of these keys often happen to span over multiple lines, in which case you're likely to see the "|-" symbols. This is YAML syntax for a literal block scalar[http://yaml.org/spec/current.html#literal%20style/syntax] and the hyphen means that the line break at the end is omitted.
+
==== Callbacks ====
 
 
 
 
Your block probably utilizes parts of GNU Radio or other modules that need to be imported. These are specified as ''imports''.
 
 
 
 
 
''make'' holds the initialization code, and often depends on several of the parameters. Some of the more involved blocks may also use the "%" symbol, denoting the use of a YAML directive[http://yaml.org/spec/current.html#directive/syntax]. This can occur both in ''imports'' and ''make''. The snippet below may be helpful:
 
 
 
<syntaxhighlight lang="yaml" line="line" highlight="7-11">
 
id: rational_resampler_xxx
 
(...)
 
    make: |-
 
        filter.rational_resampler_${type}(
 
            interpolation=${interp},
 
            decimation=${decim},
 
        % if taps:
 
            taps=${taps},
 
        % else:
 
            taps=None,
 
        % endif
 
</syntaxhighlight>
 
 
 
Please note that the "${}" is not valid syntax in a directive.
 
 
 
=== Documentation ===
 
 
 
<syntaxhighlight lang="yaml" line="line" highlight="3-4">
 
id: variable_rrc_filter_taps
 
(...)
 
documentation: |-
 
    This is a convenience wrapper for calling firdes.root_raised_cosine(...).
 
 
 
file_format: 1
 
</syntaxhighlight>
 
 
 
''documentation'' simply contains information about the block. This information is displayed in the block's Documentation tab in GRC.
 
  
 
=== File Format ===
 
=== File Format ===
Line 210: Line 91:
  
 
== Block Tree Files ==
 
== Block Tree Files ==
 
The block tree files are fairly straightforward, and tells GRC how to divide the block tree into categories. The following example snippet from gr-digital (which is part of core GNU Radio) describes two categories, ''Coding'' and ''Equalizers''. The blocks are specified using their ''id''s, which should equal their file names without ".block.yml".
 
 
<syntaxhighlight lang="yaml" line="line" >
 
'[Core]':
 
- Coding:
 
  - digital_additive_scrambler_bb
 
  - digital_descrambler_bb
 
  - digital_scrambler_bb
 
- Equalizers:
 
  - digital_cma_equalizer_cc
 
  - digital_lms_dd_equalizer_cc
 
(...)
 
</syntaxhighlight>
 

Please note that all contributions to GNU Radio are considered to be released under the Creative Commons Attribution-ShareAlike (see GNU Radio:Copyrights for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel | Editing help (opens in new window)