YAML GRC

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

id: blocks_multiply_const_vxx
label: Multiply Const

parameters:
-   id: type
    label: IO Type
(...)

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

Label

id: blocks_multiply_const_vxx
label: Multiply Const

parameters:
-   id: type
    label: IO Type
(...)

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)

id: blocks_throttle
label: Throttle
flags: throttle

parameters:
-   id: type
    label: Type
(...)

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]

Inputs (optional)

id: qtgui_freq_sink_x
(...)
    default: '1.0'
    hide: ${ ('part' if int(nconnections) >= 10 else 'all') }

inputs:
-   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
(...)

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.

Asserts (optional)

(...)    
    dtype: ${ type }
    vlen: ${ vlen }

asserts:
- ${ vlen > 0 }

templates:
    imports: from gnuradio import blocks
    make: blocks.throttle(${type.size}*${vlen}, ${samples_per_second},${ignoretag})
(...)

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.