Soapy

This functionality is available as an in-tree module in GNU Radio versions 3.10 and higher (TBD also in a future 3.9 release).

SoapySDR

SoapySDR is the driver subsystem in the Pothosware ecosystem. It provides a specification for drivers, and a management layer required to use them. Individual drivers are dynamically linked, so they can be maintained independently of the SoapySDR user (GNU Radio in this case).

gr-soapy

The gr-soapy module wraps SoapySDR, allowing it to be used in GNU Radio. The original version was developed by Libre Space Foundation. Note that the in-tree version provided with GNU Radio performs the same function as the Libre Space version, but the code has been revamped and is not API compatible. It should be straightforward to port existing applications.

Architecture

User Application

Your Python or C++ application, or one generated by GRC, uses the gr-soapy module built into GNU Radio. It specifies the name of the driver and a set of driver, stream and other option parameters. At runtime, some parameters (e.g., frequency, gains) can be adjusted via setters.

GNU Radio gr-soapy

The SoapySDR "wrapper" module built into GNU Radio, providing the soapy::source and soapy::sink blocks. These blocks are usable from Python or C++. If a recent enough version of SoapySDR is available on the build system when GNU Radio is configured, this module will be included by default.

SoapySDR

A specification and driver management layer, not part of GNU Radio. This package is SoapySDR-devel on RPM-based systems, or libsoapysdr-dev on DEB-based systems. It is also easy to build and install manually, and has a PyBOMBS recipe. See section on versions below.

SoapySDR Driver

Individual SoapySDR drivers, not part of GNU Radio, are dynamically loaded modules. There is one module for each type of hardware. These modules are typically built atop a vendor-supplied hardware support library. For example, SoapyRTLSDR. These modules are available from distro repos, or can be built manually. Many have PyBOMBS recipes.

Hardware Support Library

A vendor or other developer provides the low-level package required to talk directly to hardware. For example, the rtl-sdr library. These libraries are usually in distro or vendor repos. Many have PyBOMBS recipes.

GRC YAML Blocks

Deprecation Warning: The generic Soapy Source and Soapy Sink blocks will likely be removed before 3.10.0 and 3.9.2.

This stack is hardware-independent, from the GNU Radio point of view. Working with gr-soapy in GRC requires Source and Sink blocks to be specified in YAML format. For example the rtlsdr source is specified in soapy_rtlsdr_source.block.yml.

A set of simplified, single-channel source and sink GRC yml blocks is provided. These should be useful for many users.

Sources: AirspyHF, BladeRF, HackRF, LimeSDR, PLUTO, RTLSDR, SDRPlay Sinks: BladeRF, HackRF, LimeSDR, PLUTO

While there is a UHD driver for SoapySDR, GNU Radio's built-in gr-uhd is recommended and well maintained.

All of these drivers have PyBOMBS recipes. LimeSDR support is part of LimeSuite.

Generic source and sink GRC yml blocks from the original implementation are provided. These are a bit more complicated to use, but give access to additional parameters. It is likely that these GRC yml blocks will be removed in the future, as the device-specific blocks are fleshed out.

Users may create their own GRC yml blocks (use a different name!) and put them in ~/.grc_gnuradio. This allows for the addition of functionality or new driver modules. Note that not all of the SoapySDR API has been made available.

Versions

Currently, SoapySDR 0.7.2 or higher is required. Note that Ubuntu 18.04 and Debian 10 provide an older version. Recent Ubuntu and Fedora releases provide a new enough version.

SoapySDR driver modules will be loaded only if the ABI version number (e.g., 0.7) matches. If GNU Radio is built against SoapySDR 0.7.2, any module built against 0.7.x will load. If GNU Radio is built against SoapySDR 0.8.0, then any module built against 0.8.x will load.

Debugging

The GNU Radio gr-soapy module depends on a working installation of SoapySDR and drivers. If something is not working, verify the following first:

• Use SoapySDRUtil --info to see info on the SoapySDR installation. Version should match the one used to build GNU Radio. Driver modules (shared objects) and the associated factories (device types) are shown.

• SoapySDRUtil --find will look for hardware matching the available drivers. The keywords shown can be used as device args in case there are multiple SDRs of the same type on the system.

• SoapySDRProbe --probe=driver=rtlsdr, or a similar command for other drivers, returns detailed information about a device. Valid sample rates, bandwidths, and gains are shown. Note that the GRC blocks may not use all of the features shown. For example, simple versions of GRC blocks may use single frequency or gain values instead of allowing control over specific tuning or gain elements.

• Make sure that the SoapySDR device can be opened for use, using SoapySDRUtil --make=driver=rtlsdr. Solve any permission problems, e.g. with USB.

• Check that gnuradio-config-info --enabled-components includes gr-soapy.

gr-osmosdr

gr-osmosdr is a popular SDR abstraction layer, so why not bring that module in-tree?

This has more to do with GNU Radio maintainability than it does with any technical capability. In the stack described above, SoapySDR modules are tightly coupled to hardware support libraries, but are runtime discoverable and loadable with respect to gr-soapy. In gr-osmosdr, the equivalent modules are built-in. Bringing gr-osmosdr in-tree would place a lot of hardware knowledge in the GNU Radio code base, adding additional maintenance work and making all of the hardware support libraries direct dependencies. We recommend both gr-soapy and gr-osmosdr, and users can chose the driver framework that best meets their needs.