pwn 0.5.621 → 0.5.626

data/lib/pwn/sdr/decoder/pocsag.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: 'POCSAG',
-            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: 'POCSAG',
+              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: 'POCSAG 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: 'POCSAG',
+              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/rds.rb

@@ -6,38 +6,124 @@ require 'tty-spinner'
 module PWN
   module SDR
     module Decoder
-      # RDS Decoder Module for FM Radio Signals
+      # RDS Decoder Module for FM Radio Signals.
+      #
+      # Two entry points:
+      #   .sample  — non-interactive structured Hash (agents / cron / tools)
+      #   .decode  — interactive TTY spinner (human REPL via GQRX.init_freq)
+      #
+      # Both share the same GQRX RDS protocol path (U RDS, p RDS_PI / PS_NAME /
+      # RADIOTEXT). .sample is the canonical mid-layer API that Extrospection
+      # and any other automation should call.
       module RDS
+        DEFAULT_SETTLE_SECS = 8.0
+        DEFAULT_INTERVAL    = 0.75
+        CALLSIGN_RX         = /\A[A-Z]{1,2}[A-Z0-9]{2,4}\z/
+        CALLSIGN_RT_RX      = /\A([A-Z]{1,2}[A-Z0-9]{2,4})\b/
+
+        # Supported Method Parameters::
+        # rds_hash = PWN::SDR::Decoder::RDS.sample(
+        #   gqrx_sock:   'required unless freq_obj - TCPSocket from GQRX.connect',
+        #   freq_obj:    'required unless gqrx_sock - Hash from GQRX.init_freq',
+        #   settle_secs: 'optional - seconds to sample (default 8, max 30)',
+        #   interval:    'optional - poll interval seconds (default 0.75)',
+        #   leave_enabled: 'optional - leave RDS decoder ON after sample (default false)'
+        # )
+        #
+        # Returns::
+        #   {
+        #     pi:, ps_name:, radiotext:, station:,
+        #     samples: Integer, settle_secs: Float,
+        #     error: String?   # present when RDS backend is unavailable
+        #   }
+
+        public_class_method def self.sample(opts = {})
+          sock = resolve_sock(opts)
+          raise ArgumentError, 'gqrx_sock: or freq_obj: with :gqrx_sock required' unless sock
+
+          settle   = (opts[:settle_secs] || DEFAULT_SETTLE_SECS).to_f.clamp(0.5, 30.0)
+          interval = [(opts[:interval] || DEFAULT_INTERVAL).to_f, 0.1].max
+          leave_on = opts[:leave_enabled] ? true : false
+          samples  = []
+
+          unless enable_rds!(sock: sock)
+            return {
+              pi: nil,
+              ps_name: nil,
+              radiotext: nil,
+              station: nil,
+              samples: 0,
+              settle_secs: settle,
+              error: 'RDS not supported by this radio backend'
+            }
+          end
+
+          deadline = Time.now + settle
+          while Time.now < deadline
+            snap = poll_once(sock: sock)
+            samples << snap unless snap[:pi].empty? && snap[:ps].empty? && snap[:rt].empty?
+
+            # Early exit once we have a non-zero PI and a non-trivial RT —
+            # give one more interval for RadioText to finish filling.
+            pi = snap[:pi]
+            rt = snap[:rt]
+            if pi =~ /\A[0-9A-F]{4}\z/ && pi != '0000' && rt.length >= 8
+              sleep interval
+              snap2 = poll_once(sock: sock)
+              samples << snap2
+              break if snap2[:rt].length >= rt.length
+            end
+
+            sleep interval
+          end
+
+          disable_rds!(sock: sock) unless leave_on
+
+          aggregate(samples: samples, settle_secs: settle)
+        rescue ArgumentError
+          raise
+        rescue StandardError => e
+          disable_rds!(sock: sock) if sock && !leave_on
+          {
+            pi: nil,
+            ps_name: nil,
+            radiotext: nil,
+            station: nil,
+            samples: samples&.length.to_i,
+            settle_secs: settle,
+            error: "#{e.class}: #{e.message}"
+          }
+        end
+
         # Supported Method Parameters::
-        # rds_resp = PWN::SDR::Decoder::RDS.decode(
-        #   freq_obj: 'required - GQRX socket object returned from #connect method'
+        # PWN::SDR::Decoder::RDS.decode(
+        #   freq_obj: 'required - Hash returned from PWN::SDR::GQRX.init_freq'
         # )
+        #
+        # Interactive TTY UX: enables RDS, spins a live status line until the
+        # operator presses ENTER, then disables RDS. Does not return a Hash —
+        # callers that need structured data should use .sample instead.
 
         public_class_method def self.decode(opts = {})
           freq_obj = opts[:freq_obj]
+          raise ArgumentError, 'freq_obj: required' unless freq_obj.is_a?(Hash)
+
           gqrx_sock = freq_obj[:gqrx_sock]
+          raise ArgumentError, 'freq_obj[:gqrx_sock] required' unless gqrx_sock
 
-          # freq_obj = freq_obj.dup
-          freq_obj.delete(:gqrx_sock)
+          # Pretty-print the tuned frequency context without leaking the socket.
+          display = freq_obj.dup
+          display.delete(:gqrx_sock)
           skip_freq_char = "\n"
-          puts JSON.pretty_generate(freq_obj)
+          puts JSON.pretty_generate(display)
           puts "\n*** FM Radio RDS Decoder ***"
           puts 'Press [ENTER] to continue to next frequency...'
 
-          # Toggle RDS off and on to reset the decoder
-          PWN::SDR::GQRX.cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: 'U RDS 0',
-            resp_ok: 'RPRT 0'
-          )
-
-          PWN::SDR::GQRX.cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: 'U RDS 1',
-            resp_ok: 'RPRT 0'
-          )
+          unless enable_rds!(sock: gqrx_sock)
+            puts 'ERROR: RDS not supported by this radio backend'
+            return nil
+          end
 
-          # Spinner setup with dynamic terminal width awareness
           spinner = TTY::Spinner.new(
             '[:spinner] :status',
             format: :arrow_pulse,
@@ -45,54 +131,38 @@ module PWN
             hide_cursor: true
           )
 
-          # Conservative overhead for spinner animation, colors, and spacing
           spinner_overhead = 12
           max_title_length = [TTY::Screen.width - spinner_overhead, 50].max
 
           initial_title = 'INFO: Decoding FM radio RDS data...'
           initial_title = initial_title[0...max_title_length] if initial_title.length > max_title_length
-          spinner.update(title: initial_title)
+          spinner.update(status: initial_title)
           spinner.auto_spin
 
           last_resp = {}
 
           loop do
+            snap = poll_once(sock: gqrx_sock)
             rds_resp = {
-              rds_pi: PWN::SDR::GQRX.cmd(gqrx_sock: gqrx_sock, cmd: 'p RDS_PI').to_s.strip.chomp.delete('.'),
-              rds_ps_name: PWN::SDR::GQRX.cmd(gqrx_sock: gqrx_sock, cmd: 'p RDS_PS_NAME').to_s.strip.chomp,
-              rds_radiotext: PWN::SDR::GQRX.cmd(gqrx_sock: gqrx_sock, cmd: 'p RDS_RADIOTEXT').to_s.strip.chomp
+              rds_pi: snap[:pi],
+              rds_ps_name: snap[:ps],
+              rds_radiotext: snap[:rt]
             }
 
-            # Only update when we have valid new data
-            if rds_resp[:rds_pi] != '0000' && rds_resp != last_resp
-              # --- Enforce RDS specification bounds and clean formatting ---
-              # PI: 16-bit code >>> exactly 4 uppercase hex digits, zero-padded
-              rds_pi = rds_resp[:rds_pi].upcase
-              rds_pi = rds_pi.rjust(4, '0')[0, 4]
-
-              # PS: exactly 8 ASCII characters (pad short with spaces, truncate long)
+            if rds_resp[:rds_pi] != '0000' && !rds_resp[:rds_pi].empty? && rds_resp != last_resp
+              rds_pi = rds_resp[:rds_pi].upcase.rjust(4, '0')[0, 4]
               rds_ps = "#{rds_resp[:rds_ps_name]}        "[0, 8]
-
-              # RadioText: strip trailing spaces (stations often pad to clear)
               rds_rt = rds_resp[:rds_radiotext].rstrip
 
-              # Fixed prefix: always exactly 28 characters for predictable layout
-              # Breakdown: "PI: " (4) + 4 hex (4) + " | PS: " (7) + 8 chars (8) + " | RT: " (7) = 28
               prefix = "Program ID: #{rds_pi} | Station Name: #{rds_ps} | Radio Txt: "
-
-              # minimum visibility
-              available_for_term = max_title_length - prefix.length
-              available_for_term = [available_for_term, 10].max
-
+              available_for_term = [max_title_length - prefix.length, 10].max
               rt_display = rds_rt
               rt_display = "#{rt_display[0...available_for_term]}..." if rt_display.length > available_for_term
 
-              msg = "#{prefix}#{rt_display}"
-              spinner.update(status: msg)
+              spinner.update(status: "#{prefix}#{rt_display}")
               last_resp = rds_resp.dup
             end
 
-            # Non-blocking check for ENTER key to exit
             if $stdin.wait_readable(0)
               begin
                 char = $stdin.read_nonblock(1)
@@ -105,16 +175,10 @@ module PWN
             sleep 0.01
           end
         rescue StandardError => e
-          spinner.error('Decoding failed') if defined?(spinner)
+          spinner.error('Decoding failed') if defined?(spinner) && spinner
           raise e
         ensure
-          # Toggle RDS off and on to reset the decoder
-          PWN::SDR::GQRX.cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: 'U RDS 0',
-            resp_ok: 'RPRT 0'
-          )
-
+          disable_rds!(sock: gqrx_sock) if defined?(gqrx_sock) && gqrx_sock
           spinner.stop if defined?(spinner) && spinner
         end
 
@@ -130,6 +194,15 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
+            # Non-interactive (agents / automation) — returns a Hash:
+            rds = #{self}.sample(
+              gqrx_sock: sock,          # or freq_obj: from init_freq
+              settle_secs: 8,           # default 8, max 30
+              leave_enabled: false
+            )
+            # => { pi:, ps_name:, radiotext:, station:, samples:, settle_secs: }
+
+            # Interactive TTY spinner (human REPL via GQRX.init_freq decoder: :rds):
             #{self}.decode(
               freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq method'
             )
@@ -137,6 +210,100 @@ module PWN
             #{self}.authors
           "
         end
+
+        # ---- internals -------------------------------------------------------
+
+        private_class_method def self.resolve_sock(opts = {})
+          return opts[:gqrx_sock] if opts[:gqrx_sock]
+
+          fo = opts[:freq_obj]
+          return fo[:gqrx_sock] if fo.is_a?(Hash)
+
+          nil
+        end
+
+        private_class_method def self.enable_rds!(opts = {})
+          sock = opts[:sock]
+          begin
+            PWN::SDR::GQRX.cmd(gqrx_sock: sock, cmd: 'U RDS 0', resp_ok: 'RPRT 0')
+          rescue StandardError
+            nil
+          end
+          begin
+            PWN::SDR::GQRX.cmd(gqrx_sock: sock, cmd: 'U RDS 1', resp_ok: 'RPRT 0')
+            true
+          rescue StandardError
+            false
+          end
+        end
+
+        private_class_method def self.disable_rds!(opts = {})
+          sock = opts[:sock]
+          PWN::SDR::GQRX.cmd(gqrx_sock: sock, cmd: 'U RDS 0')
+        rescue StandardError
+          nil
+        end
+
+        private_class_method def self.poll_once(opts = {})
+          sock = opts[:sock]
+          pi = begin
+            PWN::SDR::GQRX.cmd(gqrx_sock: sock, cmd: 'p RDS_PI').to_s.strip.chomp.delete('.').upcase
+          rescue StandardError
+            ''
+          end
+          ps = begin
+            PWN::SDR::GQRX.cmd(gqrx_sock: sock, cmd: 'p RDS_PS_NAME').to_s.strip.chomp
+          rescue StandardError
+            ''
+          end
+          rt = begin
+            PWN::SDR::GQRX.cmd(gqrx_sock: sock, cmd: 'p RDS_RADIOTEXT').to_s.strip.chomp
+          rescue StandardError
+            ''
+          end
+          { pi: pi, ps: ps, rt: rt }
+        end
+
+        # Fold raw poll samples into the public Hash shape expected by
+        # Extrospection.rf_tune / agents (pi / ps_name / radiotext / station).
+        private_class_method def self.aggregate(opts = {})
+          samples = opts[:samples] || []
+          settle  = opts[:settle_secs]
+
+          best_pi = samples.map { |s| s[:pi] }.find { |p| p =~ /\A[0-9A-F]{4}\z/ && p != '0000' }
+          best_pi = best_pi.to_s.rjust(4, '0')[0, 4] if best_pi
+
+          # PS often scrolls (artist / title / callsign cycle) — collect every
+          # non-empty sample, prefer a short all-caps callsign-like token, and
+          # fall back to the longest only when no callsign was seen.
+          ps_candidates = samples.map { |s| s[:ps].to_s.strip }.reject(&:empty?)
+          callsign_like = ps_candidates.find { |p| p =~ CALLSIGN_RX }
+          best_ps = callsign_like || ps_candidates.max_by(&:length)
+          best_ps = "#{best_ps}        "[0, 8].rstrip if best_ps
+          best_rt = samples.map { |s| s[:rt].to_s.rstrip }.reject(&:empty?).max_by(&:length)
+
+          station = nil
+          if best_rt && best_rt =~ CALLSIGN_RT_RX
+            station = Regexp.last_match(1)
+          elsif callsign_like
+            station = callsign_like
+          elsif best_ps && best_ps =~ CALLSIGN_RX
+            station = best_ps
+          end
+
+          # If station callsign is known and best_ps is just a mid-scroll
+          # fragment of RadioText, prefer station so callers use station + RT.
+          best_ps = station if station && best_ps && best_rt && best_ps != station && best_rt.include?(best_ps)
+
+          {
+            pi: best_pi,
+            ps_name: best_ps,
+            radiotext: best_rt,
+            station: station,
+            samples: samples.length,
+            settle_secs: settle
+          }
+        end
       end
     end
   end

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

@@ -3,14 +3,69 @@
 module PWN
   module SDR
     module Decoder
-      # Pure-Ruby RFID activity detector for LF (125/134 kHz), HF
-      # (13.56 MHz) and UHF (860–960 MHz EPC Gen2).
-      #
-      # Near-field ASK/load-modulation on LF/HF requires an inductive
-      # coupler (not an SDR antenna); UHF backscatter is 40–640 kbps ASK.
-      # Native mode reports reader-carrier presence and tag-response
-      # bursts by band. `parse_line` retained for offline text analysis.
+      # True-air + detector-fallback decoder for RFID.
+      # 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 RFID
+        # 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::RFID.decode(
         #   freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq'
@@ -23,25 +78,26 @@ module PWN
                  elsif hz.between?(13_000_000, 14_000_000) then 'HF'
                  else 'UHF'
                  end
-          PWN::SDR::Decoder::Base.run_detector(
+
+          rate  = (opts[:sample_rate] || freq_obj[:iq_rate] || 2_000_000).to_i
+          proto = "RFID-#{band}"
+          demod = DemodIQ.new(
+            rate: rate, protocol: proto, modulation: 'ASK/load-mod',
+            extra: { threshold: 6.0 }
+          )
+          PWN::SDR::Decoder::Base.run_iq(
             freq_obj: freq_obj,
-            protocol: "RFID-#{band}",
-            note: 'Native mode reports reader-carrier and tag-backscatter bursts by band.',
+            protocol: proto,
+            sample_rate: rate,
+            source: opts[:source],
+            file: opts[:file],
+            demod: demod,
             threshold: 6.0,
-            describe: proc { |b|
-              kind = case band
-                     when 'LF'  then b[:duration_ms] > 100 ? 'reader-CW' : 'EM4x/HID-response'
-                     when 'HF'  then b[:duration_ms] > 5   ? 'ISO14443-REQA/frame' : 'ISO15693-slot'
-                     else            b[:duration_ms] > 20  ? 'reader-Query' : 'EPC-backscatter'
-                     end
-              { band: band, modulation: 'ASK/load-mod', classification: kind }
-            }
+            note: 'True-air I/Q path reports reader-carrier and tag-backscatter bursts by band.',
+            describe: proc { |b| { band: b[:band], modulation: 'ASK/load-mod', classification: b[:classification] } }
           )
         end
 
-        # Supported Method Parameters::
-        # PWN::SDR::Decoder::RFID.parse_line(line: 'UID: 04 A1 B2 C3 D4 E5 F6')
-
         public_class_method def self.parse_line(opts = {})
           line = opts[:line].to_s
           out  = { protocol: 'RFID' }
@@ -60,16 +116,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: 'UID: 04 A1 B2 C3 D4 E5 F6  SAK: 08  Mifare Classic 1K')
-
             #{self}.authors
           "
         end

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

@@ -5,17 +5,69 @@ require 'json'
 module PWN
   module SDR
     module Decoder
-      # Pure-Ruby ISM/keyfob/sensor activity detector for the 315 / 390 /
-      # 433.92 / 868 / 915 MHz device zoo.
-      #
-      # The upstream `rtl_433` binary carries ~250 device-specific protocol
-      # dissectors; re-implementing that library is out of scope. This
-      # module instead characterises OOK/ASK/FSK bursts natively (count,
-      # duration, gap, peak dBFS) — enough to fingerprint a keyfob press,
-      # a periodic weather-station beacon, or a TPMS chirp — without
-      # invoking any external binary. `parse_line` still accepts rtl_433
-      # `-F json` output for offline analysis.
+      # True-air + detector-fallback decoder for RTL433.
+      # 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 RTL433
+        # 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::RTL433.decode(
         #   freq_obj: 'required - freq_obj returned from PWN::SDR::GQRX.init_freq'
@@ -23,24 +75,32 @@ 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] || 250_000).to_i
+          proto = 'ISM-433'
+          demod = DemodIQ.new(
+            rate: rate, protocol: proto, modulation: 'OOK/ASK/FSK',
+            extra: { threshold: 10.0 }
+          )
+          PWN::SDR::Decoder::Base.run_iq(
             freq_obj: freq_obj,
-            protocol: 'ISM-433',
-            note: 'Native OOK/FSK burst characteriser (no rtl_433 binary). Feed captured `rtl_433 -F json` lines to .parse_line for per-device decode.',
+            protocol: proto,
+            sample_rate: rate,
+            source: opts[:source],
+            file: opts[:file],
+            demod: demod,
             threshold: 10.0,
+            note: 'True-air I/Q path characterises OOK/FSK bursts; offline rtl_433 JSON via .parse_line.',
             describe: proc { |b|
-              kind = if b[:duration_ms] < 20 then 'keyfob/OOK-short'
-                     elsif b[:duration_ms] < 120 then 'sensor/OOK-packet'
-                     else 'FSK-continuous'
-                     end
-              { modulation: 'OOK/ASK/FSK', classification: kind }
+              { modulation: 'OOK/ASK/FSK', classification: (if b[:duration_ms] < 20
+                                                              'keyfob/OOK-short'
+                                                            else
+                                                              (b[:duration_ms] < 120 ? 'sensor/OOK-packet' : 'FSK-continuous')
+                                                            end) }
             }
           )
         end
 
-        # Supported Method Parameters::
-        # PWN::SDR::Decoder::RTL433.parse_line(line: '{"time":"...","model":"..."}')
-
         public_class_method def self.parse_line(opts = {})
           line = opts[:line].to_s
           h = begin
@@ -67,16 +127,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: '{\"model\":\"Acurite-Tower\",\"id\":1234,...}')
-
             #{self}.authors
           "
         end