YAML GRC

From GNU Radio
Revision as of 20:19, 24 July 2018 by Haakonsv (talk | contribs) (Added info about input ports in YAML blocks)
Jump to: navigation, search

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.

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”)

Block Descriptions

The content of the block descriptions is still the same, although it has been shuffled around a bit. The parts are elaborated below, in the order they should appear in the files.

ID

1 id: blocks_multiply_const_vxx
2 label: Multiply Const
3 
4 parameters:
5 -   id: type
6     label: IO Type
7 (...)

The ID is unique for each block and is used to identify it.

Label

1 id: blocks_multiply_const_vxx
2 label: Multiply Const
3 
4 parameters:
5 -   id: type
6     label: IO Type
7 (...)

The label is simply the human-readable name of the block, and will be visible from within GRC. It will not appear in the generated code.

Flags (optional)

1 id: blocks_throttle
2 label: Throttle
3 flags: throttle
4 
5 parameters:
6 -   id: type
7     label: Type
8 (...)

The flags indicate special attributes of the block. The only current example of this is the throttle flag, which is used in the Throttle and hardware blocks. For more information on throttling, see the Guided Tutorial: [1]

Parameters

Inputs (optional)

 1 id: qtgui_freq_sink_x
 2 (...)
 3     default: '1.0'
 4     hide: ${ ('part' if int(nconnections) >= 10 else 'all') }
 5 
 6 inputs:
 7 -   domain: stream
 8     dtype: ${ type.t }
 9     multiplicity: ${ (0 if (type == 'msg_complex' or type == 'msg_float') else nconnections) }
10     optional: true
11 -   domain: message
12     id: freq
13     optional: true
14     hide: ${ showports }
15 
16 outputs:
17 -   domain: message
18 (...)

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[2] 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.

Outputs (optional)

Asserts (optional)

 1 (...)    
 2     dtype: ${ type }
 3     vlen: ${ vlen }
 4 
 5 asserts:
 6 - ${ vlen > 0 }
 7 
 8 templates:
 9     imports: from gnuradio import blocks
10     make: blocks.throttle(${type.size}*${vlen}, ${samples_per_second},${ignoretag})
11 (...)

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

Imports

Make

Callbacks

File Format

Others

Variable Make

Variable Value

Block Tree Files