rtlsdr 0.2.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '019e21a841f8f9f9aaf543741487c734d4b1c7b2ff4b2bfd20e37cf56fbfcf00'
-  data.tar.gz: c4c3657ae68d2b5f8f2b931c8256447b9ab8feb0d0bbdfe61e7d035e34ee4053
+  metadata.gz: 1b12c3758778bb23282dd45b6fd7a7875ab966902921da11a01e20e091e695f3
+  data.tar.gz: 9d89756d0d0777d2f60e650809c38c5aad56a33e115e873e6557bb5586720b02
 SHA512:
-  metadata.gz: cf8de21d50dbf21fd92dfec27cdeab872ccf83e3bbe1132ebbeab74bba98ae4e84da90f794574fc8c742da761768f2f49b26f5ea3c345b49960646a0e63ea053
-  data.tar.gz: 5d587f36838184747666800ac202e52d33584169926f9cd2bd72db1d39a5f4189be4b7025898c675f274134ba326537f08782f9682d7e6fe58dce0921f21b497
+  metadata.gz: 57cfd89abe99c55d86e66e3fee3b0da12da94f6feceab7860be79871cd9611bf31ce3f9a2fb8235f1cb2f5ae06bb353df56c3bae3df5c2b4f3affc0267d3bce9
+  data.tar.gz: 1f9c2f119f049eaa84aff2c4afbef95854ebcd3a241441d0676a0f9220b064730b91ee6e95b7d6afbbcdfc40e673418de1f8a70ae1ffea041a65bde26b7c047c

data/README.md

@@ -289,6 +289,22 @@ audio = RTLSDR::Demod.usb(samples, sample_rate: 2_048_000, bfo_offset: 1500)
 audio = RTLSDR::Demod.lsb(samples, sample_rate: 2_048_000, bfo_offset: 1500)
 ```
 
+### FSK Demodulation
+
+```ruby
+# Demodulate FSK signal at 1200 baud
+bits = RTLSDR::Demod.fsk(samples, sample_rate: 48_000, baud_rate: 1200)
+
+# RTTY at 45.45 baud
+bits = RTLSDR::Demod.fsk(samples, sample_rate: 48_000, baud_rate: 45.45)
+
+# Invert mark/space if needed
+bits = RTLSDR::Demod.fsk(samples, sample_rate: 48_000, baud_rate: 1200, invert: true)
+
+# Get raw discriminator output for debugging/visualization
+waveform = RTLSDR::Demod.fsk_raw(samples, sample_rate: 48_000, baud_rate: 1200)
+```
+
 ### Helper Functions
 
 ```ruby
@@ -542,6 +558,11 @@ ruby examples/spectrum_analyzer.rb
 - `Demod.usb(samples, sample_rate:, audio_rate:, bfo_offset:)` - Upper Sideband
 - `Demod.lsb(samples, sample_rate:, audio_rate:, bfo_offset:)` - Lower Sideband
 
+#### FSK Demodulation
+
+- `Demod.fsk(samples, sample_rate:, baud_rate:, invert:)` - FSK to bits
+- `Demod.fsk_raw(samples, sample_rate:, baud_rate:)` - Raw discriminator output
+
 #### Helper Functions
 
 - `Demod.complex_oscillator(length, frequency, sample_rate)` - Generate carrier

data/lib/rtlsdr/demod.rb

@@ -363,6 +363,111 @@ module RTLSDR
       normalize_audio(audio)
     end
 
+    # =========================================================================
+    # FSK Demodulation
+    # =========================================================================
+
+    # FSK (Frequency Shift Keying) demodulation
+    #
+    # Demodulates FSK signals by using an FM discriminator to extract
+    # instantaneous frequency, then thresholding to recover bits.
+    # FSK encodes data by switching between two frequencies (mark and space).
+    #
+    # @param [Array<Complex>] samples Input IQ samples
+    # @param [Integer] sample_rate Input sample rate in Hz
+    # @param [Numeric] baud_rate Symbol rate in baud (symbols per second)
+    # @param [Boolean] invert Swap mark/space interpretation (default: false)
+    # @return [Array<Integer>] Recovered bits (0 or 1)
+    # @example Demodulate 1200 baud FSK
+    #   bits = RTLSDR::Demod.fsk(samples, sample_rate: 48_000, baud_rate: 1200)
+    # @example Demodulate RTTY at 45.45 baud
+    #   bits = RTLSDR::Demod.fsk(samples, sample_rate: 48_000, baud_rate: 45.45)
+    def self.fsk(samples, sample_rate:, baud_rate:, invert: false)
+      return [] if samples.empty? || samples.length < 2
+
+      # Step 1: FM discriminator to get instantaneous frequency
+      freq = phase_diff(samples)
+      return [] if freq.empty?
+
+      # Step 2: Lowpass filter to smooth transitions (cutoff at 1.5x baud rate)
+      filter_cutoff = [baud_rate * 1.5, (sample_rate / 2.0) - 1].min
+      filter = DSP::Filter.lowpass(
+        cutoff: filter_cutoff,
+        sample_rate: sample_rate,
+        taps: 63
+      )
+      complex_freq = freq.map { |f| Complex(f, 0) }
+      smoothed = filter.apply(complex_freq).map(&:real)
+
+      # Step 3: Decimate to ~4x baud rate for bit decisions
+      target_rate = (baud_rate * 4).to_i
+      target_rate = [target_rate, sample_rate].min
+
+      if sample_rate > target_rate && target_rate.positive?
+        decimated = DSP.resample(
+          smoothed.map { |s| Complex(s, 0) },
+          from_rate: sample_rate,
+          to_rate: target_rate
+        ).map(&:real)
+        effective_rate = target_rate
+      else
+        decimated = smoothed
+        effective_rate = sample_rate
+      end
+
+      return [] if decimated.empty?
+
+      # Step 4: Threshold at midpoint to get raw bits
+      threshold = decimated.sum / decimated.length.to_f
+      raw_bits = decimated.map { |s| s > threshold ? 1 : 0 }
+      raw_bits = raw_bits.map { |b| 1 - b } if invert
+
+      # Step 5: Sample at symbol centers
+      samples_per_symbol = effective_rate.to_f / baud_rate
+      return raw_bits if samples_per_symbol < 1
+
+      output_bits = []
+      offset = (samples_per_symbol / 2.0).to_i
+      index = offset
+
+      while index < raw_bits.length
+        output_bits << raw_bits[index]
+        index += samples_per_symbol.round
+      end
+
+      output_bits
+    end
+
+    # FSK demodulation returning raw discriminator output
+    #
+    # Returns the smoothed frequency discriminator output without bit slicing.
+    # Useful for visualizing FSK signals, debugging, or implementing custom
+    # clock recovery algorithms.
+    #
+    # @param [Array<Complex>] samples Input IQ samples
+    # @param [Integer] sample_rate Input sample rate in Hz
+    # @param [Numeric] baud_rate Symbol rate in baud (used for filter cutoff)
+    # @return [Array<Float>] Smoothed discriminator output
+    # @example Get raw FSK waveform for plotting
+    #   waveform = RTLSDR::Demod.fsk_raw(samples, sample_rate: 48_000, baud_rate: 1200)
+    def self.fsk_raw(samples, sample_rate:, baud_rate:)
+      return [] if samples.empty? || samples.length < 2
+
+      # FM discriminator
+      freq = phase_diff(samples)
+      return [] if freq.empty?
+
+      # Lowpass filter
+      filter_cutoff = [baud_rate * 1.5, (sample_rate / 2.0) - 1].min
+      filter = DSP::Filter.lowpass(
+        cutoff: filter_cutoff,
+        sample_rate: sample_rate,
+        taps: 63
+      )
+      complex_freq = freq.map { |f| Complex(f, 0) }
+      filter.apply(complex_freq).map(&:real)
+    end
+
     # =========================================================================
     # Private Helpers
     # =========================================================================

data/lib/rtlsdr/ffi.rb

@@ -140,10 +140,11 @@ module RTLSDR
     attach_function :rtlsdr_get_offset_tuning, [:rtlsdr_dev_t], :int
 
     # Streaming functions
+    # Note: blocking: true releases the GVL so other Ruby threads can run
     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_read_sync, %i[rtlsdr_dev_t pointer int pointer], :int, blocking: true
+    attach_function :rtlsdr_wait_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer], :int, blocking: true
+    attach_function :rtlsdr_read_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer uint32 uint32], :int, blocking: true
     attach_function :rtlsdr_cancel_async, [:rtlsdr_dev_t], :int
 
     # Bias tee functions

data/lib/rtlsdr/fftw.rb

@@ -45,21 +45,49 @@ module RTLSDR
       attr_reader :load_error
     end
 
-    # FFTW planning flags
+    # @!group FFTW Planning Flags
+    # These constants control how FFTW plans are created. Higher effort flags
+    # produce faster transforms but take longer to plan.
+
+    # @return [Integer] Measure execution time to find optimal plan
     FFTW_MEASURE = 0
+
+    # @return [Integer] Allow input array to be destroyed during planning
     FFTW_DESTROY_INPUT = 1
+
+    # @return [Integer] Don't assume arrays are aligned in memory
     FFTW_UNALIGNED = 2
+
+    # @return [Integer] Minimize memory usage at cost of speed
     FFTW_CONSERVE_MEMORY = 4
+
+    # @return [Integer] Try all possible algorithms (very slow planning)
     FFTW_EXHAUSTIVE = 8
+
+    # @return [Integer] Preserve input array contents during transform
     FFTW_PRESERVE_INPUT = 16
+
+    # @return [Integer] Like MEASURE but try harder (slower planning)
     FFTW_PATIENT = 32
+
+    # @return [Integer] Use quick heuristic to pick plan (fast planning, default)
     FFTW_ESTIMATE = 64
+
+    # @return [Integer] Only use wisdom (cached plans), fail if none available
     FFTW_WISDOM_ONLY = 2_097_152
 
-    # FFT direction
+    # @!endgroup
+
+    # @!group FFT Direction Constants
+
+    # @return [Integer] Forward FFT direction (time to frequency domain)
     FFTW_FORWARD = -1
+
+    # @return [Integer] Backward/Inverse FFT direction (frequency to time domain)
     FFTW_BACKWARD = 1
 
+    # @!endgroup
+
     if available?
       # Memory allocation
       attach_function :fftw_malloc, [:size_t], :pointer

data/lib/rtlsdr/version.rb

@@ -12,5 +12,5 @@ module RTLSDR
   #
   # @return [String] Current gem version
   # @since 0.1.0
-  VERSION = "0.2.1"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rtlsdr
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.4
 platform: ruby
 authors:
 - joshfng