Field Guide · concept

Also known as: OOT module, out-of-tree module, gr-module

An out-of-tree module (OOT) is a custom GNU Radio component built and installed outside GNU Radio’s own source tree.1 It is the sanctioned way to add your own blocks without forking or modifying GNU Radio itself: you create a small package — conventionally named gr-<something> — that compiles against the installed GNU Radio libraries and registers new blocks into the runtime and into GNU Radio Companion. Nearly every third-party GNU Radio capability, from decoders to hardware drivers, ships as an OOT module.

GNU Radio core runtime + blocks gr-mymod (OOT) your blocks + CMake + bindings links against / registers into
An OOT module is a separate package that links against installed GNU Radio and registers new blocks into the shared runtime and block library.

How it works

An OOT module is generated and maintained with gr_modtool, GNU Radio’s scaffolding utility. gr_modtool newmod <name> creates the package skeleton; gr_modtool add <block> generates the source, header, QA test, GRC block definition (a YAML file), and Python binding stubs for a new block. You fill in the block’s work()/general_work(), then build and install with CMake. After installation the block is indistinguishable from a core block: it is importable from Python, usable from C++, and shows up in the GRC palette.

The package is deliberately self-contained so it can version and distribute independently of GNU Radio releases. It carries:

  • Block implementations (C++ and/or Python) plus their public headers.
  • Bindings that expose C++ blocks to Python (pybind11 in modern GNU Radio).
  • GRC block YAML so the block appears with parameters and ports in the GUI.
  • A CMake build that finds the installed GNU Radio and links against it.
  • QA / unit tests, run against captured data with no radio hardware needed.

Because it links against GNU Radio’s stable ABI rather than editing it, an OOT module rides along with the installed framework: upgrade GNU Radio and, if the API is compatible, rebuild the module against it.

In practice

OOT modules are the unit of sharing in the GNU Radio ecosystem. Community packages — gr-osmosdr for hardware access, and many protocol decoders — are OOT modules you install alongside core. A module can bundle a mix of primitive blocks and hierarchical blocks, so a project can ship both low-level DSP and ready-assembled front ends together. Convention names the package gr-<name> and the Python namespace to match, which is why installed third-party GNU Radio content is easy to spot.

Relevance to SDR

The OOT pattern is what makes GNU Radio extensible without central gatekeeping: anyone can add a demodulator or a device driver as a clean, versioned, testable package rather than patching the framework. For SDR developers it is the concrete answer to “how do I add my own processing to GNU Radio” — scaffold with gr_modtool, implement the block, build, install, done — and it enforces good habits (isolated builds, bindings, and hardware-free QA tests) along the way.

GopherTrunk has no GNU Radio dependency, so it neither is nor consumes OOT modules — its blocks are Go packages compiled into a single static binary rather than gr-modules linked against a shared GNU Radio install. The relevant contrast is architectural: the OOT model plugs new DSP into an external framework’s runtime and block registry, whereas GopherTrunk builds its DSP directly in Go and depends on nothing external at run time. Knowing the OOT workflow is still essential for anyone comparing GopherTrunk with the mainstream GNU Radio decoders it competes with, and for reusing the wider ecosystem’s blocks outside of Go.

Sources

  1. Out Of Tree Modules — GNU Radio Wiki, on creating gr- modules with gr_modtool, CMake builds, bindings, and GRC integration. ↩

See also