rtlsdr.rtlsdr

exception rtlsdr.rtlsdr.LibUSBError(errno, msg='')

Bases: OSError

class rtlsdr.rtlsdr.BaseRtlSdr(device_index=0, test_mode_enabled=False, serial_number=None, dithering_enabled=True)

Bases: object

Core interface for most API functionality

Parameters:

• device_index (int, optional) – The device index to use if there are multiple dongles attached. If only one is being used, the default value (0) will be used.

• test_mode_enabled (bool, optional) – If True, enables a special test mode, which will return the value of an internal RTL2832 8-bit counter with calls to read_bytes().

• serial_number (str, optional) – If not None, the device will be searched for by the given serial_number by get_device_index_by_serial() and the device_index returned will be used automatically.

DEFAULT_GAIN

Default gain value used on initialization: 'auto'

DEFAULT_FC

Default center_freq value used on initialization: 80e6 (80 Mhz)

Type:

float

DEFAULT_RS

Default sample_rate value used on initialization: 1.024e6 (1024 Msps)

Type:

float

DEFAULT_READ_SIZE

Default number of samples or bytes to read if no arguments are supplied for read_bytes() or read_samples(). Default value is 1024

Type:

int

gain_values

The valid gain parameters supported by the device (in tenths of dB). These are stored as returned by librtlsdr.

Type:

list(int)

valid_gains_db

The valid gains in dB

Type:

list(float)

static get_device_index_by_serial(serial)

Retrieves the device index for a device matching the given serial number

Parameters:

serial (str) – The serial number to search for

Returns:

The device_index as reported by librtlsdr

Return type:

int

Notes

Most devices by default have the same serial number: ‘0000001’. This can be set to a custom value by using the rtl_eeprom utility packaged with librtlsdr.

static get_device_serial_addresses()

Get serial numbers for all attached devices

Returns:

A list of all detected serial numbers (str)

Return type:

list(str)

get_gains()

Get all supported gain values from driver

Returns:

Gains in tenths of a dB

Return type:

list(int)

get_gpio_bit(gpio)

Get GPIO pin value.

Parameters:

gpio (int) – RTL-SDR GPIO pin number

Returns:

Setting of GPIO pin

Return type:

val (int)

get_gpio_byte()

Get multiple GPIO pin values at once as a byte.

Returns:

byte containing settings of multiple GPIO pins

Return type:

val (int)

get_tuner_type()

Get the tuner type.

Returns:

The tuner type as reported by the driver. See the tuner enum definition for more information.

Return type:

int

init_device_values()

Retrieves information from the device

This method acquires the values for gain_values. Also sets the device to the default center frequency, the sample rate and gain

open(device_index=0, test_mode_enabled=False, serial_number=None, dithering_enabled=True)

Connect to the device through the underlying wrapper library

Initializes communication with the device and retrieves information from it with a call to init_device_values().

Parameters:

• device_index (int, optional) – The device index to use if there are multiple dongles attached. If only one is being used, the default value (0) will be used.

• test_mode_enabled (bool, optional) – If True, enables a special test mode, which will return the value of an internal RTL2832 8-bit counter with calls to read_bytes().

• serial_number (str, optional) – If not None, the device will be searched for by the given serial_number by get_device_index_by_serial() and the device_index returned will be used automatically.

• dithering_enabled (bool, optional) – If False, disables PLL dithering to prevent it destroying phase coherence in CLK-synchronized dongles.

Notes

The arguments used here are passed directly from object initialization.

Raises:

IOError – If communication with the device could not be established.

packed_bytes_to_iq(bytes)

Unpack a sequence of bytes to a sequence of normalized complex numbers

This is called automatically by read_samples().

Returns:

The unpacked iq values as either a list or numpy.ndarray (if available).

read_bytes(num_bytes=1024)

Read specified number of bytes from tuner.

Does not attempt to unpack complex samples (see read_samples()), and data may be unsafe as buffer is reused.

Parameters:

num_bytes (int, optional) – The number of bytes to read. Defaults to DEFAULT_READ_SIZE.

Returns:

A buffer of len(num_bytes) containing the raw samples read.

Return type:

ctypes.Array[c_ubyte]

read_samples(num_samples=1024)

Read specified number of complex samples from tuner.

Real and imaginary parts are normalized to be in the range [-1, 1]. Data is safe after this call (will not get overwritten by another one).

Parameters:

num_samples (int, optional) – Number of samples to read. Defaults to DEFAULT_READ_SIZE.

Returns:

The samples read as either a list or numpy.ndarray (if available).

set_agc_mode(enabled)

Enable RTL2832 AGC

Parameters:

enabled (bool)

set_bias_tee(enabled)

Enable RTL2832 Bias Tee

Enables or disables the Bias Tee option (RTL-SDRv3 only)

Parameters:

enabled (bool)

Warning

Using this could potentially damage your device! Please make sure you understand what Bias Tee does before using this method.

See the Bias T section of the RTL-SDRv3 Manual for information.

Added in version 0.2.93.

set_direct_sampling(direct)

Enable direct sampling.

Parameters:

direct – If False or 0, disable direct sampling. If ‘i’ or 1, use ADC I input. If ‘q’ or 2, use ADC Q input.

set_dithering(enabled)

Enable/disable PLL dithering.

Parameters:

enabled (bool)

set_gpio_bit(gpio, val)

Set GPIO pin value.

Parameters:

• gpio (int) – RTL-SDR GPIO pin number

• val (int) – state to set GPIO pin to, 0 or 1

set_gpio_byte(val)

Set multiple GPIO pins at once using a byte.

Parameters:

val (int) – byte

set_gpio_input(gpio)

Set GPIO pin to input mode.

Parameters:

gpio (int) – RTL-SDR GPIO pin number

set_gpio_output(gpio)

Set GPIO pin to output mode.

Parameters:

gpio (int) – RTL-SDR GPIO pin number

set_gpio_status()

Get GPD register status as a byte.

Note that the librtlsdr API calls rtlsdr_read_reg, and this function is used everywhere like a getter.

Returns:

byte containing status of all GPIO pins

Return type:

val (int)

set_manual_gain_enabled(enabled)

Enable or disable manual gain control of tuner.

Parameters:

enabled (bool)

Notes

If enabled is False, then AGC should also be used by calling set_agc_mode(). It is recommended to use set_gain() instead of calling this method directly.

property bandwidth

Get/Set bandwidth value (in Hz)

Set value to 0 (default) for automatic bandwidth selection.

Notes

This value is stored locally and may not reflect the real tuner bandwidth

Type:

int

property center_freq

Get/Set the center frequency of the device (in Hz)

Type:

int

property fc

Get/Set the center frequency of the device (in Hz)

Type:

int

property freq_correction

Get/Set frequency offset of the tuner (in PPM)

Type:

int

property gain

Get/Set gain of the tuner (in dB)

Notes

If set to ‘auto’, AGC mode is enabled; otherwise gain is in dB. The actual gain used is rounded to the nearest value supported by the device (see the values in valid_gains_db).

Type:

float or str

property rs

Get/Set the sample rate of the tuner (in Hz)

Type:

int

property sample_rate

Get/Set the sample rate of the tuner (in Hz)

Type:

int

class rtlsdr.rtlsdr.RtlSdr(device_index=0, test_mode_enabled=False, serial_number=None, dithering_enabled=True)

Bases: BaseRtlSdr

This adds async read support to BaseRtlSdr

_bytes_converter_callback(raw_buffer, num_bytes, context)

Converts the raw buffer used in rtlsdr_read_async to a usable type

This method is used internally by read_bytes_async() to convert the raw data from rtlsdr_read_async into a memory-safe array.

The callback given in read_bytes_async() will then be called with the signature:

callback(values, context)

Parameters:

• raw_buffer – Buffer of type unsigned char

• num_bytes (int) – Length of raw_buffer

• context – User-defined value passed to rtlsdr_read_async. In most cases, will be a reference to the RtlSdr instance

Notes

This method is not meant to be called directly or overridden by subclasses.

_samples_converter_callback(buffer, context)

Converts the raw buffer used in rtlsdr_read_async to a usable type

This method is used internally by read_samples_async() to convert the data into a sequence of complex numbers.

The callback given in read_samples_async() will then be called with the signature:

callback(samples, context)

Parameters:

• buffer – Buffer of type unsigned char

• context – User-defined value passed to rtlsdr_read_async. In most cases, will be a reference to the RtlSdr instance

Notes

This method is not meant to be called directly or overridden by subclasses.

cancel_read_async()

Cancel async read. This should be called eventually when using async reads (read_bytes_async() or read_samples_async()), or callbacks will never stop.

See also

limit_time() and limit_calls()

read_bytes_async(callback, num_bytes=1024, context=None)

Continuously read bytes from tuner

Parameters:

• callback – A function or method that will be called with the result. See _bytes_converter_callback() for the signature.

• num_bytes (int) – Number of bytes to read for each callback. Defaults to DEFAULT_READ_SIZE.

• context (Optional) – Object to be passed as an argument to the callback. If not supplied or None, the RtlSdr instance will be used.

Notes

As with read_bytes(), the data passed to the callback may by overwritten.

read_samples_async(callback, num_samples=1024, context=None)

Continuously read ‘samples’ from the tuner

This is a combination of read_samples() and read_bytes_async()

Parameters:

• callback – A function or method that will be called with the result. See _samples_converter_callback() for the signature.

• num_samples (int) – The number of samples read into each callback. Defaults to DEFAULT_READ_SIZE.

• context (Optional) – Object to be passed as an argument to the callback. If not supplied or None, the RtlSdr instance will be used.