pwn 0.5.510 → 0.5.513

data/lib/pwn/sdr/gqrx.rb

@@ -9,7 +9,7 @@ module PWN
     module GQRX
       # Monkey patches for frequency handling
       String.class_eval do
-        def raw_hz
+        def cast_to_raw_hz
           gsub('.', '').to_i
         end
       end
@@ -20,30 +20,16 @@ module PWN
         # So 2_450_000_000 becomes 2.450.000.000
         # So 960_000_000 becomes 960.000.000
         # 1000 should be 1.000
-        def pretty_hz
+        def cast_to_pretty_hz
           str_hz = to_s
           # Nuke leading zeros
           # E.g., 002450000000 -> 2450000000
-          str_hz = str_hz.sub(/^0+/, '')
+          str_hz = str_hz.sub(/^0+/, '') unless str_hz == '0'
           # Insert dots every 3 digits from the right
           str_hz.reverse.scan(/.{1,3}/).join('.').reverse
         end
       end
 
-      # Supported Method Parameters::
-      # gqrx_sock = PWN::SDR::GQRX.connect(
-      #   target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
-      #   port: 'optional - GQRX target port (defaults to 7356)'
-      # )
-      public_class_method def self.connect(opts = {})
-        target = opts[:target] ||= '127.0.0.1'
-        port = opts[:port] ||= 7356
-
-        PWN::Plugins::Sock.connect(target: target, port: port)
-      rescue StandardError => e
-        raise e
-      end
-
       # Supported Method Parameters::
       # gqrx_resp = PWN::SDR::GQRX.gqrx_cmd(
       #   gqrx_sock: 'required - GQRX socket object returned from #connect method',
@@ -51,17 +37,22 @@ module PWN
       #   resp_ok: 'optional - Expected response from GQRX to indicate success'
       # )
 
-      public_class_method def self.gqrx_cmd(opts = {})
+      private_class_method def self.gqrx_cmd(opts = {})
         gqrx_sock = opts[:gqrx_sock]
         cmd = opts[:cmd]
         resp_ok = opts[:resp_ok]
 
         # Most Recent GQRX Command Set:
         # https://raw.githubusercontent.com/gqrx-sdr/gqrx/master/resources/remote-control.txt
+        # Remote control protocol.
+        #
         # Supported commands:
-        #  f Get frequency [Hz]
-        #  F <frequency> Set frequency [Hz]
-        #  m Get demodulator mode and passband
+        #  f
+        #     Get frequency [Hz]
+        #  F <frequency>
+        #     Set frequency [Hz]
+        #  m
+        #     Get demodulator mode and passband
         #  M <mode> [passband]
         #     Set demodulator mode and passband [Hz]
         #     Passing a '?' as the first argument instead of 'mode' will return
@@ -84,18 +75,30 @@ module PWN
         #     Set the value of the gain setting with the name <gain_name> to <value>
         #  p RDS_PI
         #     Get the RDS PI code (in hexadecimal). Returns 0000 if not applicable.
+        #  p RDS_PS_NAME
+        #     Get the RDS Program Service (PS) name
+        #  p RDS_RADIOTEXT
+        #     Get the RDS RadioText message
         #  u RECORD
         #     Get status of audio recorder
         #  U RECORD <status>
         #     Set status of audio recorder to <status>
+        #  u IQRECORD
+        #     Get status of IQ recorder
+        #  U IQRECORD <status>
+        #     Set status of IQ recorder to <status>
         #  u DSP
         #     Get DSP (SDR receiver) status
         #  U DSP <status>
         #     Set DSP (SDR receiver) status to <status>
         #  u RDS
-        #     Get RDS decoder to <status>.  Only functions in WFM mode.
+        #     Get RDS decoder status.  Only functions in WFM mode.
         #  U RDS <status>
         #     Set RDS decoder to <status>.  Only functions in WFM mode.
+        #  u MUTE
+        #     Get audio mute status
+        #  U MUTE <status>
+        #     Set audio mute to <status>
         #  q|Q
         #     Close connection
         #  AOS
@@ -122,6 +125,7 @@ module PWN
         #  _
         #     Get version
         #
+        #
         # Reply:
         #  RPRT 0
         #     Command successful
@@ -154,7 +158,7 @@ module PWN
         raise "ERROR!!! Command: #{cmd} Expected Resp: #{resp_ok}, Got: #{response_str}" if resp_ok && response_str != resp_ok
 
         # Reformat positive integer frequency responses (e.g., from 'f')
-        response_str = response_str.to_i.pretty_hz if response_str.match?(/^\d+$/) && response_str.to_i.positive?
+        response_str = response_str.to_i.cast_to_pretty_hz if response_str.match?(/^\d+$/) && response_str.to_i.positive?
 
         response_str
       rescue RuntimeError => e
@@ -170,86 +174,306 @@ module PWN
       end
 
       # Supported Method Parameters::
-      # init_freq_hash = PWN::SDR::GQRX.init_freq(
+      # strength_db = PWN::SDR::GQRX.measure_signal_strength(
+      #   gqrx_sock: 'required - GQRX socket object returned from #connect method'
+      # )
+      private_class_method def self.measure_signal_strength(opts = {})
+        gqrx_sock = opts[:gqrx_sock]
+
+        strength_db = -99.9
+        prev_strength_db = strength_db
+        # While strength_db is rising, keep measuring
+        loop do
+          strength_db = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'l STRENGTH').to_f
+          break if strength_db <= prev_strength_db
+
+          prev_strength_db = strength_db
+        end
+
+        strength_db
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # candidate_signals = PWN::SDR::GQRX.edge_detection(
+      #   gqrx_sock: 'required - GQRX socket object returned from #connect method',
+      #   hz: 'required - Frequency to start edge detection from',
+      #   step_hz: 'required - Frequency step in Hz for edge detection',
+      #   strength_lock: 'required - Strength lock in dBFS to determine signal edges'
+      # )
+      private_class_method def self.edge_detection(opts = {})
+        gqrx_sock = opts[:gqrx_sock]
+        hz = opts[:hz]
+        step_hz = opts[:step_hz]
+        strength_lock = opts[:strength_lock]
+        left_candidate_signals = []
+        right_candidate_signals = []
+        candidate_signals = []
+
+        # left_candidate_signals.clear
+        original_hz = hz
+        strength_db = 99.9
+        puts 'Finding Beginning Edge of Signal...'
+        while strength_db >= strength_lock
+          gqrx_cmd(gqrx_sock: gqrx_sock, cmd: "F #{hz}")
+          current_freq = 0
+          while current_freq.to_s.cast_to_raw_hz != hz.to_s.cast_to_raw_hz
+            current_freq = gqrx_cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: 'f'
+            )
+          end
+          strength_db = measure_signal_strength(gqrx_sock: gqrx_sock)
+          candidate = {
+            hz: hz.to_s.cast_to_raw_hz,
+            freq: hz.to_i.cast_to_pretty_hz,
+            strength: strength_db,
+            side: :left
+          }
+          left_candidate_signals.push(candidate)
+          hz -= step_hz
+        end
+        left_candidate_signals.uniq! { |s| s[:hz] }
+        left_candidate_signals.sort_by! { |s| s[:hz] }
+
+        # Now scan forwards to find the end of the signal
+        # The end of the signal is where the strength drops below strength_lock
+        # right_candidate_signals.clear
+        hz = original_hz
+
+        strength_db = 99.9
+        puts 'Finding Ending Edge of Signal...'
+        while strength_db >= strength_lock
+          gqrx_cmd(gqrx_sock: gqrx_sock, cmd: "F #{hz}")
+          current_freq = 0
+          while current_freq.to_s.cast_to_raw_hz != hz.to_s.cast_to_raw_hz
+            current_freq = gqrx_cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: 'f'
+            )
+          end
+          strength_db = measure_signal_strength(gqrx_sock: gqrx_sock)
+          candidate = {
+            hz: hz.to_s.cast_to_raw_hz,
+            freq: hz.to_i.cast_to_pretty_hz,
+            strength: strength_db,
+            side: :right
+          }
+          right_candidate_signals.push(candidate)
+          hz += step_hz
+        end
+        # Update candidate signals to remove duplicates and sort by hz
+        right_candidate_signals.uniq! { |s| s[:hz] }
+        right_candidate_signals.sort_by! { |s| s[:hz] }
+
+        candidate_signals = left_candidate_signals + right_candidate_signals
+        candidate_signals.uniq! { |s| s[:hz] }
+        candidate_signals.sort_by! { |s| s[:hz] }
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # scan_resp = PWN::SDR::GQRX.log_signals(
+      #   signals_arr: 'required - Array of detected signals',
+      #   timestamp_start: 'required - Scan start timestamp',
+      #   scan_log: 'required - Path to save detected signals log'
+      # )
+      private_class_method def self.log_signals(opts = {})
+        signals_arr = opts[:signals_arr]
+        timestamp_start = opts[:timestamp_start]
+        scan_log = opts[:scan_log]
+
+        signals = signals_arr.sort_by { |s| s[:freq].to_s.cast_to_raw_hz }
+        # Unique signals by frequency
+        signals.uniq! { |s| s[:hz] }
+
+        timestamp_end = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
+        duration_secs = Time.parse(timestamp_end) - Time.parse(timestamp_start)
+        # Convert duration seconds to hours minutes seconds
+        hours = (duration_secs / 3600).to_i
+        minutes = ((duration_secs % 3600) / 60).to_i
+        seconds = (duration_secs % 60).to_i
+        duration = format('%<hrs>02d:%<mins>02d:%<secs>02d', hrs: hours, mins: minutes, secs: seconds)
+
+        scan_resp = {
+          signals: signals,
+          total: signals.length,
+          timestamp_start: timestamp_start,
+          timestamp_end: timestamp_end,
+          duration: duration
+        }
+
+        File.write(
+          scan_log,
+          JSON.pretty_generate(scan_resp)
+        )
+
+        scan_resp
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # rds_resp = PWN::SDR::GQRX.decode_rds(
+      #   gqrx_sock: 'required - GQRX socket object returned from #connect method'
+      # )
+
+      private_class_method def self.decode_rds(opts = {})
+        gqrx_sock = opts[:gqrx_sock]
+
+        # We toggle RDS off and on to reset the decoder
+        rds_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: 'U RDS 0',
+          resp_ok: 'RPRT 0'
+        )
+
+        rds_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: 'U RDS 1',
+          resp_ok: 'RPRT 0'
+        )
+
+        rds_resp = {}
+        attempts = 0
+        max_attempts = 90
+        skip_rds = "\n"
+        print 'INFO: Decoding FM radio RDS data (Press ENTER to skip)...'
+        max_attempts.times do
+          attempts += 1
+          rds_resp[:rds_pi] = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'p RDS_PI')
+          rds_resp[:rds_ps_name] = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'p RDS_PS_NAME')
+          rds_resp[:rds_radiotext] = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'p RDS_RADIOTEXT')
+
+          # Break if ENTER key pressed
+          # This is useful if no RDS data is available
+          # on the current frequency (e.g. false+)
+          break if $stdin.ready? && $stdin.read_nonblock(1) == skip_rds
+
+          break if rds_resp[:rds_pi] != '0000' && !rds_resp[:rds_ps_name].empty? && !rds_resp[:rds_radiotext].empty?
+
+          print '.'
+          sleep 0.1
+        end
+        puts 'complete.'
+        rds_resp
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # gqrx_sock = PWN::SDR::GQRX.connect(
+      #   target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
+      #   port: 'optional - GQRX target port (defaults to 7356)'
+      # )
+      public_class_method def self.connect(opts = {})
+        target = opts[:target] ||= '127.0.0.1'
+        port = opts[:port] ||= 7356
+
+        PWN::Plugins::Sock.connect(target: target, port: port)
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # freq_obj = PWN::SDR::GQRX.init_freq(
       #   gqrx_sock: 'required - GQRX socket object returned from #connect method',
       #   freq: 'required - Frequency to set',
       #   demodulator_mode: 'optional - Demodulator mode (defaults to WFM)',
+      #   rds: 'optional - Boolean to enable/disable RDS decoding (defaults to false)',
       #   bandwidth: 'optional - Bandwidth (defaults to 200_000)',
       #   squelch: 'optional - Squelch level to set (Defaults to current value)',
       #   decoder: 'optional - Decoder key (e.g., :gsm) to start live decoding (starts recording if provided)',
-      #   record_dir: 'optional - Directory where GQRX saves recordings (required if decoder provided; defaults to Dir.home)',
-      #   decoder_opts: 'optional - Hash of additional options for the decoder',
-      #   suppress_details: 'optional - Boolean to include extra frequency details in return hash (defaults to false)'
+      #   record_dir: 'optional - Directory where GQRX saves recordings (required if decoder provided; defaults to /tmp/gqrx_recordings)',
+      #   suppress_details: 'optional - Boolean to include extra frequency details in return hash (defaults to false)',
+      #   keep_alive: 'optional - Boolean to keep GQRX connection alive after method completion (defaults to false)'
       # )
       public_class_method def self.init_freq(opts = {})
         gqrx_sock = opts[:gqrx_sock]
         freq = opts[:freq]
-        demodulator_mode = opts[:demodulator_mode] ||= 'WFM'
+        valid_demodulator_modes = %i[
+          AM
+          AM_SYNC
+          CW
+          CWL
+          CWU
+          FM
+          OFF
+          LSB
+          RAW
+          USB
+          WFM
+          WFM_ST
+          WFM_ST_OIRT
+        ]
+        demodulator_mode = opts[:demodulator_mode] ||= :WFM
+        raise "ERROR: Invalid demodulator_mode '#{demodulator_mode}'. Valid modes: #{valid_demodulator_modes.join(', ')}" unless valid_demodulator_modes.include?(demodulator_mode.to_sym)
+
+        rds = opts[:rds] ||= false
+
         bandwidth = opts[:bandwidth] ||= 200_000
         squelch = opts[:squelch]
         decoder = opts[:decoder]
-        record_dir = opts[:record_dir] ||= Dir.home
-        decoder_opts = opts[:decoder_opts] ||= {}
+        record_dir = opts[:record_dir] ||= '/tmp'
         suppress_details = opts[:suppress_details] || false
+        keep_alive = opts[:keep_alive] || false
 
         raise "ERROR: record_dir '#{record_dir}' does not exist. Please create it or provide a valid path." if decoder && !Dir.exist?(record_dir)
 
-        hz = freq.to_s.raw_hz
-
-        if squelch.is_a?(Float) && squelch >= -100.0 && squelch <= 0.0
+        unless keep_alive
+          squelch = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'l SQL').to_f if squelch.nil?
           change_squelch_resp = gqrx_cmd(
             gqrx_sock: gqrx_sock,
             cmd: "L SQL #{squelch}",
             resp_ok: 'RPRT 0'
           )
+
+          mode_str = demodulator_mode.to_s.upcase
+          passband_hz = bandwidth.to_s.cast_to_raw_hz
+          gqrx_cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: "M #{mode_str} #{passband_hz}",
+            resp_ok: 'RPRT 0'
+          )
         end
 
         change_freq_resp = gqrx_cmd(
           gqrx_sock: gqrx_sock,
-          cmd: "F #{hz}",
-          resp_ok: 'RPRT 0'
-        )
-
-        # Set demod mode and bandwidth (always, using defaults if not provided)
-        mode_str = demodulator_mode.to_s.upcase
-        passband_hz = bandwidth.to_s.raw_hz
-        gqrx_cmd(
-          gqrx_sock: gqrx_sock,
-          cmd: "M #{mode_str} #{passband_hz}",
+          cmd: "F #{freq.to_s.cast_to_raw_hz}",
           resp_ok: 'RPRT 0'
         )
 
-        # Get demodulator mode n passband
-        demod_n_passband = gqrx_cmd(
-          gqrx_sock: gqrx_sock,
-          cmd: 'm'
-        )
-
-        # Get current frequency
-        current_freq = gqrx_cmd(
-          gqrx_sock: gqrx_sock,
-          cmd: 'f'
-        )
+        current_freq = 0
+        while current_freq.to_s.cast_to_raw_hz != freq.to_s.cast_to_raw_hz
+          current_freq = gqrx_cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: 'f'
+          )
+        end
 
-        init_freq_hash = {
-          demod_mode_n_passband: demod_n_passband,
-          frequency: current_freq,
-          bandwidth: bandwidth
+        freq_obj = {
+          bandwidth: bandwidth,
+          demodulator_mode: demodulator_mode,
+          rds: rds,
+          freq: freq
         }
 
         unless suppress_details
+          demod_n_passband = gqrx_cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: 'm'
+          )
+
           audio_gain_db = gqrx_cmd(
             gqrx_sock: gqrx_sock,
             cmd: 'l AF'
           ).to_f
 
-          strength_db_float = gqrx_cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: 'l STRENGTH'
-          ).to_f
-          strength_db = strength_db_float.round(1)
+          strength_db = measure_signal_strength(gqrx_sock: gqrx_sock)
 
-          current_squelch = gqrx_cmd(
+          squelch = gqrx_cmd(
             gqrx_sock: gqrx_sock,
             cmd: 'l SQL'
           ).to_f
@@ -269,67 +493,73 @@ module PWN
             cmd: 'l BB_GAIN'
           )
 
-          init_freq_hash[:audio_gain_db] = audio_gain_db
-          init_freq_hash[:squelch_set] = current_squelch
-          init_freq_hash[:rf_gain] = rf_gain
-          init_freq_hash[:if_gain] = if_gain
-          init_freq_hash[:bb_gain] = bb_gain
-          init_freq_hash[:strength_db] = strength_db
-
-          # Start recording and decoding if decoder provided
-          decoder_module = nil
-          decoder_thread = nil
-          record_path = nil
-          if decoder
-            # Resolve decoder module via case statement for extensibility
-            case decoder
-            when :gsm
-              decoder_module = PWN::SDR::Decoder::GSM
-            else
-              raise "ERROR: Unknown decoder key: #{decoder}. Supported: :gsm"
-            end
+          rds_resp = nil
+          rds_resp = decode_rds(gqrx_sock: gqrx_sock) if rds
+
+          freq_obj[:audio_gain_db] = audio_gain_db
+          freq_obj[:demod_mode_n_passband] = demod_n_passband
+          freq_obj[:bb_gain] = bb_gain
+          freq_obj[:if_gain] = if_gain
+          freq_obj[:rf_gain] = rf_gain
+          freq_obj[:squelch] = squelch
+          freq_obj[:strength_db] = strength_db
+          freq_obj[:rds] = rds_resp
+        end
 
-            # Ensure recording is off before starting
-            record_status = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'u RECORD')
-            gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'U RECORD 0', resp_ok: 'RPRT 0') if record_status == '1'
+        # Start recording and decoding if decoder provided
+        decoder_module = nil
+        decoder_thread = nil
+        record_path = nil
+        if decoder
+          # Resolve decoder module via case statement for extensibility
+          case decoder
+          when :gsm
+            decoder_module = PWN::SDR::Decoder::GSM
+          else
+            raise "ERROR: Unknown decoder key: #{decoder}. Supported: :gsm"
+          end
 
-            # Start recording
-            gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'U RECORD 1', resp_ok: 'RPRT 0')
+          # Ensure recording is off before starting
+          record_status = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'u RECORD')
+          gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'U RECORD 0', resp_ok: 'RPRT 0') if record_status == '1'
 
-            # Prepare for decoder
-            start_time = Time.now
-            expected_filename = "gqrx_#{start_time.strftime('%Y%m%d_%H%M%S')}_#{current_freq_raw}.wav"
-            record_path = File.join(record_dir, expected_filename)
+          # Start recording
+          gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'U RECORD 1', resp_ok: 'RPRT 0')
 
-            # Build partial gqrx_obj for decoder start
-            gqrx_obj_partial = {
-              gqrx_sock: gqrx_sock,
-              record_path: record_path,
-              frequency: current_freq,
-              bandwidth: bandwidth,
-              demodulator_mode: demodulator_mode
-            }
-
-            # Initialize and start decoder (module style: .start returns thread)
-            decoder_thread = decoder_module.start(
-              gqrx_obj: gqrx_obj_partial,
-              **decoder_opts
-            )
+          # Prepare for decoder
+          start_time = Time.now
+          expected_filename = "gqrx_#{start_time.strftime('%Y%m%d_%H%M%S')}_#{current_freq_raw}.wav"
+          record_path = File.join(record_dir, expected_filename)
 
-            init_freq_hash[:decoder] = decoder
-            init_freq_hash[:decoder_module] = decoder_module
-            init_freq_hash[:decoder_thread] = decoder_thread
-            init_freq_hash[:record_path] = record_path
-          end
+          # Build partial gqrx_obj for decoder start
+          freq_obj[:record_path] = record_path
+
+          # Initialize and start decoder (module style: .start returns thread)
+          freq_obj[:gqrx_sock] = gqrx_sock
+          decoder_thread = decoder_module.start(freq_obj: freq_obj)
+          freq_obj.delete(:gqrx_sock)
+
+          freq_obj[:freq] = current_freq
+          freq_obj[:decoder] = decoder
+          freq_obj[:decoder_module] = decoder_module
+          freq_obj[:decoder_thread] = decoder_thread
+          freq_obj[:record_path] = record_path
         end
 
-        init_freq_hash
+        freq_obj
       rescue StandardError => e
         raise e
       ensure
-        # Ensure recording is stopped and decoder is stopped on error
-        gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'U RECORD 0', resp_ok: 'RPRT 0') if gqrx_sock && decoder
-        decoder_module.stop(thread: decoder_thread, gqrx_obj: init_freq_hash) if decoder_module && decoder_thread
+        # Ensure decoder recording stops
+        if decoder
+          gqrx_cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: 'U RECORD 0',
+            resp_ok: 'RPRT 0'
+          )
+          decoder_module.stop(freq_obj: freq_obj)
+        end
+        disconnect(gqrx_sock: gqrx_sock) if gqrx_sock.is_a?(TCPSocket) && !keep_alive
       end
 
       # Supported Method Parameters::
@@ -338,79 +568,124 @@ module PWN
       #   start_freq: 'required - Start frequency of scan range',
       #   target_freq: 'required - Target frequency of scan range',
       #   demodulator_mode: 'optional - Demodulator mode (e.g. WFM, AM, FM, USB, LSB, RAW, CW, RTTY / defaults to WFM)',
+      #   rds: 'optional - Boolean to enable/disable RDS decoding (defaults to false)',
       #   bandwidth: 'optional - Bandwidth in Hz (Defaults to 200_000)',
-      #   overlap_protection: 'optional - Boolean to enable/disable bandwidth overlap protection (defaults to false)',
       #   precision: 'optional - Frequency step precision (number of digits; defaults to 1)',
-      #   lock_freq_duration: 'optional - Lock frequency duration in seconds (defaults to 0.04)',
       #   strength_lock: 'optional - Strength lock in dBFS (defaults to -70.0)',
       #   squelch: 'optional - Squelch level in dBFS (defaults to strength_lock - 3.0)',
+      #   audio_gain_db: 'optional - Audio gain in dB (defaults to 6.0)',
+      #   rf_gain: 'optional - RF gain (defaults to 0.0)',
+      #   intermediate_gain: 'optional - Intermediate gain (defaults to 32.0)',
+      #   baseband_gain: 'optional - Baseband gain (defaults to 10.0)',
+      #   scan_log: 'optional - Path to save detected signals log (defaults to /tmp/pwn_sdr_gqrx_scan_<start_freq>-<target_freq>_<timestamp>.json)',
       #   location: 'optional - Location string to include in AI analysis (e.g., "New York, NY", 90210, GPS coords, etc.)'
       # )
 
       public_class_method def self.scan_range(opts = {})
+        timestamp_start = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
+        log_timestamp = Time.now.strftime('%Y-%m-%d')
+
         gqrx_sock = opts[:gqrx_sock]
+
         start_freq = opts[:start_freq]
+        hz_start = start_freq.to_s.cast_to_raw_hz
+
         target_freq = opts[:target_freq]
+        hz_target = target_freq.to_s.cast_to_raw_hz
+
         demodulator_mode = opts[:demodulator_mode]
+        rds = opts[:rds] ||= false
+
         bandwidth = opts[:bandwidth] ||= 200_000
-        overlap_protection = opts[:overlap_protection] || false
         precision = opts[:precision] ||= 1
-        lock_freq_duration = opts[:lock_freq_duration] ||= 0.04
         strength_lock = opts[:strength_lock] ||= -70.0
         squelch = opts[:squelch] ||= (strength_lock - 3.0)
+        scan_log = opts[:scan_log] ||= "/tmp/pwn_sdr_gqrx_scan_#{hz_start.to_i.cast_to_pretty_hz}-#{hz_target.to_i.cast_to_pretty_hz}_#{log_timestamp}.json"
         location = opts[:location] ||= 'United States'
 
-        timestamp_start = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
-
-        hz_start = start_freq.to_s.raw_hz
-        hz_target = target_freq.to_s.raw_hz
         step_hz = 10**(precision - 1)
         step = hz_start > hz_target ? -step_hz : step_hz
 
-        # Set demodulator mode & passband once
+        # Set squelch once for the scan
+        change_squelch_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: "L SQL #{squelch}",
+          resp_ok: 'RPRT 0'
+        )
+
+        # We always disable RDS decoding at during the scan
+        # to prevent unnecessary processing overhead.
+        # We return the rds boolean in the scan_resp object
+        # so it will be picked up and used appropriately
+        # when calling analyze_scan or analyze_log methods.
+        rds_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: 'U RDS 0',
+          resp_ok: 'RPRT 0'
+        )
+
+        # Set demodulator mode & passband once for the scan
         mode_str = demodulator_mode.to_s.upcase
-        passband_hz = bandwidth.to_s.raw_hz
+        passband_hz = bandwidth.to_s.cast_to_raw_hz
         gqrx_cmd(
           gqrx_sock: gqrx_sock,
           cmd: "M #{mode_str} #{passband_hz}",
           resp_ok: 'RPRT 0'
         )
 
-        # Prime radio at starting frequency
-        prev_freq_hash = init_freq(
+        audio_gain_db = opts[:audio_gain_db] ||= 6.0
+        audio_gain_db = audio_gain_db.to_f
+        audio_gain_db_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: "L AF #{audio_gain_db}",
+          resp_ok: 'RPRT 0'
+        )
+
+        rf_gain = opts[:rf_gain] ||= 0.0
+        rf_gain = rf_gain.to_f
+        rf_gain_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: "L RF_GAIN #{rf_gain}",
+          resp_ok: 'RPRT 0'
+        )
+
+        intermediate_gain = opts[:intermediate_gain] ||= 32.0
+        intermediate_gain = intermediate_gain.to_f
+        intermediate_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: "L IF_GAIN #{intermediate_gain}",
+          resp_ok: 'RPRT 0'
+        )
+
+        baseband_gain = opts[:baseband_gain] ||= 10.0
+        baseband_gain = baseband_gain.to_f
+        baseband_resp = gqrx_cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: "L BB_GAIN #{baseband_gain}",
+          resp_ok: 'RPRT 0'
+        )
+
+        prev_freq_obj = init_freq(
           gqrx_sock: gqrx_sock,
-          freq: start_freq,
+          freq: hz_start,
           demodulator_mode: demodulator_mode,
+          rds: rds,
           bandwidth: bandwidth,
           squelch: squelch,
-          suppress_details: true
+          suppress_details: true,
+          keep_alive: true
         )
-        prev_freq_hash[:lock_freq_duration] = lock_freq_duration
-        prev_freq_hash[:strength_lock] = strength_lock
 
-        in_signal = false
         candidate_signals = []
-        strength_history = []
 
-        # ──────────────────────────────────────────────────────────────
         # Adaptive peak finder – trims weakest ends after each pass
         # Converges quickly to the true center of the bell curve
-        # ──────────────────────────────────────────────────────────────
         find_best_peak = lambda do |opts = {}|
-          beg_of_signal_hz = opts[:beg_of_signal_hz].to_s.raw_hz
-          top_of_signal_hz = opts[:top_of_signal_hz].to_s.raw_hz
-          end_of_signal_hz = top_of_signal_hz + step_hz
-
-          # current_hz = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'f').to_s.raw_hz
-          # puts "Current Frequency: #{current_hz.pretty_hz}"
-          puts "Signal Began: #{beg_of_signal_hz.pretty_hz}"
-          puts "Signal Appeared to Peak at: #{top_of_signal_hz.pretty_hz}"
-          puts "Calculated Signal End: #{end_of_signal_hz.pretty_hz}"
-          # steps_between_beg_n_end = ((end_of_signal_hz - beg_of_signal_hz) / step_hz).abs
-          # puts steps_between_beg_n_end.inspect
+          beg_of_signal_hz = opts[:beg_of_signal_hz].to_s.cast_to_raw_hz
+          end_of_signal_hz = opts[:end_of_signal_hz].to_s.cast_to_raw_hz
 
           samples = []
-          prev_best_sample = nil
+          prev_best_sample = {}
           consecutive_best = 0
           direction_up = true
 
@@ -433,19 +708,19 @@ module PWN
               print '>' if direction_up
               print '<' unless direction_up
               gqrx_cmd(gqrx_sock: gqrx_sock, cmd: "F #{hz}")
-              sleep lock_freq_duration
-              strength_db_float = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'l STRENGTH').to_f
-              strength_db = strength_db_float.round(1)
+              strength_db = measure_signal_strength(gqrx_sock: gqrx_sock)
               samples.push({ hz: hz, strength_db: strength_db })
 
-              # current_hz = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'f').to_s.raw_hz
-              # puts "Sampled Frequency: #{current_hz.pretty_hz} => Strength: #{strength_db} dBFS"
+              # current_hz = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'f').to_s.cast_to_raw_hz
+              # puts "Sampled Frequency: #{current_hz.to_i.cast_to_pretty_hz} => Strength: #{strength_db} dBFS"
             end
 
             # Compute fresh averaged_samples from all cumulative samples
             averaged_samples = []
             samples.group_by { |s| s[:hz] }.each do |hz, grouped_samples|
-              avg_strength = (grouped_samples.map { |s| s[:strength_db] }.sum / grouped_samples.size).round(1)
+              avg_strength = (grouped_samples.map { |s| s[:strength_db] }.sum / grouped_samples.size)
+              # avg_strength = (grouped_samples.map { |s| s[:strength_db] }.sum / grouped_samples.size).round(2)
+              # avg_strength = (grouped_samples.map { |s| s[:strength_db] }.sum / grouped_samples.size).round(1)
               averaged_samples.push({ hz: hz, strength_db: avg_strength })
             end
 
@@ -475,7 +750,7 @@ module PWN
             best_sample = averaged_samples.max_by { |s| s[:strength_db] }
 
             # Check for improvement
-            if best_sample == prev_best_sample
+            if best_sample[:hz] == prev_best_sample[:hz]
               consecutive_best += 1
             else
               consecutive_best = 0
@@ -484,7 +759,7 @@ module PWN
             # Dup to avoid reference issues
             prev_best_sample = best_sample.dup
 
-            puts "Pass #{pass_count}: Best #{best_sample[:hz].pretty_hz} => #{best_sample[:strength_db]} dBFS, consecutive best count: #{consecutive_best}"
+            puts "Pass #{pass_count}: Best #{best_sample[:hz].to_i.cast_to_pretty_hz} => #{best_sample[:strength_db]} dBFS, consecutive best count: #{consecutive_best}"
 
             # Break if no improvement in 3 consecutive passes or theres only one sample left
             break if consecutive_best.positive? || averaged_samples.size == 1
@@ -494,91 +769,175 @@ module PWN
         end
 
         # Begin scanning range
-        puts "INFO: Scanning from #{hz_start.pretty_hz} to #{hz_target.pretty_hz} in steps of #{step.abs.pretty_hz} Hz.\nIf scans are slow and/or you're experiencing false positives/negatives, consider adjusting:\n1. The SDR's sample rate in GQRX\n\s\s- Click on `Configure I/O devices`.\n\s\s- A lower `Input rate` value seems counter-intuitive but works well (e.g. ADALM PLUTO ~ 1000000).\n2. Adjust the :strength_lock parameter.\n3. Adjust the :lock_freq_duration parameter.\n4. Adjust the :precision parameter.\n5. Disable AI introspection in PWN::Env\nHappy scanning!\n\n"
+        puts "\n"
+        puts '-' * 86
+        puts "INFO: Scanning from #{hz_start.to_i.cast_to_pretty_hz} to #{hz_target.to_i.cast_to_pretty_hz} in steps of #{step.abs.to_i.cast_to_pretty_hz} Hz."
+        puts "If scans are slow and/or you're experiencing false positives/negatives,"
+        puts 'consider adjusting the following:'
+        puts "1. The SDR's sample rate in GQRX"
+        puts "\s\s- Click on `Configure I/O devices`."
+        puts "\s\s- A lower `Input rate` value seems counter-intuitive but works well (e.g. ADALM PLUTO ~ 1000000)."
+        puts '2. Adjust the :strength_lock parameter.'
+        puts '3. Adjust the :precision parameter.'
+        puts '4. Disable AI introspection in PWN::Env'
+        puts 'Happy scanning!'
+        puts '-' * 86
+        puts "\n\n\n"
 
         signals_arr = []
-        hz_start.step(by: step, to: hz_target) do |hz|
+        hz = hz_start
+        while hz <= hz_target
           gqrx_cmd(gqrx_sock: gqrx_sock, cmd: "F #{hz}")
-          sleep lock_freq_duration
-          strength_db_float = gqrx_cmd(gqrx_sock: gqrx_sock, cmd: 'l STRENGTH').to_f
-          strength_db = strength_db_float.round(1)
-          prev_strength_db = strength_history.last || -Float::INFINITY
-
-          if strength_db >= strength_lock && strength_db > prev_strength_db
-            in_signal = true
-            strength_history.push(strength_db)
-            strength_history.shift if strength_history.size > 5
-            current_strength = (strength_history.sum / strength_history.size).round(1)
-
-            print '.'
-            puts "#{hz.pretty_hz} => #{strength_db}"
-
-            candidate = { hz: hz, freq: hz.pretty_hz, strength: current_strength }
-            candidate_signals.push(candidate)
-          else
-            if in_signal
-              beg_of_signal_hz = candidate_signals.map { |s| s[:hz] }.min
-              # Previous max step_hz was actually the top of the signal
-              top_of_signal_hz = candidate_signals.map { |s| s[:hz] }.max - step_hz
-
-              skip_signal = false
-              prev_frequency = prev_freq_hash[:frequency].to_s.raw_hz
-              distance_from_prev_detected_freq_hz = (beg_of_signal_hz - prev_frequency).abs
-              half_bandwidth = (bandwidth / 2).to_i
-              skip_signal = true if distance_from_prev_detected_freq_hz < half_bandwidth && overlap_protection
-              puts "Prev Dect Freq: #{prev_frequency} | New Freq Edge: #{beg_of_signal_hz} | Distance from Prev Dect Freq: #{distance_from_prev_detected_freq_hz} Hz | Step Hz: #{step_hz} | Bandwidth: #{bandwidth} Hz | Half Bandwidth: #{half_bandwidth} Hz | Overlap Protection? #{overlap_protection} | Skip Signal? #{skip_signal}"
-              next if skip_signal
-
-              best_peak = find_best_peak.call(
-                beg_of_signal_hz: beg_of_signal_hz,
-                top_of_signal_hz: top_of_signal_hz
+          current_freq = 0
+          while current_freq.to_s.cast_to_raw_hz != hz.to_s.cast_to_raw_hz
+            current_freq = gqrx_cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: 'f'
+            )
+          end
+
+          strength_db = measure_signal_strength(gqrx_sock: gqrx_sock)
+
+          if strength_db >= strength_lock
+            puts '-' * 86
+            # Find left and right edges of the signal
+            candidate_signals = edge_detection(
+              gqrx_sock: gqrx_sock,
+              hz: hz,
+              step_hz: step_hz,
+              strength_lock: strength_lock
+            )
+          elsif candidate_signals.length.positive?
+            beg_of_signal_hz = candidate_signals.first[:hz]
+            top_of_signal_hz_idx = (candidate_signals.length - 1) / 2
+            top_of_signal_hz = candidate_signals[top_of_signal_hz_idx][:hz]
+            end_of_signal_hz = candidate_signals.last[:hz]
+            puts 'Candidate Signal(s) Detected:'
+            puts JSON.pretty_generate(candidate_signals)
+
+            prev_freq = prev_freq_obj[:freq].to_s.cast_to_raw_hz
+            distance_from_prev_detected_freq_hz = (beg_of_signal_hz - prev_freq).abs
+            half_bandwidth = (bandwidth / 2).to_i
+
+            puts "Key Frequencies: Begin: #{beg_of_signal_hz.to_i.cast_to_pretty_hz} Hz | Estimated Top: #{top_of_signal_hz.to_i.cast_to_pretty_hz} Hz | End: #{end_of_signal_hz.to_i.cast_to_pretty_hz} Hz"
+
+            puts 'Finding Best Peak...'
+            best_peak = find_best_peak.call(
+              beg_of_signal_hz: beg_of_signal_hz,
+              end_of_signal_hz: end_of_signal_hz
+            )
+
+            if best_peak[:hz] && best_peak[:strength_db] > strength_lock
+              puts "\n**** Detected Signal ****"
+              best_freq = best_peak[:hz].to_i.cast_to_pretty_hz
+              best_strength_db = best_peak[:strength_db]
+              prev_freq_obj = init_freq(
+                gqrx_sock: gqrx_sock,
+                freq: best_freq,
+                rds: rds,
+                suppress_details: true,
+                keep_alive: true
+              )
+              prev_freq_obj[:strength_lock] = strength_lock
+              prev_freq_obj[:strength_db] = best_strength_db
+
+              system_role_content = "Analyze signal data captured by a software-defined-radio using GQRX at the following location: #{location}. Respond with just FCC information about the transmission if available.  If the frequency is unlicensed or not found in FCC records, state that clearly.  Be clear and concise in your analysis."
+              ai_analysis = PWN::AI::Introspection.reflect_on(
+                request: prev_freq_obj.to_json,
+                system_role_content: system_role_content,
+                suppress_pii_warning: true
               )
 
-              if best_peak[:hz] && best_peak[:strength_db] > strength_lock
-                prev_freq_hash = init_freq(
-                  gqrx_sock: gqrx_sock,
-                  freq: best_peak[:hz],
-                  demodulator_mode: demodulator_mode,
-                  bandwidth: bandwidth,
-                  squelch: squelch,
-                  suppress_details: true
-                )
-                prev_freq_hash[:lock_freq_duration] = lock_freq_duration
-                prev_freq_hash[:strength_lock] = strength_lock
-
-                system_role_content = "Analyze signal data captured by a software-defined-radio using GQRX at the following location: #{location}. Respond with just FCC information about the transmission if available.  If the frequency is unlicensed or not found in FCC records, state that clearly.  Be clear and concise in your analysis."
-                ai_analysis = PWN::AI::Introspection.reflect_on(
-                  request: prev_freq_hash.to_json,
-                  system_role_content: system_role_content,
-                  suppress_pii_warning: true
-                )
-                prev_freq_hash[:ai_analysis] = ai_analysis unless ai_analysis.nil?
-                puts "\n**** Detected Signal ****"
-                puts JSON.pretty_generate(prev_freq_hash)
-                signals_arr.push(prev_freq_hash)
-              end
-              candidate_signals.clear
-              sleep lock_freq_duration
+              prev_freq_obj[:ai_analysis] = ai_analysis unless ai_analysis.nil?
+              puts JSON.pretty_generate(prev_freq_obj)
+              puts '-' * 86
+              puts "\n\n\n"
+              signals_arr.push(prev_freq_obj)
+              log_signals(
+                signals_arr: signals_arr,
+                timestamp_start: timestamp_start,
+                scan_log: scan_log
+              )
+              hz = end_of_signal_hz
+              # gets
             end
-            in_signal = false
-            strength_history = []
+            candidate_signals.clear
           end
+          hz += step_hz
         end
-        signals = signals_arr.sort_by { |s| s[:frequency].to_s.raw_hz }
-        timestamp_end = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
-        duration_secs = Time.parse(timestamp_end) - Time.parse(timestamp_start)
-        # Convert duration seconds to hours minutes seconds
-        hours = (duration_secs / 3600).to_i
-        minutes = ((duration_secs % 3600) / 60).to_i
-        seconds = (duration_secs % 60).to_i
-        duration = format('%<hrs>02d:%<mins>02d:%<secs>02d', hrs: hours, mins: minutes, secs: seconds)
 
-        {
-          signals: signals,
+        log_signals(
+          signals_arr: signals_arr,
           timestamp_start: timestamp_start,
-          timestamp_end: timestamp_end,
-          duration: duration
-        }
+          scan_log: scan_log
+        )
+      rescue Interrupt
+        puts "\nCTRL+C detected - goodbye."
+      rescue StandardError => e
+        raise e
+      ensure
+        disconnect(gqrx_sock: gqrx_sock)
+      end
+
+      # Supported Method Parameters::
+      # PWN::SDR::GQRX.analyze_scan(
+      #   scan_resp: 'required - Scan response hash returned from #scan_range method',
+      #   target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
+      #   port: 'optional - GQRX target port (defaults to 7356)'
+      # )
+      public_class_method def self.analyze_scan(opts = {})
+        scan_resp = opts[:scan_resp]
+        raise 'ERROR: scan_resp is required.' if scan_resp.nil? || scan_resp[:signals].nil? || scan_resp[:signals].empty?
+
+        target = opts[:target]
+        port = opts[:port]
+        gqrx_sock = connect(
+          target: target,
+          port: port
+        )
+
+        scan_resp[:signals].each do |signal|
+          signal[:gqrx_sock] = gqrx_sock
+          # This is required to keep connection alive during analysis
+          signal[:keep_alive] = true
+          freq_obj = init_freq(signal)
+          freq_obj = signal.merge(freq_obj)
+          # Redact gqrx_sock from output
+          freq_obj.delete(:gqrx_sock)
+          puts JSON.pretty_generate(freq_obj)
+          print 'Press [ENTER] to continue...'
+          gets
+          puts "\n" * 3
+        end
+      rescue Interrupt
+        puts "\nCTRL+C detected - goodbye."
+      rescue StandardError => e
+        raise e
+      ensure
+        disconnect(gqrx_sock: gqrx_sock)
+      end
+
+      # Supported Method Parameters::
+      # PWN::SDR::GQRX.analyze_log(
+      #   scan_log: 'required - Path to signals log file',
+      #   target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
+      #   port: 'optional - GQRX target port (defaults to 7356)'
+      # )
+      public_class_method def self.analyze_log(opts = {})
+        scan_log = opts[:scan_log]
+        raise 'ERROR: scan_log path is required.' unless File.exist?(scan_log)
+
+        scan_resp = JSON.parse(File.read(scan_log), symbolize_names: true)
+        raise 'ERROR: No signals found in log.' if scan_resp[:signals].nil? || scan_resp[:signals].empty?
+
+        target = opts[:target]
+        port = opts[:port]
+
+        analyze_scan(
+          scan_resp: scan_resp,
+          target: target,
+          port: port
+        )
       rescue StandardError => e
         raise e
       end
@@ -590,7 +949,7 @@ module PWN
       public_class_method def self.disconnect(opts = {})
         gqrx_sock = opts[:gqrx_sock]
 
-        PWN::Plugins::Sock.disconnect(sock_obj: gqrx_sock)
+        PWN::Plugins::Sock.disconnect(sock_obj: gqrx_sock) unless gqrx_sock.closed?
       rescue StandardError => e
         raise e
       end
@@ -608,25 +967,20 @@ module PWN
       public_class_method def self.help
         puts "USAGE:
           gqrx_sock = #{self}.connect(
-          target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
+            target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
             port: 'optional - GQRX target port (defaults to 7356)'
           )
 
-          gqrx_resp = #{self}.gqrx_cmd(
-            gqrx_sock: 'required - GQRX socket object returned from #connect method',
-            cmd: 'required - GQRX command to execute',
-            resp_ok: 'optional - Expected response from GQRX to indicate success'
-          )
-
-          init_freq_hash = #{self}.init_freq(
+          freq_obj = #{self}.init_freq(
             gqrx_sock: 'required - GQRX socket object returned from #connect method',
             freq: 'required - Frequency to set',
             demodulator_mode: 'optional - Demodulator mode (defaults to WFM)',
+            rds: 'optional - Boolean to enable/disable RDS decoding (defaults to false)',
             bandwidth: 'optional - Bandwidth (defaults to 200_000)',
             decoder: 'optional - Decoder key (e.g., :gsm) to start live decoding (starts recording if provided)',
-            record_dir: 'optional - Directory where GQRX saves recordings (required if decoder provided; defaults to ~/gqrx_recordings)',
-            decoder_opts: 'optional - Hash of additional options for the decoder',
-            suppress_details: 'optional - Boolean to include extra frequency details in return hash (defaults to false)'
+            record_dir: 'optional - Directory where GQRX saves recordings (required if decoder provided; defaults to /tmp/gqrx_recordings)',
+            suppress_details: 'optional - Boolean to include extra frequency details in return hash (defaults to false)',
+            keep_alive: 'optional - Boolean to keep GQRX connection alive after method completion (defaults to false)'
           )
 
           scan_resp = #{self}.scan_range(
@@ -635,14 +989,29 @@ module PWN
             target_freq: 'required - Target frequency',
             demodulator_mode: 'optional - Demodulator mode (e.g. WFM, AM, FM, USB, LSB, RAW, CW, RTTY / defaults to WFM)',
             bandwidth: 'optional - Bandwidth in Hz (Defaults to 200_000)',
-            overlap_protection: 'optional - Boolean to enable/disable bandwidth overlap protection (defaults to false)',
             precision: 'optional - Precision (Defaults to 1)',
-            lock_freq_duration: 'optional - Lock frequency duration in seconds (defaults to 0.04)',
             strength_lock: 'optional - Strength lock (defaults to -70.0)',
             squelch: 'optional - Squelch level (defaults to strength_lock - 3.0)',
+            audio_gain_db: 'optional - Audio gain in dB (defaults to 6.0)',
+            rf_gain: 'optional - RF gain (defaults to 0.0)',
+            intermediate_gain: 'optional - Intermediate gain (defaults to 32.0)',
+            baseband_gain: 'optional - Baseband gain (defaults to 10.0)',
+            scan_log: 'optional - Path to save detected signals log (defaults to /tmp/pwn_sdr_gqrx_scan_<start_freq>-<target_freq>_<timestamp>.json)',
             location: 'optional - Location string to include in AI analysis (e.g., \"New York, NY\", 90210, GPS coords, etc.)'
           )
 
+          #{self}.analyze_scan(
+            scan_resp: 'required - Scan response object from #scan_range method',
+            target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
+            port: 'optional - GQRX target port (defaults to 7356)'
+          )
+
+          #{self}.analyze_log(
+            scan_log: 'required - Path to signals log file',
+            target: 'optional - GQRX target IP address (defaults to 127.0.0.1)',
+            port: 'optional - GQRX target port (defaults to 7356)'
+          )
+
           #{self}.disconnect(
             gqrx_sock: 'required - GQRX socket object returned from #connect method'
           )