rtlsdr 0.1.0

data/lib/rtlsdr/dsp.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RTLSDR
+  # Digital Signal Processing utilities for RTL-SDR
+  #
+  # The DSP module provides essential signal processing functions for working
+  # with RTL-SDR sample data. It includes utilities for converting raw IQ data
+  # to complex samples, calculating power spectra, performing filtering
+  # operations, and extracting signal characteristics.
+  #
+  # All methods are designed to work with Ruby's Complex number type and
+  # standard Array collections, making them easy to integrate into Ruby
+  # applications and pipelines.
+  #
+  # Features:
+  # * IQ data conversion to complex samples
+  # * Power spectrum analysis with windowing
+  # * Peak detection and frequency estimation
+  # * DC removal and filtering
+  # * Magnitude and phase extraction
+  # * Average power calculation
+  #
+  # @example Basic signal analysis
+  #   raw_data = device.read_sync(2048)
+  #   samples = RTLSDR::DSP.iq_to_complex(raw_data)
+  #   power = RTLSDR::DSP.average_power(samples)
+  #   spectrum = RTLSDR::DSP.power_spectrum(samples)
+  #   peak_idx, peak_power = RTLSDR::DSP.find_peak(spectrum)
+  #
+  # @example Signal conditioning
+  #   filtered = RTLSDR::DSP.remove_dc(samples)
+  #   magnitudes = RTLSDR::DSP.magnitude(filtered)
+  #   phases = RTLSDR::DSP.phase(filtered)
+  module DSP
+    # Convert raw IQ data to complex samples
+    def self.iq_to_complex(data)
+      samples = []
+      (0...data.length).step(2) do |i|
+        i_sample = (data[i] - 128) / 128.0
+        q_sample = (data[i + 1] - 128) / 128.0
+        samples << Complex(i_sample, q_sample)
+      end
+      samples
+    end
+
+    # Calculate power spectral density
+    def self.power_spectrum(samples, window_size = 1024)
+      return [] if samples.length < window_size
+
+      windowed_samples = samples.take(window_size)
+
+      # Apply Hanning window
+      windowed_samples = windowed_samples.each_with_index.map do |sample, i|
+        window_factor = 0.5 * (1 - Math.cos(2 * Math::PI * i / (window_size - 1)))
+        sample * window_factor
+      end
+
+      # Simple magnitude calculation (real FFT would require external library)
+      windowed_samples.map { |s| ((s.real**2) + (s.imag**2)) }
+    end
+
+    # Calculate average power
+    def self.average_power(samples)
+      return 0.0 if samples.empty?
+
+      total_power = samples.reduce(0.0) { |sum, sample| sum + sample.abs2 }
+      total_power / samples.length
+    end
+
+    # Find peak power and frequency bin
+    def self.find_peak(power_spectrum)
+      return [0, 0.0] if power_spectrum.empty?
+
+      max_power = power_spectrum.max
+      max_index = power_spectrum.index(max_power)
+      [max_index, max_power]
+    end
+
+    # DC removal (high-pass filter)
+    def self.remove_dc(samples, alpha = 0.995)
+      return samples if samples.empty?
+
+      filtered = [samples.first]
+      (1...samples.length).each do |i|
+        filtered[i] = samples[i] - samples[i - 1] + (alpha * filtered[i - 1])
+      end
+      filtered
+    end
+
+    # Simple magnitude detection
+    def self.magnitude(samples)
+      samples.map(&:abs)
+    end
+
+    # Phase detection
+    def self.phase(samples)
+      samples.map { |s| Math.atan2(s.imag, s.real) }
+    end
+
+    # Frequency estimation using zero crossings
+    def self.estimate_frequency(samples, sample_rate)
+      return 0.0 if samples.length < 2
+
+      magnitudes = magnitude(samples)
+      zero_crossings = 0
+
+      (1...magnitudes.length).each do |i|
+        if (magnitudes[i - 1] >= 0 && magnitudes[i].negative?) ||
+           (magnitudes[i - 1].negative? && magnitudes[i] >= 0)
+          zero_crossings += 1
+        end
+      end
+
+      # Frequency = (zero crossings / 2) / time_duration
+      time_duration = samples.length.to_f / sample_rate
+      (zero_crossings / 2.0) / time_duration
+    end
+  end
+end

data/lib/rtlsdr/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RTLSDR
+  class Error < StandardError; end
+  class DeviceNotFoundError < Error; end
+  class DeviceOpenError < Error; end
+  class DeviceNotOpenError < Error; end
+  class InvalidArgumentError < Error; end
+  class OperationFailedError < Error; end
+  class EEPROMError < Error; end
+  class CallbackError < Error; end
+end

data/lib/rtlsdr/ffi.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module RTLSDR
+  # Low-level FFI bindings to librtlsdr
+  #
+  # The FFI module provides direct 1:1 bindings to the librtlsdr C library,
+  # exposing all native functions with their original signatures and behaviors.
+  # This module handles library loading from multiple common locations and
+  # defines all necessary data types, constants, and function prototypes.
+  #
+  # This is the foundation layer that the high-level Device class is built upon,
+  # but can also be used directly for applications that need complete control
+  # over the C API or want to implement custom abstractions.
+  #
+  # Features:
+  # * Complete librtlsdr API coverage
+  # * Automatic library discovery and loading
+  # * Proper FFI type definitions and callbacks
+  # * Tuner type constants and helper functions
+  # * Memory management support for pointers
+  #
+  # @example Direct FFI usage
+  #   device_count = RTLSDR::FFI.rtlsdr_get_device_count
+  #   device_ptr = FFI::MemoryPointer.new(:pointer)
+  #   result = RTLSDR::FFI.rtlsdr_open(device_ptr, 0)
+  #   handle = device_ptr.read_pointer
+  #   RTLSDR::FFI.rtlsdr_set_center_freq(handle, 100_000_000)
+  #
+  # @note Most users should use the high-level RTLSDR::Device class instead
+  #   of calling these FFI functions directly.
+  module FFI
+    extend ::FFI::Library
+
+    # Try to load the library from various locations
+    begin
+      ffi_lib "rtlsdr"
+    rescue LoadError
+      begin
+        ffi_lib "./librtlsdr/build/install/lib/librtlsdr.so"
+      rescue LoadError
+        begin
+          ffi_lib "/usr/local/lib/librtlsdr.so"
+        rescue LoadError
+          begin
+            ffi_lib "/usr/lib/librtlsdr.so"
+          rescue LoadError # rubocop:disable Metrics/BlockNesting
+            raise LoadError,
+                  "Could not find librtlsdr. Make sure it's installed or built in librtlsdr/build/install/lib/"
+          end
+        end
+      end
+    end
+
+    # Opaque device pointer
+    typedef :pointer, :rtlsdr_dev_t
+
+    # Tuner types enum
+    RTLSDR_TUNER_UNKNOWN = 0
+    RTLSDR_TUNER_E4000 = 1
+    RTLSDR_TUNER_FC0012 = 2
+    RTLSDR_TUNER_FC0013 = 3
+    RTLSDR_TUNER_FC2580 = 4
+    RTLSDR_TUNER_R820T = 5
+    RTLSDR_TUNER_R828D = 6
+
+    # Callback for async reading
+    callback :rtlsdr_read_async_cb_t, %i[pointer uint32 pointer], :void
+
+    # Device enumeration functions
+    attach_function :rtlsdr_get_device_count, [], :uint32
+    attach_function :rtlsdr_get_device_name, [:uint32], :string
+    attach_function :rtlsdr_get_device_usb_strings, %i[uint32 pointer pointer pointer], :int
+    attach_function :rtlsdr_get_index_by_serial, [:string], :int
+
+    # Device control functions
+    attach_function :rtlsdr_open, %i[pointer uint32], :int
+    attach_function :rtlsdr_close, [:rtlsdr_dev_t], :int
+
+    # Configuration functions
+    attach_function :rtlsdr_set_xtal_freq, %i[rtlsdr_dev_t uint32 uint32], :int
+    attach_function :rtlsdr_get_xtal_freq, %i[rtlsdr_dev_t pointer pointer], :int
+    attach_function :rtlsdr_get_usb_strings, %i[rtlsdr_dev_t pointer pointer pointer], :int
+    attach_function :rtlsdr_write_eeprom, %i[rtlsdr_dev_t pointer uint8 uint16], :int
+    attach_function :rtlsdr_read_eeprom, %i[rtlsdr_dev_t pointer uint8 uint16], :int
+
+    # Frequency control
+    attach_function :rtlsdr_set_center_freq, %i[rtlsdr_dev_t uint32], :int
+    attach_function :rtlsdr_get_center_freq, [:rtlsdr_dev_t], :uint32
+    attach_function :rtlsdr_set_freq_correction, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_get_freq_correction, [:rtlsdr_dev_t], :int
+
+    # Tuner functions
+    attach_function :rtlsdr_get_tuner_type, [:rtlsdr_dev_t], :int
+    attach_function :rtlsdr_get_tuner_gains, %i[rtlsdr_dev_t pointer], :int
+    attach_function :rtlsdr_set_tuner_gain, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_set_tuner_bandwidth, %i[rtlsdr_dev_t uint32], :int
+    attach_function :rtlsdr_get_tuner_gain, [:rtlsdr_dev_t], :int
+    attach_function :rtlsdr_set_tuner_if_gain, %i[rtlsdr_dev_t int int], :int
+    attach_function :rtlsdr_set_tuner_gain_mode, %i[rtlsdr_dev_t int], :int
+
+    # Sample rate and mode functions
+    attach_function :rtlsdr_set_sample_rate, %i[rtlsdr_dev_t uint32], :int
+    attach_function :rtlsdr_get_sample_rate, [:rtlsdr_dev_t], :uint32
+    attach_function :rtlsdr_set_testmode, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_set_agc_mode, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_set_direct_sampling, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_get_direct_sampling, [:rtlsdr_dev_t], :int
+    attach_function :rtlsdr_set_offset_tuning, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_get_offset_tuning, [:rtlsdr_dev_t], :int
+
+    # Streaming functions
+    attach_function :rtlsdr_reset_buffer, [:rtlsdr_dev_t], :int
+    attach_function :rtlsdr_read_sync, %i[rtlsdr_dev_t pointer int pointer], :int
+    attach_function :rtlsdr_wait_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer], :int
+    attach_function :rtlsdr_read_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer uint32 uint32], :int
+    attach_function :rtlsdr_cancel_async, [:rtlsdr_dev_t], :int
+
+    # Bias tee functions
+    attach_function :rtlsdr_set_bias_tee, %i[rtlsdr_dev_t int], :int
+    attach_function :rtlsdr_set_bias_tee_gpio, %i[rtlsdr_dev_t int int], :int
+
+    # Helper function to get tuner type name
+    def self.tuner_type_name(tuner_type)
+      case tuner_type
+      when RTLSDR_TUNER_UNKNOWN then "Unknown"
+      when RTLSDR_TUNER_E4000 then "Elonics E4000"
+      when RTLSDR_TUNER_FC0012 then "Fitipower FC0012"
+      when RTLSDR_TUNER_FC0013 then "Fitipower FC0013"
+      when RTLSDR_TUNER_FC2580 then "FCI FC2580"
+      when RTLSDR_TUNER_R820T then "Rafael Micro R820T"
+      when RTLSDR_TUNER_R828D then "Rafael Micro R828D"
+      else "Unknown (#{tuner_type})"
+      end
+    end
+  end
+end

data/lib/rtlsdr/scanner.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module RTLSDR
+  # Frequency scanning and spectrum analysis
+  #
+  # The Scanner class provides high-level frequency scanning capabilities for
+  # RTL-SDR devices. It automates the process of sweeping across frequency
+  # ranges, collecting samples, and analyzing signal characteristics. This is
+  # particularly useful for spectrum analysis, signal hunting, and surveillance
+  # applications.
+  #
+  # Features:
+  # * Configurable frequency range and step size
+  # * Adjustable dwell time per frequency
+  # * Synchronous and asynchronous scanning modes
+  # * Peak detection with power thresholds
+  # * Power sweep analysis
+  # * Real-time result callbacks
+  # * Thread-safe scanning control
+  #
+  # @example Basic frequency scan
+  #   scanner = RTLSDR::Scanner.new(
+  #     device,
+  #     start_freq: 88_000_000,    # 88 MHz
+  #     end_freq: 108_000_000,     # 108 MHz
+  #     step_size: 100_000,        # 100 kHz steps
+  #     dwell_time: 0.1            # 100ms per frequency
+  #   )
+  #
+  #   scanner.scan do |result|
+  #     puts "#{result[:frequency] / 1e6} MHz: #{result[:power]} dBm"
+  #   end
+  #
+  # @example Find strong signals
+  #   peaks = scanner.find_peaks(threshold: -60)
+  #   peaks.each do |peak|
+  #     puts "Strong signal at #{peak[:frequency] / 1e6} MHz"
+  #   end
+  class Scanner
+    attr_reader :device, :start_freq, :end_freq, :step_size, :dwell_time
+
+    def initialize(device, start_freq:, end_freq:, step_size: 1_000_000, dwell_time: 0.1)
+      @device = device
+      @start_freq = start_freq
+      @end_freq = end_freq
+      @step_size = step_size
+      @dwell_time = dwell_time
+      @scanning = false
+    end
+
+    def frequencies
+      (@start_freq..@end_freq).step(@step_size).to_a
+    end
+
+    def frequency_count
+      ((end_freq - start_freq) / step_size).to_i + 1
+    end
+
+    # Perform a sweep scan
+    def scan(samples_per_freq: 1024, &block)
+      raise ArgumentError, "Block required for scan" unless block_given?
+
+      @scanning = true
+      results = {}
+
+      frequencies.each do |freq|
+        break unless @scanning
+
+        @device.center_freq = freq
+        sleep(@dwell_time)
+
+        samples = @device.read_samples(samples_per_freq)
+        power = DSP.average_power(samples)
+
+        result = {
+          frequency: freq,
+          power: power,
+          samples: samples,
+          timestamp: Time.now
+        }
+
+        results[freq] = result
+        block.call(result)
+      end
+
+      @scanning = false
+      results
+    end
+
+    # Async sweep scan
+    def scan_async(samples_per_freq: 1024, &block)
+      raise ArgumentError, "Block required for async scan" unless block_given?
+
+      Thread.new do
+        scan(samples_per_freq: samples_per_freq, &block)
+      end
+    end
+
+    # Find peaks in the spectrum
+    def find_peaks(threshold: -60, samples_per_freq: 1024)
+      peaks = []
+
+      scan(samples_per_freq: samples_per_freq) do |result|
+        power_db = 10 * Math.log10(result[:power] + 1e-10)
+        if power_db > threshold
+          peaks << {
+            frequency: result[:frequency],
+            power: result[:power],
+            power_db: power_db,
+            timestamp: result[:timestamp]
+          }
+        end
+      end
+
+      peaks.sort_by { |peak| -peak[:power] }
+    end
+
+    # Power sweep - returns array of [frequency, power] pairs
+    def power_sweep(samples_per_freq: 1024)
+      results = []
+
+      scan(samples_per_freq: samples_per_freq) do |result|
+        power_db = 10 * Math.log10(result[:power] + 1e-10)
+        results << [result[:frequency], power_db]
+      end
+
+      results
+    end
+
+    def stop
+      @scanning = false
+    end
+
+    def scanning?
+      @scanning
+    end
+
+    # Configure scan parameters
+    def configure(start_freq: nil, end_freq: nil, step_size: nil, dwell_time: nil)
+      @start_freq = start_freq if start_freq
+      @end_freq = end_freq if end_freq
+      @step_size = step_size if step_size
+      @dwell_time = dwell_time if dwell_time
+      self
+    end
+
+    def inspect
+      "#<RTLSDR::Scanner #{@start_freq / 1e6}MHz-#{@end_freq / 1e6}MHz step=#{@step_size / 1e6}MHz dwell=#{@dwell_time}s>" # rubocop:disable Layout/LineLength
+    end
+  end
+end

data/lib/rtlsdr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RTLSDR
+  VERSION = "0.1.0"
+end

data/lib/rtlsdr.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "rtlsdr/version"
+require_relative "rtlsdr/ffi"
+require_relative "rtlsdr/device"
+require_relative "rtlsdr/errors"
+require_relative "rtlsdr/dsp"
+require_relative "rtlsdr/scanner"
+
+# 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
+#
+# @example 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
+#
+# @example List all devices
+#   RTLSDR.devices.each do |dev|
+#     puts "#{dev[:index]}: #{dev[:name]}"
+#   end
+module RTLSDR
+  class << self
+    # Get the number of connected RTL-SDR devices
+    def device_count
+      FFI.rtlsdr_get_device_count
+    end
+
+    # Get the name of a device by index
+    def device_name(index)
+      FFI.rtlsdr_get_device_name(index)
+    end
+
+    # Get USB strings for a device by index
+    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
+
+    # Find device index by serial number
+    def find_device_by_serial(serial)
+      result = FFI.rtlsdr_get_index_by_serial(serial)
+      return nil if result.negative?
+
+      result
+    end
+
+    # Open a device and return a Device instance
+    def open(index = 0)
+      Device.new(index)
+    end
+
+    # List all available devices
+    def devices
+      (0...device_count).map do |i|
+        {
+          index: i,
+          name: device_name(i),
+          usb_strings: device_usb_strings(i)
+        }
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: rtlsdr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- joshfng
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: Ruby bindings for librtlsdr - turn RTL2832 based DVB dongles into SDR
+  receivers
+email:
+- me@joshfrye.dev
+executables:
+- rtlsdr
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/basic_usage.rb
+- examples/spectrum_analyzer.rb
+- exe/rtlsdr
+- lib/rtlsdr.rb
+- lib/rtlsdr/device.rb
+- lib/rtlsdr/dsp.rb
+- lib/rtlsdr/errors.rb
+- lib/rtlsdr/ffi.rb
+- lib/rtlsdr/scanner.rb
+- lib/rtlsdr/version.rb
+homepage: https://github.com/joshfng/rtlsdr-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/joshfng/rtlsdr-ruby
+  source_code_uri: https://github.com/joshfng/rtlsdr-ruby
+  changelog_uri: https://github.com/joshfng/rtlsdr-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Ruby bindings for librtlsdr
+test_files: []