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, discovered, and loaded, 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 original all-in-one GRC Soapy Source and Soapy Sink YAML 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. In the underlying C++ code, there are only generic source and sink blocks. From the GRC (GUI/code generator) point of view, Source and Sink blocks are specified in YAML format. For example the rtlsdr source is specified in soapy_rtlsdr_source.block.yml. These GRC YAML blocks contain the logic needed to operate specific SDR hardware.

A set of simple, 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. SoapySDRPlay requires prior manual installation of the vendor service (API v3).

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.

Custom Source and Custom Sink GRC yml blocks allow the user to use any SoapySDR driver available on the system. These blocks support one- or two-channel modes.

Users may create their own or modified GRC yml blocks (use a different name!) and put them in ~/.grc_gnuradio. This allows for the addition of functionality or new driver modules. The yml block files are small, and fairly easy to write.

Messages

Source and Sink blocks accept messages on the cmd port. Messages are in PMT dict format, and contain the following keys:

• chan: specifies the channel to which the message applies. Omit to affect all channels or if there is only one channel (common case).
• freq: tune frequency (double)
• gain: overall gain setting (float)
• antenna: antenna name (string)
• rate: sample rate (double)
• bandwidth: filter bandwidth (double)

Multiple keys may be present in one message. Behavior is somewhat dependent on the driver.

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. A change in API version may not result in a change in ABI version. In the 0.7.x series, the ABI version was always 0.7. Be aware, however, ABI versions on the v0.8 development branch have changed more frequently. For instance ABIs 0.8, 0.8-1 and 0.8-2 are not compatible.

If building SoapySDR from source, especially for use with a pre-packaged GNU Radio release, use the SoapySDR `maint` branch.

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. Verify that the required modules are shown, and that the listed module directories match the expected installation paths for any modules built from source.

• 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.

• SoapySDRUtil --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.

soapy via gr-osmosdr

gr-osmosdr provides a separate path to SoapySDR drivers. When devices are accessed through gr-osmosdr using a driver specification like:

driver=hackrf,soapy=0

the stack is:

• GNU Radio runtime and GRC
• gr-osmosdr out-of-tree module
• SoapySDR framework
• SoapySDR driver module
• Hardware support library

The SoapySDRUtil utility can still be used to determine whether SoapySDR drivers are installed and functional.