SDR Package (ria_toolkit_oss.sdr)

This package provides a unified API for working with a variety of software-defined radios. It streamlines tasks involving signal reception and transmission, as well as common administrative operations such as detecting and configuring available devices.

class ria_toolkit_oss.sdr.SDR

Bases: ABC

This class defines a common interface (a template) for all SDR devices. Each specific SDR implementation should subclass SDR and provide concrete implementations for the abstract methods.

To add support for a new radio, subclass this interface and implement all abstract methods. If you experience difficulties, please contact us, we are happy to provide additional direction and/or help with the implementation details.

record(num_samples=None, rx_time=None)

Create a radio recording of a given length. Either num_samples or rx_time must be provided.

Note that init_rx() must be called before record().

Parameters:

• num_samples (int, optional) – The number of samples to record.

• rx_time (int or float, optional) – The time to record.

Returns:

The Recording object

Return type:

Recording

rx(num_samples)

Return num_samples complex IQ samples as a 1-D complex64 array.

This is the interface used by the agent inference loop. On first call, init_rx() is invoked automatically using the values stored in center_freq, sample_rate, and gain (set beforehand by _apply_sdr_config). Subsequent calls stream directly.

Subclasses may override this for hardware-native capture APIs (e.g. MockSDR uses AWGN generation; PlutoSDR could use self.radio.rx()).

stream_to_zmq(zmq_address, n_samples, buffer_size=10000)

Stream iq samples as interleaved bytes via zmq.

Parameters:

• zmq_address – The zmq address.

• n_samples (int) – The number of samples to stream.

• buffer_size (int, optional) – The buffer size during streaming. Defaults to 10000.

Returns:

The trimmed Recording.

Return type:

Recording

pickle_buffer_to_zmq(zmq_address, buffer_size, num_buffers)

Stream samples to a zmq address, packaged in binary buffers using numpy.pickle. Useful for inference applications with a known input size. May reduce transfer rates, but individual buffers will not have discontinuities.

Parameters:

• zmq_address (str) – The tcp address to stream to.

• buffer_size (int) – The number of iq samples in a buffer.

• num_buffers (int) – The number of buffers to stream before stopping.

tx_recording(recording, num_samples=None, tx_time=None)

Transmit the given iq samples from the provided recording. init_tx() must be called before this function.

Parameters:

• recording (Recording or ndarray) – The recording to transmit.

• num_samples (int, optional) – The number of samples to transmit, will repeat or truncate the recording to this length. Defaults to None.

• tx_time (int or float, optional) – The time to transmit, will repeat or truncate the recording to this length. Defaults to None.

supports_bias_tee()

Return True when the radio supports bias-tee control.

set_bias_tee(enable)

Enable or disable bias-tee power when supported by the radio.

pause_rx()

pause_tx()

stop()

get_rx_sample_rate()

Retrieve the current sample rate of the receiver.

Returns:

float: The receiver’s sample rate in samples per second (Hz).

get_rx_center_frequency()

Retrieve the current center frequency of the receiver.

Returns:

float: The receiver’s center frequency in Hertz (Hz).

get_rx_gain()

Retrieve the current gain setting of the receiver.

Returns:

float: The receiver’s gain in decibels (dB).

get_tx_sample_rate()

Retrieve the current sample rate of the transmitter.

Returns:

float: The transmitter’s sample rate in samples per second (Hz).

get_tx_center_frequency()

Retrieve the current center frequency of the transmitter.

Returns:

float: The transmitter’s center frequency in Hertz (Hz).

get_tx_gain()

Retrieve the current gain setting of the transmitter.

Returns:

float: The transmitter’s gain in decibels (dB).

set_rx_sample_rate()

Set the sample rate of the receiver.

set_rx_center_frequency()

Set the center frequency of the receiver.

set_rx_gain()

Set the gain setting of the receiver.

set_tx_sample_rate()

Set the sample rate of the transmitter.

set_tx_center_frequency()

Set the center frequency of the transmitter.

set_tx_gain()

Set the gain setting of the transmitter.

supports_dynamic_updates()

Report which parameters can be updated during streaming.

Returns:

dict: {‘center_frequency’: bool, ‘sample_rate’: bool, ‘gain’: bool}

abstract close()

abstract init_rx(sample_rate, center_frequency, gain, channel, gain_mode)

abstract init_tx(sample_rate, center_frequency, gain, channel, gain_mode)

abstract set_clock_source(source)

Sets the clock source to external or internal.

Parameters:

source (str) – The clock source

exception ria_toolkit_oss.sdr.SDRError

Bases: Exception

Base exception for SDR errors.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception ria_toolkit_oss.sdr.SDRParameterError

Bases: SDRError

Invalid parameter (sample rate, freq, gain).

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception ria_toolkit_oss.sdr.SdrDisconnectedError

Bases: SDRError

Raised when the SDR device disappears mid-operation (USB unplug, network drop).

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class ria_toolkit_oss.sdr.MockSDR(buffer_size=4096, seed=None)

Bases: SDR

Software-simulated SDR that generates AWGN noise.

Args:

buffer_size: Number of complex samples per streaming buffer. seed: Optional RNG seed for reproducible output.

init_rx(sample_rate, center_frequency, gain, channel=0, gain_mode='manual')

init_tx(sample_rate, center_frequency, gain, channel=0, gain_mode='manual')

set_clock_source(source)

Sets the clock source to external or internal.

Parameters:

source (str) – The clock source

close()

rx(num_samples)

Return num_samples complex64 AWGN samples (PlutoSDR-style).

get_rx_center_frequency()

Retrieve the current center frequency of the receiver.

Returns:

float: The receiver’s center frequency in Hertz (Hz).

get_rx_gain()

Retrieve the current gain setting of the receiver.

Returns:

float: The receiver’s gain in decibels (dB).

get_rx_sample_rate()

Retrieve the current sample rate of the receiver.

Returns:

float: The receiver’s sample rate in samples per second (Hz).

get_tx_center_frequency()

Retrieve the current center frequency of the transmitter.

Returns:

float: The transmitter’s center frequency in Hertz (Hz).

get_tx_gain()

Retrieve the current gain setting of the transmitter.

Returns:

float: The transmitter’s gain in decibels (dB).

get_tx_sample_rate()

Retrieve the current sample rate of the transmitter.

Returns:

float: The transmitter’s sample rate in samples per second (Hz).

pause_rx()

pause_tx()

pickle_buffer_to_zmq(zmq_address, buffer_size, num_buffers)

Stream samples to a zmq address, packaged in binary buffers using numpy.pickle. Useful for inference applications with a known input size. May reduce transfer rates, but individual buffers will not have discontinuities.

Parameters:

• zmq_address (str) – The tcp address to stream to.

• buffer_size (int) – The number of iq samples in a buffer.

• num_buffers (int) – The number of buffers to stream before stopping.

record(num_samples=None, rx_time=None)

Create a radio recording of a given length. Either num_samples or rx_time must be provided.

Note that init_rx() must be called before record().

Parameters:

• num_samples (int, optional) – The number of samples to record.

• rx_time (int or float, optional) – The time to record.

Returns:

The Recording object

Return type:

Recording

set_bias_tee(enable)

Enable or disable bias-tee power when supported by the radio.

set_rx_center_frequency()

Set the center frequency of the receiver.

set_rx_gain()

Set the gain setting of the receiver.

set_rx_sample_rate()

Set the sample rate of the receiver.

set_tx_center_frequency()

Set the center frequency of the transmitter.

set_tx_gain()

Set the gain setting of the transmitter.

set_tx_sample_rate()

Set the sample rate of the transmitter.

stop()

stream_to_zmq(zmq_address, n_samples, buffer_size=10000)

Stream iq samples as interleaved bytes via zmq.

Parameters:

• zmq_address – The zmq address.

• n_samples (int) – The number of samples to stream.

• buffer_size (int, optional) – The buffer size during streaming. Defaults to 10000.

Returns:

The trimmed Recording.

Return type:

Recording

supports_bias_tee()

Return True when the radio supports bias-tee control.

supports_dynamic_updates()

Report which parameters can be updated during streaming.

Returns:

dict: {‘center_frequency’: bool, ‘sample_rate’: bool, ‘gain’: bool}

tx_recording(recording, num_samples=None, tx_time=None)

Transmit the given iq samples from the provided recording. init_tx() must be called before this function.

Parameters:

• recording (Recording or ndarray) – The recording to transmit.

• num_samples (int, optional) – The number of samples to transmit, will repeat or truncate the recording to this length. Defaults to None.

• tx_time (int or float, optional) – The time to transmit, will repeat or truncate the recording to this length. Defaults to None.

ria_toolkit_oss.sdr.get_sdr_device(device_type, ident=None, tx=False)

Return an SDR instance for device_type.

For "mock" / "sim" device types, returns a MockSDR immediately (no hardware required). For all real device types, delegates to ria_toolkit_oss_cli.ria_toolkit_oss.common.get_sdr_device if the CLI package is installed; otherwise raises ImportError with a helpful message.

Args:

device_type: Device name ("mock", "pluto", "usrp", …). ident: Optional device identifier (IP address, serial number, …). tx: If True, require TX capability.

ria_toolkit_oss.sdr.detect_available()

Return {device_name: driver_class} for every driver whose module imports cleanly.

Importability is a proxy for “the user has installed this driver’s optional dependency”. It does not probe for physical hardware presence — that requires actually instantiating the driver, which can be slow and side-effectful.

Radio Classes

class ria_toolkit_oss.sdr.usrp.USRP(identifier=None)

init_rx(sample_rate, center_frequency, channel, gain, gain_mode='absolute', rx_buffer_size=None)

Initializes the USRP for receiving.

Parameters:

• sample_rate (int or float) – The sample rate for receiving.

• center_frequency (int or float) – The center frequency of the recording.

• gain (int) – The gain set for receiving on the USRP

• channel (int) – The channel the USRP is set to.

• gain_mode (str) – ‘absolute’ passes gain directly to the sdr, ‘relative’ means that gain should be a negative value, and it will be subtracted from the max gain.

• rx_buffer_size (int) – Internal buffer size for receiving samples. Defaults to 960000.

Returns:

A dictionary with the actual RX parameters after configuration.

Return type:

dict

set_rx_sample_rate(sample_rate, channel=0)

Set the sample rate of the receiver. Callable during streaming.

set_rx_center_frequency(center_frequency, channel=0)

Set the center frequency of the receiver. Callable during streaming.

set_rx_gain(gain, gain_mode='absolute', channel=0)

Set the gain of the receiver. Callable during streaming.

record(num_samples=None, rx_time=None)

Create a radio recording (iq samples and metadata) of a given length from the USRP. Either num_samples or rx_time must be provided. init_rx() must be called before record()

Parameters:

• num_samples (int, optional) – The number of samples to record.

• rx_time (int or float, optional) – The time to record.

returns: Recording object (iq samples and metadata)

init_tx(sample_rate, center_frequency, gain, channel, gain_mode='absolute')

Initializes the USRP for transmitting.

Parameters:

• sample_rate (int or float) – The sample rate for transmitting.

• center_frequency (int or float) – The center frequency of the recording.

• gain (int) – The gain set for transmitting on the USRP

• channel (int) – The channel the USRP is set to.

• gain_mode (str) – ‘absolute’ passes gain directly to the sdr, ‘relative’ means that gain should be a negative value, and it will be subtracted from the max gain.

set_tx_sample_rate(sample_rate, channel=0)

Set the sample rate of the transmitter.

set_tx_center_frequency(center_frequency, channel=0)

Set the center frequency of the transmitter.

set_tx_gain(gain, gain_mode='absolute', channel=0)

Set the gain setting of the transmitter.

tx_recording(recording, num_samples=None, tx_time=None)

Transmit the given iq samples from the provided recording. init_tx() must be called before this function.

Parameters:

• recording (Recording or ndarray) – The recording to transmit.

• num_samples (int, optional) – The number of samples to transmit, will repeat or truncate the recording to this length. Defaults to None.

• tx_time (int or float, optional) – The time to transmit, will repeat or truncate the recording to this length. Defaults to None.

set_clock_source(source)

Sets the clock source to external or internal.

Parameters:

source (str) – The clock source

supports_dynamic_updates()

Report which parameters can be updated during streaming.

Returns:

dict: {‘center_frequency’: bool, ‘sample_rate’: bool, ‘gain’: bool}

class ria_toolkit_oss.sdr.blade.Blade(identifier='')

init_rx(sample_rate, center_frequency, gain, channel, buffer_size=8192, gain_mode='absolute')

Initializes the BladeRF for receiving.

Parameters:

• sample_rate (int or float) – The sample rate for receiving.

• center_frequency (int or float) – The center frequency of the recording.

• gain (int) – The gain set for receiving on the BladeRF.

• channel (int) – The channel the BladeRF is set to.

• buffer_size (int) – The buffer size during receive. Defaults to 8192.

• gain_mode (str) – ‘absolute’ passes gain directly to the SDR; ‘relative’ means that gain should be a negative value, and it will be subtracted from the max gain (60).

record(num_samples=None, rx_time=None)

Create a radio recording (iq samples and metadata) of a given length from the Blade. Either num_samples or rx_time must be provided. init_rx() must be called before record()

Parameters:

• num_samples (int, optional) – The number of samples to record.

• rx_time (int or float, optional) – The time to record.

returns: Recording object (iq samples and metadata)

init_tx(sample_rate, center_frequency, gain, channel, buffer_size=32768, gain_mode='absolute')

Initializes the BladeRF for transmitting.

Parameters:

• sample_rate (int or float) – The sample rate for transmitting.

• center_frequency (int or float) – The center frequency of the recording.

• gain (int) – The gain set for transmitting on the BladeRF

• channel (int) – The channel the BladeRF is set to.

• buffer_size (int) – The buffer size during transmission. Defaults to 8192.

• gain_mode (str) – ‘absolute’ passes gain directly to the sdr, ‘relative’ means that gain should be a negative value, and it will be subtracted from the max gain (60).

Returns:

0 if successful, -1 if there’s an error.

Return type:

int

tx_recording(recording, num_samples=None, tx_time=None)

Transmit the given IQ samples from the provided recording. init_tx() must be called before this function.

Parameters:

• recording (Recording or ndarray) – The recording to transmit.

• num_samples (int, optional) – The number of samples to transmit, will repeat or truncate the recording to this length. Defaults to None.

• tx_time (int or float, optional) – The time to transmit, will repeat or truncate the recording to this length. Defaults to None.

set_rx_sample_rate(sample_rate)

Set the sample rate of the receiver. Not callable during recording; Blade requires stream stop/restart to change sample rate.

set_rx_center_frequency(center_frequency)

Set the center frequency of the receiver. Not callable during recording; Blade requires stream stop/restart to change center frequency.

set_rx_gain(channel, gain, gain_mode)

Set the gain of the receiver. Not callable during recording; Blade requires stream stop/restart to change gain.

set_tx_sample_rate(sample_rate)

Set the sample rate of the transmitter.

set_tx_center_frequency(center_frequency)

Set the center frequency of the transmitter.

set_tx_gain(channel, gain, gain_mode)

Set the gain setting of the transmitter.

set_clock_source(source)

Sets the clock source to external or internal.

Parameters:

source (str) – The clock source

supports_bias_tee()

Return True when the radio supports bias-tee control.

set_bias_tee(enable, channel=None)

Enable or disable bias-tee power when supported by the radio.

supports_dynamic_updates()

Report which parameters can be updated during streaming.

Returns:

dict: {‘center_frequency’: bool, ‘sample_rate’: bool, ‘gain’: bool}

class ria_toolkit_oss.sdr.pluto.Pluto(identifier=None)

init_rx(sample_rate, center_frequency, gain, channel, gain_mode='absolute')

Initializes the Pluto for receiving.

Parameters:

• sample_rate (int or float) – The sample rate for receiving.

• center_frequency (int or float) – The center frequency of the recording.

• gain (int) – The gain set for receiving on the Pluto

• channel (int) – The channel the Pluto is set to. Must be 0 or 1. 0 enables channel 1, 1 enables both channels.

• gain_mode (str) – ‘absolute’ passes gain directly to the sdr, ‘relative’ means that gain should be a negative value, and it will be subtracted from the max gain (74).

init_tx(sample_rate, center_frequency, gain, channel, gain_mode='absolute')

Initializes the Pluto for transmitting. Will transmit garbage during center frequency tuning and setting the sample rate.

Parameters:

• sample_rate (int or float) – The sample rate for transmitting.

• center_frequency (int or float) – The center frequency of the recording.

• gain (int) – The gain set for transmitting on the Pluto

• channel (int) – The channel the Pluto is set to. Must be 0 or 1. 0 enables channel 1, 1 enables both channels.

• gain_mode (str) – ‘absolute’ passes gain directly to the sdr, ‘relative’ means that gain should be a negative value, and it will be subtracted from the max gain (0).

rx(num_samples=None)

PlutoSDR-style single-buffer capture returning a complex64 array.

Sets the radio buffer size to num_samples (if given) and returns one buffer directly from self.radio.rx(). Raises SdrDisconnectedError on USB/device drop so callers (e.g. the streamer) can report the failure and stop cleanly instead of crashing.

record(num_samples=None, rx_time=None)

Create a radio recording (iq samples and metadata) of a given length from the SDR. Either num_samples or rx_time must be provided. init_rx() must be called before record()

Parameters:

• num_samples (int, optional) – The number of samples to record. Pluto max = 16M.

• rx_time (int or float, optional) – The time to record.

returns: Recording object (iq samples and metadata)

tx_recording(recording, num_samples=None, tx_time=None, mode='timed')

Transmit the given iq samples from the provided recording. init_tx() must be called before this function.

Parameters:

• recording (Recording, ndarray, list[Recording, ndarray]) – The recording(s) to transmit.

• num_samples (int, optional) – The number of samples to transmit, will repeat or truncate the recording to this length. Defaults to None.

• tx_time (int or float, optional) – The time to transmit, will repeat or truncate the recording to this length. Defaults to None.

• mode (str, optional) – The mode of transmission, either timed or continuous. Defaults to timed.

set_rx_center_frequency(center_frequency)

Set the center frequency of the receiver. Callable during streaming.

set_rx_sample_rate(sample_rate)

Set the sample rate of the receiver. Callable during streaming.

set_rx_gain(gain, channel=0, gain_mode='absolute')

Set the gain of the receiver. Callable during streaming.

set_tx_center_frequency(center_frequency)

Set the center frequency of the transmitter.

set_tx_sample_rate(sample_rate)

Set the sample rate of the transmitter.

set_tx_gain(gain, channel=0, gain_mode='absolute')

Set the gain setting of the transmitter.

set_clock_source(source)

Sets the clock source to external or internal.

Parameters:

source (str) – The clock source

supports_dynamic_updates()

Report which parameters can be updated during streaming.

Returns:

dict: {‘center_frequency’: bool, ‘sample_rate’: bool, ‘gain’: bool}