Module: RTLSDR

Defined in:
lib/rtlsdr.rb,
lib/rtlsdr/dsp.rb,
lib/rtlsdr/ffi.rb,
lib/rtlsdr/device.rb,
lib/rtlsdr/errors.rb,
lib/rtlsdr/scanner.rb,
lib/rtlsdr/version.rb

Overview

Ruby bindings for RTL-SDR (Software Defined Radio) devices

RTLSDR provides a complete Ruby interface to RTL-SDR USB dongles, enabling software-defined radio applications. It offers both low-level FFI bindings that map directly to the librtlsdr C API and high-level Ruby classes with idiomatic methods and DSLs.

Features:

  • Device enumeration and control
  • Frequency, gain, and sample rate configuration
  • Synchronous and asynchronous sample reading
  • Signal processing utilities (DSP)
  • Frequency scanning and spectrum analysis
  • EEPROM reading/writing and bias tee control

Examples:

Basic usage

device = RTLSDR.open(0)
device.sample_rate = 2_048_000
device.center_freq = 100_000_000
device.gain = 496
samples = device.read_samples(1024)
device.close

List all devices

RTLSDR.devices.each do |dev|
  puts "#{dev[:index]}: #{dev[:name]}"
end

Defined Under Namespace

Modules: DSP, FFI Classes: CallbackError, Device, DeviceNotFoundError, DeviceNotOpenError, DeviceOpenError, EEPROMError, Error, InvalidArgumentError, OperationFailedError, Scanner

Constant Summary collapse

VERSION =

Current version of the RTL-SDR Ruby gem

This constant defines the semantic version of the Ruby bindings. The version follows semantic versioning (semver) conventions: MAJOR.MINOR.PATCH where:

  • MAJOR: Backwards-incompatible API changes
  • MINOR: New features, backwards-compatible
  • PATCH: Bug fixes, backwards-compatible

Returns:

  • (String) —

    Current gem version

Since:

  • 0.1.0

"0.1.12"

Class Method Summary collapse

Class Method Details

.device_count ⇒ Integer

Get the number of connected RTL-SDR devices

Examples:

Check for devices

if RTLSDR.device_count > 0
  puts "Found #{RTLSDR.device_count} RTL-SDR devices"
end

Returns:

  • (Integer) —

    Number of RTL-SDR devices found



46
47
48
 
# File 'lib/rtlsdr.rb', line 46

def device_count
  FFI.rtlsdr_get_device_count
end

.device_name(index) ⇒ String

Get the name of a device by index

Examples:

Get device name

name = RTLSDR.device_name(0)
puts "Device 0: #{name}"

Parameters:

  • index (Integer) —

    Device index (0-based)

Returns:

  • (String) —

    Device name string



57
58
59
 
# File 'lib/rtlsdr.rb', line 57

def device_name(index)
  FFI.rtlsdr_get_device_name(index)
end

.device_usb_strings(index) ⇒ Hash?

Get USB device strings for a device by index

Retrieves the USB manufacturer, product, and serial number strings for the specified device.

Examples:

Get USB info

usb_info = RTLSDR.device_usb_strings(0)
puts "#{usb_info[:manufacturer]} #{usb_info[:product]}"

Parameters:

  • index (Integer) —

    Device index (0-based)

Returns:

  • (Hash, nil) —

    Hash with :manufacturer, :product, :serial keys, or nil on error



71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/rtlsdr.rb', line 71

def device_usb_strings(index)
  manufact = " " * 256
  product = " " * 256
  serial = " " * 256

  result = FFI.rtlsdr_get_device_usb_strings(index, manufact, product, serial)
  return nil if result != 0

  {
    manufacturer: manufact.strip,
    product: product.strip,
    serial: serial.strip
  }
end

.devices ⇒ Array<Hash>

List all available devices with their information

Returns an array of hashes containing information about all connected RTL-SDR devices, including index, name, and USB strings.

Examples:

List all devices

RTLSDR.devices.each do |device|
  puts "#{device[:index]}: #{device[:name]}"
  puts "  #{device[:usb_strings][:manufacturer]} #{device[:usb_strings][:product]}"
end

Returns:

  • (Array<Hash>) —

    Array of device information hashes



130
131
132
133
134
135
136
137
138
 
# File 'lib/rtlsdr.rb', line 130

def devices
  (0...device_count).map do |i|
    {
      index: i,
      name: device_name(i),
      usb_strings: device_usb_strings(i)
    }
  end
end

.find_device_by_serial(serial) ⇒ Integer?

Find device index by serial number

Searches for a device with the specified serial number and returns its index if found.

Examples:

Find device by serial

index = RTLSDR.find_device_by_serial("00000001")
device = RTLSDR.open(index) if index

Parameters:

  • serial (String) —

    Serial number to search for

Returns:

  • (Integer, nil) —

    Device index if found, nil otherwise



96
97
98
99
100
101
 
# File 'lib/rtlsdr.rb', line 96

def find_device_by_serial(serial)
  result = FFI.rtlsdr_get_index_by_serial(serial)
  return nil if result.negative?

  result
end

.open(index = 0) ⇒ RTLSDR::Device

Open a device and return a Device instance

Creates and returns a new Device instance for the specified device index. The device will be automatically opened and ready for use.

Examples:

Open first device

device = RTLSDR.open(0)
device.center_freq = 100_000_000

Parameters:

  • index (Integer) (defaults to: 0) —

    Device index to open (default: 0)

Returns:

Raises:



115
116
117
 
# File 'lib/rtlsdr.rb', line 115

def open(index = 0)
  Device.new(index)
end