Field Guide · technology

Also known as: GNU Radio Companion, GRC

GNU Radio Companion (GRC) is the graphical flowgraph editor bundled with GNU Radio: a drag-and-drop canvas on which an engineer places signal-processing blocks, connects their inputs and outputs, and sets each block’s parameters, after which GRC generates a complete, runnable Python program.1 It turns building a software-defined radio from a coding exercise into a wiring exercise, which is why it is the entry point most people use to learn GNU Radio.

GRC canvas (.grc) source throttle filter sink generated top_block.py generate wire blocks visually → GRC writes Python you can run or edit
GRC compiles a visual flowgraph into a Python top-block program: the canvas is the design, and the generated code is what actually runs.

How it works

GRC reads block definitions from GNU Radio’s installed component libraries and lists them in a searchable tree. Dragging a block onto the canvas creates an instance whose parameters — sample rate, filter taps, gain, frequency — are edited in a properties dialog. Ports are typed and colored by sample format (complex, float, byte, message), and GRC refuses to connect mismatched ports, catching a whole class of errors before the program ever runs. Variables and GUI controls (sliders, entry boxes, QT range widgets) can be dropped in too, so a parameter like center frequency becomes a live knob.

The document itself is a .grc file — a YAML description of blocks, parameters, and connections. When you press Generate, GRC’s code generator (grcc) walks that graph and emits a Python module: a top_block class that instantiates each block, calls self.connect(...) for every wire, and exposes the GUI. Running it simply executes the GNU Radio runtime with that flowgraph. Two consequences follow:

  • The GUI is not a black box. The generated Python is ordinary, readable code you can open, extend, or embed in a larger program — GRC is a starting point, not a cage.
  • Custom logic still fits. An Embedded Python Block lets you write a small block inline on the canvas, and anything the block tree lacks can be added as an out-of-tree module and it appears alongside the built-ins.

Reusable sub-designs are packaged as hierarchical blocks: a flowgraph exported as a hier block shows up as a single block in other flowgraphs, so complex receivers stay legible.

Relevance to SDR

GRC is where most SDR practitioners first assemble a working radio, and it remains the fastest way to prototype one. Tuning a dongle, filtering a channel, demodulating FM or a digital mode, and piping audio or bits to a sink is a few minutes of wiring rather than an afternoon of code. Because it sources from gr-osmosdr and SoapySDR, the same flowgraph drives an RTL-SDR, a HackRF, or a USRP. Teaching material, conference demos, and the first cut of many decoders all begin as .grc files, and researchers routinely export a proven flowgraph to Python and then harden it into a standalone tool.

GopherTrunk does not use GRC and produces no flowgraphs — it is a purpose-built, pure-Go trunking scanner with its own hand-written DSP chain, shipped as a single static binary with no GNU Radio runtime. GRC is nonetheless a natural bench companion for GopherTrunk work: it is an excellent scratchpad for inspecting a signal, capturing IQ to a file, or prototyping a demodulator idea visually before that idea is reimplemented in Go for GopherTrunk’s decode path.

Sources

  1. GNU Radio Companion — GNU Radio project wiki, documenting the flowgraph canvas, block/port typing, the .grc document, Python code generation, embedded blocks, and hierarchical blocks. ↩

See also