rtlsdr 0.1.0

data/examples/spectrum_analyzer.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rtlsdr"
+
+# Simple spectrum analyzer example
+class SpectrumAnalyzer
+  def initialize(device_index = 0)
+    @device = RTLSDR.open(device_index)
+    puts "Opened device: #{@device.inspect}"
+
+    # Configure device
+    @device.configure(
+      frequency: 100_000_000,    # 100 MHz
+      sample_rate: 2_048_000,    # 2.048 MHz
+      gain: 400,                 # 40.0 dB
+      agc_mode: false
+    )
+
+    puts "Device info:"
+    puts "  Tuner: #{@device.tuner_name}"
+    puts "  Center frequency: #{@device.center_freq / 1e6} MHz"
+    puts "  Sample rate: #{@device.sample_rate / 1e6} MHz"
+    puts "  Gain: #{@device.tuner_gain / 10.0} dB"
+    puts "  Available gains: #{@device.tuner_gains.map { |g| g / 10.0 }} dB"
+  end
+
+  def analyze_current_frequency(samples_count = 8192)
+    puts "\nAnalyzing #{samples_count} samples at #{@device.center_freq / 1e6} MHz..."
+
+    samples = @device.read_samples(samples_count)
+
+    avg_power = RTLSDR::DSP.average_power(samples)
+    power_db = 10 * Math.log10(avg_power + 1e-10)
+
+    magnitude = RTLSDR::DSP.magnitude(samples)
+    RTLSDR::DSP.phase(samples)
+
+    puts "  Average power: #{power_db.round(2)} dB"
+    puts "  Peak magnitude: #{magnitude.max.round(4)}"
+    puts "  Sample count: #{samples.length}"
+
+    # Estimate frequency content
+    freq_est = RTLSDR::DSP.estimate_frequency(samples, @device.sample_rate)
+    puts "  Estimated frequency offset: #{freq_est.round(2)} Hz"
+
+    samples
+  end
+
+  def frequency_sweep(start_freq, end_freq, step = 1_000_000)
+    scanner = RTLSDR::Scanner.new(@device,
+                                  start_freq: start_freq,
+                                  end_freq: end_freq,
+                                  step_size: step,
+                                  dwell_time: 0.05)
+
+    puts "\nPerforming frequency sweep from #{start_freq / 1e6} MHz to #{end_freq / 1e6} MHz"
+    puts "Step size: #{step / 1e6} MHz"
+    puts "Frequencies to scan: #{scanner.frequency_count}"
+
+    results = scanner.power_sweep(samples_per_freq: 2048)
+
+    puts "\nSweep results (top 10 strongest signals):"
+    results.sort_by { |_freq, power| -power }.first(10).each do |freq, power_db|
+      puts "  #{(freq / 1e6).round(3)} MHz: #{power_db.round(2)} dB"
+    end
+
+    results
+  end
+
+  def find_active_frequencies(start_freq, end_freq, threshold = -50)
+    scanner = RTLSDR::Scanner.new(@device,
+                                  start_freq: start_freq,
+                                  end_freq: end_freq,
+                                  step_size: 500_000)
+
+    puts "\nScanning for active frequencies above #{threshold} dB..."
+    peaks = scanner.find_peaks(threshold: threshold, samples_per_freq: 4096)
+
+    if peaks.empty?
+      puts "No signals found above #{threshold} dB threshold"
+    else
+      puts "Found #{peaks.length} active frequencies:"
+      peaks.each do |peak|
+        puts "  #{(peak[:frequency] / 1e6).round(3)} MHz: #{peak[:power_db].round(2)} dB"
+      end
+    end
+
+    peaks
+  end
+
+  def monitor_frequency(frequency = 100 * 1e6, duration = 1)
+    puts "\nMonitoring #{frequency / 1e6} MHz for #{duration} seconds..."
+
+    start_time = Time.now
+    sample_count = 0
+    monitoring = true
+
+    # Start async reading in a separate thread
+    monitoring_thread = @device.read_samples_async(buffer_count: 8, buffer_length: 32_768) do |samples|
+      next unless monitoring
+
+      sample_count += samples.length
+      elapsed = Time.now - start_time
+
+      if elapsed >= duration
+        monitoring = false
+        next
+      end
+
+      avg_power = RTLSDR::DSP.average_power(samples)
+      power_db = 10 * Math.log10(avg_power + 1e-10)
+
+      print "\rTime: #{elapsed.round(1)}s, Samples: #{sample_count}, Power: #{power_db.round(2)} dB"
+      $stdout.flush
+    end
+
+    # Wait for completion or timeout
+    start_wait = Time.now
+    sleep(0.1) while monitoring && (Time.now - start_wait) < (duration + 1.0)
+
+    # Cancel if still running
+    if @device.streaming?
+      @device.cancel_async
+      monitoring_thread&.join(1.0) # Wait up to 1 second for clean shutdown
+    end
+
+    puts "\nMonitoring complete. Total samples: #{sample_count}"
+  end
+
+  def close
+    @device&.close
+  end
+end
+
+# Main execution
+if __FILE__ == $PROGRAM_NAME
+  begin
+    puts "RTL-SDR Spectrum Analyzer Example"
+    puts "================================="
+
+    # Check for devices
+    puts "Available RTL-SDR devices:"
+    RTLSDR.devices.each_with_index do |device, i|
+      puts "  #{i}: #{device[:name]} (#{device[:usb_strings][:manufacturer]} #{device[:usb_strings][:product]})"
+    end
+
+    if RTLSDR.device_count.zero?
+      puts "No RTL-SDR devices found!"
+      exit 1
+    end
+
+    analyzer = SpectrumAnalyzer.new(0)
+
+    analyzer.analyze_current_frequency(4096)
+
+    analyzer.frequency_sweep(88_000_000, 108_000_000, 200_000)
+
+    frequencies = analyzer.find_active_frequencies(88_000_000, 108_000_000, -60)
+
+    frequencies.each do |freq|
+      analyzer.monitor_frequency(freq[:frequency], 1)
+    end
+
+    analyzer.monitor_frequency(5)
+  rescue RTLSDR::Error => e
+    puts "RTL-SDR Error: #{e.message}"
+    exit 1
+  rescue Interrupt
+    puts "\nInterrupted by user"
+  ensure
+    analyzer&.close
+    puts "Device closed."
+  end
+end

data/exe/rtlsdr

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rtlsdr"

data/lib/rtlsdr/device.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module RTLSDR
+  # High-level interface to RTL-SDR devices
+  #
+  # The Device class provides a Ruby-idiomatic interface to RTL-SDR dongles,
+  # wrapping the low-level librtlsdr C API with convenient methods and automatic
+  # resource management. It supports both synchronous and asynchronous sample
+  # reading, comprehensive device configuration, and implements Enumerable for
+  # streaming operations.
+  #
+  # Features:
+  # * Automatic device lifecycle management (open/close)
+  # * Frequency, gain, and sample rate control with validation
+  # * Multiple gain modes (manual, automatic, AGC)
+  # * Synchronous and asynchronous sample reading
+  # * IQ sample conversion to Ruby Complex numbers
+  # * EEPROM access and bias tee control
+  # * Enumerable interface for continuous streaming
+  # * Comprehensive error handling with custom exceptions
+  #
+  # @example Basic device setup
+  #   device = RTLSDR::Device.new(0)
+  #   device.configure(
+  #     frequency: 100_000_000,    # 100 MHz
+  #     sample_rate: 2_048_000,    # 2.048 MSPS
+  #     gain: 496                   # 49.6 dB
+  #   )
+  #
+  # @example Streaming samples
+  #   device.each(samples_per_read: 1024) do |samples|
+  #     power = RTLSDR::DSP.average_power(samples)
+  #     puts "Average power: #{power}"
+  #   end
+  #
+  # @example Asynchronous reading
+  #   device.read_samples_async do |samples|
+  #     # Process samples in real-time
+  #     spectrum = RTLSDR::DSP.power_spectrum(samples)
+  #   end
+  class Device
+    include Enumerable
+
+    attr_reader :index, :handle
+
+    def initialize(index = 0)
+      @index = index
+      @handle = nil
+      @streaming = false
+      @async_thread = nil
+      @buffer_reset_done = false
+      open_device
+    end
+
+    # Device lifecycle
+    def open?
+      !@handle.nil?
+    end
+
+    def close
+      return unless open?
+
+      cancel_async if streaming?
+      result = FFI.rtlsdr_close(@handle)
+      @handle = nil
+      check_result(result, "Failed to close device")
+    end
+
+    def closed?
+      !open?
+    end
+
+    # Device information
+    def name
+      RTLSDR.device_name(@index)
+    end
+
+    def usb_strings
+      return @usb_strings if @usb_strings
+
+      manufact = " " * 256
+      product = " " * 256
+      serial = " " * 256
+
+      result = FFI.rtlsdr_get_usb_strings(@handle, manufact, product, serial)
+      check_result(result, "Failed to get USB strings")
+
+      @usb_strings = {
+        manufacturer: manufact.strip,
+        product: product.strip,
+        serial: serial.strip
+      }
+    end
+
+    def tuner_type
+      @tuner_type ||= FFI.rtlsdr_get_tuner_type(@handle)
+    end
+
+    def tuner_name
+      FFI.tuner_type_name(tuner_type)
+    end
+
+    # Frequency control
+    def center_freq=(freq)
+      result = FFI.rtlsdr_set_center_freq(@handle, freq)
+      check_result(result, "Failed to set center frequency")
+    end
+
+    def center_freq
+      FFI.rtlsdr_get_center_freq(@handle)
+    end
+    alias frequency center_freq
+    alias frequency= center_freq=
+
+    def freq_correction=(ppm)
+      result = FFI.rtlsdr_set_freq_correction(@handle, ppm)
+      check_result(result, "Failed to set frequency correction")
+    end
+
+    def freq_correction
+      FFI.rtlsdr_get_freq_correction(@handle)
+    end
+
+    # Crystal oscillator frequencies
+    def set_xtal_freq(rtl_freq, tuner_freq)
+      result = FFI.rtlsdr_set_xtal_freq(@handle, rtl_freq, tuner_freq)
+      check_result(result, "Failed to set crystal frequencies")
+      [rtl_freq, tuner_freq]
+    end
+
+    def xtal_freq
+      rtl_freq_ptr = ::FFI::MemoryPointer.new(:uint32)
+      tuner_freq_ptr = ::FFI::MemoryPointer.new(:uint32)
+
+      result = FFI.rtlsdr_get_xtal_freq(@handle, rtl_freq_ptr, tuner_freq_ptr)
+      check_result(result, "Failed to get crystal frequencies")
+
+      [rtl_freq_ptr.read_uint32, tuner_freq_ptr.read_uint32]
+    end
+
+    # Gain control
+    def tuner_gains
+      # First call to get count
+      count = FFI.rtlsdr_get_tuner_gains(@handle, nil)
+      return [] if count <= 0
+
+      # Second call to get actual gains
+      gains_ptr = ::FFI::MemoryPointer.new(:int, count)
+      result = FFI.rtlsdr_get_tuner_gains(@handle, gains_ptr)
+      return [] if result <= 0
+
+      gains_ptr.read_array_of_int(result)
+    end
+
+    def tuner_gain=(gain)
+      result = FFI.rtlsdr_set_tuner_gain(@handle, gain)
+      check_result(result, "Failed to set tuner gain")
+    end
+
+    def tuner_gain
+      FFI.rtlsdr_get_tuner_gain(@handle)
+    end
+    alias gain tuner_gain
+    alias gain= tuner_gain=
+
+    def tuner_gain_mode=(manual)
+      mode = manual ? 1 : 0
+      result = FFI.rtlsdr_set_tuner_gain_mode(@handle, mode)
+      check_result(result, "Failed to set gain mode")
+    end
+
+    def manual_gain_mode!
+      self.tuner_gain_mode = true
+    end
+
+    def auto_gain_mode!
+      self.tuner_gain_mode = false
+    end
+
+    def set_tuner_if_gain(stage, gain)
+      result = FFI.rtlsdr_set_tuner_if_gain(@handle, stage, gain)
+      check_result(result, "Failed to set IF gain")
+      gain
+    end
+
+    def tuner_bandwidth=(bw)
+      result = FFI.rtlsdr_set_tuner_bandwidth(@handle, bw)
+      check_result(result, "Failed to set bandwidth")
+    end
+
+    # Sample rate control
+    def sample_rate=(rate)
+      result = FFI.rtlsdr_set_sample_rate(@handle, rate)
+      check_result(result, "Failed to set sample rate")
+    end
+
+    def sample_rate
+      FFI.rtlsdr_get_sample_rate(@handle)
+    end
+    alias samp_rate sample_rate
+    alias samp_rate= sample_rate=
+
+    # Mode control
+    def test_mode=(enabled)
+      mode = enabled ? 1 : 0
+      result = FFI.rtlsdr_set_testmode(@handle, mode)
+      check_result(result, "Failed to set test mode")
+    end
+
+    def test_mode!
+      self.test_mode = true
+    end
+
+    def agc_mode=(enabled)
+      mode = enabled ? 1 : 0
+      result = FFI.rtlsdr_set_agc_mode(@handle, mode)
+      check_result(result, "Failed to set AGC mode")
+    end
+
+    def agc_mode!
+      self.agc_mode = true
+    end
+
+    def direct_sampling=(mode)
+      result = FFI.rtlsdr_set_direct_sampling(@handle, mode)
+      check_result(result, "Failed to set direct sampling")
+    end
+
+    def direct_sampling
+      result = FFI.rtlsdr_get_direct_sampling(@handle)
+      return nil if result.negative?
+
+      result
+    end
+
+    def offset_tuning=(enabled)
+      mode = enabled ? 1 : 0
+      result = FFI.rtlsdr_set_offset_tuning(@handle, mode)
+      check_result(result, "Failed to set offset tuning")
+    end
+
+    def offset_tuning
+      result = FFI.rtlsdr_get_offset_tuning(@handle)
+      return nil if result.negative?
+
+      result == 1
+    end
+
+    def offset_tuning!
+      self.offset_tuning = true
+    end
+
+    # Bias tee control
+    def bias_tee=(enabled)
+      mode = enabled ? 1 : 0
+      result = FFI.rtlsdr_set_bias_tee(@handle, mode)
+      check_result(result, "Failed to set bias tee")
+    end
+
+    def bias_tee!
+      self.bias_tee = true
+    end
+
+    def set_bias_tee_gpio(gpio, enabled)
+      mode = enabled ? 1 : 0
+      result = FFI.rtlsdr_set_bias_tee_gpio(@handle, gpio, mode)
+      check_result(result, "Failed to set bias tee GPIO")
+      enabled
+    end
+
+    # EEPROM access
+    def read_eeprom(offset, length)
+      data_ptr = ::FFI::MemoryPointer.new(:uint8, length)
+      result = FFI.rtlsdr_read_eeprom(@handle, data_ptr, offset, length)
+      check_result(result, "Failed to read EEPROM")
+      data_ptr.read_array_of_uint8(length)
+    end
+
+    def write_eeprom(data, offset)
+      data_ptr = ::FFI::MemoryPointer.new(:uint8, data.length)
+      data_ptr.write_array_of_uint8(data)
+      result = FFI.rtlsdr_write_eeprom(@handle, data_ptr, offset, data.length)
+      check_result(result, "Failed to write EEPROM")
+      data.length
+    end
+
+    # Streaming control
+    def reset_buffer
+      result = FFI.rtlsdr_reset_buffer(@handle)
+      check_result(result, "Failed to reset buffer")
+    end
+
+    def read_sync(length)
+      # Reset buffer before first read to avoid stale data
+      reset_buffer unless @buffer_reset_done
+      @buffer_reset_done = true
+
+      buffer = ::FFI::MemoryPointer.new(:uint8, length)
+      n_read_ptr = ::FFI::MemoryPointer.new(:int)
+
+      result = FFI.rtlsdr_read_sync(@handle, buffer, length, n_read_ptr)
+      check_result(result, "Failed to read synchronously")
+
+      n_read = n_read_ptr.read_int
+      buffer.read_array_of_uint8(n_read)
+    end
+
+    def read_samples(count = 1024)
+      # RTL-SDR outputs 8-bit I/Q samples, so we need 2 bytes per complex sample
+      data = read_sync(count * 2)
+
+      # Convert to complex numbers (I + jQ)
+      samples = []
+      (0...data.length).step(2) do |i|
+        i_sample = (data[i] - 128) / 128.0      # Convert to -1.0 to 1.0 range
+        q_sample = (data[i + 1] - 128) / 128.0  # Convert to -1.0 to 1.0 range
+        samples << Complex(i_sample, q_sample)
+      end
+
+      samples
+    end
+
+    def streaming?
+      @streaming
+    end
+
+    def read_async(buffer_count: 15, buffer_length: 262_144, &block)
+      raise ArgumentError, "Block required for async reading" unless block_given?
+      raise OperationFailedError, "Already streaming" if streaming?
+
+      @streaming = true
+      @async_callback = proc do |buf_ptr, len, _ctx|
+        data = buf_ptr.read_array_of_uint8(len)
+        block.call(data)
+      rescue StandardError => e
+        puts "Error in async callback: #{e.message}"
+        cancel_async
+      end
+
+      @async_thread = Thread.new do
+        result = FFI.rtlsdr_read_async(@handle, @async_callback, nil, buffer_count, buffer_length)
+        @streaming = false
+        # Don't raise error for cancellation (-1) or timeout (-5)
+        check_result(result, "Async read failed") unless [-1, -5].include?(result)
+      end
+
+      @async_thread
+    end
+
+    def read_samples_async(buffer_count: 15, buffer_length: 262_144, &block)
+      raise ArgumentError, "Block required for async reading" unless block_given?
+
+      read_async(buffer_count: buffer_count, buffer_length: buffer_length) do |data|
+        # Convert to complex samples
+        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
+
+        block.call(samples)
+      end
+    end
+
+    def cancel_async
+      return unless streaming?
+
+      result = FFI.rtlsdr_cancel_async(@handle)
+      @streaming = false
+
+      # Only join if we're not calling from within the async thread itself
+      if @async_thread && @async_thread != Thread.current
+        @async_thread.join(1) # Wait up to 1 second for thread to finish
+      end
+
+      @async_thread = nil
+      @async_callback = nil
+
+      check_result(result, "Failed to cancel async operation")
+    end
+
+    # Enumerable interface for reading samples
+    def each(samples_per_read: 1024)
+      return enum_for(:each, samples_per_read: samples_per_read) unless block_given?
+
+      loop do
+        samples = read_samples(samples_per_read)
+        yield samples
+      rescue StandardError => e
+        break if e.is_a?(Interrupt)
+
+        raise
+      end
+    end
+
+    # Configuration shortcuts
+    def configure(frequency: nil, sample_rate: nil, gain: nil, **options)
+      self.center_freq = frequency if frequency
+      self.sample_rate = sample_rate if sample_rate
+
+      if gain
+        manual_gain_mode!
+        self.tuner_gain = gain
+      end
+
+      options.each do |key, value|
+        case key
+        when :freq_correction then self.freq_correction = value
+        when :bandwidth then self.tuner_bandwidth = value
+        when :agc_mode then self.agc_mode = value
+        when :test_mode then self.test_mode = value
+        when :bias_tee then self.bias_tee = value
+        when :direct_sampling then self.direct_sampling = value
+        when :offset_tuning then self.offset_tuning = value
+        end
+      end
+
+      self
+    end
+
+    # Device info as hash
+    def info
+      {
+        index: @index,
+        name: name,
+        usb_strings: usb_strings,
+        tuner_type: tuner_type,
+        tuner_name: tuner_name,
+        center_freq: center_freq,
+        sample_rate: sample_rate,
+        tuner_gain: tuner_gain,
+        tuner_gains: tuner_gains,
+        freq_correction: freq_correction,
+        direct_sampling: direct_sampling,
+        offset_tuning: offset_tuning
+      }
+    end
+
+    def inspect
+      if open?
+        "#<RTLSDR::Device:#{object_id.to_s(16)} index=#{@index} name=\"#{name}\" tuner=\"#{tuner_name}\" freq=#{center_freq}Hz rate=#{sample_rate}Hz>" # rubocop:disable Layout/LineLength
+      else
+        "#<RTLSDR::Device:#{object_id.to_s(16)} index=#{@index} closed>"
+      end
+    end
+
+    private
+
+    def open_device
+      dev_ptr = ::FFI::MemoryPointer.new(:pointer)
+      result = FFI.rtlsdr_open(dev_ptr, @index)
+
+      case result
+      when 0
+        @handle = dev_ptr.read_pointer
+      when -1
+        raise DeviceNotFoundError, "Device #{@index} not found"
+      when -2
+        raise DeviceOpenError, "Device #{@index} already in use"
+      when -3
+        raise DeviceOpenError, "Device #{@index} cannot be opened"
+      else
+        raise DeviceOpenError, "Failed to open device #{@index}: error #{result}"
+      end
+    end
+
+    def check_result(result, message)
+      return if result.zero?
+
+      error_msg = "#{message}: error #{result}"
+      case result
+      when -1 then raise DeviceNotOpenError, error_msg
+      when -2 then raise InvalidArgumentError, error_msg
+      when -3 then raise EEPROMError, error_msg
+      else raise OperationFailedError, error_msg
+      end
+    end
+  end
+end