rtlsdr 0.1.0 → 0.1.2

data/lib/rtlsdr/ffi.rb

@@ -30,6 +30,7 @@ module RTLSDR
   #
   # @note Most users should use the high-level RTLSDR::Device class instead
   #   of calling these FFI functions directly.
+  # @since 0.1.0
   module FFI
     extend ::FFI::Library
 
@@ -56,26 +57,54 @@ module RTLSDR
     # Opaque device pointer
     typedef :pointer, :rtlsdr_dev_t
 
-    # Tuner types enum
+    # Tuner types enum constants
+    #
+    # These constants identify the different tuner chips that can be found
+    # in RTL-SDR devices. Each tuner has different characteristics and
+    # supported frequency ranges.
+
+    # Unknown or unsupported tuner type
     RTLSDR_TUNER_UNKNOWN = 0
+    # Elonics E4000 tuner (52 - 2200 MHz with gaps)
     RTLSDR_TUNER_E4000 = 1
+    # Fitipower FC0012 tuner (22 - 948 MHz)
     RTLSDR_TUNER_FC0012 = 2
+    # Fitipower FC0013 tuner (22 - 1100 MHz)
     RTLSDR_TUNER_FC0013 = 3
+    # FCI FC2580 tuner (146 - 308 MHz and 438 - 924 MHz)
     RTLSDR_TUNER_FC2580 = 4
+    # Rafael Micro R820T tuner (24 - 1766 MHz)
     RTLSDR_TUNER_R820T = 5
+    # Rafael Micro R828D tuner (24 - 1766 MHz)
     RTLSDR_TUNER_R828D = 6
 
-    # Callback for async reading
+    # Callback function type for asynchronous reading
+    #
+    # This callback is called by the C library when new sample data is available
+    # during asynchronous reading operations. The callback receives a pointer to
+    # the buffer data, the length of the buffer, and a user context pointer.
     callback :rtlsdr_read_async_cb_t, %i[pointer uint32 pointer], :void
 
     # Device enumeration functions
+
+    # Get the number of available RTL-SDR devices
     attach_function :rtlsdr_get_device_count, [], :uint32
+
+    # Get the name of an RTL-SDR device by index
     attach_function :rtlsdr_get_device_name, [:uint32], :string
+
+    # Get USB device strings (manufacturer, product, serial)
     attach_function :rtlsdr_get_device_usb_strings, %i[uint32 pointer pointer pointer], :int
+
+    # Find device index by serial number
     attach_function :rtlsdr_get_index_by_serial, [:string], :int
 
     # Device control functions
+
+    # Open an RTL-SDR device
     attach_function :rtlsdr_open, %i[pointer uint32], :int
+
+    # Close an RTL-SDR device
     attach_function :rtlsdr_close, [:rtlsdr_dev_t], :int
 
     # Configuration functions
@@ -121,7 +150,13 @@ module RTLSDR
     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
+    # Convert tuner type constant to human-readable name
+    #
+    # @param [Integer] tuner_type One of the RTLSDR_TUNER_* constants
+    # @return [String] Human-readable tuner name with chip details
+    # @example Get tuner name
+    #   RTLSDR::FFI.tuner_type_name(RTLSDR::FFI::RTLSDR_TUNER_R820T)
+    #   # => "Rafael Micro R820T"
     def self.tuner_type_name(tuner_type)
       case tuner_type
       when RTLSDR_TUNER_UNKNOWN then "Unknown"

data/lib/rtlsdr/scanner.rb

@@ -37,8 +37,32 @@ module RTLSDR
   #     puts "Strong signal at #{peak[:frequency] / 1e6} MHz"
   #   end
   class Scanner
-    attr_reader :device, :start_freq, :end_freq, :step_size, :dwell_time
+    # @return [RTLSDR::Device] The RTL-SDR device being used for scanning
+    attr_reader :device
+    # @return [Integer] Starting frequency in Hz
+    attr_reader :start_freq
+    # @return [Integer] Ending frequency in Hz
+    attr_reader :end_freq
+    # @return [Integer] Frequency step size in Hz
+    attr_reader :step_size
+    # @return [Float] Time to dwell on each frequency in seconds
+    attr_reader :dwell_time
 
+    # Create a new frequency scanner
+    #
+    # @param [RTLSDR::Device] device RTL-SDR device to use for scanning
+    # @param [Integer] start_freq Starting frequency in Hz
+    # @param [Integer] end_freq Ending frequency in Hz
+    # @param [Integer] step_size Frequency step size in Hz (default: 1 MHz)
+    # @param [Float] dwell_time Time to spend on each frequency in seconds (default: 0.1s)
+    # @example Create FM band scanner
+    #   scanner = RTLSDR::Scanner.new(
+    #     device,
+    #     start_freq: 88_000_000,    # 88 MHz
+    #     end_freq: 108_000_000,     # 108 MHz
+    #     step_size: 200_000,        # 200 kHz
+    #     dwell_time: 0.05           # 50ms per frequency
+    #   )
     def initialize(device, start_freq:, end_freq:, step_size: 1_000_000, dwell_time: 0.1)
       @device = device
       @start_freq = start_freq
@@ -48,15 +72,38 @@ module RTLSDR
       @scanning = false
     end
 
+    # Get array of all frequencies to be scanned
+    #
+    # @return [Array<Integer>] Array of frequencies in Hz
+    # @example Get frequency list
+    #   freqs = scanner.frequencies
+    #   puts "Will scan #{freqs.length} frequencies"
     def frequencies
       (@start_freq..@end_freq).step(@step_size).to_a
     end
 
+    # Get total number of frequencies to be scanned
+    #
+    # @return [Integer] Number of frequency steps
     def frequency_count
       ((end_freq - start_freq) / step_size).to_i + 1
     end
 
-    # Perform a sweep scan
+    # Perform a frequency sweep scan
+    #
+    # Scans through all frequencies in the configured range, collecting samples
+    # and calling the provided block for each frequency. The block receives a
+    # hash with frequency, power, samples, and timestamp information.
+    #
+    # @param [Integer] samples_per_freq Number of samples to collect per frequency
+    # @yield [Hash] Block called for each frequency with scan results
+    # @yieldparam result [Hash] Scan result containing :frequency, :power, :samples, :timestamp
+    # @return [Hash] Hash of all results keyed by frequency
+    # @example Scan and log results
+    #   results = scanner.scan(samples_per_freq: 2048) do |result|
+    #     power_db = 10 * Math.log10(result[:power] + 1e-10)
+    #     puts "#{result[:frequency]/1e6} MHz: #{power_db.round(1)} dB"
+    #   end
     def scan(samples_per_freq: 1024, &block)
       raise ArgumentError, "Block required for scan" unless block_given?
 
@@ -87,7 +134,20 @@ module RTLSDR
       results
     end
 
-    # Async sweep scan
+    # Perform asynchronous frequency sweep scan
+    #
+    # Same as {#scan} but runs in a separate thread, allowing the calling
+    # thread to continue execution while scanning proceeds in the background.
+    #
+    # @param [Integer] samples_per_freq Number of samples to collect per frequency
+    # @yield [Hash] Block called for each frequency with scan results
+    # @return [Thread] Thread object running the scan
+    # @example Background scanning
+    #   scan_thread = scanner.scan_async do |result|
+    #     # Process results in background
+    #   end
+    #   # Do other work...
+    #   scan_thread.join  # Wait for completion
     def scan_async(samples_per_freq: 1024, &block)
       raise ArgumentError, "Block required for async scan" unless block_given?
 
@@ -96,7 +156,20 @@ module RTLSDR
       end
     end
 
-    # Find peaks in the spectrum
+    # Find signal peaks above a power threshold
+    #
+    # Scans the frequency range and returns all frequencies where the signal
+    # power exceeds the specified threshold. Results are sorted by power
+    # in descending order (strongest signals first).
+    #
+    # @param [Float] threshold Power threshold in dB (default: -60 dB)
+    # @param [Integer] samples_per_freq Number of samples per frequency
+    # @return [Array<Hash>] Array of peak information hashes
+    # @example Find strong signals
+    #   peaks = scanner.find_peaks(threshold: -50, samples_per_freq: 4096)
+    #   peaks.each do |peak|
+    #     puts "#{peak[:frequency]/1e6} MHz: #{peak[:power_db]} dB"
+    #   end
     def find_peaks(threshold: -60, samples_per_freq: 1024)
       peaks = []
 
@@ -115,7 +188,19 @@ module RTLSDR
       peaks.sort_by { |peak| -peak[:power] }
     end
 
-    # Power sweep - returns array of [frequency, power] pairs
+    # Perform a power sweep across the frequency range
+    #
+    # Scans all frequencies and returns an array of [frequency, power_db] pairs.
+    # This is useful for generating spectrum plots or finding the overall
+    # power distribution across a frequency band.
+    #
+    # @param [Integer] samples_per_freq Number of samples per frequency
+    # @return [Array<Array>] Array of [frequency_hz, power_db] pairs
+    # @example Generate spectrum data
+    #   spectrum_data = scanner.power_sweep(samples_per_freq: 2048)
+    #   spectrum_data.each do |freq, power|
+    #     puts "#{freq/1e6} MHz: #{power.round(1)} dB"
+    #   end
     def power_sweep(samples_per_freq: 1024)
       results = []
 
@@ -127,15 +212,35 @@ module RTLSDR
       results
     end
 
+    # Stop the current scan operation
+    #
+    # Sets the scanning flag to false, which will cause any active scan
+    # to terminate after the current frequency step completes.
+    #
+    # @return [Boolean] false (new scanning state)
     def stop
       @scanning = false
     end
 
+    # Check if a scan is currently in progress
+    #
+    # @return [Boolean] true if scanning, false otherwise
     def scanning?
       @scanning
     end
 
-    # Configure scan parameters
+    # Update scan configuration parameters
+    #
+    # Allows modification of scan parameters after the scanner has been created.
+    # Only non-nil parameters will be updated.
+    #
+    # @param [Integer, nil] start_freq New starting frequency in Hz
+    # @param [Integer, nil] end_freq New ending frequency in Hz
+    # @param [Integer, nil] step_size New step size in Hz
+    # @param [Float, nil] dwell_time New dwell time in seconds
+    # @return [Scanner] self for method chaining
+    # @example Reconfigure scanner
+    #   scanner.configure(start_freq: 400_000_000, step_size: 25_000)
     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
@@ -144,6 +249,9 @@ module RTLSDR
       self
     end
 
+    # Return string representation of scanner
+    #
+    # @return [String] Human-readable scanner configuration
     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

data/lib/rtlsdr/version.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
 module RTLSDR
-  VERSION = "0.1.0"
+  # 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
+  #
+  # @return [String] Current gem version
+  # @since 0.1.0
+  VERSION = "0.1.2"
 end

data/lib/rtlsdr.rb

@@ -37,16 +37,37 @@ require_relative "rtlsdr/scanner"
 module RTLSDR
   class << self
     # Get the number of connected RTL-SDR devices
+    #
+    # @return [Integer] Number of RTL-SDR devices found
+    # @example Check for devices
+    #   if RTLSDR.device_count > 0
+    #     puts "Found #{RTLSDR.device_count} RTL-SDR devices"
+    #   end
     def device_count
       FFI.rtlsdr_get_device_count
     end
 
     # Get the name of a device by index
+    #
+    # @param [Integer] index Device index (0-based)
+    # @return [String] Device name string
+    # @example Get device name
+    #   name = RTLSDR.device_name(0)
+    #   puts "Device 0: #{name}"
     def device_name(index)
       FFI.rtlsdr_get_device_name(index)
     end
 
-    # Get USB strings for a device by index
+    # Get USB device strings for a device by index
+    #
+    # Retrieves the USB manufacturer, product, and serial number strings
+    # for the specified device.
+    #
+    # @param [Integer] index Device index (0-based)
+    # @return [Hash, nil] Hash with :manufacturer, :product, :serial keys, or nil on error
+    # @example Get USB info
+    #   usb_info = RTLSDR.device_usb_strings(0)
+    #   puts "#{usb_info[:manufacturer]} #{usb_info[:product]}"
     def device_usb_strings(index)
       manufact = " " * 256
       product = " " * 256
@@ -63,6 +84,15 @@ module RTLSDR
     end
 
     # Find device index by serial number
+    #
+    # Searches for a device with the specified serial number and returns
+    # its index if found.
+    #
+    # @param [String] serial Serial number to search for
+    # @return [Integer, nil] Device index if found, nil otherwise
+    # @example Find device by serial
+    #   index = RTLSDR.find_device_by_serial("00000001")
+    #   device = RTLSDR.open(index) if index
     def find_device_by_serial(serial)
       result = FFI.rtlsdr_get_index_by_serial(serial)
       return nil if result.negative?
@@ -71,11 +101,32 @@ module RTLSDR
     end
 
     # 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.
+    #
+    # @param [Integer] index Device index to open (default: 0)
+    # @return [RTLSDR::Device] Device instance
+    # @raise [DeviceNotFoundError] if device doesn't exist
+    # @raise [DeviceOpenError] if device cannot be opened
+    # @example Open first device
+    #   device = RTLSDR.open(0)
+    #   device.center_freq = 100_000_000
     def open(index = 0)
       Device.new(index)
     end
 
-    # List all available devices
+    # 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.
+    #
+    # @return [Array<Hash>] Array of device information hashes
+    # @example List all devices
+    #   RTLSDR.devices.each do |device|
+    #     puts "#{device[:index]}: #{device[:name]}"
+    #     puts "  #{device[:usb_strings][:manufacturer]} #{device[:usb_strings][:product]}"
+    #   end
     def devices
       (0...device_count).map do |i|
         {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rtlsdr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - joshfng
@@ -30,15 +30,21 @@ email:
 executables:
 - rtlsdr
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
 files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardconfig"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- doc_config.rb
 - examples/basic_usage.rb
 - examples/spectrum_analyzer.rb
 - exe/rtlsdr
@@ -58,7 +64,13 @@ metadata:
   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: []
+  documentation_uri: https://rubydoc.info/gems/rtlsdr
+  bug_tracker_uri: https://github.com/joshfng/rtlsdr-ruby/issues
+rdoc_options:
+- "--main"
+- README.md
+- "--line-numbers"
+- "--all"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement