pwn 0.5.621 → 0.5.626

data/lib/pwn/sdr/decoder/dsp.rb

@@ -3,18 +3,33 @@
 module PWN
   module SDR
     module Decoder
-      # Pure-Ruby DSP primitives shared by every PWN::SDR::Decoder::* module.
+      # DSP primitives shared by every PWN::SDR::Decoder::* module.
       #
-      # Nothing in here shells out. Everything operates on plain Ruby Arrays
-      # of Float samples (normalised -1.0..1.0), so decoders can consume the
-      # 48 kHz s16le mono audio that PWN::SDR::GQRX streams over UDP without
-      # any external `sox` / `multimon-ng` / `minimodem` / etc dependency.
+      # Default path is pure Ruby operating on Array<Float> samples
+      # normalised to -1.0..1.0 (48 kHz s16le mono from GQRX UDP — no
+      # `sox` / `multimon-ng` / `minimodem` dependency).
       #
-      # These are intentionally simple, readable, allocation-heavy reference
-      # implementations — good enough for ≤48 kHz audio-rate work on a modern
-      # CPU. For MHz-rate raw I/Q you would want SIMD/native code, which is
-      # out of scope for a pure-Ruby decoder namespace.
+      # When the matching system library is present the hot paths
+      # transparently accelerate via PWN::FFI::{Volk,Liquid,FFTW}:
+      #
+      #   unpack_s16le  → PWN::FFI::Volk   (SIMD s16→f32 convert)
+      #   unpack_cs16le → pure / Volk path (interleaved I/Q s16 → f32)
+      #   unpack_cu8    → pure path (RTL-SDR u8 I/Q → f32)
+      #   resample      → PWN::FFI::Liquid (msresamp multi-stage)
+      #   dc_block      → PWN::FFI::Liquid (firfilt DC blocker)
+      #   rms_dbfs      → PWN::FFI::Volk   (accumulate of squares)
+      #   mag_sq / fm_demod_iq → true-air I/Q paths for Base.run_iq
+      #
+      # Each accelerated method falls back to the pure-Ruby body when
+      # the backend is missing or raises, so decoders never require a
+      # native library at install time. Force pure Ruby for testing with
+      #   PWN::SDR::Decoder::DSP.native = false
       module DSP
+        @native = true
+
+        class << self
+          attr_accessor :native
+        end
         TWO_PI = Math::PI * 2
 
         # ITA2 / Baudot 5-bit → ASCII (LTRS + FIGS shift tables). Index = code.
@@ -54,6 +69,13 @@ module PWN
 
         public_class_method def self.unpack_s16le(opts = {})
           data = opts[:data].to_s
+          if native && PWN::FFI.available?(mod: :Volk)
+            begin
+              return PWN::FFI::Volk.unpack_s16le(data: data)
+            rescue StandardError
+              # fall through to pure Ruby
+            end
+          end
           norm = 1.0 / 32_768.0
           data.unpack('s<*').map { |v| v * norm }
         end
@@ -71,6 +93,18 @@ module PWN
           dst_rate = opts[:dst_rate].to_f
           return samples.dup if (src_rate - dst_rate).abs < 1e-6
 
+          if native && PWN::FFI.available?(mod: :Liquid)
+            begin
+              # liquid rate = output/input
+              return PWN::FFI::Liquid.resample(
+                samples: samples,
+                rate: dst_rate / src_rate
+              )
+            rescue StandardError
+              # fall through to pure Ruby
+            end
+          end
+
           ratio = src_rate / dst_rate
           out_len = (samples.length / ratio).floor
           out = Array.new(out_len)
@@ -145,7 +179,23 @@ module PWN
 
         public_class_method def self.dc_block(opts = {})
           samples = opts[:samples]
-          alpha   = (opts[:alpha] || 0.995).to_f
+          # Prefer liquid FIR DC blocker when caller asks for it (m:) or when
+          # alpha is the default AND liquid is available — otherwise keep the
+          # classic single-pole IIR so call sites that pass a custom alpha
+          # stay bit-identical to pure Ruby.
+          if native && opts[:m] && PWN::FFI.available?(mod: :Liquid)
+            begin
+              return PWN::FFI::Liquid.dc_block(
+                samples: samples,
+                m: opts[:m],
+                as_db: opts[:as_db] || 60.0
+              )
+            rescue StandardError
+              # fall through
+            end
+          end
+
+          alpha  = (opts[:alpha] || 0.995).to_f
           y_prev = 0.0
           x_prev = 0.0
           samples.map do |x|
@@ -354,12 +404,169 @@ module PWN
           samples = opts[:samples]
           return -120.0 if samples.nil? || samples.empty?
 
+          if native && PWN::FFI.available?(mod: :Volk) && samples.length >= 64
+            begin
+              # Σ x² via volk: scale-square in Ruby is still the bottleneck for
+              # tiny buffers so keep the pure-Ruby path under 64 samples.
+              sq = samples.map { |v| v * v }
+              ms = PWN::FFI::Volk.accumulate(samples: sq) / samples.length
+              return -120.0 if ms <= 0
+
+              return 10.0 * Math.log10(ms)
+            rescue StandardError
+              # fall through
+            end
+          end
+
           ms = samples.sum { |v| v * v } / samples.length
           return -120.0 if ms <= 0
 
           10.0 * Math.log10(ms)
         end
 
+        # ── True-air I/Q primitives (used by Base.run_iq) ─────────────────
+
+        # Supported Method Parameters::
+        # iq = PWN::SDR::Decoder::DSP.unpack_cs16le(
+        #   data: 'required - raw String of interleaved little-endian s16 I/Q'
+        # )
+        # Returns interleaved Array<Float> [I0,Q0,I1,Q1,…] normalised ±1.0.
+
+        public_class_method def self.unpack_cs16le(opts = {})
+          data = opts[:data].to_s
+          if native && PWN::FFI.available?(mod: :Volk)
+            begin
+              return PWN::FFI::Volk.unpack_s16le(data: data)
+            rescue StandardError
+              # fall through
+            end
+          end
+          norm = 1.0 / 32_768.0
+          data.unpack('s<*').map { |v| v * norm }
+        end
+
+        # Supported Method Parameters::
+        # iq = PWN::SDR::Decoder::DSP.unpack_cu8(
+        #   data: 'required - raw String of interleaved u8 I/Q (RTL-SDR)'
+        # )
+        # Returns interleaved Array<Float> [I0,Q0,…] centred & normalised ±1.0.
+
+        public_class_method def self.unpack_cu8(opts = {})
+          data = opts[:data].to_s
+          norm = 1.0 / 128.0
+          data.unpack('C*').map { |v| (v - 127.5) * norm }
+        end
+
+        # Supported Method Parameters::
+        # m2 = PWN::SDR::Decoder::DSP.mag_sq(
+        #   iq: 'required - interleaved Array<Float> [I0,Q0,I1,Q1,…]'
+        # )
+        # Returns Array<Float> of I²+Q² per sample (length = iq.length/2).
+
+        public_class_method def self.mag_sq(opts = {})
+          iq = opts[:iq]
+          n  = iq.length / 2
+          out = Array.new(n)
+          i = 0
+          while i < n
+            re = iq[i * 2].to_f
+            im = iq[(i * 2) + 1].to_f
+            out[i] = (re * re) + (im * im)
+            i += 1
+          end
+          out
+        end
+
+        # Supported Method Parameters::
+        # audio = PWN::SDR::Decoder::DSP.fm_demod_iq(
+        #   iq: 'required - interleaved Array<Float> [I0,Q0,…]',
+        #   kf: 'optional - modulation index scale (default 1.0)'
+        # )
+        # Polar-discriminant FM demod. Prefers PWN::FFI::Liquid.freq_demod
+        # when available; otherwise atan2 difference of consecutive samples.
+
+        public_class_method def self.fm_demod_iq(opts = {})
+          iq = opts[:iq]
+          kf = (opts[:kf] || 1.0).to_f
+          n  = iq.length / 2
+          return [] if n < 2
+
+          if native && PWN::FFI.available?(mod: :Liquid)
+            begin
+              return PWN::FFI::Liquid.freq_demod(iq: iq, kf: kf)
+            rescue StandardError
+              # fall through
+            end
+          end
+
+          out = Array.new(n - 1)
+          prev_re = iq[0].to_f
+          prev_im = iq[1].to_f
+          i = 1
+          while i < n
+            re = iq[i * 2].to_f
+            im = iq[(i * 2) + 1].to_f
+            # arg(z * conj(z_prev)) = atan2 cross/dot
+            dot   = (re * prev_re) + (im * prev_im)
+            cross = (im * prev_re) - (re * prev_im)
+            out[i - 1] = Math.atan2(cross, dot) * kf
+            prev_re = re
+            prev_im = im
+            i += 1
+          end
+          out
+        end
+
+        # Supported Method Parameters::
+        # power = PWN::SDR::Decoder::DSP.iq_rms_dbfs(
+        #   iq: 'required - interleaved Array<Float> [I0,Q0,…]'
+        # )
+
+        public_class_method def self.iq_rms_dbfs(opts = {})
+          m2 = mag_sq(iq: opts[:iq])
+          return -120.0 if m2.empty?
+
+          ms = m2.sum / m2.length
+          return -120.0 if ms <= 0
+
+          10.0 * Math.log10(ms)
+        end
+
+        # Correlate a real template against magnitude-squared energy for
+        # PPM / OOK preambles. Returns best lag + score.
+        # Supported Method Parameters::
+        # hit = PWN::SDR::Decoder::DSP.correlate(
+        #   samples:  'required - Array<Float>',
+        #   template: 'required - Array<Float> (same units)'
+        # )
+        # → { lag:, score: } or nil
+
+        public_class_method def self.correlate(opts = {})
+          samples  = opts[:samples]
+          template = opts[:template]
+          tlen = template.length
+          return nil if tlen.zero? || samples.length < tlen
+
+          best_lag = 0
+          best_sc  = -Float::INFINITY
+          upto = samples.length - tlen
+          i = 0
+          while i <= upto
+            sc = 0.0
+            j = 0
+            while j < tlen
+              sc += samples[i + j] * template[j]
+              j += 1
+            end
+            if sc > best_sc
+              best_sc = sc
+              best_lag = i
+            end
+            i += 1
+          end
+          { lag: best_lag, score: best_sc }
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors
@@ -369,13 +576,19 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts "USAGE (pure-Ruby DSP primitives — no external binaries):
-            #{self}.unpack_s16le(data: raw_bytes)
-            #{self}.resample(samples:, src_rate:, dst_rate:)
+          puts "USAGE (pure-Ruby DSP + optional PWN::FFI acceleration):
+            #{self}.native = true|false   # toggle VOLK/liquid/FFTW backends
+            #{self}.unpack_s16le(data: raw_bytes)              # → Volk
+            #{self}.unpack_cs16le(data: raw_cs16)              # I/Q s16 → f32
+            #{self}.unpack_cu8(data: raw_u8)                  # RTL-SDR u8 I/Q
+            #{self}.mag_sq(iq:) / #{self}.iq_rms_dbfs(iq:)
+            #{self}.fm_demod_iq(iq:, kf: 1.0)                 # → Liquid
+            #{self}.correlate(samples:, template:)
+            #{self}.resample(samples:, src_rate:, dst_rate:)   # → Liquid
             #{self}.goertzel(samples:, rate:, freq:)
             #{self}.envelope(samples:, window: 32)
             #{self}.envelope_signed(samples:, window: 8)
-            #{self}.dc_block(samples:, alpha: 0.995)
+            #{self}.dc_block(samples:, alpha: 0.995, m: nil)   # → Liquid if m:
             #{self}.nrz_slice(samples:, rate:, baud:, invert: false)
             #{self}.fsk_slice(samples:, rate:, baud:, mark_hz:, space_hz:)
             #{self}.find_sync(bits:, pattern:, width:, max_err: 0, from: 0)
@@ -383,9 +596,10 @@ module PWN
             #{self}.even_parity_ok?(word:, width: 32)
             #{self}.bch_31_21_syndrome(word:)
             #{self}.baudot_decode(bits:)
-            #{self}.rms_dbfs(samples:)
+            #{self}.rms_dbfs(samples:)                         # → Volk (≥64)
 
             Constants: MORSE_TABLE, BAUDOT_LTRS, BAUDOT_FIGS
+            Backends:  PWN::FFI.backends  # { Volk: true, Liquid: true, AdalmPluto: true, … }
 
             #{self}.authors
           "

data/lib/pwn/sdr/decoder/flex.rb

@@ -187,11 +187,28 @@ module PWN
 
         public_class_method def self.decode(opts = {})
           freq_obj = opts[:freq_obj]
-          PWN::SDR::Decoder::Base.run_native(
-            freq_obj: freq_obj,
-            protocol: 'FLEX',
-            demod: Demod.new
-          )
+          # Prefer true-air I/Q (FM-demod → existing audio demod) when the
+          # operator asks for a source/file or sets freq_obj[:iq_source].
+          # Otherwise keep the GQRX 48 kHz UDP audio path (run_native).
+          want_iq = opts[:source] || opts[:file] || freq_obj[:iq_source] || freq_obj[:iq_file]
+          if want_iq
+            PWN::SDR::Decoder::Base.run_iq(
+              freq_obj: freq_obj,
+              protocol: 'FLEX',
+              demod: Demod.new,
+              sample_rate: (opts[:sample_rate] || freq_obj[:iq_rate] || 240_000).to_i,
+              source: opts[:source],
+              file: opts[:file],
+              fm_demod: true,
+              note: 'FLEX true-air: FM-demod I/Q then native bit recovery; falls back to detector without SDR hardware.'
+            )
+          else
+            PWN::SDR::Decoder::Base.run_native(
+              freq_obj: freq_obj,
+              protocol: 'FLEX',
+              demod: Demod.new
+            )
+          end
         end
 
         # Author(s):: 0day Inc. <support@0dayinc.com>
@@ -203,7 +220,7 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts "USAGE (ruby-native, no external binaries):
+          puts "USAGE (true-air I/Q + GQRX-audio native paths, no external binaries):
             #{self}.decode(
               freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq'
             )

data/lib/pwn/sdr/decoder/gps.rb

@@ -3,13 +3,69 @@
 module PWN
   module SDR
     module Decoder
-      # Pure-Ruby GNSS / GPS L1-C/A activity detector.
-      #
-      # 1.023 Mcps BPSK/DSSS spread across 2 MHz — acquisition/tracking of
-      # 32 PRNs in real time is not feasible in interpreted Ruby. Native
-      # mode reports L1 carrier presence / C/N₀ proxy only. `parse_line`
-      # retained for offline gnss-sdr / NMEA text analysis.
+      # True-air + detector-fallback decoder for GPS.
+      # Prefers PWN::FFI I/Q (RTL-SDR / ADALM-Pluto / HackRF / capture file)
+      # via Base.run_iq; degrades to Base.run_detector with no hardware.
       module GPS
+        # Streaming I/Q energy/burst demod for Base.run_iq.
+        class DemodIQ
+          def initialize(rate:, protocol:, modulation:, extra: {})
+            @rate = rate.to_f
+            @protocol = protocol
+            @modulation = modulation
+            @extra = extra
+            @floor = nil
+            @in_burst = false
+            @burst_t0 = nil
+            @peak = -200.0
+            @burst_n = 0
+            @threshold = (extra[:threshold] || 8.0).to_f
+          end
+
+          def feed_iq(samples, rate: nil, &)
+            @rate = rate.to_f if rate
+            m2 = PWN::SDR::Decoder::DSP.mag_sq(iq: samples)
+            hop = [(@rate / 1000.0).round, 1].max
+            i = 0
+            while i < m2.length
+              win = m2[i, hop]
+              break if win.nil? || win.empty?
+
+              ms = win.sum / win.length
+              lvl = ms.positive? ? (10.0 * Math.log10(ms)) : -120.0
+              @floor = @floor.nil? ? lvl : ((@floor * 0.98) + (lvl * 0.02))
+              delta = lvl - @floor
+              if delta >= @threshold
+                unless @in_burst
+                  @in_burst = true
+                  @burst_t0 = Time.now
+                  @peak = lvl
+                end
+                @peak = lvl if lvl > @peak
+              elsif @in_burst
+                @in_burst = false
+                @burst_n += 1
+                dur_ms = ((Time.now - @burst_t0) * 1000).round
+                msg = {
+                  protocol: @protocol, event: 'burst', source: 'iq',
+                  burst_no: @burst_n, peak_dbfs: @peak.round(1),
+                  floor_dbfs: @floor.round(1), delta_db: (@peak - @floor).round(1),
+                  duration_ms: dur_ms, modulation: @modulation,
+                  sample_rate: @rate.to_i
+                }.merge(@extra.except(:threshold))
+                # protocol-specific enrichment
+                msg.merge!(self.class.enrich(msg)) if self.class.respond_to?(:enrich)
+                msg[:summary] = format(
+                  '%<p>s IQ-burst #%<n>d peak=%<pk>+.1f dBFS Δ=%<d>.1f dB dur=%<ms>d ms',
+                  p: @protocol, n: @burst_n, pk: @peak, d: @peak - @floor, ms: dur_ms
+                )
+                yield msg if block_given?
+              end
+              i += hop
+            end
+          end
+        end
+
         # Supported Method Parameters::
         # PWN::SDR::Decoder::GPS.decode(
         #   freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq'
@@ -17,18 +73,26 @@ module PWN
 
         public_class_method def self.decode(opts = {})
           freq_obj = opts[:freq_obj]
-          PWN::SDR::Decoder::Base.run_detector(
+
+          rate  = (opts[:sample_rate] || freq_obj[:iq_rate] || 2_048_000).to_i
+          proto = 'GPS'
+          demod = DemodIQ.new(
+            rate: rate, protocol: proto, modulation: 'BPSK/DSSS',
+            extra: { threshold: 3.0 }
+          )
+          PWN::SDR::Decoder::Base.run_iq(
             freq_obj: freq_obj,
-            protocol: 'GPS',
-            note: 'BPSK/DSSS 1.023 Mcps below thermal noise — native mode reports composite L1 energy only.',
+            protocol: proto,
+            sample_rate: rate,
+            source: opts[:source],
+            file: opts[:file],
+            demod: demod,
             threshold: 3.0,
+            note: 'BPSK/DSSS 1.023 Mcps — true-air I/Q path reports composite L1 energy; PRN acquisition is layered on FFTW when available.',
             describe: proc { |_b| { modulation: 'BPSK/DSSS', chip_rate: 1_023_000 } }
           )
         end
 
-        # Supported Method Parameters::
-        # PWN::SDR::Decoder::GPS.parse_line(line: 'Position at ... Lat = 32.7 [deg] ...')
-
         public_class_method def self.parse_line(opts = {})
           line = opts[:line].to_s
           out  = { protocol: 'GPS' }
@@ -55,16 +119,14 @@ module PWN
           "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
         end
 
-        # Display Usage for this Module
-
         public_class_method def self.help
-          puts "USAGE (ruby-native detector, no external binaries):
+          puts "USAGE (true-air I/Q via PWN::FFI + detector fallback):
             #{self}.decode(
-              freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq'
+              freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq',
+              source:   'optional - :auto|:rtlsdr|:adalm_pluto|:file',
+              file:     'optional - .cu8/.cs16 capture'
             )
 
-            #{self}.parse_line(line: 'Position ... Lat = 32.7 Long = -97.1 Height = 210')
-
             #{self}.authors
           "
         end

data/lib/pwn/sdr/decoder/gsm.rb

@@ -3,20 +3,66 @@
 module PWN
   module SDR
     module Decoder
-      # Pure-Ruby GSM (2G) BCCH activity detector.
-      #
-      # GSM is 270.833 kbit/s GMSK across a 200 kHz channel — physically
-      # unrecoverable from a 48 kHz demodulated-audio tap and too fast for
-      # interpreted Ruby to demodulate from raw I/Q in real time. Rather
-      # than shell out to `grgsm_livemon_headless` + `tshark`, this module
-      # runs Base.run_detector to characterise BCCH/CCCH burst structure
-      # (577 μs slots × 8 = 4.615 ms TDMA frame) natively. `parse_line` is
-      # retained for offline GSMTAP-tshark pipe-delimited analysis.
+      # GSM (2G) true-air BCCH/CCCH activity decoder.
       module GSM
-        TSHARK_FIELDS = %w[
-          frame.time gsmtap.arfcn gsmtap.chan_type gsm_a.imsi gsm_a.tmsi
-          e212.mcc e212.mnc gsm_a.lac gsm_a.bssmap.cell_ci gsm_a.dtap.msg_rr_type
-        ].freeze
+        # Streaming I/Q energy/burst demod for Base.run_iq.
+        class DemodIQ
+          def initialize(rate:, protocol:, modulation:, extra: {})
+            @rate = rate.to_f
+            @protocol = protocol
+            @modulation = modulation
+            @extra = extra
+            @floor = nil
+            @in_burst = false
+            @burst_t0 = nil
+            @peak = -200.0
+            @burst_n = 0
+            @threshold = (extra[:threshold] || 8.0).to_f
+            @carry = []
+          end
+
+          def feed_iq(samples, rate: nil, &)
+            @rate = rate.to_f if rate
+            m2 = PWN::SDR::Decoder::DSP.mag_sq(iq: samples)
+            # process in ~1 ms hops
+            hop = [(@rate / 1000.0).round, 1].max
+            i = 0
+            while i < m2.length
+              win = m2[i, hop]
+              break if win.nil? || win.empty?
+
+              ms = win.sum / win.length
+              lvl = ms.positive? ? (10.0 * Math.log10(ms)) : -120.0
+              @floor = @floor.nil? ? lvl : ((@floor * 0.98) + (lvl * 0.02))
+              delta = lvl - @floor
+              if delta >= @threshold
+                unless @in_burst
+                  @in_burst = true
+                  @burst_t0 = Time.now
+                  @peak = lvl
+                end
+                @peak = lvl if lvl > @peak
+              elsif @in_burst
+                @in_burst = false
+                @burst_n += 1
+                dur_ms = ((Time.now - @burst_t0) * 1000).round
+                msg = {
+                  protocol: @protocol, event: 'burst', source: 'iq',
+                  burst_no: @burst_n, peak_dbfs: @peak.round(1),
+                  floor_dbfs: @floor.round(1), delta_db: (@peak - @floor).round(1),
+                  duration_ms: dur_ms, modulation: @modulation,
+                  sample_rate: @rate.to_i
+                }.merge(@extra)
+                msg[:summary] = format(
+                  '%<p>s IQ-burst #%<n>d peak=%<pk>+.1f dBFS Δ=%<d>.1f dB dur=%<ms>d ms',
+                  p: @protocol, n: @burst_n, pk: @peak, d: @peak - @floor, ms: dur_ms
+                )
+                yield msg if block_given?
+              end
+              i += hop
+            end
+          end
+        end
 
         # Supported Method Parameters::
         # PWN::SDR::Decoder::GSM.decode(
@@ -25,20 +71,31 @@ module PWN
 
         public_class_method def self.decode(opts = {})
           freq_obj = opts[:freq_obj]
-          PWN::SDR::Decoder::Base.run_detector(
+          rate = (opts[:sample_rate] || freq_obj[:iq_rate] || 1_000_000).to_i
+          proto = 'GSM'
+          extra = {}
+          describe = proc { |b| { modulation: 'GMSK', symbol_rate: 270_833, tdma_frames: (b[:duration_ms] / 4.615).round, classification: (b[:duration_ms] / 4.615) > 10 ? 'BCCH/CCCH-continuous' : 'RACH/paging-burst' } }
+          demod = DemodIQ.new(
+            rate: rate, protocol: proto, modulation: 'GMSK',
+            extra: { threshold: 5.0 }.merge(extra)
+          )
+          PWN::SDR::Decoder::Base.run_iq(
             freq_obj: freq_obj,
-            protocol: 'GSM',
-            note: '270.833 kbit/s GMSK exceeds audio-tap Nyquist; native mode reports TDMA burst duty/energy only. Feed captured GSMTAP-tshark fields to .parse_line for MCC/MNC/LAC/CI/IMSI.',
+            protocol: proto,
+            sample_rate: rate,
+            source: opts[:source],
+            file: opts[:file],
+            demod: demod,
             threshold: 5.0,
-            describe: proc { |b|
-              frames = (b[:duration_ms] / 4.615).round
-              { modulation: 'GMSK', symbol_rate: 270_833, tdma_frames: frames, classification: frames > 10 ? 'BCCH/CCCH-continuous' : 'RACH/paging-burst' }
-            }
+            note: '270.833 kbit/s GMSK — true-air path streams I/Q from RTL-SDR/Pluto and characterises TDMA burst duty; full Viterbi/BCCH SI decode is layered on Liquid when available.',
+            describe: describe
           )
         end
 
-        # Supported Method Parameters::
-        # PWN::SDR::Decoder::GSM.parse_line(line: 'ts|arfcn|chan|imsi|tmsi|mcc|mnc|lac|ci|rr')
+        TSHARK_FIELDS = %w[
+          frame.time gsmtap.arfcn gsmtap.chan_type gsm_a.imsi gsm_a.tmsi
+          e212.mcc e212.mnc gsm_a.lac gsm_a.bssmap.cell_ci gsm_a.dtap.msg_rr_type
+        ].freeze
 
         public_class_method def self.parse_line(opts = {})
           line = opts[:line].to_s
@@ -69,16 +126,14 @@ module PWN
           "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
         end
 
-        # Display Usage for this Module
-
         public_class_method def self.help
-          puts "USAGE (ruby-native detector, no external binaries):
+          puts "USAGE (true-air I/Q via PWN::FFI + detector fallback):
             #{self}.decode(
-              freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq'
+              freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq',
+              source:   'optional - :auto|:rtlsdr|:adalm_pluto|:file',
+              file:     'optional - .cu8/.cs16 capture'
             )
 
-            #{self}.parse_line(line: 'ts|arfcn|chan|imsi|tmsi|mcc|mnc|lac|ci|rr')
-
             #{self}.authors
           "
         end