rtlsdr 0.1.0 → 0.1.1

data/lib/rtlsdr/device.rb

@@ -43,8 +43,22 @@ module RTLSDR
   class Device
     include Enumerable
 
-    attr_reader :index, :handle
-
+    # @return [Integer] Device index (0-based)
+    attr_reader :index
+    # @return [FFI::Pointer] Internal device handle pointer
+    attr_reader :handle
+
+    # Create a new RTL-SDR device instance
+    #
+    # Opens the specified RTL-SDR device and prepares it for use. The device
+    # will be automatically opened during initialization.
+    #
+    # @param [Integer] index Device index to open (default: 0)
+    # @raise [DeviceNotFoundError] if device doesn't exist
+    # @raise [DeviceOpenError] if device cannot be opened
+    # @example Create device instance
+    #   device = RTLSDR::Device.new(0)
+    #   puts "Opened: #{device.name}"
     def initialize(index = 0)
       @index = index
       @handle = nil
@@ -59,6 +73,16 @@ module RTLSDR
       !@handle.nil?
     end
 
+    # Close the RTL-SDR device
+    #
+    # Closes the device handle and releases system resources. If async reading
+    # is active, it will be cancelled first. After closing, the device cannot
+    # be used until reopened.
+    #
+    # @return [void]
+    # @example Close device
+    #   device.close
+    #   puts "Device closed"
     def close
       return unless open?
 
@@ -68,6 +92,9 @@ module RTLSDR
       check_result(result, "Failed to close device")
     end
 
+    # Check if the device is closed
+    #
+    # @return [Boolean] true if device is closed, false if open
     def closed?
       !open?
     end
@@ -77,6 +104,15 @@ module RTLSDR
       RTLSDR.device_name(@index)
     end
 
+    # Get USB device strings
+    #
+    # Retrieves the USB manufacturer, product, and serial number strings
+    # for this device. Results are cached after the first call.
+    #
+    # @return [Hash] Hash with :manufacturer, :product, :serial keys
+    # @example Get USB information
+    #   usb_info = device.usb_strings
+    #   puts "#{usb_info[:manufacturer]} #{usb_info[:product]}"
     def usb_strings
       return @usb_strings if @usb_strings
 
@@ -94,10 +130,22 @@ module RTLSDR
       }
     end
 
+    # Get the tuner type constant
+    #
+    # Returns the tuner type as one of the RTLSDR_TUNER_* constants.
+    # The result is cached after the first call.
+    #
+    # @return [Integer] Tuner type constant
+    # @see RTLSDR::FFI::RTLSDR_TUNER_*
     def tuner_type
       @tuner_type ||= FFI.rtlsdr_get_tuner_type(@handle)
     end
 
+    # Get human-readable tuner name
+    #
+    # @return [String] Tuner chip name and manufacturer
+    # @example Get tuner information
+    #   puts "Tuner: #{device.tuner_name}"
     def tuner_name
       FFI.tuner_type_name(tuner_type)
     end
@@ -108,17 +156,33 @@ module RTLSDR
       check_result(result, "Failed to set center frequency")
     end
 
+    # Get the current center frequency
+    #
+    # @return [Integer] Center frequency in Hz
     def center_freq
       FFI.rtlsdr_get_center_freq(@handle)
     end
+    # @!method frequency
+    #   Alias for {#center_freq}
+    #   @return [Integer] Center frequency in Hz
     alias frequency center_freq
+    # @!method frequency=
+    #   Alias for {#center_freq=}
     alias frequency= center_freq=
 
+    # Set frequency correction in PPM
+    #
+    # @param [Integer] ppm Frequency correction in parts per million
+    # @example Set 15 PPM correction
+    #   device.freq_correction = 15
     def freq_correction=(ppm)
       result = FFI.rtlsdr_set_freq_correction(@handle, ppm)
       check_result(result, "Failed to set frequency correction")
     end
 
+    # Get current frequency correction
+    #
+    # @return [Integer] Frequency correction in PPM
     def freq_correction
       FFI.rtlsdr_get_freq_correction(@handle)
     end
@@ -130,6 +194,9 @@ module RTLSDR
       [rtl_freq, tuner_freq]
     end
 
+    # Get crystal oscillator frequencies
+    #
+    # @return [Array<Integer>] Array of [rtl_freq, tuner_freq] in Hz
     def xtal_freq
       rtl_freq_ptr = ::FFI::MemoryPointer.new(:uint32)
       tuner_freq_ptr = ::FFI::MemoryPointer.new(:uint32)
@@ -154,37 +221,67 @@ module RTLSDR
       gains_ptr.read_array_of_int(result)
     end
 
+    # Set tuner gain in tenths of dB
+    #
+    # @param [Integer] gain Gain in tenths of dB (e.g., 496 = 49.6 dB)
+    # @example Set 40 dB gain
+    #   device.tuner_gain = 400
     def tuner_gain=(gain)
       result = FFI.rtlsdr_set_tuner_gain(@handle, gain)
       check_result(result, "Failed to set tuner gain")
     end
 
+    # Get current tuner gain
+    #
+    # @return [Integer] Current gain in tenths of dB
     def tuner_gain
       FFI.rtlsdr_get_tuner_gain(@handle)
     end
+    # @!method gain
+    #   Alias for {#tuner_gain}
+    #   @return [Integer] Current gain in tenths of dB
     alias gain tuner_gain
+    # @!method gain=
+    #   Alias for {#tuner_gain=}
     alias gain= tuner_gain=
 
+    # Set gain mode (manual or automatic)
+    #
+    # @param [Boolean] manual true for manual gain mode, false for automatic
     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
 
+    # Enable manual gain mode
+    #
+    # @return [Boolean] true
     def manual_gain_mode!
       self.tuner_gain_mode = true
     end
 
+    # Enable automatic gain mode
+    #
+    # @return [Boolean] false
     def auto_gain_mode!
       self.tuner_gain_mode = false
     end
 
+    # Set IF gain for specific stage
+    #
+    # @param [Integer] stage IF stage number
+    # @param [Integer] gain Gain value in tenths of dB
+    # @return [Integer] The gain value that was set
     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
 
+    # Set tuner bandwidth
+    #
+    # @param [Integer] bw Bandwidth in Hz
     def tuner_bandwidth=(bw)
       result = FFI.rtlsdr_set_tuner_bandwidth(@handle, bw)
       check_result(result, "Failed to set bandwidth")
@@ -196,10 +293,18 @@ module RTLSDR
       check_result(result, "Failed to set sample rate")
     end
 
+    # Get current sample rate
+    #
+    # @return [Integer] Sample rate in Hz
     def sample_rate
       FFI.rtlsdr_get_sample_rate(@handle)
     end
+    # @!method samp_rate
+    #   Alias for {#sample_rate}
+    #   @return [Integer] Sample rate in Hz
     alias samp_rate sample_rate
+    # @!method samp_rate=
+    #   Alias for {#sample_rate=}
     alias samp_rate= sample_rate=
 
     # Mode control
@@ -209,25 +314,40 @@ module RTLSDR
       check_result(result, "Failed to set test mode")
     end
 
+    # Enable test mode
+    #
+    # @return [Boolean] true
     def test_mode!
       self.test_mode = true
     end
 
+    # Set automatic gain control mode
+    #
+    # @param [Boolean] enabled true to enable AGC, false to disable
     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
 
+    # Enable automatic gain control
+    #
+    # @return [Boolean] true
     def agc_mode!
       self.agc_mode = true
     end
 
+    # Set direct sampling mode
+    #
+    # @param [Integer] mode Direct sampling mode (0=off, 1=I-ADC, 2=Q-ADC)
     def direct_sampling=(mode)
       result = FFI.rtlsdr_set_direct_sampling(@handle, mode)
       check_result(result, "Failed to set direct sampling")
     end
 
+    # Get current direct sampling mode
+    #
+    # @return [Integer, nil] Direct sampling mode or nil on error
     def direct_sampling
       result = FFI.rtlsdr_get_direct_sampling(@handle)
       return nil if result.negative?
@@ -235,12 +355,18 @@ module RTLSDR
       result
     end
 
+    # Set offset tuning mode
+    #
+    # @param [Boolean] enabled true to enable offset tuning, false to disable
     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
 
+    # Get current offset tuning mode
+    #
+    # @return [Boolean, nil] true if enabled, false if disabled, nil on error
     def offset_tuning
       result = FFI.rtlsdr_get_offset_tuning(@handle)
       return nil if result.negative?
@@ -248,6 +374,9 @@ module RTLSDR
       result == 1
     end
 
+    # Enable offset tuning
+    #
+    # @return [Boolean] true
     def offset_tuning!
       self.offset_tuning = true
     end
@@ -259,10 +388,18 @@ module RTLSDR
       check_result(result, "Failed to set bias tee")
     end
 
+    # Enable bias tee
+    #
+    # @return [Boolean] true
     def bias_tee!
       self.bias_tee = true
     end
 
+    # Set bias tee GPIO state
+    #
+    # @param [Integer] gpio GPIO pin number
+    # @param [Boolean] enabled true to enable, false to disable
+    # @return [Boolean] The enabled state that was set
     def set_bias_tee_gpio(gpio, enabled)
       mode = enabled ? 1 : 0
       result = FFI.rtlsdr_set_bias_tee_gpio(@handle, gpio, mode)
@@ -278,6 +415,11 @@ module RTLSDR
       data_ptr.read_array_of_uint8(length)
     end
 
+    # Write data to EEPROM
+    #
+    # @param [Array<Integer>] data Array of bytes to write
+    # @param [Integer] offset EEPROM offset address
+    # @return [Integer] Number of bytes written
     def write_eeprom(data, offset)
       data_ptr = ::FFI::MemoryPointer.new(:uint8, data.length)
       data_ptr.write_array_of_uint8(data)
@@ -292,6 +434,13 @@ module RTLSDR
       check_result(result, "Failed to reset buffer")
     end
 
+    # Read raw IQ data synchronously
+    #
+    # Reads raw 8-bit IQ data from the device. The buffer is automatically
+    # reset on the first read to avoid stale data.
+    #
+    # @param [Integer] length Number of bytes to read
+    # @return [Array<Integer>] Array of 8-bit unsigned integers
     def read_sync(length)
       # Reset buffer before first read to avoid stale data
       reset_buffer unless @buffer_reset_done
@@ -307,6 +456,16 @@ module RTLSDR
       buffer.read_array_of_uint8(n_read)
     end
 
+    # Read complex samples synchronously
+    #
+    # Reads the specified number of complex samples from the device and
+    # converts them from raw 8-bit IQ data to Ruby Complex numbers.
+    #
+    # @param [Integer] count Number of complex samples to read (default: 1024)
+    # @return [Array<Complex>] Array of complex samples
+    # @example Read 2048 samples
+    #   samples = device.read_samples(2048)
+    #   puts "Read #{samples.length} samples"
     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)
@@ -322,10 +481,24 @@ module RTLSDR
       samples
     end
 
+    # Check if asynchronous streaming is active
+    #
+    # @return [Boolean] true if streaming, false otherwise
     def streaming?
       @streaming
     end
 
+    # Read raw IQ data asynchronously
+    #
+    # Starts asynchronous reading of raw 8-bit IQ data. The provided block
+    # will be called for each buffer of data received.
+    #
+    # @param [Integer] buffer_count Number of buffers to use (default: 15)
+    # @param [Integer] buffer_length Length of each buffer in bytes (default: 262144)
+    # @yield [Array<Integer>] Block called with each buffer of raw IQ data
+    # @return [Thread] Thread object running the async operation
+    # @raise [ArgumentError] if no block is provided
+    # @raise [OperationFailedError] if already streaming
     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?
@@ -349,6 +522,16 @@ module RTLSDR
       @async_thread
     end
 
+    # Read complex samples asynchronously
+    #
+    # Starts asynchronous reading and converts raw IQ data to complex samples.
+    # The provided block will be called for each buffer of complex samples.
+    #
+    # @param [Integer] buffer_count Number of buffers to use (default: 15)
+    # @param [Integer] buffer_length Length of each buffer in bytes (default: 262144)
+    # @yield [Array<Complex>] Block called with each buffer of complex samples
+    # @return [Thread] Thread object running the async operation
+    # @raise [ArgumentError] if no block is provided
     def read_samples_async(buffer_count: 15, buffer_length: 262_144, &block)
       raise ArgumentError, "Block required for async reading" unless block_given?
 
@@ -365,6 +548,12 @@ module RTLSDR
       end
     end
 
+    # Cancel asynchronous reading operation
+    #
+    # Stops any active asynchronous reading and cleans up resources.
+    # This method is safe to call from within async callbacks.
+    #
+    # @return [void]
     def cancel_async
       return unless streaming?
 
@@ -439,6 +628,9 @@ module RTLSDR
       }
     end
 
+    # Return string representation of device
+    #
+    # @return [String] Human-readable device information
     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
@@ -449,6 +641,12 @@ module RTLSDR
 
     private
 
+    # Open the RTL-SDR device handle
+    #
+    # @return [void]
+    # @raise [DeviceNotFoundError] if device doesn't exist
+    # @raise [DeviceOpenError] if device cannot be opened
+    # @private
     def open_device
       dev_ptr = ::FFI::MemoryPointer.new(:pointer)
       result = FFI.rtlsdr_open(dev_ptr, @index)
@@ -467,6 +665,13 @@ module RTLSDR
       end
     end
 
+    # Check FFI function result and raise appropriate error
+    #
+    # @param [Integer] result Return code from FFI function
+    # @param [String] message Error message prefix
+    # @return [void]
+    # @raise [DeviceNotOpenError, InvalidArgumentError, EEPROMError, OperationFailedError]
+    # @private
     def check_result(result, message)
       return if result.zero?
 

data/lib/rtlsdr/dsp.rb

@@ -33,6 +33,17 @@ module RTLSDR
   #   phases = RTLSDR::DSP.phase(filtered)
   module DSP
     # Convert raw IQ data to complex samples
+    #
+    # Converts raw 8-bit IQ data from RTL-SDR devices to Ruby Complex numbers.
+    # The RTL-SDR outputs unsigned 8-bit integers centered at 128, which are
+    # converted to floating point values in the range [-1.0, 1.0].
+    #
+    # @param [Array<Integer>] data Array of 8-bit unsigned integers (I, Q, I, Q, ...)
+    # @return [Array<Complex>] Array of Complex numbers representing I+jQ samples
+    # @example Convert device samples
+    #   raw_data = [127, 130, 125, 135, 120, 140]  # 3 IQ pairs
+    #   samples = RTLSDR::DSP.iq_to_complex(raw_data)
+    #   # => [(-0.008+0.016i), (-0.024+0.055i), (-0.063+0.094i)]
     def self.iq_to_complex(data)
       samples = []
       (0...data.length).step(2) do |i|
@@ -44,6 +55,18 @@ module RTLSDR
     end
 
     # Calculate power spectral density
+    #
+    # Computes a basic power spectrum from complex samples using windowing.
+    # This applies a Hanning window to reduce spectral leakage and then
+    # calculates the power (magnitude squared) for each sample. A proper
+    # FFT implementation would require an external library.
+    #
+    # @param [Array<Complex>] samples Array of complex samples
+    # @param [Integer] window_size Size of the analysis window (default 1024)
+    # @return [Array<Float>] Power spectrum values
+    # @example Calculate spectrum
+    #   spectrum = RTLSDR::DSP.power_spectrum(samples, 512)
+    #   max_power = spectrum.max
     def self.power_spectrum(samples, window_size = 1024)
       return [] if samples.length < window_size
 
@@ -59,7 +82,16 @@ module RTLSDR
       windowed_samples.map { |s| ((s.real**2) + (s.imag**2)) }
     end
 
-    # Calculate average power
+    # Calculate average power of complex samples
+    #
+    # Computes the mean power (magnitude squared) across all samples.
+    # This is useful for signal strength measurements and AGC calculations.
+    #
+    # @param [Array<Complex>] samples Array of complex samples
+    # @return [Float] Average power value (0.0 if no samples)
+    # @example Measure signal power
+    #   power = RTLSDR::DSP.average_power(samples)
+    #   power_db = 10 * Math.log10(power + 1e-10)
     def self.average_power(samples)
       return 0.0 if samples.empty?
 
@@ -67,7 +99,17 @@ module RTLSDR
       total_power / samples.length
     end
 
-    # Find peak power and frequency bin
+    # Find peak power and frequency bin in spectrum
+    #
+    # Locates the frequency bin with maximum power in a power spectrum.
+    # Returns both the bin index and the power value at that bin.
+    #
+    # @param [Array<Float>] power_spectrum Array of power values
+    # @return [Array<Integer, Float>] [bin_index, peak_power] or [0, 0.0] if empty
+    # @example Find strongest signal
+    #   spectrum = RTLSDR::DSP.power_spectrum(samples)
+    #   peak_bin, peak_power = RTLSDR::DSP.find_peak(spectrum)
+    #   freq_offset = (peak_bin - spectrum.length/2) * sample_rate / spectrum.length
     def self.find_peak(power_spectrum)
       return [0, 0.0] if power_spectrum.empty?
 
@@ -76,7 +118,17 @@ module RTLSDR
       [max_index, max_power]
     end
 
-    # DC removal (high-pass filter)
+    # Remove DC component using high-pass filter
+    #
+    # Applies a simple first-order high-pass filter to remove DC bias
+    # from the signal. This is useful for RTL-SDR devices which often
+    # have a DC offset in their I/Q samples.
+    #
+    # @param [Array<Complex>] samples Array of complex samples
+    # @param [Float] alpha Filter coefficient (0.995 = ~160Hz cutoff at 2.4MHz sample rate)
+    # @return [Array<Complex>] Filtered samples with DC component removed
+    # @example Remove DC bias
+    #   clean_samples = RTLSDR::DSP.remove_dc(samples, 0.99)
     def self.remove_dc(samples, alpha = 0.995)
       return samples if samples.empty?
 
@@ -87,17 +139,46 @@ module RTLSDR
       filtered
     end
 
-    # Simple magnitude detection
+    # Extract magnitude from complex samples
+    #
+    # Calculates the magnitude (absolute value) of each complex sample.
+    # This converts I+jQ samples to their envelope/amplitude values.
+    #
+    # @param [Array<Complex>] samples Array of complex samples
+    # @return [Array<Float>] Array of magnitude values
+    # @example Get signal envelope
+    #   magnitudes = RTLSDR::DSP.magnitude(samples)
+    #   peak_amplitude = magnitudes.max
     def self.magnitude(samples)
       samples.map(&:abs)
     end
 
-    # Phase detection
+    # Extract phase from complex samples
+    #
+    # Calculates the phase angle (argument) of each complex sample in radians.
+    # The phase represents the angle between the I and Q components.
+    #
+    # @param [Array<Complex>] samples Array of complex samples
+    # @return [Array<Float>] Array of phase values in radians (-π to π)
+    # @example Get phase information
+    #   phases = RTLSDR::DSP.phase(samples)
+    #   phase_degrees = phases.map { |p| p * 180 / Math::PI }
     def self.phase(samples)
       samples.map { |s| Math.atan2(s.imag, s.real) }
     end
 
-    # Frequency estimation using zero crossings
+    # Estimate frequency using zero-crossing detection
+    #
+    # Provides a rough frequency estimate by counting zero crossings in the
+    # magnitude signal. This is a simple method that works reasonably well
+    # for single-tone signals but may be inaccurate for complex signals.
+    #
+    # @param [Array<Complex>] samples Array of complex samples
+    # @param [Integer] sample_rate Sample rate in Hz
+    # @return [Float] Estimated frequency in Hz
+    # @example Estimate carrier frequency
+    #   freq_hz = RTLSDR::DSP.estimate_frequency(samples, 2_048_000)
+    #   puts "Estimated frequency: #{freq_hz} Hz"
     def self.estimate_frequency(samples, sample_rate)
       return 0.0 if samples.length < 2
 

data/lib/rtlsdr/errors.rb

@@ -1,12 +1,72 @@
 # frozen_string_literal: true
 
 module RTLSDR
+  # Base error class for all RTL-SDR related exceptions
+  #
+  # This is the parent class for all RTL-SDR specific errors. It extends
+  # Ruby's StandardError and provides a consistent error hierarchy for
+  # the gem. All other RTL-SDR errors inherit from this class.
+  #
+  # @since 0.1.0
   class Error < StandardError; end
+
+  # Raised when a requested device cannot be found
+  #
+  # This exception is thrown when attempting to open or access a device
+  # by index that doesn't exist, or when a device with a specific serial
+  # number cannot be located.
+  #
+  # @since 0.1.0
   class DeviceNotFoundError < Error; end
+
+  # Raised when a device cannot be opened
+  #
+  # This exception occurs when a device exists but cannot be opened,
+  # typically because it's already in use by another process or the
+  # user lacks sufficient permissions.
+  #
+  # @since 0.1.0
   class DeviceOpenError < Error; end
+
+  # Raised when attempting to use a device that hasn't been opened
+  #
+  # This exception is thrown when trying to perform operations on a
+  # device that has been closed or was never properly opened.
+  #
+  # @since 0.1.0
   class DeviceNotOpenError < Error; end
+
+  # Raised when invalid arguments are passed to device functions
+  #
+  # This exception occurs when function parameters are out of range,
+  # of the wrong type, or otherwise invalid for the requested operation.
+  #
+  # @since 0.1.0
   class InvalidArgumentError < Error; end
+
+  # Raised when a device operation fails
+  #
+  # This is a general exception for operations that fail at the hardware
+  # or driver level, such as setting frequencies, gains, or sample rates
+  # that the device cannot support.
+  #
+  # @since 0.1.0
   class OperationFailedError < Error; end
+
+  # Raised when EEPROM operations fail
+  #
+  # This exception occurs when reading from or writing to the device's
+  # EEPROM memory fails, either due to hardware issues or invalid
+  # memory addresses.
+  #
+  # @since 0.1.0
   class EEPROMError < Error; end
+
+  # Raised when asynchronous callback operations fail
+  #
+  # This exception is thrown when errors occur within the async reading
+  # callback functions, typically during real-time sample processing.
+  #
+  # @since 0.1.0
   class CallbackError < Error; end
 end