Module: RTLSDR

Defined in:
lib/rtlsdr.rb,
lib/rtlsdr/dsp.rb,
lib/rtlsdr/ffi.rb,
lib/rtlsdr/fftw.rb,
lib/rtlsdr/demod.rb,
lib/rtlsdr/device.rb,
lib/rtlsdr/errors.rb,
lib/rtlsdr/scanner.rb,
lib/rtlsdr/version.rb,
lib/rtlsdr/dsp/filter.rb,
lib/rtlsdr/tcp_client.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 with local device

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

Connect to remote rtl_tcp server

device = RTLSDR.connect("192.168.1.100", 1234)
device.sample_rate = 2_048_000
device.center_freq = 100_000_000
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, Demod, FFI, FFTW Classes: CallbackError, ConnectionError, Device, DeviceNotFoundError, DeviceNotOpenError, DeviceOpenError, EEPROMError, Error, InvalidArgumentError, OperationFailedError, Scanner, TcpClient

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.3.0"

Class Method Summary collapse

Class Method Details

.connect(host, port = TcpClient::DEFAULT_PORT, timeout: 10) ⇒ RTLSDR::TcpClient

Connect to a remote rtl_tcp server

Creates and returns a TcpClient instance connected to the specified rtl_tcp server. The client implements the same interface as Device, allowing seamless switching between local and remote devices.

Examples:

Connect to remote device

device = RTLSDR.connect("192.168.1.100")
device.center_freq = 100_000_000

Connect with custom port

device = RTLSDR.connect("192.168.1.100", 5555)

Parameters:

  • host (String) —

    Hostname or IP address of rtl_tcp server

  • port (Integer) (defaults to: TcpClient::DEFAULT_PORT) —

    Port number (default: 1234)

  • timeout (Integer) (defaults to: 10) —

    Connection timeout in seconds (default: 10)

Returns:

Raises:

Since:

  • 0.3.0



147
148
149
 
# File 'lib/rtlsdr.rb', line 147

def connect(host, port = TcpClient::DEFAULT_PORT, timeout: 10)
  TcpClient.new(host, port, timeout: timeout)
end

.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



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

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



68
69
70
 
# File 'lib/rtlsdr.rb', line 68

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



82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/rtlsdr.rb', line 82

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



162
163
164
165
166
167
168
169
170
 
# File 'lib/rtlsdr.rb', line 162

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



107
108
109
110
111
112
 
# File 'lib/rtlsdr.rb', line 107

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:



126
127
128
 
# File 'lib/rtlsdr.rb', line 126

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