pwn 0.5.532 → 0.5.534

data/lib/pwn/sdr/gqrx.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'fileutils'
 require 'json'
 require 'time'
 
@@ -144,6 +145,49 @@ module PWN
         raise e
       end
 
+      # Supported Method Parameters::
+      # noise_floor = PWN::SDR::GQRX.measure_noise_floor(
+      #   gqrx_sock: 'required - GQRX socket object returned from #connect method',
+      #   freq: 'required - Frequency to measure noise floor',
+      #   precision: 'required - Frequency step precision',
+      #   step_hz_direction: 'required - Frequency step in Hz direction for noise floor measurement'
+      # )
+      private_class_method def self.measure_noise_floor(opts = {})
+        gqrx_sock = opts[:gqrx_sock]
+        freq = opts[:freq]
+        precision = opts[:precision]
+        step_hz_direction = opts[:step_hz_direction]
+        freqs_to_sample = 10
+        samples_per_freq = 100
+
+        # Quickly sample multiple frequencies around target frequency
+        start_hz = PWN::SDR.hz_to_i(freq)
+        hz = start_hz
+        # puts step_hz_direction.class; gets
+        target_hz = start_hz + (step_hz_direction * freqs_to_sample)
+        noise_floors = []
+        puts "*** Sampling #{freqs_to_sample} Noise Floor to Dynamically Determine Squelch Level"
+        while (step_hz_direction.positive? && hz <= target_hz) || (step_hz_direction.negative? && hz >= target_hz)
+          tune_to(gqrx_sock: gqrx_sock, hz: hz)
+          print '.'
+
+          strengths = []
+          samples_per_freq.times do
+            strength_db = cmd(gqrx_sock: gqrx_sock, cmd: 'l STRENGTH').to_f
+            strengths << strength_db
+            sleep 0.001
+          end
+          freq_noise_floor = strengths.sum / strengths.size
+          noise_floors.push(freq_noise_floor)
+          hz += step_hz_direction
+        end
+
+        noise_floor = noise_floors.min
+        noise_floor.round(1)
+      rescue StandardError => e
+        raise e
+      end
+
       # Supported Method Parameters::
       # strength_db = PWN::SDR::GQRX.measure_signal_strength(
       #   gqrx_sock: 'required - GQRX socket object returned from #connect method',
@@ -318,36 +362,61 @@ module PWN
         raise e
       end
 
+      # Supported Method Parameters::
+      # duration = PWN::SDR::GQRX.duration_between(
+      #   timestamp_start: 'required - Start timestamp',
+      #   timestamp_end: 'required - End timestamp'
+      # )
+      private_class_method def self.duration_between(opts = {})
+        timestamp_start = opts[:timestamp_start]
+        timestamp_end = opts[:timestamp_end]
+        raise 'ERROR: timestamp_start && timestamp_end must are required parameters.' if timestamp_start.nil? || timestamp_end.nil?
+
+        duration_secs = Time.parse(timestamp_end).to_f - Time.parse(timestamp_start).to_f
+
+        # 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
+        format('%<hrs>02d:%<mins>02d:%<secs>02d', hrs: hours, mins: minutes, secs: seconds)
+      rescue StandardError => e
+        raise e
+      end
+
       # Supported Method Parameters::
       # scan_resp = PWN::SDR::GQRX.log_signals(
-      #   signals_arr: 'required - Array of detected signals',
+      #   signals_detected: 'required - Array of detected signals',
       #   timestamp_start: 'required - Scan start timestamp',
-      #   scan_log: 'required - Path to save detected signals log'
+      #   scan_log: 'required - Path to save detected signals log',
+      #   iteration_metrics: 'optional - Hash of iteration metrics per range iteration'
       # )
       private_class_method def self.log_signals(opts = {})
-        signals_arr = opts[:signals_arr]
+        signals_detected = opts[:signals_detected]
         timestamp_start = opts[:timestamp_start]
         scan_log = opts[:scan_log]
 
-        signals = signals_arr.sort_by { |s| PWN::SDR.hz_to_i(s[:freq]) }
+        existing_scan_resp = JSON.parse(File.read(scan_log), symbolize_names: true) if File.exist?(scan_log)
+
+        # BUG: iteration_metrics not being properly initialized from existing log
+        iteration_metrics = opts[:iteration_metrics]
+        iteration_metrics ||= existing_scan_resp[:iteration_metrics] if existing_scan_resp.is_a?(Hash) && existing_scan_resp.key?(:iteration_metrics) && existing_scan_resp[:iteration_metrics].is_a?(Array) && !existing_scan_resp[:iteration_metrics].empty?
+        iteration_metrics ||= []
+
+        signals = signals_detected.sort_by { |s| PWN::SDR.hz_to_i(s[:freq]) }
         # Unique signals by frequency
         signals.uniq! { |s| PWN::SDR.hz_to_i(s[:freq]) }
 
         timestamp_end = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
-        duration_secs = Time.parse(timestamp_end).to_f - Time.parse(timestamp_start).to_f
-
-        # 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)
+        duration = duration_between(timestamp_start: timestamp_start, timestamp_end: timestamp_end)
 
+        # TODO: Implement iteration_metrics logging per range iteration
         scan_resp = {
           signals: signals,
           total: signals.length,
           timestamp_start: timestamp_start,
           timestamp_end: timestamp_end,
-          duration: duration
+          duration: duration,
+          iteration_metrics: iteration_metrics
         }
 
         File.write(
@@ -391,14 +460,16 @@ module PWN
 
         pass_count = 0
         infinite_loop_safeguard = false
+        # loop do
+        # Why doesn't this work with loop do ???
         while true
           pass_count += 1
 
           # Safeguard against infinite loop
           # infinite_loop_safeguard = true if pass_count >= 100
-          infinite_loop_safeguard = true if pass_count >= 10
-          puts 'WARNING: Infinite loop safeguard triggered in find_best_peak!' if infinite_loop_safeguard
-          break if infinite_loop_safeguard
+          # infinite_loop_safeguard = true if pass_count >= 10
+          # puts 'WARNING: Infinite loop safeguard triggered in find_best_peak!' if infinite_loop_safeguard
+          # break if infinite_loop_safeguard
 
           direction_up = !direction_up
           start_hz_direction = direction_up ? beg_of_signal_hz : end_of_signal_hz
@@ -450,6 +521,7 @@ module PWN
 
           # Recalculate best_sample after trim
           best_sample = averaged_samples.max_by { |s| s[:strength_db] }
+          next unless best_sample.is_a?(Hash)
 
           # Check for improvement
           if best_sample[:hz] == prev_best_sample[:hz]
@@ -494,7 +566,8 @@ module PWN
       #   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 /tmp/gqrx_recordings)',
+      #   udp_ip: 'optional - UDP IP address for decoder module (defaults to 127.0.0.1)',
+      #   udp_port: 'optional - UDP port for decoder module (defaults to 7355)',
       #   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)'
       # )
@@ -523,12 +596,11 @@ module PWN
         bandwidth = opts[:bandwidth] ||= '200.000'
         squelch = opts[:squelch]
         decoder = opts[:decoder]
-        record_dir = opts[:record_dir] ||= '/tmp'
+        udp_ip = opts[:udp_ip]
+        udp_port = opts[:udp_port]
         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)
-
         unless keep_alive
           squelch = cmd(gqrx_sock: gqrx_sock, cmd: 'l SQL').to_f if squelch.nil?
           change_squelch_resp = cmd(
@@ -559,7 +631,8 @@ module PWN
           demodulator_mode: demodulator_mode,
           bandwidth: bandwidth,
           strength_db: strength_db,
-          decoder: decoder
+          decoder: decoder,
+          squelch: squelch
         }
 
         unless suppress_details
@@ -604,11 +677,11 @@ module PWN
           if decoder
             decoder = decoder.to_s.to_sym
             decoder_module = nil
-            decoder_thread = nil
-            record_path = nil
 
             # Resolve decoder module via case statement for extensibility
             case decoder
+            when :flex
+              decoder_module = PWN::SDR::Decoder::Flex
             when :gsm
               decoder_module = PWN::SDR::Decoder::GSM
             when :pocsag
@@ -619,21 +692,12 @@ module PWN
               raise "ERROR: Unknown decoder key: #{decoder}. Supported: :gsm"
             end
 
-            # Ensure recording is off before starting
-            unless decoder == :rds
-              record_path = "#{record_dir}/gqrx_recording.wav"
-              freq_obj[:record_path] = record_path
-            end
-
             # Initialize and start decoder (module style: .start returns thread)
             freq_obj[:gqrx_sock] = gqrx_sock
+            freq_obj[:udp_ip] = udp_ip
+            freq_obj[:udp_port] = udp_port
             freq_obj[:decoder_module] = decoder_module
-            freq_obj[:record_path] = record_path
-            decoder_thread = decoder_module.decode(
-              freq_obj: freq_obj,
-              record_dir: record_dir
-            )
-            # freq_obj[:decoder_thread] = decoder_thread if decoder_thread.is_a?(Thread)
+            decoder_module.decode(freq_obj: freq_obj)
           end
         end
 
@@ -653,7 +717,7 @@ module PWN
       #   precision: 'optional - Frequency step precision (number of digits; defaults to 1)',
       #   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)',
+      #   audio_gain_db: 'optional - Audio gain in dB (defaults to 0.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)',
@@ -664,157 +728,177 @@ module PWN
 
       public_class_method def self.scan_range(opts = {})
         timestamp_start = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
+        range_timestamp_start = ''
 
-        loop_count = 1
-        loop do
-          gqrx_sock = opts[:gqrx_sock]
+        gqrx_sock = opts[:gqrx_sock]
 
-          ranges = opts[:ranges]
-          raise 'ERROR: ranges must be an Array of Hash objects with :start_freq and :target_freq keys.' unless ranges.is_a?(Array) && ranges.all? { |r| r.is_a?(Hash) && r.key?(:start_freq) && r.key?(:target_freq) }
+        ranges = opts[:ranges]
+        raise 'ERROR: ranges must be an Array of Hash objects with :start_freq and :target_freq keys.' unless ranges.is_a?(Array) && ranges.all? { |r| r.is_a?(Hash) && r.key?(:start_freq) && r.key?(:target_freq) }
 
-          # Verify all frequencies are valid
-          ranges.each do |r|
-            start_freq = r[:start_freq]
-            hz_start = PWN::SDR.hz_to_i(start_freq)
-            raise "ERROR: Invalid start_freq '#{start_freq}' provided." if hz_start.zero?
+        demodulator_mode = opts[:demodulator_mode]
 
-            target_freq = r[:target_freq]
-            hz_target = PWN::SDR.hz_to_i(target_freq)
-            raise "ERROR: Invalid target_freq '#{target_freq}' provided." if hz_target.zero?
-          end
+        bandwidth = opts[:bandwidth] ||= '200.000'
 
-          first_start_freq = ranges.first[:start_freq]
-          hz_start = PWN::SDR.hz_to_i(first_start_freq)
+        precision = opts[:precision] ||= 1
+        raise 'ERROR: precision must be an Integer between 1 and 12.' unless precision.is_a?(Integer) && precision.between?(1, 12)
 
-          first_target_freq = ranges.first[:target_freq]
-          hz_target = PWN::SDR.hz_to_i(first_target_freq)
+        step_hz = 10**(precision - 1)
 
-          demodulator_mode = opts[:demodulator_mode]
+        strength_lock = opts[:strength_lock] ||= -70.0
+        squelch = opts[:squelch] ||= (strength_lock - 3.0)
+        raise 'ERROR: squelch must always be less than strength_lock.' if squelch >= strength_lock
 
-          bandwidth = opts[:bandwidth] ||= '200.000'
+        decoder = opts[:decoder]
+        keep_looping = opts[:keep_looping] || false
+        log_timestamp = Time.now.strftime('%Y-%m-%d')
 
-          precision = opts[:precision] ||= 1
-          strength_lock = opts[:strength_lock] ||= -70.0
-          squelch = opts[:squelch] ||= (strength_lock - 3.0)
-          decoder = opts[:decoder]
+        location = opts[:location] ||= 'United States'
 
-          keep_looping = opts[:keep_looping] || false
+        # This is for looping through ranges indefinitely if keep_looping is true
+        # Generate ranges strings for log filename
+        range_str = ''
+        ranges.each do |range|
+          start_freq = range[:start_freq]
+          hz_start = PWN::SDR.hz_to_i(start_freq)
+          hz_start_str = PWN::SDR.hz_to_s(hz_start)
 
-          log_timestamp = Time.now.strftime('%Y-%m-%d')
-          scan_log = opts[:scan_log] ||= "/tmp/pwn_sdr_gqrx_scan_#{PWN::SDR.hz_to_s(hz_start)}-#{PWN::SDR.hz_to_s(hz_target)}_#{log_timestamp}.json"
+          target_freq = range[:target_freq]
+          hz_target = PWN::SDR.hz_to_i(target_freq)
+          hz_target_str = PWN::SDR.hz_to_s(hz_target)
 
-          if keep_looping
-            # inject _lN before file extension if keep_looping is true
-            scan_log.gsub!("_l#{loop_count}", '')
-            scan_log = File.join(
-              File.dirname(scan_log),
-              "#{File.basename(scan_log, '.*')}_l#{loop_count}#{File.extname(scan_log)}"
-            )
-          end
+          range_str = "#{range_str}_#{hz_start_str}-#{hz_target_str}"
+        end
+        scan_log = opts[:scan_log] ||= "/tmp/pwn_sdr_gqrx_scan#{range_str}_#{log_timestamp}.json"
 
-          location = opts[:location] ||= 'United States'
+        iteration_metrics = []
+        candidate_signals = []
+        signals_detected = []
+        iteration_total = 1
+        signals_detected_total = 0
+        loop do
+          signals_detected_delta = 0
+          iter_metrics_hash = {}
+          ranges.each do |range|
+            range_timestamp_start = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
+            iter_metrics_hash[:iteration] = iteration_total
+            iter_metrics_hash[:range] = range
+            iter_metrics_hash[:timestamp_start] = range_timestamp_start
 
-          step_hz = 10**(precision - 1)
-          step_hz_direction = hz_start > hz_target ? -step_hz : step_hz
+            # Verify all frequencies are valid
+            start_freq = range[:start_freq]
+            hz_start = PWN::SDR.hz_to_i(start_freq)
+            raise "ERROR: Invalid start_freq '#{start_freq}' provided." if hz_start.zero?
 
-          # Begin scanning range
-          puts "\n"
-          puts '-' * 86
-          puts 'SESSION PARAMS >> Scan Range(s):'
-          puts ranges
-          puts "SESSION PARAMS >> Step Increment: #{PWN::SDR.hz_to_s(step_hz_direction.abs)} Hz."
-          puts "SESSION PARAMS >> Continuously Loop through Scan Range(s): #{keep_looping}"
-          puts "\nIf 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
-          # print 'Pressing ENTER to begin scan...'
-          # gets
-          puts "\n\n\n"
-
-          # Set squelch once for the scan
-          change_squelch_resp = cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: "L SQL #{squelch}",
-            resp_ok: 'RPRT 0'
-          )
+            target_freq = range[:target_freq]
+            hz_target = PWN::SDR.hz_to_i(target_freq)
+            hz_target_str = PWN::SDR.hz_to_s(hz_target)
+            raise "ERROR: Invalid target_freq '#{target_freq}' provided." if hz_target.zero?
 
-          # 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 = cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: 'U RDS 0',
-            resp_ok: 'RPRT 0'
-          )
+            step_hz_direction = hz_start > hz_target ? -step_hz : step_hz
+            noise_floor = measure_noise_floor(
+              gqrx_sock: gqrx_sock,
+              freq: start_freq,
+              precision: precision,
+              step_hz_direction: step_hz_direction
+            )
+            if squelch < noise_floor
+              squelch = noise_floor.round + 7
+              strength_lock = squelch + 3.0
+              puts "Adjusted strength_lock to #{strength_lock} dBFS and squelch to #{squelch} dBFS based on measured noise floor.  This ensures proper signal detection..."
+            end
 
-          # Set demodulator mode & passband once for the scan
-          mode_str = demodulator_mode.to_s.upcase
-          passband_hz = PWN::SDR.hz_to_i(bandwidth)
-          cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: "M #{mode_str} #{passband_hz}",
-            resp_ok: 'RPRT 0'
-          )
+            # Begin scanning range
+            puts "\n"
+            puts '-' * 86
+            puts 'SESSION PARAMS >> Scan Range(s):'
+            puts ranges
+            puts "SESSION PARAMS >> Step Increment: #{PWN::SDR.hz_to_s(step_hz_direction.abs)} Hz."
+            puts "SESSION PARAMS >> Continuously Loop through Scan Range(s): #{keep_looping}"
+            puts "\nIf 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
+            # print 'Pressing ENTER to begin scan...'
+            # gets
+            puts "\n\n\n"
 
-          audio_gain_db = opts[:audio_gain_db] ||= 6.0
-          audio_gain_db = audio_gain_db.to_f
-          audio_gain_db_resp = cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: "L AF #{audio_gain_db}",
-            resp_ok: 'RPRT 0'
-          )
+            # Set squelch once for each range
+            change_squelch_resp = cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: "L SQL #{squelch}",
+              resp_ok: 'RPRT 0'
+            )
 
-          rf_gain = opts[:rf_gain] ||= 0.0
-          rf_gain = rf_gain.to_f
-          rf_gain_resp = cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: "L RF_GAIN #{rf_gain}",
-            resp_ok: 'RPRT 0'
-          )
+            # We always disable RDS decoding 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 = cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: 'U RDS 0',
+              resp_ok: 'RPRT 0'
+            )
 
-          intermediate_gain = opts[:intermediate_gain] ||= 32.0
-          intermediate_gain = intermediate_gain.to_f
-          intermediate_resp = cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: "L IF_GAIN #{intermediate_gain}",
-            resp_ok: 'RPRT 0'
-          )
+            # Set demodulator mode & passband once for the scan
+            mode_str = demodulator_mode.to_s.upcase
+            passband_hz = PWN::SDR.hz_to_i(bandwidth)
+            cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: "M #{mode_str} #{passband_hz}",
+              resp_ok: 'RPRT 0'
+            )
 
-          baseband_gain = opts[:baseband_gain] ||= 10.0
-          baseband_gain = baseband_gain.to_f
-          baseband_resp = cmd(
-            gqrx_sock: gqrx_sock,
-            cmd: "L BB_GAIN #{baseband_gain}",
-            resp_ok: 'RPRT 0'
-          )
+            audio_gain_db = opts[:audio_gain_db] ||= 0.0
+            audio_gain_db = audio_gain_db.to_f
+            audio_gain_db_resp = cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: "L AF #{audio_gain_db}",
+              resp_ok: 'RPRT 0'
+            )
 
-          prev_freq_obj = init_freq(
-            gqrx_sock: gqrx_sock,
-            freq: hz_start,
-            precision: precision,
-            demodulator_mode: demodulator_mode,
-            bandwidth: bandwidth,
-            squelch: squelch,
-            decoder: decoder,
-            suppress_details: true,
-            keep_alive: true
-          )
+            rf_gain = opts[:rf_gain] ||= 0.0
+            rf_gain = rf_gain.to_f
+            rf_gain_resp = 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 = cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: "L IF_GAIN #{intermediate_gain}",
+              resp_ok: 'RPRT 0'
+            )
 
-          candidate_signals = []
+            baseband_gain = opts[:baseband_gain] ||= 10.0
+            baseband_gain = baseband_gain.to_f
+            baseband_resp = cmd(
+              gqrx_sock: gqrx_sock,
+              cmd: "L BB_GAIN #{baseband_gain}",
+              resp_ok: 'RPRT 0'
+            )
 
-          signals_arr = []
-          hz = hz_start
+            prev_freq_obj = init_freq(
+              gqrx_sock: gqrx_sock,
+              freq: hz_start,
+              precision: precision,
+              demodulator_mode: demodulator_mode,
+              bandwidth: bandwidth,
+              squelch: squelch,
+              decoder: decoder,
+              suppress_details: true,
+              keep_alive: true
+            )
 
-          ranges.each do |range|
             start_freq = range[:start_freq]
             hz_start = PWN::SDR.hz_to_i(start_freq)
             hz = hz_start
@@ -824,7 +908,8 @@ module PWN
 
             # puts "#{range} #{start_freq} (#{hz_start})to #{target_freq} (#{hz_target})"
             # gets
-            while step_hz_direction.positive? ? hz <= hz_target : hz >= hz_target
+            # while step_hz_direction.positive? ? hz <= hz_target : hz >= hz_target
+            while (step_hz_direction.positive? && hz <= hz_target) || (step_hz_direction.negative? && hz >= hz_target)
               tune_to(gqrx_sock: gqrx_sock, hz: hz)
               strength_db = measure_signal_strength(
                 gqrx_sock: gqrx_sock,
@@ -870,6 +955,7 @@ module PWN
                   )
                   prev_freq_obj[:strength_lock] = strength_lock
                   prev_freq_obj[:strength_db] = best_strength_db.round(1)
+                  prev_freq_obj[:iteration] = iteration_total
 
                   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(
@@ -882,9 +968,9 @@ module PWN
                   puts JSON.pretty_generate(prev_freq_obj)
                   puts '-' * 86
                   puts "\n\n\n"
-                  signals_arr.push(prev_freq_obj)
+                  signals_detected.push(prev_freq_obj)
                   log_signals(
-                    signals_arr: signals_arr,
+                    signals_detected: signals_detected,
                     timestamp_start: timestamp_start,
                     scan_log: scan_log
                   )
@@ -897,20 +983,53 @@ module PWN
             end
 
             log_signals(
-              signals_arr: signals_arr,
+              signals_detected: signals_detected,
               timestamp_start: timestamp_start,
               scan_log: scan_log
             )
           end
           break unless keep_looping
 
-          print "\nScan iteration ##{loop_count} complete.  Resuming in 30 seconds.  Press CTRL+C to exit"
-          30.times do
+          # Determine how many new signals were detected this iteration
+          # Reduces signals_detected to an array of unique frequencies only
+          signals_detected.uniq! { |s| PWN::SDR.hz_to_i(s[:freq]) }
+          signals_detected_total = signals_detected.select { |s| s[:iteration] == iteration_total }.length
+          signals_detected_delta = signals_detected_total - signals_detected_delta
+          start_next_iteration = case signals_detected_delta
+                                 when 0
+                                   30
+                                 when 1..5
+                                   10
+                                 else
+                                   5
+                                 end
+
+          range_timestamp_end = Time.now.strftime('%Y-%m-%d %H:%M:%S%z')
+          iter_metrics_hash[:timestamp_end] = range_timestamp_end
+
+          duration = duration_between(timestamp_start: range_timestamp_start, timestamp_end: range_timestamp_end)
+          iter_metrics_hash[:duration] = duration
+          iter_metrics_hash[:signals_detected] = signals_detected_delta
+
+          iteration_metrics.push(iter_metrics_hash)
+          puts "\nScan iteration(s) ##{iteration_total} complete."
+          puts JSON.pretty_generate(iter_metrics_hash)
+
+          puts "Resuming next scan iteration in #{start_next_iteration} seconds.  Press CTRL+C to exit"
+          start_next_iteration.times do
             print '.'
             sleep 1
           end
           puts "\n"
-          loop_count += 1
+
+          # Log current signals one last time just to capture scan iterations accurately
+          iteration_total += 1
+          log_signals(
+            signals_detected: signals_detected,
+            timestamp_start: timestamp_start,
+            scan_log: scan_log,
+            iteration_metrics: iteration_metrics
+          )
         end
       rescue Interrupt
         puts "\nCTRL+C detected - goodbye."
@@ -940,8 +1059,38 @@ module PWN
         scan_resp[:signals].each do |signal|
           # puts JSON.pretty_generate(signal)
           signal[:gqrx_sock] = gqrx_sock
+
           # This is required to keep connection alive during analysis
           signal[:keep_alive] = true
+
+          # We do this because we need keep_alive true for init_freq calls below
+          squelch = signal[:squelch]
+          squelch = cmd(gqrx_sock: gqrx_sock, cmd: 'l SQL').to_f if squelch.nil?
+          change_squelch_resp = cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: "L SQL #{squelch}",
+            resp_ok: 'RPRT 0'
+          )
+
+          audio_gain_db = signal[:audio_gain_db] ||= 0.0
+          audio_gain_db = audio_gain_db.to_f
+          audio_gain_db_resp = cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: "L AF #{audio_gain_db}",
+            resp_ok: 'RPRT 0'
+          )
+
+          demodulator_mode = signal[:demodulator_mode] || :WFM
+          mode_str = demodulator_mode.to_s.upcase
+
+          bandwidth = signal[:bandwidth] ||= '200.000'
+          passband_hz = PWN::SDR.hz_to_i(bandwidth)
+          cmd(
+            gqrx_sock: gqrx_sock,
+            cmd: "M #{mode_str} #{passband_hz}",
+            resp_ok: 'RPRT 0'
+          )
+
           freq_obj = init_freq(signal)
           freq_obj = signal.merge(freq_obj)
           # Redact gqrx_sock from output
@@ -986,6 +1135,96 @@ module PWN
         raise e
       end
 
+      # Supported Method Parameters::
+      # udp_listener = PWN::SDR::GQRX.listen_udp(
+      #   udp_ip: 'optional - IP address to bind UDP listener (defaults to 127.0.0.1)',
+      #   upd_port: 'optional - Port to bind UDP listener (defaults to 7355)'
+      # )
+
+      public_class_method def self.listen_udp(opts = {})
+        udp_ip = opts[:udp_ip] ||= '127.0.0.1'
+        udp_port = opts[:udp_port] ||= 7355
+
+        PWN::Plugins::Sock.listen(
+          server_ip: udp_ip,
+          port: udp_port,
+          protocol: :udp,
+          detach: true
+        )
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # PWN::SDR::GQRX.disconnect_udp(
+      #   udp_listener: 'required - UDP socket object returned from #listen_udp method'
+      # )
+
+      public_class_method def self.disconnect_udp(opts = {})
+        udp_listener = opts[:udp_listener]
+        raise 'ERROR: udp_sock is required!' if udp_listener.nil?
+
+        PWN::Plugins::Sock.disconnect(sock_obj: udp_listener) unless udp_listener.closed?
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # iq_raw_file = PWN::SDR::GQRX.record(
+      #   gqrx_sock: 'required - GQRX socket object returned from #connect method'
+      # )
+
+      public_class_method def self.record(opts = {})
+        gqrx_sock = opts[:gqrx_sock]
+        raise 'ERROR: gqrx_sock is required!' if gqrx_sock.nil?
+
+        # Toggle I/Q RECORD on in GQRX for brevity
+        cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: 'U IQRECORD 0',
+          resp_ok: 'RPRT 0'
+        )
+
+        cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: 'U IQRECORD 1',
+          resp_ok: 'RPRT 0'
+        )
+
+        record_dir = Dir.home
+        iq_raw_file = Dir.glob("#{record_dir}/gqrx_*.raw").max_by { |f| File.mtime(f) }
+        raise 'ERROR: No GQRX .raw I/Q data file found!' unless iq_raw_file
+
+        iq_raw_file
+      rescue StandardError => e
+        raise e
+      end
+
+      # Supported Method Parameters::
+      # PWN::SDR::GQRX.stop_recording(
+      #   gqrx_sock: 'required - GQRX socket object returned from #connect method',
+      #   iq_raw_file: 'required - iq_raw_file returned from #connect method'
+      # )
+
+      public_class_method def self.stop_recording(opts = {})
+        gqrx_sock = opts[:gqrx_sock]
+        raise 'ERROR: gqrx_sock is required!' if gqrx_sock.nil?
+
+        iq_raw_file = opts[:iq_raw_file]
+        raise 'ERROR: iq_raw_file is required!' if iq_raw_file.nil?
+
+        # Toggle IQRECORD off
+        cmd(
+          gqrx_sock: gqrx_sock,
+          cmd: 'U IQRECORD 0',
+          resp_ok: 'RPRT 0'
+        )
+
+        FileUtils.rm_f(iq_raw_file)
+      rescue StandardError => e
+        raise e
+      end
+
       # Supported Method Parameters::
       # PWN::SDR::GQRX.disconnect(
       #   gqrx_sock: 'required - GQRX socket object returned from #connect method'
@@ -1028,7 +1267,6 @@ module PWN
             demodulator_mode: 'optional - Demodulator mode (defaults to WFM)',
             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 /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)'
           )
@@ -1041,7 +1279,7 @@ module PWN
             precision: 'optional - Precision (Defaults to 1)',
             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)',
+            audio_gain_db: 'optional - Audio gain in dB (defaults to 0.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)',
@@ -1062,6 +1300,24 @@ module PWN
             port: 'optional - GQRX target port (defaults to 7356)'
           )
 
+          udp_listener = #{self}.listen_udp(
+            udp_ip: 'optional - IP address to bind UDP listener (defaults to 127.0.0.1)',
+            udp_port: 'optional - Port to bind UDP listener (defaults to 7355)'
+          )
+
+          #{self}.disconnect_udp(
+            udp_listener: 'required - UDP socket object returned from #listen_udp method'
+          )
+
+          iq_raw_file = #{self}.record(
+            gqrx_sock: 'required - GQRX socket object returned from #connect method'
+          )
+
+          #{self}.stop_recording(
+            gqrx_sock: 'required - GQRX socket object returned from #connect method',
+            iq_raw_file: 'required - iq_raw_file returned from #record method'
+          )
+
           #{self}.disconnect(
             gqrx_sock: 'required - GQRX socket object returned from #connect method'
           )