Revert "Add UM982 GPS driver (um982_gps.h/.cpp) for NMEA sentence parsing and…"

Add UM982 GPS driver (um982_gps.h/.cpp) for NMEA sentence parsing and…

.github/workflows/ci-tests.yml

@@ -46,7 +46,9 @@ jobs:
       - name: Unit tests
         run: >
           uv run pytest
-          9_Firmware/9_3_GUI/test_radar_dashboard.py -v --tb=short
+          9_Firmware/9_3_GUI/test_GUI_V65_Tk.py
+          9_Firmware/9_3_GUI/test_v7.py
+          -v --tb=short
 
   # ===========================================================================
   # MCU Firmware Unit Tests (20 tests)

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/ADAR1000_AGC.cpp

@@ -0,0 +1,116 @@
+// ADAR1000_AGC.cpp -- STM32 outer-loop AGC implementation
+//
+// See ADAR1000_AGC.h for architecture overview.
+
+#include "ADAR1000_AGC.h"
+#include "ADAR1000_Manager.h"
+#include "diag_log.h"
+
+#include <cstring>
+
+// ---------------------------------------------------------------------------
+// Constructor -- set all config fields to safe defaults
+// ---------------------------------------------------------------------------
+ADAR1000_AGC::ADAR1000_AGC()
+    : agc_base_gain(ADAR1000Manager::kDefaultRxVgaGain) // 30
+    , gain_step_down(4)
+    , gain_step_up(1)
+    , min_gain(0)
+    , max_gain(127)
+    , holdoff_frames(4)
+    , enabled(true)
+    , holdoff_counter(0)
+    , last_saturated(false)
+    , saturation_event_count(0)
+{
+    memset(cal_offset, 0, sizeof(cal_offset));
+}
+
+// ---------------------------------------------------------------------------
+// update -- called once per frame with the FPGA DIG_5 saturation flag
+//
+// Returns true if agc_base_gain changed (caller should then applyGain).
+// ---------------------------------------------------------------------------
+void ADAR1000_AGC::update(bool fpga_saturation)
+{
+    if (!enabled)
+        return;
+
+    last_saturated = fpga_saturation;
+
+    if (fpga_saturation) {
+        // Attack: reduce gain immediately
+        saturation_event_count++;
+        holdoff_counter = 0;
+
+        if (agc_base_gain >= gain_step_down + min_gain) {
+            agc_base_gain -= gain_step_down;
+        } else {
+            agc_base_gain = min_gain;
+        }
+
+        DIAG("AGC", "SAT detected -- gain_base -> %u  (events=%lu)",
+             (unsigned)agc_base_gain, (unsigned long)saturation_event_count);
+
+    } else {
+        // Recovery: wait for holdoff, then increase gain
+        holdoff_counter++;
+
+        if (holdoff_counter >= holdoff_frames) {
+            holdoff_counter = 0;
+
+            if (agc_base_gain + gain_step_up <= max_gain) {
+                agc_base_gain += gain_step_up;
+            } else {
+                agc_base_gain = max_gain;
+            }
+
+            DIAG("AGC", "Recovery step -- gain_base -> %u", (unsigned)agc_base_gain);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// applyGain -- write effective gain to all 16 RX VGA channels
+//
+// Uses the Manager's adarSetRxVgaGain which takes 1-based channel indices
+// (matching the convention in setBeamAngle).
+// ---------------------------------------------------------------------------
+void ADAR1000_AGC::applyGain(ADAR1000Manager &mgr)
+{
+    for (uint8_t dev = 0; dev < AGC_NUM_DEVICES; ++dev) {
+        for (uint8_t ch = 0; ch < AGC_NUM_CHANNELS; ++ch) {
+            uint8_t gain = effectiveGain(dev * AGC_NUM_CHANNELS + ch);
+            // Channel parameter is 1-based per Manager convention
+            mgr.adarSetRxVgaGain(dev, ch + 1, gain, BROADCAST_OFF);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// resetState -- clear runtime counters, preserve configuration
+// ---------------------------------------------------------------------------
+void ADAR1000_AGC::resetState()
+{
+    holdoff_counter = 0;
+    last_saturated = false;
+    saturation_event_count = 0;
+}
+
+// ---------------------------------------------------------------------------
+// effectiveGain -- compute clamped per-channel gain
+// ---------------------------------------------------------------------------
+uint8_t ADAR1000_AGC::effectiveGain(uint8_t channel_index) const
+{
+    if (channel_index >= AGC_TOTAL_CHANNELS)
+        return min_gain;  // safety fallback — OOB channels get minimum gain
+
+    int16_t raw = static_cast<int16_t>(agc_base_gain) + cal_offset[channel_index];
+
+    if (raw < static_cast<int16_t>(min_gain))
+        return min_gain;
+    if (raw > static_cast<int16_t>(max_gain))
+        return max_gain;
+
+    return static_cast<uint8_t>(raw);
+}

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/ADAR1000_AGC.h

@@ -0,0 +1,97 @@
+// ADAR1000_AGC.h -- STM32 outer-loop AGC for ADAR1000 RX VGA gain
+//
+// Adjusts the analog VGA common-mode gain on each ADAR1000 RX channel based on
+// the FPGA's saturation flag (DIG_5 / PD13).  Runs once per radar frame
+// (~258 ms) in the main loop, after runRadarPulseSequence().
+//
+// Architecture:
+//   - Inner loop (FPGA, per-sample): rx_gain_control auto-adjusts digital
+//     gain_shift based on peak magnitude / saturation.  Range ±42 dB.
+//   - Outer loop (THIS MODULE, per-frame): reads FPGA DIG_5 GPIO.  If
+//     saturation detected, reduces agc_base_gain immediately (attack).  If no
+//     saturation for holdoff_frames, increases agc_base_gain (decay/recovery).
+//
+// Per-channel gain formula:
+//   VGA[dev][ch] = clamp(agc_base_gain + cal_offset[dev*4+ch], min_gain, max_gain)
+//
+// The cal_offset array allows per-element calibration to correct inter-channel
+// gain imbalance.  Default is all zeros (uniform gain).
+
+#ifndef ADAR1000_AGC_H
+#define ADAR1000_AGC_H
+
+#include <stdint.h>
+
+// Forward-declare to avoid pulling in the full ADAR1000_Manager header here.
+// The .cpp includes the real header.
+class ADAR1000Manager;
+
+// Number of ADAR1000 devices
+#define AGC_NUM_DEVICES   4
+// Number of channels per ADAR1000
+#define AGC_NUM_CHANNELS  4
+// Total RX channels
+#define AGC_TOTAL_CHANNELS (AGC_NUM_DEVICES * AGC_NUM_CHANNELS)
+
+class ADAR1000_AGC {
+public:
+    // --- Configuration (public for easy field-testing / GUI override) ---
+
+    // Common-mode base gain (raw ADAR1000 register value, 0-255).
+    // Default matches ADAR1000Manager::kDefaultRxVgaGain = 30.
+    uint8_t agc_base_gain;
+
+    // Per-channel calibration offset (signed, added to agc_base_gain).
+    // Index = device*4 + channel.  Default: all 0.
+    int8_t cal_offset[AGC_TOTAL_CHANNELS];
+
+    // How much to decrease agc_base_gain per frame when saturated (attack).
+    uint8_t gain_step_down;
+
+    // How much to increase agc_base_gain per frame when recovering (decay).
+    uint8_t gain_step_up;
+
+    // Minimum allowed agc_base_gain (floor).
+    uint8_t min_gain;
+
+    // Maximum allowed agc_base_gain (ceiling).
+    uint8_t max_gain;
+
+    // Number of consecutive non-saturated frames required before gain-up.
+    uint8_t holdoff_frames;
+
+    // Master enable.  When false, update() is a no-op.
+    bool enabled;
+
+    // --- Runtime state (read-only for diagnostics) ---
+
+    // Consecutive non-saturated frame counter (resets on saturation).
+    uint8_t holdoff_counter;
+
+    // True if the last update() saw saturation.
+    bool last_saturated;
+
+    // Total saturation events since reset/construction.
+    uint32_t saturation_event_count;
+
+    // --- Methods ---
+
+    ADAR1000_AGC();
+
+    // Call once per frame after runRadarPulseSequence().
+    // fpga_saturation: result of HAL_GPIO_ReadPin(GPIOD, GPIO_PIN_13) == GPIO_PIN_SET
+    void update(bool fpga_saturation);
+
+    // Apply the current gain to all 16 RX VGA channels via the Manager.
+    void applyGain(ADAR1000Manager &mgr);
+
+    // Reset runtime state (holdoff counter, saturation count) without
+    // changing configuration.
+    void resetState();
+
+    // Compute the effective gain for a specific channel index (0-15),
+    // clamped to [min_gain, max_gain].  Useful for diagnostics.
+    uint8_t effectiveGain(uint8_t channel_index) const;
+};
+
+#endif // ADAR1000_AGC_H

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/USBHandler.cpp

@@ -43,6 +43,11 @@ void USBHandler::processStartFlag(const uint8_t* data, uint32_t length) {
     // Start flag: bytes [23, 46, 158, 237]
     const uint8_t START_FLAG[] = {23, 46, 158, 237};
     
+    // Guard: need at least 4 bytes to contain a start flag.
+    // Without this, length - 4 wraps to ~4 billion (uint32_t unsigned underflow)
+    // and the loop reads far past the buffer boundary.
+    if (length < 4) return;
+    
     // Check if start flag is in the received data
     for (uint32_t i = 0; i <= length - 4; i++) {
         if (memcmp(data + i, START_FLAG, 4) == 0) {

9_Firmware/9_1_Microcontroller/9_1_3_C_Cpp_Code/main.cpp

@@ -23,6 +23,7 @@
 #include "usbd_cdc_if.h"
 #include "adar1000.h"
 #include "ADAR1000_Manager.h"
+#include "ADAR1000_AGC.h"
 extern "C" {
 #include "ad9523.h"
 }
@@ -224,6 +225,7 @@ extern SPI_HandleTypeDef hspi4;
 //ADAR1000
 
 ADAR1000Manager adarManager;
+ADAR1000_AGC    outerAgc;
 static uint8_t matrix1[15][16];
 static uint8_t matrix2[15][16];
 static uint8_t vector_0[16] = {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0};
@@ -639,6 +641,7 @@ SystemError_t checkSystemHealth(void) {
         if (s0 == GPIO_PIN_RESET || s1 == GPIO_PIN_RESET) {
             current_error = ERROR_AD9523_CLOCK;
             DIAG_ERR("CLK", "AD9523 clock health check FAILED (STATUS0=%d STATUS1=%d)", s0, s1);
+            return current_error;
         }
         last_clock_check = HAL_GetTick();
     }
@@ -649,10 +652,12 @@ SystemError_t checkSystemHealth(void) {
         if (!tx_locked) {
             current_error = ERROR_ADF4382_TX_UNLOCK;
             DIAG_ERR("LO", "Health check: TX LO UNLOCKED");
+            return current_error;
         }
         if (!rx_locked) {
             current_error = ERROR_ADF4382_RX_UNLOCK;
             DIAG_ERR("LO", "Health check: RX LO UNLOCKED");
+            return current_error;
         }
     }
 
@@ -661,14 +666,14 @@ SystemError_t checkSystemHealth(void) {
         if (!adarManager.verifyDeviceCommunication(i)) {
             current_error = ERROR_ADAR1000_COMM;
             DIAG_ERR("BF", "Health check: ADAR1000 #%d comm FAILED", i);
-            break;
+            return current_error;
         }
 
         float temp = adarManager.readTemperature(i);
         if (temp > 85.0f) {
             current_error = ERROR_ADAR1000_TEMP;
             DIAG_ERR("BF", "Health check: ADAR1000 #%d OVERTEMP %.1fC > 85C", i, temp);
-            break;
+            return current_error;
         }
     }
 
@@ -678,6 +683,7 @@ SystemError_t checkSystemHealth(void) {
         if (!GY85_Update(&imu)) {
             current_error = ERROR_IMU_COMM;
             DIAG_ERR("IMU", "Health check: GY85_Update() FAILED");
+            return current_error;
         }
         last_imu_check = HAL_GetTick();
     }
@@ -689,6 +695,7 @@ SystemError_t checkSystemHealth(void) {
         if (pressure < 30000.0 || pressure > 110000.0 || isnan(pressure)) {
             current_error = ERROR_BMP180_COMM;
             DIAG_ERR("SYS", "Health check: BMP180 pressure out of range: %.0f", pressure);
+            return current_error;
         }
         last_bmp_check = HAL_GetTick();
     }
@@ -701,6 +708,7 @@ SystemError_t checkSystemHealth(void) {
     if (HAL_GetTick() - last_gps_fix > 30000) {
         current_error = ERROR_GPS_COMM;
         DIAG_WARN("SYS", "Health check: GPS no fix for >30s");
+        return current_error;
     }
 
     // 7. Check RF Power Amplifier Current
@@ -709,12 +717,12 @@ SystemError_t checkSystemHealth(void) {
             if (Idq_reading[i] > 2.5f) {
                 current_error = ERROR_RF_PA_OVERCURRENT;
                 DIAG_ERR("PA", "Health check: PA ch%d OVERCURRENT Idq=%.3fA > 2.5A", i, Idq_reading[i]);
-                break;
+                return current_error;
             }
             if (Idq_reading[i] < 0.1f) {
                 current_error = ERROR_RF_PA_BIAS;
                 DIAG_ERR("PA", "Health check: PA ch%d BIAS FAULT Idq=%.3fA < 0.1A", i, Idq_reading[i]);
-                break;
+                return current_error;
             }
         }
     }
@@ -723,6 +731,7 @@ SystemError_t checkSystemHealth(void) {
     if (temperature > 75.0f) {
         current_error = ERROR_TEMPERATURE_HIGH;
         DIAG_ERR("SYS", "Health check: System OVERTEMP %.1fC > 75C", temperature);
+        return current_error;
     }
 
     // 9. Simple watchdog check
@@ -730,6 +739,7 @@ SystemError_t checkSystemHealth(void) {
     if (HAL_GetTick() - last_health_check > 60000) {
         current_error = ERROR_WATCHDOG_TIMEOUT;
         DIAG_ERR("SYS", "Health check: Watchdog timeout (>60s since last check)");
+        return current_error;
     }
     last_health_check = HAL_GetTick();
 
@@ -919,38 +929,41 @@ bool checkSystemHealthStatus(void) {
 // Get system status for GUI
 // Get system status for GUI with 8 temperature variables
 void getSystemStatusForGUI(char* status_buffer, size_t buffer_size) {
-    char temp_buffer[200];
-    char final_status[500] = "System Status: ";
+    // Build status string directly in the output buffer using offset-tracked
+    // snprintf.  Each call returns the number of chars written (excluding NUL),
+    // so we advance 'off' and shrink 'rem' to guarantee we never overflow.
+    size_t off = 0;
+    size_t rem = buffer_size;
+    int w;
 
     // Basic status
     if (system_emergency_state) {
-        strcat(final_status, "EMERGENCY_STOP|");
+        w = snprintf(status_buffer + off, rem, "System Status: EMERGENCY_STOP|");
     } else {
-        strcat(final_status, "NORMAL|");
+        w = snprintf(status_buffer + off, rem, "System Status: NORMAL|");
     }
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // Error information
-    snprintf(temp_buffer, sizeof(temp_buffer), "LastError:%d|ErrorCount:%lu|",
+    w = snprintf(status_buffer + off, rem, "LastError:%d|ErrorCount:%lu|",
                  last_error, error_count);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // Sensor status
-    snprintf(temp_buffer, sizeof(temp_buffer), "IMU:%.1f,%.1f,%.1f|GPS:%.6f,%.6f|ALT:%.1f|",
+    w = snprintf(status_buffer + off, rem, "IMU:%.1f,%.1f,%.1f|GPS:%.6f,%.6f|ALT:%.1f|",
                  Pitch_Sensor, Roll_Sensor, Yaw_Sensor,
                  RADAR_Latitude, RADAR_Longitude, RADAR_Altitude);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // LO Status
     bool tx_locked, rx_locked;
     ADF4382A_CheckLockStatus(&lo_manager, &tx_locked, &rx_locked);
-    snprintf(temp_buffer, sizeof(temp_buffer), "LO_TX:%s|LO_RX:%s|",
+    w = snprintf(status_buffer + off, rem, "LO_TX:%s|LO_RX:%s|",
                  tx_locked ? "LOCKED" : "UNLOCKED",
                  rx_locked ? "LOCKED" : "UNLOCKED");
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // Temperature readings (8 variables)
-    // You'll need to populate these temperature values from your sensors
-    // For now, I'll show how to format them - replace with actual temperature readings
     Temperature_1 = ADS7830_Measure_SingleEnded(&hadc3, 0);
     Temperature_2 = ADS7830_Measure_SingleEnded(&hadc3, 1);
     Temperature_3 = ADS7830_Measure_SingleEnded(&hadc3, 2);
@@ -961,11 +974,11 @@ void getSystemStatusForGUI(char* status_buffer, size_t buffer_size) {
     Temperature_8 = ADS7830_Measure_SingleEnded(&hadc3, 7);
 
     // Format all 8 temperature variables
-    snprintf(temp_buffer, sizeof(temp_buffer),
+    w = snprintf(status_buffer + off, rem,
                  "T1:%.1f|T2:%.1f|T3:%.1f|T4:%.1f|T5:%.1f|T6:%.1f|T7:%.1f|T8:%.1f|",
                  Temperature_1, Temperature_2, Temperature_3, Temperature_4,
                  Temperature_5, Temperature_6, Temperature_7, Temperature_8);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // RF Power Amplifier status (if enabled)
     if (PowerAmplifier) {
@@ -975,18 +988,17 @@ void getSystemStatusForGUI(char* status_buffer, size_t buffer_size) {
         }
         avg_current /= 16.0f;
 
-        snprintf(temp_buffer, sizeof(temp_buffer), "PA_AvgCurrent:%.2f|PA_Enabled:%d|",
+        w = snprintf(status_buffer + off, rem, "PA_AvgCurrent:%.2f|PA_Enabled:%d|",
                      avg_current, PowerAmplifier);
-        strcat(final_status, temp_buffer);
+        if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
     }
 
     // Radar operation status
-    snprintf(temp_buffer, sizeof(temp_buffer), "BeamPos:%d|Azimuth:%d|ChirpCount:%d|",
+    w = snprintf(status_buffer + off, rem, "BeamPos:%d|Azimuth:%d|ChirpCount:%d|",
                  n, y, m);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
-    // Copy to output buffer
-    strncpy(status_buffer, final_status, buffer_size - 1);
+    // NUL termination guaranteed by snprintf, but be safe
     status_buffer[buffer_size - 1] = '\0';
 }
 
@@ -1995,12 +2007,13 @@ int main(void)
 	        HAL_UART_Transmit(&huart3, (uint8_t*)emergency_msg, strlen(emergency_msg), 1000);
 	        DIAG_ERR("SYS", "SAFE MODE ACTIVE -- blinking all LEDs, waiting for system_emergency_state clear");
 
-	        // Blink all LEDs to indicate safe mode
+	        // Blink all LEDs to indicate safe mode (500ms period, visible to operator)
 	        while (system_emergency_state) {
 	            HAL_GPIO_TogglePin(LED_1_GPIO_Port, LED_1_Pin);
 	            HAL_GPIO_TogglePin(LED_2_GPIO_Port, LED_2_Pin);
 	            HAL_GPIO_TogglePin(LED_3_GPIO_Port, LED_3_Pin);
 	            HAL_GPIO_TogglePin(LED_4_GPIO_Port, LED_4_Pin);
+	            HAL_Delay(250);
 	        }
 	        DIAG("SYS", "Exited safe mode blink loop -- system_emergency_state cleared");
 	    }
@@ -2114,6 +2127,16 @@ int main(void)
 
       runRadarPulseSequence();
 
+      /* [AGC] Outer-loop AGC: read FPGA saturation flag (DIG_5 / PD13),
+       * adjust ADAR1000 VGA common gain once per radar frame (~258 ms).
+       * Only run when AGC is enabled — otherwise leave VGA gains untouched. */
+      if (outerAgc.enabled) {
+          bool sat = HAL_GPIO_ReadPin(FPGA_DIG5_SAT_GPIO_Port,
+                                      FPGA_DIG5_SAT_Pin) == GPIO_PIN_SET;
+          outerAgc.update(sat);
+          outerAgc.applyGain(adarManager);
+      }
+
       /* [GAP-3 FIX 2] Kick hardware watchdog — if we don't reach here within
        * ~4 s, the IWDG resets the MCU automatically. */
       HAL_IWDG_Refresh(&hiwdg);

9_Firmware/9_1_Microcontroller/9_1_3_C_Cpp_Code/main.h

@@ -141,6 +141,15 @@ void Error_Handler(void);
 #define EN_DIS_RFPA_VDD_GPIO_Port GPIOD
 #define EN_DIS_COOLING_Pin GPIO_PIN_7
 #define EN_DIS_COOLING_GPIO_Port GPIOD
+
+/* FPGA digital I/O (directly connected GPIOs) */
+#define FPGA_DIG5_SAT_Pin       GPIO_PIN_13
+#define FPGA_DIG5_SAT_GPIO_Port GPIOD
+#define FPGA_DIG6_Pin           GPIO_PIN_14
+#define FPGA_DIG6_GPIO_Port     GPIOD
+#define FPGA_DIG7_Pin           GPIO_PIN_15
+#define FPGA_DIG7_GPIO_Port     GPIOD
+
 #define ADF4382_RX_CE_Pin GPIO_PIN_9
 #define ADF4382_RX_CE_GPIO_Port GPIOG
 #define ADF4382_RX_CS_Pin GPIO_PIN_10

9_Firmware/9_1_Microcontroller/tests/Makefile

@@ -16,10 +16,17 @@
 ################################################################################
 
 CC       := cc
+CXX      := c++
 CFLAGS   := -std=c11 -Wall -Wextra -Wno-unused-parameter -g -O0
+CXXFLAGS := -std=c++17 -Wall -Wextra -Wno-unused-parameter -g -O0
 # Shim headers come FIRST so they override real headers
 INCLUDES := -Ishims -I. -I../9_1_1_C_Cpp_Libraries
 
+# C++ library directory (AGC, ADAR1000 Manager)
+CXX_LIB_DIR := ../9_1_1_C_Cpp_Libraries
+CXX_SRCS    := $(CXX_LIB_DIR)/ADAR1000_AGC.cpp $(CXX_LIB_DIR)/ADAR1000_Manager.cpp
+CXX_OBJS    := ADAR1000_AGC.o ADAR1000_Manager.o
+
 # Real source files compiled against mock headers
 REAL_SRC := ../9_1_1_C_Cpp_Libraries/adf4382a_manager.c
 
@@ -62,7 +69,10 @@ TESTS_STANDALONE := test_bug12_pa_cal_loop_inverted \
 # Tests that need platform_noos_stm32.o + mocks
 TESTS_WITH_PLATFORM := test_bug11_platform_spi_transmit_only
 
-ALL_TESTS := $(TESTS_WITH_REAL) $(TESTS_MOCK_ONLY) $(TESTS_STANDALONE) $(TESTS_WITH_PLATFORM)
+# C++ tests (AGC outer loop)
+TESTS_WITH_CXX := test_agc_outer_loop
+
+ALL_TESTS := $(TESTS_WITH_REAL) $(TESTS_MOCK_ONLY) $(TESTS_STANDALONE) $(TESTS_WITH_PLATFORM) $(TESTS_WITH_CXX)
 
 .PHONY: all build test clean \
         $(addprefix test_,bug1 bug2 bug3 bug4 bug5 bug6 bug7 bug8 bug9 bug10 bug11 bug12 bug13 bug14 bug15) \
@@ -156,6 +166,24 @@ test_gap3_emergency_state_ordering: test_gap3_emergency_state_ordering.c
 $(TESTS_WITH_PLATFORM): %: %.c $(MOCK_OBJS) $(PLATFORM_OBJ)
 	$(CC) $(CFLAGS) $(INCLUDES) $< $(MOCK_OBJS) $(PLATFORM_OBJ) -o $@
 
+# --- C++ object rules ---
+
+ADAR1000_AGC.o: $(CXX_LIB_DIR)/ADAR1000_AGC.cpp $(CXX_LIB_DIR)/ADAR1000_AGC.h
+	$(CXX) $(CXXFLAGS) $(INCLUDES) -c $< -o $@
+
+ADAR1000_Manager.o: $(CXX_LIB_DIR)/ADAR1000_Manager.cpp $(CXX_LIB_DIR)/ADAR1000_Manager.h
+	$(CXX) $(CXXFLAGS) $(INCLUDES) -c $< -o $@
+
+# --- C++ test binary rules ---
+
+test_agc_outer_loop: test_agc_outer_loop.cpp $(CXX_OBJS) $(MOCK_OBJS)
+	$(CXX) $(CXXFLAGS) $(INCLUDES) $< $(CXX_OBJS) $(MOCK_OBJS) -o $@
+
+# Convenience target
+.PHONY: test_agc
+test_agc: test_agc_outer_loop
+	./test_agc_outer_loop
+
 # --- Individual test targets ---
 
 test_bug1: test_bug1_timed_sync_init_ordering

9_Firmware/9_1_Microcontroller/tests/shims/main.h

@@ -129,6 +129,14 @@ void Error_Handler(void);
 #define GYR_INT_Pin GPIO_PIN_8
 #define GYR_INT_GPIO_Port GPIOC
 
+/* FPGA digital I/O (directly connected GPIOs) */
+#define FPGA_DIG5_SAT_Pin       GPIO_PIN_13
+#define FPGA_DIG5_SAT_GPIO_Port GPIOD
+#define FPGA_DIG6_Pin           GPIO_PIN_14
+#define FPGA_DIG6_GPIO_Port     GPIOD
+#define FPGA_DIG7_Pin           GPIO_PIN_15
+#define FPGA_DIG7_GPIO_Port     GPIOD
+
 #ifdef __cplusplus
 }
 #endif

9_Firmware/9_1_Microcontroller/tests/stm32_hal_mock.c

@@ -175,7 +175,7 @@ void HAL_Delay(uint32_t Delay)
     mock_tick += Delay;
 }
 
-HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, uint8_t *pData,
+HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, const uint8_t *pData,
                                      uint16_t Size, uint32_t Timeout)
 {
     spy_push((SpyRecord){

9_Firmware/9_1_Microcontroller/tests/stm32_hal_mock.h

@@ -34,6 +34,10 @@ typedef uint32_t HAL_StatusTypeDef;
 
 #define HAL_MAX_DELAY 0xFFFFFFFFU
 
+#ifndef __NOP
+#define __NOP() ((void)0)
+#endif
+
 /* ========================= GPIO Types ============================ */
 
 typedef struct {
@@ -182,7 +186,7 @@ GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin);
 void          HAL_GPIO_TogglePin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin);
 uint32_t      HAL_GetTick(void);
 void          HAL_Delay(uint32_t Delay);
-HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size, uint32_t Timeout);
+HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size, uint32_t Timeout);
 
 /* ========================= SPI stubs ============================== */
 

9_Firmware/9_1_Microcontroller/tests/test_agc_outer_loop.cpp

@@ -0,0 +1,361 @@
+// test_agc_outer_loop.cpp -- C++ unit tests for ADAR1000_AGC outer-loop AGC
+//
+// Tests the STM32 outer-loop AGC class that adjusts ADAR1000 VGA gain based
+// on the FPGA's saturation flag.  Uses the existing HAL mock/spy framework.
+//
+// Build: c++ -std=c++17 ... (see Makefile TESTS_WITH_CXX rule)
+
+#include <cassert>
+#include <cstdio>
+#include <cstring>
+
+// Shim headers override real STM32/diag headers
+#include "stm32_hal_mock.h"
+#include "ADAR1000_AGC.h"
+#include "ADAR1000_Manager.h"
+
+// ---------------------------------------------------------------------------
+// Linker symbols required by ADAR1000_Manager.cpp (pulled in via main.h shim)
+// ---------------------------------------------------------------------------
+uint8_t GUI_start_flag_received = 0;
+uint8_t USB_Buffer[64] = {0};
+extern "C" void Error_Handler(void) {}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+static int tests_passed = 0;
+static int tests_total  = 0;
+
+#define RUN_TEST(fn)                                                           \
+    do {                                                                        \
+        tests_total++;                                                          \
+        printf("  [%2d] %-55s ", tests_total, #fn);                            \
+        fn();                                                                   \
+        tests_passed++;                                                         \
+        printf("PASS\n");                                                       \
+    } while (0)
+
+// ---------------------------------------------------------------------------
+// Test 1: Default construction matches design spec
+// ---------------------------------------------------------------------------
+static void test_defaults()
+{
+    ADAR1000_AGC agc;
+
+    assert(agc.agc_base_gain == 30);  // kDefaultRxVgaGain
+    assert(agc.gain_step_down == 4);
+    assert(agc.gain_step_up == 1);
+    assert(agc.min_gain == 0);
+    assert(agc.max_gain == 127);
+    assert(agc.holdoff_frames == 4);
+    assert(agc.enabled == true);
+    assert(agc.holdoff_counter == 0);
+    assert(agc.last_saturated == false);
+    assert(agc.saturation_event_count == 0);
+
+    // All cal offsets zero
+    for (int i = 0; i < AGC_TOTAL_CHANNELS; ++i) {
+        assert(agc.cal_offset[i] == 0);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: Saturation reduces gain by step_down
+// ---------------------------------------------------------------------------
+static void test_saturation_reduces_gain()
+{
+    ADAR1000_AGC agc;
+    uint8_t initial = agc.agc_base_gain;  // 30
+
+    agc.update(true);  // saturation
+
+    assert(agc.agc_base_gain == initial - agc.gain_step_down);  // 26
+    assert(agc.last_saturated == true);
+    assert(agc.holdoff_counter == 0);
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: Holdoff prevents premature gain-up
+// ---------------------------------------------------------------------------
+static void test_holdoff_prevents_early_gain_up()
+{
+    ADAR1000_AGC agc;
+    agc.update(true);  // saturate once -> gain = 26
+    uint8_t after_sat = agc.agc_base_gain;
+
+    // Feed (holdoff_frames - 1) clear frames — should NOT increase gain
+    for (uint8_t i = 0; i < agc.holdoff_frames - 1; ++i) {
+        agc.update(false);
+        assert(agc.agc_base_gain == after_sat);
+    }
+
+    // holdoff_counter should be holdoff_frames - 1
+    assert(agc.holdoff_counter == agc.holdoff_frames - 1);
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: Recovery after holdoff period
+// ---------------------------------------------------------------------------
+static void test_recovery_after_holdoff()
+{
+    ADAR1000_AGC agc;
+    agc.update(true);  // saturate -> gain = 26
+    uint8_t after_sat = agc.agc_base_gain;
+
+    // Feed exactly holdoff_frames clear frames
+    for (uint8_t i = 0; i < agc.holdoff_frames; ++i) {
+        agc.update(false);
+    }
+
+    assert(agc.agc_base_gain == after_sat + agc.gain_step_up);  // 27
+    assert(agc.holdoff_counter == 0);  // reset after recovery
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: Min gain clamping
+// ---------------------------------------------------------------------------
+static void test_min_gain_clamp()
+{
+    ADAR1000_AGC agc;
+    agc.min_gain = 10;
+    agc.agc_base_gain = 12;
+    agc.gain_step_down = 4;
+
+    agc.update(true);  // 12 - 4 = 8, but min = 10
+    assert(agc.agc_base_gain == 10);
+
+    agc.update(true);  // already at min
+    assert(agc.agc_base_gain == 10);
+}
+
+// ---------------------------------------------------------------------------
+// Test 6: Max gain clamping
+// ---------------------------------------------------------------------------
+static void test_max_gain_clamp()
+{
+    ADAR1000_AGC agc;
+    agc.max_gain = 32;
+    agc.agc_base_gain = 31;
+    agc.gain_step_up = 2;
+    agc.holdoff_frames = 1;  // immediate recovery
+
+    agc.update(false);  // 31 + 2 = 33, but max = 32
+    assert(agc.agc_base_gain == 32);
+
+    agc.update(false);  // already at max
+    assert(agc.agc_base_gain == 32);
+}
+
+// ---------------------------------------------------------------------------
+// Test 7: Per-channel calibration offsets
+// ---------------------------------------------------------------------------
+static void test_calibration_offsets()
+{
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 30;
+    agc.min_gain = 0;
+    agc.max_gain = 60;
+
+    agc.cal_offset[0]  =  5;   // 30 + 5  = 35
+    agc.cal_offset[1]  = -10;  // 30 - 10 = 20
+    agc.cal_offset[15] =  40;  // 30 + 40 = 60 (clamped to max)
+
+    assert(agc.effectiveGain(0) == 35);
+    assert(agc.effectiveGain(1) == 20);
+    assert(agc.effectiveGain(15) == 60);  // clamped to max_gain
+
+    // Negative clamp
+    agc.cal_offset[2] = -50;   // 30 - 50 = -20, clamped to min_gain = 0
+    assert(agc.effectiveGain(2) == 0);
+
+    // Out-of-range index returns min_gain
+    assert(agc.effectiveGain(16) == agc.min_gain);
+}
+
+// ---------------------------------------------------------------------------
+// Test 8: Disabled AGC is a no-op
+// ---------------------------------------------------------------------------
+static void test_disabled_noop()
+{
+    ADAR1000_AGC agc;
+    agc.enabled = false;
+    uint8_t original = agc.agc_base_gain;
+
+    agc.update(true);   // should be ignored
+    assert(agc.agc_base_gain == original);
+    assert(agc.last_saturated == false);  // not updated when disabled
+    assert(agc.saturation_event_count == 0);
+
+    agc.update(false);  // also ignored
+    assert(agc.agc_base_gain == original);
+}
+
+// ---------------------------------------------------------------------------
+// Test 9: applyGain() produces correct SPI writes
+// ---------------------------------------------------------------------------
+static void test_apply_gain_spi()
+{
+    spy_reset();
+
+    ADAR1000Manager mgr;  // creates 4 devices
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 42;
+
+    agc.applyGain(mgr);
+
+    // Each channel: adarSetRxVgaGain -> adarWrite(gain) + adarWrite(LOAD_WORKING)
+    // Each adarWrite: CS_low (GPIO_WRITE) + SPI_TRANSMIT + CS_high (GPIO_WRITE)
+    // = 3 spy records per adarWrite
+    // = 6 spy records per channel
+    // = 16 channels * 6 = 96 total spy records
+
+    // Verify SPI transmit count: 2 SPI calls per channel * 16 channels = 32
+    int spi_count = spy_count_type(SPY_SPI_TRANSMIT);
+    assert(spi_count == 32);
+
+    // Verify GPIO write count: 4 GPIO writes per channel (CS low + CS high for each of 2 adarWrite calls)
+    int gpio_writes = spy_count_type(SPY_GPIO_WRITE);
+    assert(gpio_writes == 64);  // 16 ch * 2 adarWrite * 2 GPIO each
+}
+
+// ---------------------------------------------------------------------------
+// Test 10: resetState() clears counters but preserves config
+// ---------------------------------------------------------------------------
+static void test_reset_preserves_config()
+{
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 42;
+    agc.gain_step_down = 8;
+    agc.cal_offset[3] = -5;
+
+    // Generate some state
+    agc.update(true);
+    agc.update(true);
+    assert(agc.saturation_event_count == 2);
+    assert(agc.last_saturated == true);
+
+    agc.resetState();
+
+    // State cleared
+    assert(agc.holdoff_counter == 0);
+    assert(agc.last_saturated == false);
+    assert(agc.saturation_event_count == 0);
+
+    // Config preserved
+    assert(agc.agc_base_gain == 42 - 8 - 8);  // two saturations applied before reset
+    assert(agc.gain_step_down == 8);
+    assert(agc.cal_offset[3] == -5);
+}
+
+// ---------------------------------------------------------------------------
+// Test 11: Saturation counter increments correctly
+// ---------------------------------------------------------------------------
+static void test_saturation_counter()
+{
+    ADAR1000_AGC agc;
+
+    for (int i = 0; i < 10; ++i) {
+        agc.update(true);
+    }
+    assert(agc.saturation_event_count == 10);
+
+    // Clear frames don't increment saturation count
+    for (int i = 0; i < 5; ++i) {
+        agc.update(false);
+    }
+    assert(agc.saturation_event_count == 10);
+}
+
+// ---------------------------------------------------------------------------
+// Test 12: Mixed saturation/clear sequence
+// ---------------------------------------------------------------------------
+static void test_mixed_sequence()
+{
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 30;
+    agc.gain_step_down = 4;
+    agc.gain_step_up = 1;
+    agc.holdoff_frames = 3;
+
+    // Saturate: 30 -> 26
+    agc.update(true);
+    assert(agc.agc_base_gain == 26);
+    assert(agc.holdoff_counter == 0);
+
+    // 2 clear frames (not enough for recovery)
+    agc.update(false);
+    agc.update(false);
+    assert(agc.agc_base_gain == 26);
+    assert(agc.holdoff_counter == 2);
+
+    // Saturate again: 26 -> 22, counter resets
+    agc.update(true);
+    assert(agc.agc_base_gain == 22);
+    assert(agc.holdoff_counter == 0);
+    assert(agc.saturation_event_count == 2);
+
+    // 3 clear frames -> recovery: 22 -> 23
+    agc.update(false);
+    agc.update(false);
+    agc.update(false);
+    assert(agc.agc_base_gain == 23);
+    assert(agc.holdoff_counter == 0);
+
+    // 3 more clear -> 23 -> 24
+    agc.update(false);
+    agc.update(false);
+    agc.update(false);
+    assert(agc.agc_base_gain == 24);
+}
+
+// ---------------------------------------------------------------------------
+// Test 13: Effective gain with edge-case base_gain values
+// ---------------------------------------------------------------------------
+static void test_effective_gain_edge_cases()
+{
+    ADAR1000_AGC agc;
+    agc.min_gain = 5;
+    agc.max_gain = 250;
+
+    // Base gain at zero with positive offset
+    agc.agc_base_gain = 0;
+    agc.cal_offset[0] = 3;
+    assert(agc.effectiveGain(0) == 5);  // 0 + 3 = 3, clamped to min_gain=5
+
+    // Base gain at max with zero offset
+    agc.agc_base_gain = 250;
+    agc.cal_offset[0] = 0;
+    assert(agc.effectiveGain(0) == 250);
+
+    // Base gain at max with positive offset -> clamped
+    agc.agc_base_gain = 250;
+    agc.cal_offset[0] = 10;
+    assert(agc.effectiveGain(0) == 250);  // clamped to max_gain
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+int main()
+{
+    printf("=== ADAR1000_AGC Outer-Loop Unit Tests ===\n");
+
+    RUN_TEST(test_defaults);
+    RUN_TEST(test_saturation_reduces_gain);
+    RUN_TEST(test_holdoff_prevents_early_gain_up);
+    RUN_TEST(test_recovery_after_holdoff);
+    RUN_TEST(test_min_gain_clamp);
+    RUN_TEST(test_max_gain_clamp);
+    RUN_TEST(test_calibration_offsets);
+    RUN_TEST(test_disabled_noop);
+    RUN_TEST(test_apply_gain_spi);
+    RUN_TEST(test_reset_preserves_config);
+    RUN_TEST(test_saturation_counter);
+    RUN_TEST(test_mixed_sequence);
+    RUN_TEST(test_effective_gain_edge_cases);
+
+    printf("=== Results: %d/%d passed ===\n", tests_passed, tests_total);
+    return (tests_passed == tests_total) ? 0 : 1;
+}

9_Firmware/9_2_FPGA/adc_clk_mmcm.v

@@ -212,6 +212,11 @@ BUFG bufg_feedback (
 
 // ---- Output BUFG ----
 // Routes the jitter-cleaned 400 MHz CLKOUT0 onto a global clock network.
+// DONT_TOUCH prevents phys_opt_design AggressiveExplore from replicating this
+// BUFG into a cascaded chain (4 BUFGs in series observed in Build 26), which
+// added ~243ps of clock insertion delay and caused -187ps clock skew on the
+// NCO→DSP mixer critical path.
+(* DONT_TOUCH = "TRUE" *)
 BUFG bufg_clk400m (
     .I(clk_mmcm_out0),
     .O(clk_400m_out)

9_Firmware/9_2_FPGA/cic_decimator_4x_enhanced.v

@@ -66,13 +66,13 @@ reg signed [COMB_WIDTH-1:0] comb_delay [0:STAGES-1][0:COMB_DELAY-1];
 // Pipeline valid for comb stages 1-4: delayed by 1 cycle vs comb_pipe to
 // account for CREG+AREG+BREG pipeline inside comb_0_dsp (explicit DSP48E1).
 // Comb[0] result appears 1 cycle after data_valid_comb_pipe.
-(* keep = "true", max_fanout = 4 *) reg data_valid_comb_0_out;
+(* keep = "true", max_fanout = 16 *) reg data_valid_comb_0_out;
 
 // Enhanced control and monitoring
 reg [1:0] decimation_counter;
-(* keep = "true", max_fanout = 4 *) reg data_valid_delayed;
-(* keep = "true", max_fanout = 4 *) reg data_valid_comb;
-(* keep = "true", max_fanout = 4 *) reg data_valid_comb_pipe;
+(* keep = "true", max_fanout = 16 *) reg data_valid_delayed;
+(* keep = "true", max_fanout = 16 *) reg data_valid_comb;
+(* keep = "true", max_fanout = 16 *) reg data_valid_comb_pipe;
 reg [7:0] output_counter;
 reg [ACC_WIDTH-1:0] max_integrator_value;
 reg overflow_detected;

9_Firmware/9_2_FPGA/constraints/adc_clk_mmcm.xdc

@@ -83,3 +83,13 @@ set_false_path -through [get_pins rx_inst/adc/mmcm_inst/mmcm_adc_400m/LOCKED]
 # Waiving hold on these 8 paths (adc_d_p[0..7] → IDDR) is standard practice
 # for source-synchronous LVDS ADC interfaces using BUFIO capture.
 set_false_path -hold -from [get_ports {adc_d_p[*]}] -to [get_clocks adc_dco_p]
+
+# --------------------------------------------------------------------------
+# Timing margin for 400 MHz critical paths
+# --------------------------------------------------------------------------
+# Extra setup uncertainty forces Vivado to leave margin for temperature/voltage/
+# aging variation. Reduced from 200 ps to 100 ps after NCO→mixer pipeline
+# register fix eliminated the dominant timing bottleneck (WNS went from +0.002ns
+# to comfortable margin). 100 ps still provides ~4% guardband on the 2.5ns period.
+# This is additive to the existing jitter-based uncertainty (~53 ps).
+set_clock_uncertainty -setup -add 0.100 [get_clocks clk_mmcm_out0]

9_Firmware/9_2_FPGA/constraints/xc7a50t_ftg256.xdc

@@ -222,8 +222,16 @@ set_property IOSTANDARD LVCMOS33 [get_ports {stm32_new_*}]
 set_property IOSTANDARD LVCMOS33 [get_ports {stm32_mixers_enable}]
 # reset_n is DIG_4 (PD12) — constrained above in the RESET section
 
-# DIG_5 = H11, DIG_6 = G12, DIG_7 = H12 — available for FPGA→STM32 status
-# Currently unused in RTL. Could be connected to status outputs if needed.
+# DIG_5 = H11, DIG_6 = G12, DIG_7 = H12 — FPGA→STM32 status outputs
+# DIG_5: AGC saturation flag (PD13 on STM32)
+# DIG_6: reserved (PD14)
+# DIG_7: reserved (PD15)
+set_property PACKAGE_PIN H11 [get_ports {gpio_dig5}]
+set_property PACKAGE_PIN G12 [get_ports {gpio_dig6}]
+set_property PACKAGE_PIN H12 [get_ports {gpio_dig7}]
+set_property IOSTANDARD LVCMOS33 [get_ports {gpio_dig*}]
+set_property DRIVE 8 [get_ports {gpio_dig*}]
+set_property SLEW SLOW [get_ports {gpio_dig*}]
 
 # ============================================================================
 # ADC INTERFACE (LVDS — Bank 14, VCCO=3.3V)

9_Firmware/9_2_FPGA/ddc_400m.v

@@ -102,14 +102,19 @@ wire signed [17:0] debug_mixed_q_trunc;
 reg [7:0] signal_power_i, signal_power_q;
 
 // Internal mixing signals
-// DSP48E1 with AREG=1, BREG=1, MREG=1, PREG=1 handles all internal pipelining
-// Latency: 4 cycles (1 for AREG/BREG, 1 for MREG, 1 for PREG, 1 for post-DSP retiming)
+// Pipeline: NCO fabric reg (1) + DSP48E1 AREG/BREG (1) + MREG (1) + PREG (1) + retiming (1) = 5 cycles
+// The NCO fabric pipeline register was added to break the long NCO→DSP B-port route
+// (1.505ns routing in Build 26, WNS=+0.002ns). With BREG=1 still active inside the DSP,
+// total latency increases by 1 cycle (2.5ns at 400MHz — negligible for radar).
 wire signed [MIXER_WIDTH-1:0] adc_signed_w;
 reg signed [MIXER_WIDTH + NCO_WIDTH -1:0] mixed_i, mixed_q;
 reg mixed_valid;
 reg mixer_overflow_i, mixer_overflow_q;
-// Pipeline valid tracking: 4-stage shift register (3 for DSP48E1 + 1 for post-DSP retiming)
-reg [3:0] dsp_valid_pipe;
+// Pipeline valid tracking: 5-stage shift register (1 NCO pipe + 3 DSP48E1 + 1 retiming)
+reg [4:0] dsp_valid_pipe;
+// NCO→DSP pipeline registers — breaks the long NCO sin/cos → DSP48E1 B-port route
+// DONT_TOUCH prevents Vivado from absorbing these into the DSP or optimizing away
+(* DONT_TOUCH = "TRUE" *) reg signed [15:0] cos_nco_pipe, sin_nco_pipe;
 // Post-DSP retiming registers — breaks DSP48E1 CLK→P to fabric timing path
 // This extra pipeline stage absorbs the 1.866ns DSP output prop delay + routing,
 // ensuring WNS > 0 at 400 MHz regardless of placement seed
@@ -210,11 +215,11 @@ nco_400m_enhanced nco_core (
 //
 // Architecture:
 //   ADC data → sign-extend to 18b → DSP48E1 A-port (AREG=1 pipelines it)
-//   NCO cos/sin → sign-extend to 18b → DSP48E1 B-port (BREG=1 pipelines it)
+//   NCO cos/sin → fabric pipeline reg → DSP48E1 B-port (BREG=1 pipelines it)
 //   Multiply result captured by MREG=1, then output registered by PREG=1
 //   force_saturation override applied AFTER DSP48E1 output (not on input path)
 //
-// Latency: 3 clock cycles (AREG/BREG + MREG + PREG)
+// Latency: 4 clock cycles (1 NCO pipe + 1 AREG/BREG + 1 MREG + 1 PREG) + 1 retiming = 5 total
 // PREG=1 absorbs DSP48E1 CLK→P delay internally, preventing fabric timing violations
 // In simulation (Icarus), uses behavioral equivalent since DSP48E1 is Xilinx-only
 // ============================================================================
@@ -223,24 +228,35 @@ nco_400m_enhanced nco_core (
 assign adc_signed_w = {1'b0, adc_data, {(MIXER_WIDTH-ADC_WIDTH-1){1'b0}}} - 
                       {1'b0, {ADC_WIDTH{1'b1}}, {(MIXER_WIDTH-ADC_WIDTH-1){1'b0}}} / 2;
 
-// Valid pipeline: 4-stage shift register (3 for DSP48E1 AREG+MREG+PREG + 1 for retiming)
+// Valid pipeline: 5-stage shift register (1 NCO pipe + 3 DSP48E1 AREG+MREG+PREG + 1 retiming)
 always @(posedge clk_400m or negedge reset_n_400m) begin
     if (!reset_n_400m) begin
-        dsp_valid_pipe <= 4'b0000;
+        dsp_valid_pipe <= 5'b00000;
     end else begin
-        dsp_valid_pipe <= {dsp_valid_pipe[2:0], (nco_ready && adc_data_valid_i && adc_data_valid_q)};
+        dsp_valid_pipe <= {dsp_valid_pipe[3:0], (nco_ready && adc_data_valid_i && adc_data_valid_q)};
     end
 end
 
 `ifdef SIMULATION
 // ---- Behavioral model for Icarus Verilog simulation ----
-// Mimics DSP48E1 with AREG=1, BREG=1, MREG=1, PREG=1 (3-cycle latency)
+// Mimics NCO pipeline + DSP48E1 with AREG=1, BREG=1, MREG=1, PREG=1 (4-cycle DSP + 1 NCO pipe)
 reg signed [MIXER_WIDTH-1:0] adc_signed_reg;     // Models AREG
 reg signed [15:0] cos_pipe_reg, sin_pipe_reg;     // Models BREG
 reg signed [MIXER_WIDTH+NCO_WIDTH-1:0] mult_i_internal, mult_q_internal;  // Models MREG
 reg signed [MIXER_WIDTH+NCO_WIDTH-1:0] mult_i_reg, mult_q_reg;            // Models PREG
 
-// Stage 1: AREG/BREG equivalent
+// Stage 0: NCO pipeline — breaks long NCO→DSP route (matches synthesis fabric registers)
+always @(posedge clk_400m or negedge reset_n_400m) begin
+    if (!reset_n_400m) begin
+        cos_nco_pipe <= 0;
+        sin_nco_pipe <= 0;
+    end else begin
+        cos_nco_pipe <= cos_out;
+        sin_nco_pipe <= sin_out;
+    end
+end
+
+// Stage 1: AREG/BREG equivalent (uses pipelined NCO outputs)
 always @(posedge clk_400m or negedge reset_n_400m) begin
     if (!reset_n_400m) begin
         adc_signed_reg <= 0;
@@ -248,8 +264,8 @@ always @(posedge clk_400m or negedge reset_n_400m) begin
         sin_pipe_reg <= 0;
     end else begin
         adc_signed_reg <= adc_signed_w;
-        cos_pipe_reg <= cos_out;
-        sin_pipe_reg <= sin_out;
+        cos_pipe_reg <= cos_nco_pipe;
+        sin_pipe_reg <= sin_nco_pipe;
     end
 end
 
@@ -291,6 +307,20 @@ end
 // This guarantees AREG/BREG/MREG are used, achieving timing closure at 400 MHz
 wire [47:0] dsp_p_i, dsp_p_q;
 
+// NCO pipeline stage — breaks the long NCO sin/cos → DSP48E1 B-port route
+// (1.505ns routing observed in Build 26). These fabric registers are placed
+// near the DSP by the placer, splitting the route into two shorter segments.
+// DONT_TOUCH on the reg declaration (above) prevents absorption/retiming.
+always @(posedge clk_400m or negedge reset_n_400m) begin
+    if (!reset_n_400m) begin
+        cos_nco_pipe <= 0;
+        sin_nco_pipe <= 0;
+    end else begin
+        cos_nco_pipe <= cos_out;
+        sin_nco_pipe <= sin_out;
+    end
+end
+
 // DSP48E1 for I-channel mixer (adc_signed * cos_out)
 DSP48E1 #(
     // Feature control attributes
@@ -350,7 +380,7 @@ DSP48E1 #(
     .CEINMODE(1'b0),
     // Data ports
     .A({{12{adc_signed_w[MIXER_WIDTH-1]}}, adc_signed_w}),   // Sign-extend 18b to 30b
-    .B({{2{cos_out[15]}}, cos_out}),                          // Sign-extend 16b to 18b
+    .B({{2{cos_nco_pipe[15]}}, cos_nco_pipe}),                // Sign-extend 16b to 18b (pipelined)
     .C(48'b0),
     .D(25'b0),
     .CARRYIN(1'b0),
@@ -432,7 +462,7 @@ DSP48E1 #(
     .CED(1'b0),
     .CEINMODE(1'b0),
     .A({{12{adc_signed_w[MIXER_WIDTH-1]}}, adc_signed_w}),
-    .B({{2{sin_out[15]}}, sin_out}),
+    .B({{2{sin_nco_pipe[15]}}, sin_nco_pipe}),
     .C(48'b0),
     .D(25'b0),
     .CARRYIN(1'b0),
@@ -492,7 +522,7 @@ always @(posedge clk_400m or negedge reset_n_400m) begin
         mixer_overflow_q <= 0;
         saturation_count <= 0;
         overflow_detected <= 0;
-    end else if (dsp_valid_pipe[3]) begin
+    end else if (dsp_valid_pipe[4]) begin
         // Force saturation for testing (applied after DSP output, not on input path)
         if (force_saturation_sync) begin
             mixed_i <= 34'h1FFFFFFFF;

9_Firmware/9_2_FPGA/fpga_self_test.v

@@ -296,7 +296,7 @@ always @(posedge clk or negedge reset_n) begin
                     state           <= ST_DONE;
                 end
             end
-            // Timeout: if no ADC data after 10000 cycles, FAIL
+            // Timeout: if no ADC data after 1000 cycles (10 us @ 100 MHz), FAIL
             step_cnt <= step_cnt + 1;
             if (step_cnt >= 10'd1000 && adc_cap_cnt == 0) begin
                 result_flags[4] <= 1'b0;

9_Firmware/9_2_FPGA/radar_receiver_final.v

@@ -42,6 +42,13 @@ module radar_receiver_final (
     // [2:0]=shift amount: 0..7 bits. Default 0 = pass-through.
     input wire [3:0] host_gain_shift,
 
+    // AGC configuration (opcodes 0x28-0x2C, active only when agc_enable=1)
+    input wire        host_agc_enable,      // 0x28: 0=manual, 1=auto AGC
+    input wire [7:0]  host_agc_target,      // 0x29: target peak magnitude
+    input wire [3:0]  host_agc_attack,      // 0x2A: gain-down step on clipping
+    input wire [3:0]  host_agc_decay,       // 0x2B: gain-up step when weak
+    input wire [3:0]  host_agc_holdoff,     // 0x2C: frames before gain-up
+
     // STM32 toggle signals for mode 00 (STM32-driven) pass-through.
     // These are CDC-synchronized in radar_system_top.v / radar_transmitter.v
     // before reaching this module. In mode 00, the RX mode controller uses
@@ -60,7 +67,12 @@ module radar_receiver_final (
     // ADC raw data tap (clk_100m domain, post-DDC, for self-test / debug)
     output wire [15:0] dbg_adc_i,            // DDC output I (16-bit signed, 100 MHz)
     output wire [15:0] dbg_adc_q,            // DDC output Q (16-bit signed, 100 MHz)
-    output wire        dbg_adc_valid         // DDC output valid (100 MHz)
+    output wire        dbg_adc_valid,        // DDC output valid (100 MHz)
+
+    // AGC status outputs (for status readback / STM32 outer loop)
+    output wire [7:0]  agc_saturation_count, // Per-frame clipped sample count
+    output wire [7:0]  agc_peak_magnitude,   // Per-frame peak (upper 8 bits)
+    output wire [3:0]  agc_current_gain      // Effective gain_shift encoding
 );
 
 // ========== INTERNAL SIGNALS ==========
@@ -86,7 +98,9 @@ wire adc_valid_sync;
 // Gain-controlled signals (between DDC output and matched filter)
 wire signed [15:0] gc_i, gc_q;
 wire gc_valid;
-wire [7:0] gc_saturation_count;  // Diagnostic: clipped sample counter
+wire [7:0] gc_saturation_count;  // Diagnostic: per-frame clipped sample counter
+wire [7:0] gc_peak_magnitude;    // Diagnostic: per-frame peak magnitude
+wire [3:0] gc_current_gain;      // Diagnostic: effective gain_shift
 
 // Reference signals for the processing chain
 wire [15:0] long_chirp_real, long_chirp_imag;
@@ -160,7 +174,7 @@ wire clk_400m;
 // the buffered 400MHz DCO clock via adc_dco_bufg, avoiding duplicate
 // IBUFDS instantiations on the same LVDS clock pair.
 
-// 1. ADC + CDC + AGC
+// 1. ADC + CDC + Digital Gain
 
 // CMOS Output Interface (400MHz Domain)
 wire [7:0] adc_data_cmos;  // 8-bit ADC data (CMOS, from ad9484_interface_400m)
@@ -222,9 +236,10 @@ ddc_input_interface ddc_if (
     .data_sync_error()
 );
 
-// 2b. Digital Gain Control (Fix 3)
+// 2b. Digital Gain Control with AGC
 // Host-configurable power-of-2 shift between DDC output and matched filter.
-// Default gain_shift=0 → pass-through (no behavioral change from baseline).
+// Default gain_shift=0, agc_enable=0 → pass-through (no behavioral change).
+// When agc_enable=1: auto-adjusts gain per frame based on peak/saturation.
 rx_gain_control gain_ctrl (
     .clk(clk),
     .reset_n(reset_n),
@@ -232,10 +247,21 @@ rx_gain_control gain_ctrl (
     .data_q_in(adc_q_scaled),
     .valid_in(adc_valid_sync),
     .gain_shift(host_gain_shift),
+    // AGC configuration
+    .agc_enable(host_agc_enable),
+    .agc_target(host_agc_target),
+    .agc_attack(host_agc_attack),
+    .agc_decay(host_agc_decay),
+    .agc_holdoff(host_agc_holdoff),
+    // Frame boundary from Doppler processor
+    .frame_boundary(doppler_frame_done),
+    // Outputs
     .data_i_out(gc_i),
     .data_q_out(gc_q),
     .valid_out(gc_valid),
-    .saturation_count(gc_saturation_count)
+    .saturation_count(gc_saturation_count),
+    .peak_magnitude(gc_peak_magnitude),
+    .current_gain(gc_current_gain)
 );
 
 // 3. Dual Chirp Memory Loader
@@ -474,4 +500,9 @@ assign dbg_adc_i     = adc_i_scaled;
 assign dbg_adc_q     = adc_q_scaled;
 assign dbg_adc_valid = adc_valid_sync;
 
+// ========== AGC STATUS OUTPUTS ==========
+assign agc_saturation_count = gc_saturation_count;
+assign agc_peak_magnitude   = gc_peak_magnitude;
+assign agc_current_gain     = gc_current_gain;
+
 endmodule

9_Firmware/9_2_FPGA/radar_system_top.v

@@ -125,7 +125,13 @@ module radar_system_top (
     output wire [5:0] dbg_range_bin,
     
     // System status
-    output wire [3:0] system_status
+    output wire [3:0] system_status,
+
+    // FPGA→STM32 GPIO outputs (DIG_5..DIG_7 on 50T board)
+    // Used by STM32 outer AGC loop to read saturation state without USB polling.
+    output wire gpio_dig5,          // DIG_5 (H11→PD13): AGC saturation flag (1=clipping detected)
+    output wire gpio_dig6,          // DIG_6 (G12→PD14): reserved (tied low)
+    output wire gpio_dig7           // DIG_7 (H12→PD15): reserved (tied low)
 );
 
 // ============================================================================
@@ -187,6 +193,11 @@ wire [15:0] rx_dbg_adc_i;
 wire [15:0] rx_dbg_adc_q;
 wire        rx_dbg_adc_valid;
 
+// AGC status from receiver (for status readback and GPIO)
+wire [7:0]  rx_agc_saturation_count;
+wire [7:0]  rx_agc_peak_magnitude;
+wire [3:0]  rx_agc_current_gain;
+
 // Data packing for USB
 wire [31:0] usb_range_profile;
 wire usb_range_valid;
@@ -259,6 +270,13 @@ reg        host_cfar_enable;      // Opcode 0x25: 1=CFAR, 0=simple threshold
 reg        host_mti_enable;       // Opcode 0x26: 1=MTI active, 0=pass-through
 reg [2:0]  host_dc_notch_width;   // Opcode 0x27: DC notch ±width bins (0=off, 1..7)
 
+// AGC configuration registers (host-configurable via USB, opcodes 0x28-0x2C)
+reg        host_agc_enable;       // Opcode 0x28: 0=manual gain, 1=auto AGC
+reg [7:0]  host_agc_target;       // Opcode 0x29: target peak magnitude (default 200)
+reg [3:0]  host_agc_attack;       // Opcode 0x2A: gain-down step on clipping (default 1)
+reg [3:0]  host_agc_decay;        // Opcode 0x2B: gain-up step when weak (default 1)
+reg [3:0]  host_agc_holdoff;      // Opcode 0x2C: frames to wait before gain-up (default 4)
+
 // Board bring-up self-test registers (opcode 0x30 trigger, 0x31 readback)
 reg        host_self_test_trigger;  // Opcode 0x30: self-clearing pulse
 wire       self_test_busy;
@@ -518,6 +536,12 @@ radar_receiver_final rx_inst (
     .host_chirps_per_elev(host_chirps_per_elev),
     // Fix 3: digital gain control
     .host_gain_shift(host_gain_shift),
+    // AGC configuration (opcodes 0x28-0x2C)
+    .host_agc_enable(host_agc_enable),
+    .host_agc_target(host_agc_target),
+    .host_agc_attack(host_agc_attack),
+    .host_agc_decay(host_agc_decay),
+    .host_agc_holdoff(host_agc_holdoff),
     // STM32 toggle signals for RX mode controller (mode 00 pass-through).
     // These are the raw GPIO inputs — the RX mode controller's edge detectors
     // (inside radar_mode_controller) handle debouncing/edge detection.
@@ -532,7 +556,11 @@ radar_receiver_final rx_inst (
     // ADC debug tap (for self-test / bring-up)
     .dbg_adc_i(rx_dbg_adc_i),
     .dbg_adc_q(rx_dbg_adc_q),
-    .dbg_adc_valid(rx_dbg_adc_valid)
+    .dbg_adc_valid(rx_dbg_adc_valid),
+    // AGC status outputs
+    .agc_saturation_count(rx_agc_saturation_count),
+    .agc_peak_magnitude(rx_agc_peak_magnitude),
+    .agc_current_gain(rx_agc_current_gain)
 );
 
 // ============================================================================
@@ -744,7 +772,13 @@ if (USB_MODE == 0) begin : gen_ft601
         // Self-test status readback
         .status_self_test_flags(self_test_flags_latched),
         .status_self_test_detail(self_test_detail_latched),
-        .status_self_test_busy(self_test_busy)
+        .status_self_test_busy(self_test_busy),
+
+        // AGC status readback
+        .status_agc_current_gain(rx_agc_current_gain),
+        .status_agc_peak_magnitude(rx_agc_peak_magnitude),
+        .status_agc_saturation_count(rx_agc_saturation_count),
+        .status_agc_enable(host_agc_enable)
     );
 
     // FT2232H ports unused in FT601 mode — tie off
@@ -805,7 +839,13 @@ end else begin : gen_ft2232h
         // Self-test status readback
         .status_self_test_flags(self_test_flags_latched),
         .status_self_test_detail(self_test_detail_latched),
-        .status_self_test_busy(self_test_busy)
+        .status_self_test_busy(self_test_busy),
+
+        // AGC status readback
+        .status_agc_current_gain(rx_agc_current_gain),
+        .status_agc_peak_magnitude(rx_agc_peak_magnitude),
+        .status_agc_saturation_count(rx_agc_saturation_count),
+        .status_agc_enable(host_agc_enable)
     );
 
     // FT601 ports unused in FT2232H mode — tie off
@@ -892,6 +932,12 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
         // Ground clutter removal defaults (disabled — backward-compatible)
         host_mti_enable         <= 1'b0;      // MTI off
         host_dc_notch_width     <= 3'd0;      // DC notch off
+        // AGC defaults (disabled — backward-compatible with manual gain)
+        host_agc_enable         <= 1'b0;      // AGC off (manual gain)
+        host_agc_target         <= 8'd200;    // Target peak magnitude
+        host_agc_attack         <= 4'd1;      // 1-step gain-down on clipping
+        host_agc_decay          <= 4'd1;      // 1-step gain-up when weak
+        host_agc_holdoff        <= 4'd4;      // 4 frames before gain-up
         // Self-test defaults
         host_self_test_trigger  <= 1'b0;      // Self-test idle
     end else begin
@@ -936,6 +982,12 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
                 // Ground clutter removal opcodes
                 8'h26: host_mti_enable         <= usb_cmd_value[0];
                 8'h27: host_dc_notch_width     <= usb_cmd_value[2:0];
+                // AGC configuration opcodes
+                8'h28: host_agc_enable         <= usb_cmd_value[0];
+                8'h29: host_agc_target         <= usb_cmd_value[7:0];
+                8'h2A: host_agc_attack         <= usb_cmd_value[3:0];
+                8'h2B: host_agc_decay          <= usb_cmd_value[3:0];
+                8'h2C: host_agc_holdoff        <= usb_cmd_value[3:0];
                 // Board bring-up self-test opcodes
                 8'h30: host_self_test_trigger  <= 1'b1;  // Trigger self-test
                 8'h31: host_status_request     <= 1'b1;  // Self-test readback (status alias)
@@ -978,6 +1030,16 @@ end
 
 assign system_status = status_reg;
 
+// ============================================================================
+// FPGA→STM32 GPIO OUTPUTS (DIG_5, DIG_6, DIG_7)
+// ============================================================================
+// DIG_5: AGC saturation flag — high when per-frame saturation_count > 0.
+//        STM32 reads PD13 to detect clipping and adjust ADAR1000 VGA gain.
+// DIG_6, DIG_7: Reserved (tied low for future use).
+assign gpio_dig5 = (rx_agc_saturation_count != 8'd0);
+assign gpio_dig6 = 1'b0;
+assign gpio_dig7 = 1'b0;
+
 // ============================================================================
 // DEBUG AND VERIFICATION
 // ============================================================================

9_Firmware/9_2_FPGA/radar_system_top_50t.v

@@ -76,7 +76,12 @@ module radar_system_top_50t (
     output wire ft_rd_n,              // Read strobe (active low)
     output wire ft_wr_n,              // Write strobe (active low)
     output wire ft_oe_n,              // Output enable / bus direction
-    output wire ft_siwu               // Send Immediate / WakeUp
+    output wire ft_siwu,              // Send Immediate / WakeUp
+
+    // ===== FPGA→STM32 GPIO (Bank 15: 3.3V) =====
+    output wire gpio_dig5,            // DIG_5 (H11→PD13): AGC saturation flag
+    output wire gpio_dig6,            // DIG_6 (G12→PD14): reserved
+    output wire gpio_dig7             // DIG_7 (H12→PD15): reserved
 );
 
     // ===== Tie-off wires for unconstrained FT601 inputs (inactive with USB_MODE=1) =====
@@ -207,7 +212,12 @@ module radar_system_top_50t (
         .dbg_doppler_valid      (dbg_doppler_valid_nc),
         .dbg_doppler_bin        (dbg_doppler_bin_nc),
         .dbg_range_bin          (dbg_range_bin_nc),
-        .system_status          (system_status_nc)
+        .system_status          (system_status_nc),
+
+        // ----- FPGA→STM32 GPIO (DIG_5..DIG_7) -----
+        .gpio_dig5              (gpio_dig5),
+        .gpio_dig6              (gpio_dig6),
+        .gpio_dig7              (gpio_dig7)
     );
 
 endmodule

9_Firmware/9_2_FPGA/rx_gain_control.v

@@ -3,19 +3,32 @@
 /**
  * rx_gain_control.v
  *
- * Host-configurable digital gain control for the receive path.
- * Placed between DDC output (ddc_input_interface) and matched filter input.
+ * Digital gain control with optional per-frame automatic gain control (AGC)
+ * for the receive path. Placed between DDC output and matched filter input.
  *
- * Features:
- *   - Bidirectional power-of-2 gain shift (arithmetic shift)
+ * Manual mode (agc_enable=0):
+ *   - Uses host_gain_shift directly (backward-compatible, no behavioral change)
  *   - gain_shift[3]   = direction: 0 = left shift (amplify), 1 = right shift (attenuate)
  *   - gain_shift[2:0] = amount: 0..7 bits
- *   - Symmetric saturation to ±32767 on overflow (left shift only)
- *   - Saturation counter: 8-bit, counts samples that clipped (wraps at 255)
- *   - 1-cycle latency, valid-in/valid-out pipeline
- *   - Zero-overhead pass-through when gain_shift == 0
+ *   - Symmetric saturation to ±32767 on overflow
  *
- * Intended insertion point in radar_receiver_final.v:
+ * AGC mode (agc_enable=1):
+ *   - Per-frame automatic gain adjustment based on peak/saturation metrics
+ *   - Internal signed gain: -7 (max attenuation) to +7 (max amplification)
+ *   - On frame_boundary:
+ *       * If saturation detected: gain -= agc_attack (fast, immediate)
+ *       * Else if peak < target after holdoff frames: gain += agc_decay (slow)
+ *       * Else: hold current gain
+ *   - host_gain_shift serves as initial gain when AGC first enabled
+ *
+ * Status outputs (for readback via status_words):
+ *   - current_gain[3:0]: effective gain_shift encoding (manual or AGC)
+ *   - peak_magnitude[7:0]: per-frame peak |sample| (upper 8 bits of 15-bit value)
+ *   - saturation_count[7:0]: per-frame clipped sample count (capped at 255)
+ *
+ * Timing: 1-cycle data latency, valid-in/valid-out pipeline.
+ *
+ * Insertion point in radar_receiver_final.v:
  *   ddc_input_interface → rx_gain_control → matched_filter_multi_segment
  */
 
@@ -28,27 +41,75 @@ module rx_gain_control (
     input  wire signed [15:0] data_q_in,
     input  wire               valid_in,
 
-    // Gain configuration (from host via USB command)
-    // [3]   = direction: 0=amplify (left shift), 1=attenuate (right shift)
-    // [2:0] = shift amount: 0..7 bits
+    // Host gain configuration (from USB command opcode 0x16)
+    // [3]=direction: 0=amplify (left shift), 1=attenuate (right shift)
+    // [2:0]=shift amount: 0..7 bits. Default 0x00 = pass-through.
+    // In AGC mode: serves as initial gain on AGC enable transition.
     input  wire [3:0]  gain_shift,
 
+    // AGC configuration inputs (from host via USB, opcodes 0x28-0x2C)
+    input  wire        agc_enable,     // 0x28: 0=manual gain, 1=auto AGC
+    input  wire [7:0]  agc_target,     // 0x29: target peak magnitude (unsigned, default 200)
+    input  wire [3:0]  agc_attack,     // 0x2A: attenuation step on clipping (default 1)
+    input  wire [3:0]  agc_decay,      // 0x2B: amplification step when weak (default 1)
+    input  wire [3:0]  agc_holdoff,    // 0x2C: frames to wait before gain-up (default 4)
+
+    // Frame boundary pulse (1 clk cycle, from Doppler frame_complete)
+    input  wire        frame_boundary,
+
     // Data output (to matched filter)
     output reg  signed [15:0] data_i_out,
     output reg  signed [15:0] data_q_out,
     output reg                valid_out,
 
-    // Diagnostics
-    output reg  [7:0]  saturation_count  // Number of clipped samples (wraps at 255)
+    // Diagnostics / status readback
+    output reg  [7:0]  saturation_count,  // Per-frame clipped sample count (capped at 255)
+    output reg  [7:0]  peak_magnitude,    // Per-frame peak |sample| (upper 8 bits of 15-bit)
+    output reg  [3:0]  current_gain       // Current effective gain_shift (for status readback)
 );
 
-// Decompose gain_shift
-wire       shift_right = gain_shift[3];
-wire [2:0] shift_amt   = gain_shift[2:0];
+// =========================================================================
+// INTERNAL AGC STATE
+// =========================================================================
 
-// -------------------------------------------------------------------------
-// Combinational shift + saturation
-// -------------------------------------------------------------------------
+// Signed internal gain: -7 (max attenuation) to +7 (max amplification)
+// Stored as 4-bit signed (range -8..+7, clamped to -7..+7)
+reg signed [3:0] agc_gain;
+
+// Holdoff counter: counts frames without saturation before allowing gain-up
+reg [3:0] holdoff_counter;
+
+// Per-frame accumulators (running, reset on frame_boundary)
+reg [7:0]  frame_sat_count;    // Clipped samples this frame
+reg [14:0] frame_peak;         // Peak |sample| this frame (15-bit unsigned)
+
+// Previous AGC enable state (for detecting 0→1 transition)
+reg agc_enable_prev;
+
+// Combinational helpers for inclusive frame-boundary snapshot
+// (used when valid_in and frame_boundary coincide)
+reg wire_frame_sat_incr;
+reg wire_frame_peak_update;
+
+// =========================================================================
+// EFFECTIVE GAIN SELECTION
+// =========================================================================
+
+// Convert between signed internal gain and the gain_shift[3:0] encoding.
+//   gain_shift[3]=0, [2:0]=N → amplify by N bits (internal gain = +N)
+//   gain_shift[3]=1, [2:0]=N → attenuate by N bits (internal gain = -N)
+
+// Effective gain_shift used for the actual shift operation
+wire [3:0] effective_gain;
+assign effective_gain = agc_enable ? current_gain : gain_shift;
+
+// Decompose effective gain for shift logic
+wire       shift_right = effective_gain[3];
+wire [2:0] shift_amt   = effective_gain[2:0];
+
+// =========================================================================
+// COMBINATIONAL SHIFT + SATURATION
+// =========================================================================
 // Use wider intermediates to detect overflow on left shift.
 // 24 bits is enough: 16 + 7 shift = 23 significant bits max.
 
@@ -69,26 +130,153 @@ wire signed [15:0] sat_i = overflow_i ? (shifted_i[23] ? -16'sd32768 : 16'sd3276
 wire signed [15:0] sat_q = overflow_q ? (shifted_q[23] ? -16'sd32768 : 16'sd32767)
                                       : shifted_q[15:0];
 
-// -------------------------------------------------------------------------
-// Registered output stage (1-cycle latency)
-// -------------------------------------------------------------------------
+// =========================================================================
+// PEAK MAGNITUDE TRACKING (combinational)
+// =========================================================================
+// Absolute value of signed 16-bit: flip sign bit if negative.
+// Result is 15-bit unsigned [0, 32767]. (We ignore -32768 → 32767 edge case.)
+wire [14:0] abs_i = data_i_in[15] ? (~data_i_in[14:0] + 15'd1) : data_i_in[14:0];
+wire [14:0] abs_q = data_q_in[15] ? (~data_q_in[14:0] + 15'd1) : data_q_in[14:0];
+wire [14:0] max_iq = (abs_i > abs_q) ? abs_i : abs_q;
+
+// =========================================================================
+// SIGNED GAIN ↔ GAIN_SHIFT ENCODING CONVERSION
+// =========================================================================
+// Convert signed agc_gain to gain_shift[3:0] encoding
+function [3:0] signed_to_encoding;
+    input signed [3:0] g;
+    begin
+        if (g >= 0)
+            signed_to_encoding = {1'b0, g[2:0]};       // amplify
+        else
+            signed_to_encoding = {1'b1, (~g[2:0]) + 3'd1}; // attenuate: -g
+    end
+endfunction
+
+// Convert gain_shift[3:0] encoding to signed gain
+function signed [3:0] encoding_to_signed;
+    input [3:0] enc;
+    begin
+        if (enc[3] == 1'b0)
+            encoding_to_signed = {1'b0, enc[2:0]};     // +0..+7
+        else
+            encoding_to_signed = -$signed({1'b0, enc[2:0]}); // -1..-7
+    end
+endfunction
+
+// =========================================================================
+// CLAMPING HELPER
+// =========================================================================
+// Clamp a wider signed value to [-7, +7]
+function signed [3:0] clamp_gain;
+    input signed [4:0] val;  // 5-bit to handle overflow from add
+    begin
+        if (val > 5'sd7)
+            clamp_gain = 4'sd7;
+        else if (val < -5'sd7)
+            clamp_gain = -4'sd7;
+        else
+            clamp_gain = val[3:0];
+    end
+endfunction
+
+// =========================================================================
+// REGISTERED OUTPUT + AGC STATE MACHINE
+// =========================================================================
 always @(posedge clk or negedge reset_n) begin
     if (!reset_n) begin
+        // Data path
         data_i_out       <= 16'sd0;
         data_q_out       <= 16'sd0;
         valid_out        <= 1'b0;
+        // Status outputs
         saturation_count <= 8'd0;
+        peak_magnitude   <= 8'd0;
+        current_gain     <= 4'd0;
+        // AGC internal state
+        agc_gain         <= 4'sd0;
+        holdoff_counter  <= 4'd0;
+        frame_sat_count  <= 8'd0;
+        frame_peak       <= 15'd0;
+        agc_enable_prev  <= 1'b0;
     end else begin
-        valid_out <= valid_in;
+        // Track AGC enable transitions
+        agc_enable_prev <= agc_enable;
 
+        // Compute inclusive metrics: if valid_in fires this cycle,
+        // include current sample in the snapshot taken at frame_boundary.
+        // This avoids losing the last sample when valid_in and
+        // frame_boundary coincide (NBA last-write-wins would otherwise
+        // snapshot stale values then reset, dropping the sample entirely).
+        wire_frame_sat_incr = (valid_in && (overflow_i || overflow_q)
+                               && (frame_sat_count != 8'hFF));
+        wire_frame_peak_update = (valid_in && (max_iq > frame_peak));
+
+        // ---- Data pipeline (1-cycle latency) ----
+        valid_out <= valid_in;
         if (valid_in) begin
             data_i_out <= sat_i;
             data_q_out <= sat_q;
 
-            // Count clipped samples (either channel clipping counts as 1)
-            if ((overflow_i || overflow_q) && (saturation_count != 8'hFF))
-                saturation_count <= saturation_count + 8'd1;
+            // Per-frame saturation counting
+            if ((overflow_i || overflow_q) && (frame_sat_count != 8'hFF))
+                frame_sat_count <= frame_sat_count + 8'd1;
+
+            // Per-frame peak tracking (pre-gain, measures input signal level)
+            if (max_iq > frame_peak)
+                frame_peak <= max_iq;
         end
+
+        // ---- Frame boundary: AGC update + metric snapshot ----
+        if (frame_boundary) begin
+            // Snapshot per-frame metrics INCLUDING current sample if valid_in
+            saturation_count <= wire_frame_sat_incr
+                                ? (frame_sat_count + 8'd1)
+                                : frame_sat_count;
+            peak_magnitude   <= wire_frame_peak_update
+                                ? max_iq[14:7]
+                                : frame_peak[14:7];
+
+            // Reset per-frame accumulators for next frame
+            frame_sat_count <= 8'd0;
+            frame_peak      <= 15'd0;
+
+            if (agc_enable) begin
+                // AGC auto-adjustment at frame boundary
+                // Use inclusive counts/peaks (accounting for simultaneous valid_in)
+                if (wire_frame_sat_incr || frame_sat_count > 8'd0) begin
+                    // Clipping detected: reduce gain immediately (attack)
+                    agc_gain <= clamp_gain($signed({agc_gain[3], agc_gain}) -
+                                           $signed({1'b0, agc_attack}));
+                    holdoff_counter <= agc_holdoff;  // Reset holdoff
+                end else if ((wire_frame_peak_update ? max_iq[14:7] : frame_peak[14:7])
+                             < agc_target) begin
+                    // Signal too weak: increase gain after holdoff expires
+                    if (holdoff_counter == 4'd0) begin
+                        agc_gain <= clamp_gain($signed({agc_gain[3], agc_gain}) +
+                                               $signed({1'b0, agc_decay}));
+                    end else begin
+                        holdoff_counter <= holdoff_counter - 4'd1;
+                    end
+                end else begin
+                    // Signal in good range, no saturation: hold gain
+                    // Reset holdoff so next weak frame has to wait again
+                    holdoff_counter <= agc_holdoff;
+                end
+            end
+        end
+
+        // ---- AGC enable transition: initialize from host gain ----
+        if (agc_enable && !agc_enable_prev) begin
+            agc_gain        <= encoding_to_signed(gain_shift);
+            holdoff_counter <= agc_holdoff;
+        end
+
+        // ---- Update current_gain output ----
+        if (agc_enable)
+            current_gain <= signed_to_encoding(agc_gain);
+        else
+            current_gain <= gain_shift;
     end
 end
 

9_Firmware/9_2_FPGA/scripts/50t/build_50t.tcl

@@ -120,9 +120,10 @@ set_property CLOCK_DEDICATED_ROUTE FALSE [get_nets {ft_clkout_IBUF}]
 
 # ---- Run implementation steps ----
 opt_design -directive Explore
-place_design -directive Explore
+place_design -directive ExtraNetDelay_high
+phys_opt_design -directive AggressiveExplore
+route_design -directive AggressiveExplore
 phys_opt_design -directive AggressiveExplore
-route_design -directive Explore
 phys_opt_design -directive AggressiveExplore
 
 set impl_elapsed [expr {[clock seconds] - $impl_start}]

9_Firmware/9_2_FPGA/tb/tb_rx_gain_control.v

@@ -38,10 +38,20 @@ reg signed [15:0] data_q_in;
 reg               valid_in;
 reg [3:0]         gain_shift;
 
+// AGC configuration (default: AGC disabled — manual mode)
+reg               agc_enable;
+reg [7:0]         agc_target;
+reg [3:0]         agc_attack;
+reg [3:0]         agc_decay;
+reg [3:0]         agc_holdoff;
+reg               frame_boundary;
+
 wire signed [15:0] data_i_out;
 wire signed [15:0] data_q_out;
 wire               valid_out;
 wire [7:0]         saturation_count;
+wire [7:0]         peak_magnitude;
+wire [3:0]         current_gain;
 
 rx_gain_control dut (
     .clk(clk),
@@ -50,10 +60,18 @@ rx_gain_control dut (
     .data_q_in(data_q_in),
     .valid_in(valid_in),
     .gain_shift(gain_shift),
+    .agc_enable(agc_enable),
+    .agc_target(agc_target),
+    .agc_attack(agc_attack),
+    .agc_decay(agc_decay),
+    .agc_holdoff(agc_holdoff),
+    .frame_boundary(frame_boundary),
     .data_i_out(data_i_out),
     .data_q_out(data_q_out),
     .valid_out(valid_out),
-    .saturation_count(saturation_count)
+    .saturation_count(saturation_count),
+    .peak_magnitude(peak_magnitude),
+    .current_gain(current_gain)
 );
 
 // ---------------------------------------------------------------
@@ -105,6 +123,13 @@ initial begin
     data_q_in  = 0;
     valid_in   = 0;
     gain_shift = 4'd0;
+    // AGC disabled for backward-compatible tests (Tests 1-12)
+    agc_enable     = 0;
+    agc_target     = 8'd200;
+    agc_attack     = 4'd1;
+    agc_decay      = 4'd1;
+    agc_holdoff    = 4'd4;
+    frame_boundary = 0;
 
     repeat (4) @(posedge clk);
     reset_n = 1;
@@ -152,6 +177,9 @@ initial begin
           "T3.1: I saturated to +32767");
     check(data_q_out == -16'sd32768,
           "T3.2: Q saturated to -32768");
+    // Pulse frame_boundary to snapshot the per-frame saturation count
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
     check(saturation_count == 8'd1,
           "T3.3: Saturation counter = 1 (both channels clipped counts as 1)");
 
@@ -173,6 +201,9 @@ initial begin
           "T4.1: I attenuated 4000>>2 = 1000");
     check(data_q_out == -16'sd500,
           "T4.2: Q attenuated -2000>>2 = -500");
+    // Pulse frame_boundary to snapshot (should be 0 — no clipping)
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
     check(saturation_count == 8'd0,
           "T4.3: No saturation on right shift");
 
@@ -315,13 +346,18 @@ initial begin
     valid_in = 1'b0;
     @(posedge clk); #1;
 
+    // Pulse frame_boundary to snapshot per-frame saturation count
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
     check(saturation_count == 8'd255,
           "T11.1: Counter capped at 255 after 256 saturating samples");
 
-    // One more sample — should stay at 255
+    // One more sample + frame boundary — should still be capped at 1 (new frame)
     send_sample(16'sd20000, 16'sd20000);
-    check(saturation_count == 8'd255,
-          "T11.2: Counter stays at 255 (no wrap)");
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    check(saturation_count == 8'd1,
+          "T11.2: New frame counter = 1 (single sample)");
 
     // ---------------------------------------------------------------
     // TEST 12: Reset clears everything
@@ -329,6 +365,8 @@ initial begin
     $display("");
     $display("--- Test 12: Reset clears all ---");
 
+    gain_shift = 4'd0;  // Reset gain_shift to 0 so current_gain reads 0
+    agc_enable = 0;
     reset_n = 0;
     repeat (2) @(posedge clk);
     reset_n = 1;
@@ -342,6 +380,479 @@ initial begin
           "T12.3: valid_out cleared on reset");
     check(saturation_count == 8'd0,
           "T12.4: Saturation counter cleared on reset");
+    check(current_gain == 4'd0,
+          "T12.5: current_gain cleared on reset");
+
+    // ---------------------------------------------------------------
+    // TEST 13: current_gain reflects gain_shift in manual mode
+    // ---------------------------------------------------------------
+    $display("");
+    $display("--- Test 13: current_gain tracks gain_shift (manual) ---");
+
+    gain_shift = 4'b0_011;  // amplify x8
+    @(posedge clk); @(posedge clk); #1;
+    check(current_gain == 4'b0011,
+          "T13.1: current_gain = 0x3 (amplify x8)");
+
+    gain_shift = 4'b1_010;  // attenuate /4
+    @(posedge clk); @(posedge clk); #1;
+    check(current_gain == 4'b1010,
+          "T13.2: current_gain = 0xA (attenuate /4)");
+
+    // ---------------------------------------------------------------
+    // TEST 14: Peak magnitude tracking
+    // ---------------------------------------------------------------
+    $display("");
+    $display("--- Test 14: Peak magnitude tracking ---");
+
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift = 4'b0_000;  // pass-through
+    // Send samples with increasing magnitude
+    send_sample(16'sd100, 16'sd50);
+    send_sample(16'sd1000, 16'sd500);
+    send_sample(16'sd8000, 16'sd2000);   // peak = 8000
+    send_sample(16'sd200, 16'sd100);
+    // Pulse frame_boundary to snapshot
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    // peak_magnitude = upper 8 bits of 15-bit peak (8000)
+    // 8000 = 0x1F40, 15-bit = 0x1F40, [14:7] = 0x3E = 62
+    check(peak_magnitude == 8'd62,
+          "T14.1: Peak magnitude = 62 (8000 >> 7)");
+
+    // ---------------------------------------------------------------
+    // TEST 15: AGC auto gain-down on saturation
+    // ---------------------------------------------------------------
+    $display("");
+    $display("--- Test 15: AGC gain-down on saturation ---");
+
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    // Start with amplify x4 (gain_shift = 0x02), then enable AGC
+    gain_shift  = 4'b0_010;  // amplify x4, internal gain = +2
+    agc_enable  = 0;
+    agc_attack  = 4'd1;
+    agc_decay   = 4'd1;
+    agc_holdoff = 4'd2;
+    agc_target  = 8'd100;
+    @(posedge clk); @(posedge clk);
+
+    // Enable AGC — should initialize from gain_shift
+    agc_enable = 1;
+    @(posedge clk); @(posedge clk); @(posedge clk); #1;
+    check(current_gain == 4'b0010,
+          "T15.1: AGC initialized from gain_shift (amplify x4)");
+
+    // Send saturating samples (will clip at x4 gain)
+    send_sample(16'sd20000, 16'sd20000);
+    send_sample(16'sd20000, 16'sd20000);
+
+    // Pulse frame_boundary — AGC should reduce gain by attack=1
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    // current_gain lags agc_gain by 1 cycle (NBA), wait one extra cycle
+    @(posedge clk); #1;
+    // Internal gain was +2, attack=1 → new gain = +1 (0x01)
+    check(current_gain == 4'b0001,
+          "T15.2: AGC reduced gain to x2 after saturation");
+
+    // Another frame with saturation (20000*2 = 40000 > 32767)
+    send_sample(16'sd20000, 16'sd20000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    // gain was +1, attack=1 → new gain = 0 (0x00)
+    check(current_gain == 4'b0000,
+          "T15.3: AGC reduced gain to x1 (pass-through)");
+
+    // At gain 0 (pass-through), 20000 does NOT overflow 16-bit range,
+    // so no saturation occurs. Signal peak = 20000 >> 7 = 156 > target(100),
+    // so AGC correctly holds gain at 0. This is expected behavior.
+    // To test crossing into attenuation: increase attack to 3.
+    agc_attack = 4'd3;
+    // Reset and start fresh with gain +2, attack=3
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift = 4'b0_010;  // amplify x4, internal gain = +2
+    agc_enable = 0;
+    @(posedge clk);
+    agc_enable = 1;
+    @(posedge clk); @(posedge clk); @(posedge clk); #1;
+
+    // Send saturating samples
+    send_sample(16'sd20000, 16'sd20000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    // gain was +2, attack=3 → new gain = -1 → encoding 0x09
+    check(current_gain == 4'b1001,
+          "T15.4: Large attack step crosses to attenuation (gain +2 - 3 = -1 → 0x9)");
+
+    // ---------------------------------------------------------------
+    // TEST 16: AGC auto gain-up after holdoff
+    // ---------------------------------------------------------------
+    $display("");
+    $display("--- Test 16: AGC gain-up after holdoff ---");
+
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    // Start with low gain, weak signal, holdoff=2
+    gain_shift  = 4'b0_000;  // pass-through (internal gain = 0)
+    agc_enable  = 0;
+    agc_attack  = 4'd1;
+    agc_decay   = 4'd1;
+    agc_holdoff = 4'd2;
+    agc_target  = 8'd100;  // target peak = 100 (in upper 8 bits = 12800 raw)
+    @(posedge clk); @(posedge clk);
+
+    agc_enable = 1;
+    @(posedge clk); @(posedge clk); #1;
+
+    // Frame 1: send weak signal (peak < target), holdoff counter = 2
+    send_sample(16'sd100, 16'sd50);  // peak=100, [14:7]=0 (very weak)
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b0000,
+          "T16.1: Gain held during holdoff (frame 1, holdoff=2)");
+
+    // Frame 2: still weak, holdoff counter decrements to 1
+    send_sample(16'sd100, 16'sd50);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b0000,
+          "T16.2: Gain held during holdoff (frame 2, holdoff=1)");
+
+    // Frame 3: holdoff expired (was 0 at start of frame) → gain up
+    send_sample(16'sd100, 16'sd50);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b0001,
+          "T16.3: Gain increased after holdoff expired (gain 0->1)");
+
+    // ---------------------------------------------------------------
+    // TEST 17: Repeated attacks drive gain negative, clamp at -7,
+    //          then decay recovers
+    // ---------------------------------------------------------------
+    $display("");
+    $display("--- Test 17: Repeated attack → negative clamp → decay recovery ---");
+
+    // ----- 17a: Walk gain from +7 down through zero via repeated attack -----
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift  = 4'b0_111;  // amplify x128, internal gain = +7
+    agc_enable  = 0;
+    agc_attack  = 4'd2;
+    agc_decay   = 4'd1;
+    agc_holdoff = 4'd2;
+    agc_target  = 8'd100;
+    @(posedge clk);
+    agc_enable = 1;
+    @(posedge clk); @(posedge clk); @(posedge clk); #1;
+    check(current_gain == 4'b0_111,
+          "T17a.1: AGC initialized at gain +7 (0x7)");
+
+    // Frame 1: saturating at gain +7 → gain 7-2=5
+    send_sample(16'sd1000, 16'sd1000);  // 1000<<7 = 128000 → overflow
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b0_101,
+          "T17a.2: After attack: gain +5 (0x5)");
+
+    // Frame 2: still saturating at gain +5 → gain 5-2=3
+    send_sample(16'sd1000, 16'sd1000);  // 1000<<5 = 32000 → no overflow
+    send_sample(16'sd2000, 16'sd2000);  // 2000<<5 = 64000 → overflow
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b0_011,
+          "T17a.3: After attack: gain +3 (0x3)");
+
+    // Frame 3: saturating at gain +3 → gain 3-2=1
+    send_sample(16'sd5000, 16'sd5000);  // 5000<<3 = 40000 → overflow
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b0_001,
+          "T17a.4: After attack: gain +1 (0x1)");
+
+    // Frame 4: saturating at gain +1 → gain 1-2=-1 → encoding 0x9
+    send_sample(16'sd20000, 16'sd20000); // 20000<<1 = 40000 → overflow
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_001,
+          "T17a.5: Attack crossed zero: gain -1 (0x9)");
+
+    // Frame 5: at gain -1 (right shift 1), 20000>>>1=10000, NO overflow.
+    // peak = 20000 → [14:7]=156 > target(100) → HOLD, gain stays -1
+    send_sample(16'sd20000, 16'sd20000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_001,
+          "T17a.6: No overflow at -1, peak>target → HOLD, gain stays -1");
+
+    // ----- 17b: Max attack step clamps at -7 -----
+    $display("");
+    $display("--- Test 17b: Max attack clamps at -7 ---");
+
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift  = 4'b0_011;  // amplify x8, internal gain = +3
+    agc_attack  = 4'd15;     // max attack step
+    agc_enable  = 0;
+    @(posedge clk);
+    agc_enable = 1;
+    @(posedge clk); @(posedge clk); @(posedge clk); #1;
+    check(current_gain == 4'b0_011,
+          "T17b.1: Initialized at gain +3");
+
+    // One saturating frame: gain = clamp(3 - 15) = clamp(-12) = -7 → 0xF
+    send_sample(16'sd5000, 16'sd5000);  // 5000<<3 = 40000 → overflow
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_111,
+          "T17b.2: Gain clamped at -7 (0xF) after max attack");
+
+    // Another frame at gain -7: 5000>>>7 = 39, peak = 5000→[14:7]=39 < target(100)
+    // → decay path, but holdoff counter was reset to 2 by the attack above
+    send_sample(16'sd5000, 16'sd5000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_111,
+          "T17b.3: Gain still -7 (holdoff active, 2→1)");
+
+    // ----- 17c: Decay recovery from -7 after holdoff -----
+    $display("");
+    $display("--- Test 17c: Decay recovery from deep negative ---");
+
+    // Holdoff was 2. After attack (frame above), holdoff=2.
+    // Frame after 17b.3: holdoff decrements to 0
+    send_sample(16'sd5000, 16'sd5000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_111,
+          "T17c.1: Gain still -7 (holdoff 1→0)");
+
+    // Now holdoff=0, next weak frame should trigger decay: -7 + 1 = -6 → 0xE
+    send_sample(16'sd5000, 16'sd5000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_110,
+          "T17c.2: Decay from -7 to -6 (0xE) after holdoff expired");
+
+    // One more decay: -6 + 1 = -5 → 0xD
+    send_sample(16'sd5000, 16'sd5000);
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+    check(current_gain == 4'b1_101,
+          "T17c.3: Decay from -6 to -5 (0xD)");
+
+    // Verify output is actually attenuated: at gain -5 (right shift 5),
+    // 5000 >>> 5 = 156
+    send_sample(16'sd5000, 16'sd0);
+    check(data_i_out == 16'sd156,
+          "T17c.4: Output correctly attenuated: 5000>>>5 = 156");
+
+    // =================================================================
+    // Test 18: valid_in + frame_boundary on the SAME cycle
+    // Verify the coincident sample is included in the frame snapshot
+    // (Bug #7 fix — previously lost due to NBA last-write-wins)
+    // =================================================================
+    $display("");
+    $display("--- Test 18: valid_in + frame_boundary simultaneous ---");
+
+    // ----- 18a: Coincident saturating sample included in sat count -----
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift  = 4'b0_011;  // amplify x8 (shift left 3)
+    agc_attack  = 4'd1;
+    agc_decay   = 4'd1;
+    agc_holdoff = 4'd2;
+    agc_target  = 8'd100;
+    agc_enable  = 1;
+    @(posedge clk); @(posedge clk); @(posedge clk); #1;
+
+    // Send one normal sample first (establishes a non-zero frame)
+    send_sample(16'sd100, 16'sd100);  // small, no overflow at gain +3
+
+    // Now: assert valid_in AND frame_boundary on the SAME posedge.
+    // The sample is large enough to overflow at gain +3: 5000<<3 = 40000 > 32767
+    @(negedge clk);
+    data_i_in      = 16'sd5000;
+    data_q_in      = 16'sd5000;
+    valid_in       = 1'b1;
+    frame_boundary = 1'b1;
+    @(posedge clk); #1;  // DUT samples both signals
+    @(negedge clk);
+    valid_in       = 1'b0;
+    frame_boundary = 1'b0;
+    @(posedge clk); #1;  // let NBA settle
+    @(posedge clk); #1;
+
+    // Saturation count should be 1 (the coincident sample overflowed)
+    check(saturation_count == 8'd1,
+          "T18a.1: Coincident saturating sample counted in snapshot (sat_count=1)");
+
+    // Peak should reflect pre-gain max(|5000|,|5000|) = 5000 → [14:7] = 39
+    // (or at least >= the first sample's peak of 100→[14:7]=0)
+    check(peak_magnitude == 8'd39,
+          "T18a.2: Coincident sample peak included in snapshot (peak=39)");
+
+    // AGC should have attacked (sat > 0): gain +3 → +3-1 = +2
+    check(current_gain == 4'b0_010,
+          "T18a.3: AGC attacked on coincident saturation (gain +3 → +2)");
+
+    // ----- 18b: Coincident non-saturating peak updates snapshot -----
+    $display("");
+    $display("--- Test 18b: Coincident peak-only sample ---");
+
+    reset_n = 0;
+    agc_enable  = 0;  // deassert so transition fires with NEW gain_shift
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift  = 4'b0_000;  // no amplification (shift 0)
+    agc_attack  = 4'd1;
+    agc_decay   = 4'd1;
+    agc_holdoff = 4'd0;
+    agc_target  = 8'd200;    // high target so signal is "weak"
+    agc_enable  = 1;
+    @(posedge clk); @(posedge clk); @(posedge clk); #1;
+
+    // Send a small sample
+    send_sample(16'sd50, 16'sd50);
+
+    // Coincident frame_boundary + valid_in with a LARGER sample (not saturating)
+    @(negedge clk);
+    data_i_in      = 16'sd10000;
+    data_q_in      = 16'sd10000;
+    valid_in       = 1'b1;
+    frame_boundary = 1'b1;
+    @(posedge clk); #1;
+    @(negedge clk);
+    valid_in       = 1'b0;
+    frame_boundary = 1'b0;
+    @(posedge clk); #1;
+    @(posedge clk); #1;
+
+    // Peak should be max(|10000|,|10000|) = 10000 → [14:7] = 78
+    check(peak_magnitude == 8'd78,
+          "T18b.1: Coincident larger peak included (peak=78)");
+    // No saturation at gain 0
+    check(saturation_count == 8'd0,
+          "T18b.2: No saturation (gain=0, no overflow)");
+
+    // =================================================================
+    // Test 19: AGC enable toggle mid-frame
+    // Verify gain initializes from gain_shift and holdoff resets
+    // =================================================================
+    $display("");
+    $display("--- Test 19: AGC enable toggle mid-frame ---");
+
+    // ----- 19a: Enable AGC mid-frame, verify gain init -----
+    reset_n = 0;
+    repeat (2) @(posedge clk);
+    reset_n = 1;
+    repeat (2) @(posedge clk);
+
+    gain_shift  = 4'b0_101;  // amplify x32 (shift left 5), internal = +5
+    agc_attack  = 4'd2;
+    agc_decay   = 4'd1;
+    agc_holdoff = 4'd3;
+    agc_target  = 8'd100;
+    agc_enable  = 0;         // start disabled
+    @(posedge clk); #1;
+
+    // With AGC off, current_gain should follow gain_shift directly
+    check(current_gain == 4'b0_101,
+          "T19a.1: AGC disabled → current_gain = gain_shift (0x5)");
+
+    // Send a few samples (building up frame metrics)
+    send_sample(16'sd1000, 16'sd1000);
+    send_sample(16'sd2000, 16'sd2000);
+
+    // Toggle AGC enable ON mid-frame
+    @(negedge clk);
+    agc_enable = 1;
+    @(posedge clk); #1;
+    @(posedge clk); #1;  // let enable transition register
+
+    // Gain should initialize from gain_shift encoding (0b0_101 → +5)
+    check(current_gain == 4'b0_101,
+          "T19a.2: AGC enabled mid-frame → gain initialized from gain_shift (+5)");
+
+    // Send a saturating sample, then boundary
+    send_sample(16'sd5000, 16'sd5000);  // 5000<<5 overflows
+    @(negedge clk); frame_boundary = 1; @(posedge clk); #1;
+    @(negedge clk); frame_boundary = 0; @(posedge clk); #1;
+    @(posedge clk); #1;
+
+    // AGC should attack: gain +5 → +5-2 = +3
+    check(current_gain == 4'b0_011,
+          "T19a.3: After boundary, AGC attacked (gain +5 → +3)");
+
+    // ----- 19b: Disable AGC mid-frame, verify passthrough -----
+    $display("");
+    $display("--- Test 19b: Disable AGC mid-frame ---");
+
+    // Change gain_shift to a new value
+    @(negedge clk);
+    gain_shift = 4'b1_010;  // attenuate by 2 (right shift 2)
+    agc_enable = 0;
+    @(posedge clk); #1;
+    @(posedge clk); #1;
+
+    // With AGC off, current_gain should follow gain_shift
+    check(current_gain == 4'b1_010,
+          "T19b.1: AGC disabled → current_gain = gain_shift (0xA, atten 2)");
+
+    // Send sample: 1000 >> 2 = 250
+    send_sample(16'sd1000, 16'sd0);
+    check(data_i_out == 16'sd250,
+          "T19b.2: Output uses host gain_shift when AGC off: 1000>>2=250");
+
+    // ----- 19c: Re-enable, verify gain re-initializes -----
+    @(negedge clk);
+    gain_shift = 4'b0_010;  // amplify by 4 (shift left 2), internal = +2
+    agc_enable = 1;
+    @(posedge clk); #1;
+    @(posedge clk); #1;
+
+    check(current_gain == 4'b0_010,
+          "T19c.1: AGC re-enabled → gain re-initialized from gain_shift (+2)");
 
     // ---------------------------------------------------------------
     // SUMMARY

9_Firmware/9_2_FPGA/tb/tb_usb_data_interface.v

@@ -79,6 +79,12 @@ module tb_usb_data_interface;
     reg  [7:0]  status_self_test_detail;
     reg         status_self_test_busy;
 
+    // AGC status readback inputs
+    reg  [3:0]  status_agc_current_gain;
+    reg  [7:0]  status_agc_peak_magnitude;
+    reg  [7:0]  status_agc_saturation_count;
+    reg         status_agc_enable;
+
     // ── Clock generators (asynchronous) ────────────────────────
     always #(CLK_PERIOD / 2) clk = ~clk;
     always #(FT_CLK_PERIOD / 2) ft601_clk_in = ~ft601_clk_in;
@@ -134,7 +140,13 @@ module tb_usb_data_interface;
         // Self-test status readback
         .status_self_test_flags (status_self_test_flags),
         .status_self_test_detail(status_self_test_detail),
-        .status_self_test_busy  (status_self_test_busy)
+        .status_self_test_busy  (status_self_test_busy),
+
+        // AGC status readback
+        .status_agc_current_gain    (status_agc_current_gain),
+        .status_agc_peak_magnitude  (status_agc_peak_magnitude),
+        .status_agc_saturation_count(status_agc_saturation_count),
+        .status_agc_enable          (status_agc_enable)
     );
 
     // ── Test bookkeeping ───────────────────────────────────────
@@ -194,6 +206,10 @@ module tb_usb_data_interface;
             status_self_test_flags  = 5'b00000;
             status_self_test_detail = 8'd0;
             status_self_test_busy   = 1'b0;
+            status_agc_current_gain     = 4'd0;
+            status_agc_peak_magnitude   = 8'd0;
+            status_agc_saturation_count = 8'd0;
+            status_agc_enable           = 1'b0;
             repeat (6) @(posedge ft601_clk_in);
             reset_n = 1;
             // Wait enough cycles for stream_control CDC to propagate
@@ -902,6 +918,11 @@ module tb_usb_data_interface;
         status_self_test_flags  = 5'b11111;
         status_self_test_detail = 8'hA5;
         status_self_test_busy   = 1'b0;
+        // AGC status: gain=5, peak=180, sat_count=12, enabled
+        status_agc_current_gain     = 4'd5;
+        status_agc_peak_magnitude   = 8'd180;
+        status_agc_saturation_count = 8'd12;
+        status_agc_enable           = 1'b1;
 
         // Pulse status_request (1 cycle in clk domain — toggles status_req_toggle_100m)
         @(posedge clk);
@@ -958,8 +979,8 @@ module tb_usb_data_interface;
               "Status readback: word 2 = {guard, short_chirp}");
         check(uut.status_words[3] === {16'd17450, 10'd0, 6'd32},
               "Status readback: word 3 = {short_listen, 0, chirps_per_elev}");
-        check(uut.status_words[4] === {30'd0, 2'b10},
-              "Status readback: word 4 = range_mode=2'b10");
+        check(uut.status_words[4] === {4'd5, 8'd180, 8'd12, 1'b1, 9'd0, 2'b10},
+              "Status readback: word 4 = {agc_gain=5, peak=180, sat=12, en=1, range_mode=2}");
         // status_words[5] = {7'd0, busy, 8'd0, detail[7:0], 3'd0, flags[4:0]}
         // = {7'd0, 1'b0, 8'd0, 8'hA5, 3'd0, 5'b11111}
         check(uut.status_words[5] === {7'd0, 1'b0, 8'd0, 8'hA5, 3'd0, 5'b11111},

9_Firmware/9_2_FPGA/usb_data_interface.v

@@ -20,8 +20,8 @@ module usb_data_interface (
     // Control signals
     output reg ft601_txe_n,          // Transmit enable (active low)
     output reg ft601_rxf_n,          // Receive enable (active low)
-    input wire ft601_txe,             // Transmit FIFO empty
-    input wire ft601_rxf,             // Receive FIFO full
+    input wire ft601_txe,             // TXE: Transmit FIFO Not Full (high = space available to write)
+    input wire ft601_rxf,             // RXF: Receive FIFO Not Empty (high = data available to read)
     output reg ft601_wr_n,            // Write strobe (active low)
     output reg ft601_rd_n,            // Read strobe (active low)
     output reg ft601_oe_n,            // Output enable (active low)
@@ -77,7 +77,13 @@ module usb_data_interface (
     // Self-test status readback (opcode 0x31 / included in 0xFF status packet)
     input wire [4:0]  status_self_test_flags,  // Per-test PASS(1)/FAIL(0) latched
     input wire [7:0]  status_self_test_detail, // Diagnostic detail byte latched
-    input wire        status_self_test_busy    // Self-test FSM still running
+    input wire        status_self_test_busy,   // Self-test FSM still running
+
+    // AGC status readback
+    input wire [3:0]  status_agc_current_gain,
+    input wire [7:0]  status_agc_peak_magnitude,
+    input wire [7:0]  status_agc_saturation_count,
+    input wire        status_agc_enable
 );
 
 // USB packet structure (same as before)
@@ -267,8 +273,13 @@ always @(posedge ft601_clk_in or negedge ft601_reset_n) begin
             status_words[2] <= {status_guard, status_short_chirp};
             // Word 3: {short_listen_cycles[15:0], chirps_per_elev[5:0], 10'b0}
             status_words[3] <= {status_short_listen, 10'd0, status_chirps_per_elev};
-            // Word 4: Fix 7 — range_mode in bits [1:0], rest reserved
-            status_words[4] <= {30'd0, status_range_mode};
+            // Word 4: AGC metrics + range_mode
+            status_words[4] <= {status_agc_current_gain,        // [31:28]
+                                status_agc_peak_magnitude,      // [27:20]
+                                status_agc_saturation_count,    // [19:12]
+                                status_agc_enable,              // [11]
+                                9'd0,                           // [10:2] reserved
+                                status_range_mode};             // [1:0]
             // Word 5: Self-test results {reserved[6:0], busy, reserved[7:0], detail[7:0], reserved[2:0], flags[4:0]}
             status_words[5] <= {7'd0, status_self_test_busy,
                                 8'd0, status_self_test_detail,

9_Firmware/9_2_FPGA/usb_data_interface_ft2232h.v

@@ -90,7 +90,13 @@ module usb_data_interface_ft2232h (
     // Self-test status readback
     input wire [4:0]  status_self_test_flags,
     input wire [7:0]  status_self_test_detail,
-    input wire        status_self_test_busy
+    input wire        status_self_test_busy,
+
+    // AGC status readback
+    input wire [3:0]  status_agc_current_gain,
+    input wire [7:0]  status_agc_peak_magnitude,
+    input wire [7:0]  status_agc_saturation_count,
+    input wire        status_agc_enable
 );
 
 // ============================================================================
@@ -281,7 +287,12 @@ always @(posedge ft_clk or negedge ft_reset_n) begin
             status_words[1] <= {status_long_chirp, status_long_listen};
             status_words[2] <= {status_guard, status_short_chirp};
             status_words[3] <= {status_short_listen, 10'd0, status_chirps_per_elev};
-            status_words[4] <= {30'd0, status_range_mode};
+            status_words[4] <= {status_agc_current_gain,        // [31:28]
+                                status_agc_peak_magnitude,      // [27:20]
+                                status_agc_saturation_count,    // [19:12]
+                                status_agc_enable,              // [11]
+                                9'd0,                           // [10:2] reserved
+                                status_range_mode};             // [1:0]
             status_words[5] <= {7'd0, status_self_test_busy,
                                 8'd0, status_self_test_detail,
                                 3'd0, status_self_test_flags};

9_Firmware/9_3_GUI/GUI_versions.txt

@@ -8,6 +8,6 @@ GUI_V5 ==> Added Mercury Color
 
 GUI_V6 ==> Added USB3 FT601 support
 
-radar_dashboard ==> Board bring-up dashboard (FT2232H reader, real-time R-D heatmap, CFAR overlay, waterfall, host commands, HDF5 recording)
+GUI_V65_Tk ==> Board bring-up dashboard (FT2232H reader, real-time R-D heatmap, CFAR overlay, waterfall, host commands, HDF5 recording, replay, demo mode)
 radar_protocol ==> Protocol layer (packet parsing, command building, FT2232H connection, data recorder, acquisition thread)
 smoke_test ==> Board bring-up smoke test host script (triggers FPGA self-test via opcode 0x30)

9_Firmware/9_3_GUI/adi_agc_analysis.py

@@ -0,0 +1,338 @@
+# ruff: noqa: T201
+#!/usr/bin/env python3
+"""
+One-off AGC saturation analysis for ADI CN0566 raw IQ captures.
+
+Bit-accurate simulation of rx_gain_control.v AGC inner loop applied
+to real captured IQ data.  Three scenarios per dataset:
+
+  Row 1 — AGC OFF:  Fixed gain_shift=0 (pass-through).  Shows raw clipping.
+  Row 2 — AGC ON:   Auto-adjusts from gain_shift=0.  Clipping clears.
+  Row 3 — AGC delayed: OFF for first half, ON at midpoint.
+           Shows the transition: clipping → AGC activates → clears.
+
+Key RTL details modelled exactly:
+  - gain_shift[3]=direction (0=amplify/left, 1=attenuate/right), [2:0]=amount
+  - Internal agc_gain is signed -7..+7
+  - Peak is measured PRE-gain (raw input |sample|, upper 8 of 15 bits)
+  - Saturation is measured POST-gain (overflow from shift)
+  - Attack: gain -= agc_attack when any sample clips (immediate)
+  - Decay: gain += agc_decay when peak < target AND holdoff expired
+  - Hold: when peak >= target AND no saturation, hold gain, reset holdoff
+
+Usage:
+  python adi_agc_analysis.py
+  python adi_agc_analysis.py --data /path/to/file.npy --label "my capture"
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from v7.agc_sim import (
+    encoding_to_signed,
+    apply_gain_shift,
+    quantize_iq,
+    AGCConfig,
+    AGCState,
+    process_agc_frame,
+)
+
+# ---------------------------------------------------------------------------
+# FPGA AGC parameters (rx_gain_control.v reset defaults)
+# ---------------------------------------------------------------------------
+AGC_TARGET = 200       # host_agc_target (8-bit, default 200)
+ADC_RAIL = 4095        # 12-bit ADC max absolute value
+
+
+# ---------------------------------------------------------------------------
+# Per-frame AGC simulation using v7.agc_sim (bit-accurate to RTL)
+# ---------------------------------------------------------------------------
+
+def simulate_agc(frames: np.ndarray, agc_enabled: bool = True,
+                 enable_at_frame: int = 0,
+                 initial_gain_enc: int = 0x00) -> dict:
+    """Simulate FPGA inner-loop AGC across all frames.
+
+    Parameters
+    ----------
+    frames : (N, chirps, samples) complex — raw ADC captures (12-bit range)
+    agc_enabled : if False, gain stays fixed
+    enable_at_frame : frame index where AGC activates
+    initial_gain_enc : gain_shift[3:0] encoding when AGC enables (default 0x00 = pass-through)
+    """
+    n_frames = frames.shape[0]
+
+    # Output arrays
+    out_gain_enc = np.zeros(n_frames, dtype=int)
+    out_gain_signed = np.zeros(n_frames, dtype=int)
+    out_peak_mag = np.zeros(n_frames, dtype=int)
+    out_sat_count = np.zeros(n_frames, dtype=int)
+    out_sat_rate = np.zeros(n_frames, dtype=float)
+    out_rms_post = np.zeros(n_frames, dtype=float)
+
+    # AGC state — managed by process_agc_frame()
+    state = AGCState(
+        gain=encoding_to_signed(initial_gain_enc),
+        holdoff_counter=0,
+        was_enabled=False,
+    )
+
+    for i in range(n_frames):
+        frame_i, frame_q = quantize_iq(frames[i])
+
+        agc_active = agc_enabled and (i >= enable_at_frame)
+
+        # Build per-frame config (enable toggles at enable_at_frame)
+        config = AGCConfig(enabled=agc_active)
+
+        result = process_agc_frame(frame_i, frame_q, config, state)
+
+        # RMS of shifted signal
+        rms = float(np.sqrt(np.mean(
+            result.shifted_i.astype(np.float64)**2
+            + result.shifted_q.astype(np.float64)**2)))
+
+        total_samples = frame_i.size + frame_q.size
+        sat_rate = result.overflow_raw / total_samples if total_samples > 0 else 0.0
+
+        # Record outputs
+        out_gain_enc[i] = result.gain_enc
+        out_gain_signed[i] = result.gain_signed
+        out_peak_mag[i] = result.peak_mag_8bit
+        out_sat_count[i] = result.saturation_count
+        out_sat_rate[i] = sat_rate
+        out_rms_post[i] = rms
+
+    return {
+        "gain_enc": out_gain_enc,
+        "gain_signed": out_gain_signed,
+        "peak_mag": out_peak_mag,
+        "sat_count": out_sat_count,
+        "sat_rate": out_sat_rate,
+        "rms_post": out_rms_post,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Range-Doppler processing for heatmap display
+# ---------------------------------------------------------------------------
+
+def process_frame_rd(frame: np.ndarray, gain_enc: int,
+                     n_range: int = 64,
+                     n_doppler: int = 32) -> np.ndarray:
+    """Range-Doppler magnitude for one frame with gain applied."""
+    frame_i, frame_q = quantize_iq(frame)
+    si, sq, _ = apply_gain_shift(frame_i, frame_q, gain_enc)
+
+    iq = si.astype(np.float64) + 1j * sq.astype(np.float64)
+    n_chirps, _ = iq.shape
+
+    range_fft = np.fft.fft(iq, axis=1)[:, :n_range]
+    doppler_fft = np.fft.fftshift(np.fft.fft(range_fft, axis=0), axes=0)
+    center = n_chirps // 2
+    half_d = n_doppler // 2
+    doppler_fft = doppler_fft[center - half_d:center + half_d, :]
+
+    rd_mag = np.abs(doppler_fft.real) + np.abs(doppler_fft.imag)
+    return rd_mag.T  # (n_range, n_doppler)
+
+
+# ---------------------------------------------------------------------------
+# Plotting
+# ---------------------------------------------------------------------------
+
+def plot_scenario(axes, data: np.ndarray, agc: dict, title: str,
+                  enable_frame: int = 0):
+    """Plot one AGC scenario across 5 axes."""
+    n = data.shape[0]
+    xs = np.arange(n)
+
+    # Range-Doppler heatmap
+    if enable_frame > 0 and enable_frame < n:
+        f_before = max(0, enable_frame - 1)
+        f_after = min(n - 1, n - 2)
+        rd_before = process_frame_rd(data[f_before], int(agc["gain_enc"][f_before]))
+        rd_after = process_frame_rd(data[f_after], int(agc["gain_enc"][f_after]))
+        combined = np.hstack([rd_before, rd_after])
+        im = axes[0].imshow(
+            20 * np.log10(combined + 1), aspect="auto", origin="lower",
+            cmap="inferno", interpolation="nearest")
+        axes[0].axvline(x=rd_before.shape[1] - 0.5, color="cyan",
+                        linewidth=2, linestyle="--")
+        axes[0].set_title(f"{title}\nL: f{f_before} (pre) | R: f{f_after} (post)")
+    else:
+        worst = int(np.argmax(agc["sat_count"]))
+        best = int(np.argmin(agc["sat_count"]))
+        f_show = worst if agc["sat_count"][worst] > 0 else best
+        rd = process_frame_rd(data[f_show], int(agc["gain_enc"][f_show]))
+        im = axes[0].imshow(
+            20 * np.log10(rd + 1), aspect="auto", origin="lower",
+            cmap="inferno", interpolation="nearest")
+        axes[0].set_title(f"{title}\nFrame {f_show}")
+
+    axes[0].set_xlabel("Doppler bin")
+    axes[0].set_ylabel("Range bin")
+    plt.colorbar(im, ax=axes[0], label="dB", shrink=0.8)
+
+    # Signed gain history (the real AGC state)
+    axes[1].plot(xs, agc["gain_signed"], color="#00ff88", linewidth=1.5)
+    axes[1].axhline(y=0, color="gray", linestyle=":", alpha=0.5,
+                    label="Pass-through")
+    if enable_frame > 0:
+        axes[1].axvline(x=enable_frame, color="yellow", linewidth=2,
+                        linestyle="--", label="AGC ON")
+    axes[1].set_ylim(-8, 8)
+    axes[1].set_ylabel("Gain (signed)")
+    axes[1].set_title("AGC Internal Gain (-7=max atten, +7=max amp)")
+    axes[1].legend(fontsize=7, loc="upper right")
+    axes[1].grid(True, alpha=0.3)
+
+    # Peak magnitude (PRE-gain, 8-bit)
+    axes[2].plot(xs, agc["peak_mag"], color="#ffaa00", linewidth=1.0)
+    axes[2].axhline(y=AGC_TARGET, color="cyan", linestyle="--",
+                    alpha=0.7, label=f"Target ({AGC_TARGET})")
+    axes[2].axhspan(240, 255, color="red", alpha=0.15, label="Clip zone")
+    if enable_frame > 0:
+        axes[2].axvline(x=enable_frame, color="yellow", linewidth=2,
+                        linestyle="--", alpha=0.8)
+    axes[2].set_ylim(0, 260)
+    axes[2].set_ylabel("Peak (8-bit)")
+    axes[2].set_title("Peak Magnitude (pre-gain, raw input)")
+    axes[2].legend(fontsize=7, loc="upper right")
+    axes[2].grid(True, alpha=0.3)
+
+    # Saturation count (POST-gain overflow)
+    axes[3].fill_between(xs, agc["sat_count"], color="red", alpha=0.4)
+    axes[3].plot(xs, agc["sat_count"], color="red", linewidth=0.8)
+    if enable_frame > 0:
+        axes[3].axvline(x=enable_frame, color="yellow", linewidth=2,
+                        linestyle="--", alpha=0.8)
+    axes[3].set_ylabel("Overflow Count")
+    total = int(agc["sat_count"].sum())
+    axes[3].set_title(f"Post-Gain Overflow (total={total})")
+    axes[3].grid(True, alpha=0.3)
+
+    # RMS signal level (post-gain)
+    axes[4].plot(xs, agc["rms_post"], color="#44aaff", linewidth=1.0)
+    if enable_frame > 0:
+        axes[4].axvline(x=enable_frame, color="yellow", linewidth=2,
+                        linestyle="--", alpha=0.8)
+    axes[4].set_ylabel("RMS")
+    axes[4].set_xlabel("Frame")
+    axes[4].set_title("Post-Gain RMS Level")
+    axes[4].grid(True, alpha=0.3)
+
+
+def analyze_dataset(data: np.ndarray, label: str):
+    """Run 3-scenario analysis for one dataset."""
+    n_frames = data.shape[0]
+    mid = n_frames // 2
+
+    print(f"\n{'='*60}")
+    print(f"  {label}  —  shape {data.shape}")
+    print(f"{'='*60}")
+
+    # Raw ADC stats
+    raw_sat = np.sum((np.abs(data.real) >= ADC_RAIL) |
+                     (np.abs(data.imag) >= ADC_RAIL))
+    print(f"  Raw ADC saturation: {raw_sat} samples "
+          f"({100*raw_sat/(2*data.size):.2f}%)")
+
+    # Scenario 1: AGC OFF — pass-through (gain_shift=0x00)
+    print("  [1/3] AGC OFF (gain=0, pass-through) ...")
+    agc_off = simulate_agc(data, agc_enabled=False, initial_gain_enc=0x00)
+    print(f"        Post-gain overflow: {agc_off['sat_count'].sum()} "
+          f"(should be 0 — no amplification)")
+
+    # Scenario 2: AGC ON from frame 0
+    print("  [2/3] AGC ON (from start) ...")
+    agc_on = simulate_agc(data, agc_enabled=True, enable_at_frame=0,
+                          initial_gain_enc=0x00)
+    print(f"        Final gain: {agc_on['gain_signed'][-1]} "
+          f"(enc=0x{agc_on['gain_enc'][-1]:X})")
+    print(f"        Post-gain overflow: {agc_on['sat_count'].sum()}")
+
+    # Scenario 3: AGC delayed
+    print(f"  [3/3] AGC delayed (ON at frame {mid}) ...")
+    agc_delayed = simulate_agc(data, agc_enabled=True,
+                               enable_at_frame=mid,
+                               initial_gain_enc=0x00)
+    pre_sat = int(agc_delayed["sat_count"][:mid].sum())
+    post_sat = int(agc_delayed["sat_count"][mid:].sum())
+    print(f"        Pre-AGC overflow: {pre_sat}  "
+          f"Post-AGC overflow: {post_sat}")
+
+    # Plot
+    fig, axes = plt.subplots(3, 5, figsize=(28, 14))
+    fig.suptitle(f"AERIS-10 AGC Analysis — {label}\n"
+                 f"({n_frames} frames, {data.shape[1]} chirps, "
+                 f"{data.shape[2]} samples/chirp, "
+                 f"raw ADC sat={100*raw_sat/(2*data.size):.2f}%)",
+                 fontsize=13, fontweight="bold", y=0.99)
+
+    plot_scenario(axes[0], data, agc_off, "AGC OFF (pass-through)")
+    plot_scenario(axes[1], data, agc_on, "AGC ON (from start)")
+    plot_scenario(axes[2], data, agc_delayed,
+                  f"AGC delayed (ON at frame {mid})", enable_frame=mid)
+
+    for ax, lbl in zip(axes[:, 0],
+                       ["AGC OFF", "AGC ON", "AGC DELAYED"],
+                       strict=True):
+        ax.annotate(lbl, xy=(-0.35, 0.5), xycoords="axes fraction",
+                    fontsize=13, fontweight="bold", color="white",
+                    ha="center", va="center", rotation=90)
+
+    plt.tight_layout(rect=[0.03, 0, 1, 0.95])
+    return fig
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="AGC analysis for ADI raw IQ captures "
+                    "(bit-accurate rx_gain_control.v simulation)")
+    parser.add_argument("--amp", type=str,
+                        default=str(Path.home() / "Downloads/adi_radar_data"
+                                    "/amp_radar"
+                                    "/phaser_amp_4MSPS_500M_300u_256_m3dB.npy"),
+                        help="Path to amplified radar .npy")
+    parser.add_argument("--noamp", type=str,
+                        default=str(Path.home() / "Downloads/adi_radar_data"
+                                    "/no_amp_radar"
+                                    "/phaser_NOamp_4MSPS_500M_300u_256.npy"),
+                        help="Path to non-amplified radar .npy")
+    parser.add_argument("--data", type=str, default=None,
+                        help="Single dataset mode")
+    parser.add_argument("--label", type=str, default="Custom Data")
+    args = parser.parse_args()
+
+    plt.style.use("dark_background")
+
+    if args.data:
+        data = np.load(args.data)
+        analyze_dataset(data, args.label)
+        plt.show()
+        return
+
+    figs = []
+    for path, label in [(args.amp, "With Amplifier (-3 dB)"),
+                        (args.noamp, "No Amplifier")]:
+        if not Path(path).exists():
+            print(f"WARNING: {path} not found, skipping")
+            continue
+        data = np.load(path)
+        fig = analyze_dataset(data, label)
+        figs.append(fig)
+
+    if not figs:
+        print("No data found. Use --amp/--noamp or --data.")
+        sys.exit(1)
+
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()

9_Firmware/9_3_GUI/radar_dashboard.py

@@ -1,708 +0,0 @@
-#!/usr/bin/env python3
-"""
-AERIS-10 Radar Dashboard
-===================================================
-Real-time visualization and control for the AERIS-10 phased-array radar
-via FT2232H USB 2.0 interface.
-
-Features:
-  - FT2232H USB reader with packet parsing (matches usb_data_interface_ft2232h.v)
-  - Real-time range-Doppler magnitude heatmap (64x32)
-  - CFAR detection overlay (flagged cells highlighted)
-  - Range profile waterfall plot (range vs. time)
-  - Host command sender (opcodes per radar_system_top.v:
-    0x01-0x04, 0x10-0x16, 0x20-0x27, 0x30-0x31, 0xFF)
-  - Configuration panel for all radar parameters
-  - HDF5 data recording for offline analysis
-  - Mock mode for development/testing without hardware
-
-Usage:
-  python radar_dashboard.py              # Launch with mock data
-  python radar_dashboard.py --live       # Launch with FT2232H hardware
-  python radar_dashboard.py --record     # Launch with HDF5 recording
-"""
-
-import os
-import time
-import queue
-import logging
-import argparse
-import threading
-import contextlib
-from collections import deque
-
-import numpy as np
-
-import tkinter as tk
-from tkinter import ttk, filedialog
-
-import matplotlib
-matplotlib.use("TkAgg")
-from matplotlib.figure import Figure
-from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg
-
-# Import protocol layer (no GUI deps)
-from radar_protocol import (
-    RadarProtocol, FT2232HConnection, ReplayConnection,
-    DataRecorder, RadarAcquisition,
-    RadarFrame, StatusResponse,
-    NUM_RANGE_BINS, NUM_DOPPLER_BINS, WATERFALL_DEPTH,
-)
-
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s [%(levelname)s] %(message)s",
-    datefmt="%H:%M:%S",
-)
-log = logging.getLogger("radar_dashboard")
-
-
-
-# ============================================================================
-# Dashboard GUI
-# ============================================================================
-
-# Dark theme colors
-BG = "#1e1e2e"
-BG2 = "#282840"
-FG = "#cdd6f4"
-ACCENT = "#89b4fa"
-GREEN = "#a6e3a1"
-RED = "#f38ba8"
-YELLOW = "#f9e2af"
-SURFACE = "#313244"
-
-
-class RadarDashboard:
-    """Main tkinter application: real-time radar visualization and control."""
-
-    UPDATE_INTERVAL_MS = 100  # 10 Hz display refresh
-
-    # Radar parameters used for range-axis scaling.
-    BANDWIDTH = 500e6        # Hz — chirp bandwidth
-    C = 3e8                  # m/s — speed of light
-
-    def __init__(self, root: tk.Tk, connection: FT2232HConnection,
-                 recorder: DataRecorder, device_index: int = 0):
-        self.root = root
-        self.conn = connection
-        self.recorder = recorder
-        self.device_index = device_index
-
-        self.root.title("AERIS-10 Radar Dashboard")
-        self.root.geometry("1600x950")
-        self.root.configure(bg=BG)
-
-        # Frame queue (acquisition → display)
-        self.frame_queue: queue.Queue[RadarFrame] = queue.Queue(maxsize=8)
-        self._acq_thread: RadarAcquisition | None = None
-
-        # Display state
-        self._current_frame = RadarFrame()
-        self._waterfall = deque(maxlen=WATERFALL_DEPTH)
-        for _ in range(WATERFALL_DEPTH):
-            self._waterfall.append(np.zeros(NUM_RANGE_BINS))
-
-        self._frame_count = 0
-        self._fps_ts = time.time()
-        self._fps = 0.0
-
-        # Stable colorscale — exponential moving average of vmax
-        self._vmax_ema = 1000.0
-        self._vmax_alpha = 0.15  # smoothing factor (lower = more stable)
-
-        self._build_ui()
-        self._schedule_update()
-
-    # ------------------------------------------------------------------ UI
-    def _build_ui(self):
-        style = ttk.Style()
-        style.theme_use("clam")
-        style.configure(".", background=BG, foreground=FG, fieldbackground=SURFACE)
-        style.configure("TFrame", background=BG)
-        style.configure("TLabel", background=BG, foreground=FG)
-        style.configure("TButton", background=SURFACE, foreground=FG)
-        style.configure("TLabelframe", background=BG, foreground=ACCENT)
-        style.configure("TLabelframe.Label", background=BG, foreground=ACCENT)
-        style.configure("Accent.TButton", background=ACCENT, foreground=BG)
-        style.configure("TNotebook", background=BG)
-        style.configure("TNotebook.Tab", background=SURFACE, foreground=FG,
-                         padding=[12, 4])
-        style.map("TNotebook.Tab", background=[("selected", ACCENT)],
-                  foreground=[("selected", BG)])
-
-        # Top bar
-        top = ttk.Frame(self.root)
-        top.pack(fill="x", padx=8, pady=(8, 0))
-
-        self.lbl_status = ttk.Label(top, text="DISCONNECTED", foreground=RED,
-                                     font=("Menlo", 11, "bold"))
-        self.lbl_status.pack(side="left", padx=8)
-
-        self.lbl_fps = ttk.Label(top, text="0.0 fps", font=("Menlo", 10))
-        self.lbl_fps.pack(side="left", padx=16)
-
-        self.lbl_detections = ttk.Label(top, text="Det: 0", font=("Menlo", 10))
-        self.lbl_detections.pack(side="left", padx=16)
-
-        self.lbl_frame = ttk.Label(top, text="Frame: 0", font=("Menlo", 10))
-        self.lbl_frame.pack(side="left", padx=16)
-
-        self.btn_connect = ttk.Button(top, text="Connect",
-                                       command=self._on_connect,
-                                       style="Accent.TButton")
-        self.btn_connect.pack(side="right", padx=4)
-
-        self.btn_record = ttk.Button(top, text="Record", command=self._on_record)
-        self.btn_record.pack(side="right", padx=4)
-
-        # -- Tabbed notebook layout --
-        nb = ttk.Notebook(self.root)
-        nb.pack(fill="both", expand=True, padx=8, pady=8)
-
-        tab_display = ttk.Frame(nb)
-        tab_control = ttk.Frame(nb)
-        tab_log = ttk.Frame(nb)
-        nb.add(tab_display, text="  Display  ")
-        nb.add(tab_control, text="  Control  ")
-        nb.add(tab_log, text="  Log  ")
-
-        self._build_display_tab(tab_display)
-        self._build_control_tab(tab_control)
-        self._build_log_tab(tab_log)
-
-    def _build_display_tab(self, parent):
-        # Compute physical axis limits
-        # Range resolution: dR = c / (2 * BW) per range bin
-        # But we decimate 1024→64 bins, so each bin spans 16 FFT bins.
-        # Range resolution derivation: c/(2*BW) gives ~0.3 m per FFT bin.
-        # After 1024-to-64 decimation each displayed range bin spans 16 FFT bins.
-        range_res = self.C / (2.0 * self.BANDWIDTH)  # ~0.3 m per FFT bin
-        # After decimation 1024→64, each range bin = 16 FFT bins
-        range_per_bin = range_res * 16
-        max_range = range_per_bin * NUM_RANGE_BINS
-
-        doppler_bin_lo = 0
-        doppler_bin_hi = NUM_DOPPLER_BINS
-
-        # Matplotlib figure with 3 subplots
-        self.fig = Figure(figsize=(14, 7), facecolor=BG)
-        self.fig.subplots_adjust(left=0.07, right=0.98, top=0.94, bottom=0.10,
-                                  wspace=0.30, hspace=0.35)
-
-        # Range-Doppler heatmap
-        self.ax_rd = self.fig.add_subplot(1, 3, (1, 2))
-        self.ax_rd.set_facecolor(BG2)
-        self._rd_img = self.ax_rd.imshow(
-            np.zeros((NUM_RANGE_BINS, NUM_DOPPLER_BINS)),
-            aspect="auto", cmap="inferno", origin="lower",
-            extent=[doppler_bin_lo, doppler_bin_hi, 0, max_range],
-            vmin=0, vmax=1000,
-        )
-        self.ax_rd.set_title("Range-Doppler Map", color=FG, fontsize=12)
-        self.ax_rd.set_xlabel("Doppler Bin (0-15: long PRI, 16-31: short PRI)", color=FG)
-        self.ax_rd.set_ylabel("Range (m)", color=FG)
-        self.ax_rd.tick_params(colors=FG)
-
-        # Save axis limits for coordinate conversions
-        self._max_range = max_range
-        self._range_per_bin = range_per_bin
-
-        # CFAR detection overlay (scatter)
-        self._det_scatter = self.ax_rd.scatter([], [], s=30, c=GREEN,
-                                                marker="x", linewidths=1.5,
-                                                zorder=5, label="CFAR Det")
-
-        # Waterfall plot (range profile vs time)
-        self.ax_wf = self.fig.add_subplot(1, 3, 3)
-        self.ax_wf.set_facecolor(BG2)
-        wf_init = np.zeros((WATERFALL_DEPTH, NUM_RANGE_BINS))
-        self._wf_img = self.ax_wf.imshow(
-            wf_init, aspect="auto", cmap="viridis", origin="lower",
-            extent=[0, max_range, 0, WATERFALL_DEPTH],
-            vmin=0, vmax=5000,
-        )
-        self.ax_wf.set_title("Range Waterfall", color=FG, fontsize=12)
-        self.ax_wf.set_xlabel("Range (m)", color=FG)
-        self.ax_wf.set_ylabel("Frame", color=FG)
-        self.ax_wf.tick_params(colors=FG)
-
-        canvas = FigureCanvasTkAgg(self.fig, master=parent)
-        canvas.draw()
-        canvas.get_tk_widget().pack(fill="both", expand=True)
-        self._canvas = canvas
-
-    def _build_control_tab(self, parent):
-        """Host command sender — organized by FPGA register groups.
-
-        Layout: scrollable canvas with three columns:
-          Left:   Quick Actions + Diagnostics (self-test)
-          Center: Waveform Timing + Signal Processing
-          Right:  Detection (CFAR) + Custom Command
-        """
-        # Scrollable wrapper for small screens
-        canvas = tk.Canvas(parent, bg=BG, highlightthickness=0)
-        scrollbar = ttk.Scrollbar(parent, orient="vertical", command=canvas.yview)
-        outer = ttk.Frame(canvas)
-        outer.bind("<Configure>",
-                   lambda _e: canvas.configure(scrollregion=canvas.bbox("all")))
-        canvas.create_window((0, 0), window=outer, anchor="nw")
-        canvas.configure(yscrollcommand=scrollbar.set)
-        canvas.pack(side="left", fill="both", expand=True, padx=8, pady=8)
-        scrollbar.pack(side="right", fill="y")
-
-        self._param_vars: dict[str, tk.StringVar] = {}
-
-        # ── Left column: Quick Actions + Diagnostics ──────────────────
-        left = ttk.Frame(outer)
-        left.grid(row=0, column=0, sticky="nsew", padx=(0, 6))
-
-        # -- Radar Operation --
-        grp_op = ttk.LabelFrame(left, text="Radar Operation", padding=10)
-        grp_op.pack(fill="x", pady=(0, 8))
-
-        ttk.Button(grp_op, text="Radar Mode On",
-                   command=lambda: self._send_cmd(0x01, 1)).pack(fill="x", pady=2)
-        ttk.Button(grp_op, text="Radar Mode Off",
-                   command=lambda: self._send_cmd(0x01, 0)).pack(fill="x", pady=2)
-        ttk.Button(grp_op, text="Trigger Chirp",
-                   command=lambda: self._send_cmd(0x02, 1)).pack(fill="x", pady=2)
-
-        # Stream Control (3-bit mask)
-        sc_row = ttk.Frame(grp_op)
-        sc_row.pack(fill="x", pady=2)
-        ttk.Label(sc_row, text="Stream Control").pack(side="left")
-        var_sc = tk.StringVar(value="7")
-        self._param_vars["4"] = var_sc
-        ttk.Entry(sc_row, textvariable=var_sc, width=6).pack(side="left", padx=6)
-        ttk.Label(sc_row, text="0-7", foreground=ACCENT,
-                  font=("Menlo", 9)).pack(side="left")
-        ttk.Button(sc_row, text="Set",
-                   command=lambda: self._send_validated(
-                       0x04, var_sc, bits=3)).pack(side="right")
-
-        ttk.Button(grp_op, text="Request Status",
-                   command=lambda: self._send_cmd(0xFF, 0)).pack(fill="x", pady=2)
-
-        # -- Signal Processing --
-        grp_sp = ttk.LabelFrame(left, text="Signal Processing", padding=10)
-        grp_sp.pack(fill="x", pady=(0, 8))
-
-        sp_params = [
-            # Format: label, opcode, default, bits, hint
-            ("Detect Threshold",  0x03, "10000", 16, "0-65535"),
-            ("Gain Shift",        0x16, "0",     4,  "0-15, dir+shift"),
-            ("MTI Enable",        0x26, "0",     1,  "0=off, 1=on"),
-            ("DC Notch Width",    0x27, "0",     3,  "0-7 bins"),
-        ]
-        for label, opcode, default, bits, hint in sp_params:
-            self._add_param_row(grp_sp, label, opcode, default, bits, hint)
-
-        # MTI quick toggle
-        mti_row = ttk.Frame(grp_sp)
-        mti_row.pack(fill="x", pady=2)
-        ttk.Button(mti_row, text="Enable MTI",
-                   command=lambda: self._send_cmd(0x26, 1)).pack(
-                       side="left", expand=True, fill="x", padx=(0, 2))
-        ttk.Button(mti_row, text="Disable MTI",
-                   command=lambda: self._send_cmd(0x26, 0)).pack(
-                       side="left", expand=True, fill="x", padx=(2, 0))
-
-        # -- Diagnostics --
-        grp_diag = ttk.LabelFrame(left, text="Diagnostics", padding=10)
-        grp_diag.pack(fill="x", pady=(0, 8))
-
-        ttk.Button(grp_diag, text="Run Self-Test",
-                   command=lambda: self._send_cmd(0x30, 1)).pack(fill="x", pady=2)
-        ttk.Button(grp_diag, text="Read Self-Test Result",
-                   command=lambda: self._send_cmd(0x31, 0)).pack(fill="x", pady=2)
-
-        st_frame = ttk.LabelFrame(grp_diag, text="Self-Test Results", padding=6)
-        st_frame.pack(fill="x", pady=(4, 0))
-        self._st_labels = {}
-        for name, default_text in [
-            ("busy", "Busy: --"),
-            ("flags", "Flags: -----"),
-            ("detail", "Detail: 0x--"),
-            ("t0", "T0 BRAM: --"),
-            ("t1", "T1 CIC:  --"),
-            ("t2", "T2 FFT:  --"),
-            ("t3", "T3 Arith: --"),
-            ("t4", "T4 ADC:  --"),
-        ]:
-            lbl = ttk.Label(st_frame, text=default_text, font=("Menlo", 9))
-            lbl.pack(anchor="w")
-            self._st_labels[name] = lbl
-
-        # ── Center column: Waveform Timing ────────────────────────────
-        center = ttk.Frame(outer)
-        center.grid(row=0, column=1, sticky="nsew", padx=6)
-
-        grp_wf = ttk.LabelFrame(center, text="Waveform Timing", padding=10)
-        grp_wf.pack(fill="x", pady=(0, 8))
-
-        wf_params = [
-            ("Long Chirp Cycles",   0x10, "3000",  16, "0-65535, rst=3000"),
-            ("Long Listen Cycles",  0x11, "13700", 16, "0-65535, rst=13700"),
-            ("Guard Cycles",        0x12, "17540", 16, "0-65535, rst=17540"),
-            ("Short Chirp Cycles",  0x13, "50",    16, "0-65535, rst=50"),
-            ("Short Listen Cycles", 0x14, "17450", 16, "0-65535, rst=17450"),
-            ("Chirps Per Elevation", 0x15, "32",    6, "1-32, clamped"),
-        ]
-        for label, opcode, default, bits, hint in wf_params:
-            self._add_param_row(grp_wf, label, opcode, default, bits, hint)
-
-        # ── Right column: Detection (CFAR) + Custom ───────────────────
-        right = ttk.Frame(outer)
-        right.grid(row=0, column=2, sticky="nsew", padx=(6, 0))
-
-        grp_cfar = ttk.LabelFrame(right, text="Detection (CFAR)", padding=10)
-        grp_cfar.pack(fill="x", pady=(0, 8))
-
-        cfar_params = [
-            ("CFAR Enable",       0x25, "0",  1,  "0=off, 1=on"),
-            ("CFAR Guard Cells",  0x21, "2",  4,  "0-15, rst=2"),
-            ("CFAR Train Cells",  0x22, "8",  5,  "1-31, rst=8"),
-            ("CFAR Alpha (Q4.4)", 0x23, "48", 8,  "0-255, rst=0x30=3.0"),
-            ("CFAR Mode",         0x24, "0",  2,  "0=CA 1=GO 2=SO"),
-        ]
-        for label, opcode, default, bits, hint in cfar_params:
-            self._add_param_row(grp_cfar, label, opcode, default, bits, hint)
-
-        # CFAR quick toggle
-        cfar_row = ttk.Frame(grp_cfar)
-        cfar_row.pack(fill="x", pady=2)
-        ttk.Button(cfar_row, text="Enable CFAR",
-                   command=lambda: self._send_cmd(0x25, 1)).pack(
-                       side="left", expand=True, fill="x", padx=(0, 2))
-        ttk.Button(cfar_row, text="Disable CFAR",
-                   command=lambda: self._send_cmd(0x25, 0)).pack(
-                       side="left", expand=True, fill="x", padx=(2, 0))
-
-        # ── Custom Command (advanced / debug) ─────────────────────────
-        grp_cust = ttk.LabelFrame(right, text="Custom Command", padding=10)
-        grp_cust.pack(fill="x", pady=(0, 8))
-
-        r0 = ttk.Frame(grp_cust)
-        r0.pack(fill="x", pady=2)
-        ttk.Label(r0, text="Opcode (hex)").pack(side="left")
-        self._custom_op = tk.StringVar(value="01")
-        ttk.Entry(r0, textvariable=self._custom_op, width=8).pack(
-            side="left", padx=6)
-
-        r1 = ttk.Frame(grp_cust)
-        r1.pack(fill="x", pady=2)
-        ttk.Label(r1, text="Value (dec)").pack(side="left")
-        self._custom_val = tk.StringVar(value="0")
-        ttk.Entry(r1, textvariable=self._custom_val, width=8).pack(
-            side="left", padx=6)
-
-        ttk.Button(grp_cust, text="Send",
-                   command=self._send_custom).pack(fill="x", pady=2)
-
-        # Column weights
-        outer.columnconfigure(0, weight=1)
-        outer.columnconfigure(1, weight=1)
-        outer.columnconfigure(2, weight=1)
-        outer.rowconfigure(0, weight=1)
-
-    def _add_param_row(self, parent, label: str, opcode: int,
-                       default: str, bits: int, hint: str):
-        """Add a single parameter row: label, entry, hint, Set button with validation."""
-        row = ttk.Frame(parent)
-        row.pack(fill="x", pady=2)
-        ttk.Label(row, text=label).pack(side="left")
-        var = tk.StringVar(value=default)
-        self._param_vars[str(opcode)] = var
-        ttk.Entry(row, textvariable=var, width=8).pack(side="left", padx=6)
-        ttk.Label(row, text=hint, foreground=ACCENT,
-                  font=("Menlo", 9)).pack(side="left")
-        ttk.Button(row, text="Set",
-                   command=lambda: self._send_validated(
-                       opcode, var, bits=bits)).pack(side="right")
-
-    def _send_validated(self, opcode: int, var: tk.StringVar, bits: int):
-        """Parse, clamp to bit-width, send command, and update the entry."""
-        try:
-            raw = int(var.get())
-        except ValueError:
-            log.error(f"Invalid value for opcode 0x{opcode:02X}: {var.get()!r}")
-            return
-        max_val = (1 << bits) - 1
-        clamped = max(0, min(raw, max_val))
-        if clamped != raw:
-            log.warning(f"Value {raw} clamped to {clamped} "
-                        f"({bits}-bit max={max_val}) for opcode 0x{opcode:02X}")
-            var.set(str(clamped))
-        self._send_cmd(opcode, clamped)
-
-    def _build_log_tab(self, parent):
-        self.log_text = tk.Text(parent, bg=BG2, fg=FG, font=("Menlo", 10),
-                                 insertbackground=FG, wrap="word")
-        self.log_text.pack(fill="both", expand=True, padx=8, pady=8)
-
-        # Redirect log handler to text widget
-        handler = _TextHandler(self.log_text)
-        handler.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] %(message)s",
-                                                datefmt="%H:%M:%S"))
-        logging.getLogger().addHandler(handler)
-
-    # ------------------------------------------------------------ Actions
-    def _on_connect(self):
-        if self.conn.is_open:
-            # Disconnect
-            if self._acq_thread is not None:
-                self._acq_thread.stop()
-                self._acq_thread.join(timeout=2)
-                self._acq_thread = None
-            self.conn.close()
-            self.lbl_status.config(text="DISCONNECTED", foreground=RED)
-            self.btn_connect.config(text="Connect")
-            log.info("Disconnected")
-            return
-
-        # Open connection in a background thread to avoid blocking the GUI
-        self.lbl_status.config(text="CONNECTING...", foreground=YELLOW)
-        self.btn_connect.config(state="disabled")
-        self.root.update_idletasks()
-
-        def _do_connect():
-            ok = self.conn.open(self.device_index)
-            # Schedule UI update back on the main thread
-            self.root.after(0, lambda: self._on_connect_done(ok))
-
-        threading.Thread(target=_do_connect, daemon=True).start()
-
-    def _on_connect_done(self, success: bool):
-        """Called on main thread after connection attempt completes."""
-        self.btn_connect.config(state="normal")
-        if success:
-            self.lbl_status.config(text="CONNECTED", foreground=GREEN)
-            self.btn_connect.config(text="Disconnect")
-            self._acq_thread = RadarAcquisition(
-                self.conn, self.frame_queue, self.recorder,
-                status_callback=self._on_status_received)
-            self._acq_thread.start()
-            log.info("Connected and acquisition started")
-        else:
-            self.lbl_status.config(text="CONNECT FAILED", foreground=RED)
-            self.btn_connect.config(text="Connect")
-
-    def _on_record(self):
-        if self.recorder.recording:
-            self.recorder.stop()
-            self.btn_record.config(text="Record")
-            return
-
-        filepath = filedialog.asksaveasfilename(
-            defaultextension=".h5",
-            filetypes=[("HDF5", "*.h5"), ("All", "*.*")],
-            initialfile=f"radar_{time.strftime('%Y%m%d_%H%M%S')}.h5",
-        )
-        if filepath:
-            self.recorder.start(filepath)
-            self.btn_record.config(text="Stop Rec")
-
-    def _send_cmd(self, opcode: int, value: int):
-        cmd = RadarProtocol.build_command(opcode, value)
-        ok = self.conn.write(cmd)
-        log.info(f"CMD 0x{opcode:02X} val={value} ({'OK' if ok else 'FAIL'})")
-
-    def _send_custom(self):
-        try:
-            op = int(self._custom_op.get(), 16)
-            val = int(self._custom_val.get())
-            self._send_cmd(op, val)
-        except ValueError:
-            log.error("Invalid custom command values")
-
-    def _on_status_received(self, status: StatusResponse):
-        """Called from acquisition thread — schedule UI update on main thread."""
-        self.root.after(0, self._update_self_test_labels, status)
-
-    def _update_self_test_labels(self, status: StatusResponse):
-        """Update the self-test result labels from a StatusResponse."""
-        if not hasattr(self, '_st_labels'):
-            return
-        flags = status.self_test_flags
-        detail = status.self_test_detail
-        busy = status.self_test_busy
-
-        busy_str = "RUNNING" if busy else "IDLE"
-        busy_color = YELLOW if busy else FG
-        self._st_labels["busy"].config(text=f"Busy: {busy_str}",
-                                        foreground=busy_color)
-        self._st_labels["flags"].config(text=f"Flags: {flags:05b}")
-        self._st_labels["detail"].config(text=f"Detail: 0x{detail:02X}")
-
-        # Individual test results (bit = 1 means PASS)
-        test_names = [
-            ("t0", "T0 BRAM"),
-            ("t1", "T1 CIC"),
-            ("t2", "T2 FFT"),
-            ("t3", "T3 Arith"),
-            ("t4", "T4 ADC"),
-        ]
-        for i, (key, name) in enumerate(test_names):
-            if busy:
-                result_str = "..."
-                color = YELLOW
-            elif flags & (1 << i):
-                result_str = "PASS"
-                color = GREEN
-            else:
-                result_str = "FAIL"
-                color = RED
-            self._st_labels[key].config(
-                text=f"{name}: {result_str}", foreground=color)
-
-    # --------------------------------------------------------- Display loop
-    def _schedule_update(self):
-        self._update_display()
-        self.root.after(self.UPDATE_INTERVAL_MS, self._schedule_update)
-
-    def _update_display(self):
-        """Pull latest frame from queue and update plots."""
-        frame = None
-        # Drain queue, keep latest
-        while True:
-            try:
-                frame = self.frame_queue.get_nowait()
-            except queue.Empty:
-                break
-
-        if frame is None:
-            return
-
-        self._current_frame = frame
-        self._frame_count += 1
-
-        # FPS calculation
-        now = time.time()
-        dt = now - self._fps_ts
-        if dt > 0.5:
-            self._fps = self._frame_count / dt
-            self._frame_count = 0
-            self._fps_ts = now
-
-        # Update labels
-        self.lbl_fps.config(text=f"{self._fps:.1f} fps")
-        self.lbl_detections.config(text=f"Det: {frame.detection_count}")
-        self.lbl_frame.config(text=f"Frame: {frame.frame_number}")
-
-        # Update range-Doppler heatmap in raw dual-subframe bin order
-        mag = frame.magnitude
-        det_shifted = frame.detections
-
-        # Stable colorscale via EMA smoothing of vmax
-        frame_vmax = float(np.max(mag)) if np.max(mag) > 0 else 1.0
-        self._vmax_ema = (self._vmax_alpha * frame_vmax +
-                          (1.0 - self._vmax_alpha) * self._vmax_ema)
-        stable_vmax = max(self._vmax_ema, 1.0)
-
-        self._rd_img.set_data(mag)
-        self._rd_img.set_clim(vmin=0, vmax=stable_vmax)
-
-        # Update CFAR overlay in raw Doppler-bin coordinates
-        det_coords = np.argwhere(det_shifted > 0)
-        if len(det_coords) > 0:
-            # det_coords[:, 0] = range bin, det_coords[:, 1] = Doppler bin
-            range_m = (det_coords[:, 0] + 0.5) * self._range_per_bin
-            doppler_bins = det_coords[:, 1] + 0.5
-            offsets = np.column_stack([doppler_bins, range_m])
-            self._det_scatter.set_offsets(offsets)
-        else:
-            self._det_scatter.set_offsets(np.empty((0, 2)))
-
-        # Update waterfall
-        self._waterfall.append(frame.range_profile.copy())
-        wf_arr = np.array(list(self._waterfall))
-        wf_max = max(np.max(wf_arr), 1.0)
-        self._wf_img.set_data(wf_arr)
-        self._wf_img.set_clim(vmin=0, vmax=wf_max)
-
-        self._canvas.draw_idle()
-
-
-class _TextHandler(logging.Handler):
-    """Logging handler that writes to a tkinter Text widget."""
-
-    def __init__(self, text_widget: tk.Text):
-        super().__init__()
-        self._text = text_widget
-
-    def emit(self, record):
-        msg = self.format(record)
-        with contextlib.suppress(Exception):
-            self._text.after(0, self._append, msg)
-
-    def _append(self, msg: str):
-        self._text.insert("end", msg + "\n")
-        self._text.see("end")
-        # Keep last 500 lines
-        lines = int(self._text.index("end-1c").split(".")[0])
-        if lines > 500:
-            self._text.delete("1.0", f"{lines - 500}.0")
-
-
-# ============================================================================
-# Entry Point
-# ============================================================================
-
-def main():
-    parser = argparse.ArgumentParser(description="AERIS-10 Radar Dashboard")
-    parser.add_argument("--live", action="store_true",
-                        help="Use real FT2232H hardware (default: mock mode)")
-    parser.add_argument("--replay", type=str, metavar="NPY_DIR",
-                        help="Replay real data from .npy directory "
-                             "(e.g. tb/cosim/real_data/hex/)")
-    parser.add_argument("--no-mti", action="store_true",
-                        help="With --replay, use non-MTI Doppler data")
-    parser.add_argument("--record", action="store_true",
-                        help="Start HDF5 recording immediately")
-    parser.add_argument("--device", type=int, default=0,
-                        help="FT2232H device index (default: 0)")
-    args = parser.parse_args()
-
-    if args.replay:
-        npy_dir = os.path.abspath(args.replay)
-        conn = ReplayConnection(npy_dir, use_mti=not args.no_mti)
-        mode_str = f"REPLAY ({npy_dir}, MTI={'OFF' if args.no_mti else 'ON'})"
-    elif args.live:
-        conn = FT2232HConnection(mock=False)
-        mode_str = "LIVE"
-    else:
-        conn = FT2232HConnection(mock=True)
-        mode_str = "MOCK"
-
-    recorder = DataRecorder()
-
-    root = tk.Tk()
-
-    dashboard = RadarDashboard(root, conn, recorder, device_index=args.device)
-
-    if args.record:
-        filepath = os.path.join(
-            os.getcwd(),
-            f"radar_{time.strftime('%Y%m%d_%H%M%S')}.h5"
-        )
-        recorder.start(filepath)
-
-    def on_closing():
-        if dashboard._acq_thread is not None:
-            dashboard._acq_thread.stop()
-            dashboard._acq_thread.join(timeout=2)
-        if conn.is_open:
-            conn.close()
-        if recorder.recording:
-            recorder.stop()
-        root.destroy()
-
-    root.protocol("WM_DELETE_WINDOW", on_closing)
-
-    log.info(f"Dashboard started (mode={mode_str})")
-    root.mainloop()
-
-
-if __name__ == "__main__":
-    main()

9_Firmware/9_3_GUI/radar_protocol.py

@@ -15,7 +15,6 @@ USB Packet Protocol (11-byte):
     Command: 4 bytes received sequentially {opcode, addr, value_hi, value_lo}
 """
 
-import os
 import struct
 import time
 import threading
@@ -59,9 +58,9 @@ class Opcode(IntEnum):
         0x03  host_detect_threshold  0x16  host_gain_shift
         0x04  host_stream_control    0x20  host_range_mode
         0x10  host_long_chirp_cycles 0x21-0x27  CFAR / MTI / DC-notch
-        0x11  host_long_listen_cycles 0x30  host_self_test_trigger
-        0x12  host_guard_cycles      0x31  host_status_request
-        0x13  host_short_chirp_cycles 0xFF  host_status_request
+        0x11  host_long_listen_cycles 0x28-0x2C  AGC control
+        0x12  host_guard_cycles      0x30  host_self_test_trigger
+        0x13  host_short_chirp_cycles 0x31/0xFF  host_status_request
     """
     # --- Basic control (0x01-0x04) ---
     RADAR_MODE          = 0x01  # 2-bit mode select
@@ -90,6 +89,13 @@ class Opcode(IntEnum):
     MTI_ENABLE          = 0x26
     DC_NOTCH_WIDTH      = 0x27
 
+    # --- AGC (0x28-0x2C) ---
+    AGC_ENABLE          = 0x28
+    AGC_TARGET          = 0x29
+    AGC_ATTACK          = 0x2A
+    AGC_DECAY           = 0x2B
+    AGC_HOLDOFF         = 0x2C
+
     # --- Board self-test / status (0x30-0x31, 0xFF) ---
     SELF_TEST_TRIGGER   = 0x30
     SELF_TEST_STATUS    = 0x31
@@ -135,6 +141,11 @@ class StatusResponse:
     self_test_flags: int = 0     # 5-bit result flags [4:0]
     self_test_detail: int = 0    # 8-bit detail code [7:0]
     self_test_busy: int = 0      # 1-bit busy flag
+    # AGC metrics (word 4, added for hybrid AGC)
+    agc_current_gain: int = 0    # 4-bit current gain encoding [3:0]
+    agc_peak_magnitude: int = 0  # 8-bit peak magnitude [7:0]
+    agc_saturation_count: int = 0  # 8-bit saturation count [7:0]
+    agc_enable: int = 0          # 1-bit AGC enable readback
 
 
 # ============================================================================
@@ -232,8 +243,13 @@ class RadarProtocol:
         # Word 3: {short_listen[31:16], 10'd0, chirps_per_elev[5:0]}
         sr.chirps_per_elev = words[3] & 0x3F
         sr.short_listen = (words[3] >> 16) & 0xFFFF
-        # Word 4: {30'd0, range_mode[1:0]}
+        # Word 4: {agc_current_gain[31:28], agc_peak_magnitude[27:20],
+        #          agc_saturation_count[19:12], agc_enable[11], 9'd0, range_mode[1:0]}
         sr.range_mode = words[4] & 0x03
+        sr.agc_enable = (words[4] >> 11) & 0x01
+        sr.agc_saturation_count = (words[4] >> 12) & 0xFF
+        sr.agc_peak_magnitude = (words[4] >> 20) & 0xFF
+        sr.agc_current_gain = (words[4] >> 28) & 0x0F
         # Word 5: {7'd0, self_test_busy, 8'd0, self_test_detail[7:0],
         #           3'd0, self_test_flags[4:0]}
         sr.self_test_flags = words[5] & 0x1F
@@ -426,377 +442,7 @@ class FT2232HConnection:
         return bytes(buf)
 
 
-# ============================================================================
-# Replay Connection — feed real .npy data through the dashboard
-# ============================================================================
 
-# Hardware-only opcodes that cannot be adjusted in replay mode
-# Values must match radar_system_top.v case(usb_cmd_opcode).
-_HARDWARE_ONLY_OPCODES = {
-    0x01,  # RADAR_MODE
-    0x02,  # TRIGGER_PULSE
-    0x03,  # DETECT_THRESHOLD
-    0x04,  # STREAM_CONTROL
-    0x10,  # LONG_CHIRP
-    0x11,  # LONG_LISTEN
-    0x12,  # GUARD
-    0x13,  # SHORT_CHIRP
-    0x14,  # SHORT_LISTEN
-    0x15,  # CHIRPS_PER_ELEV
-    0x16,  # GAIN_SHIFT
-    0x20,  # RANGE_MODE
-    0x30,  # SELF_TEST_TRIGGER
-    0x31,  # SELF_TEST_STATUS
-    0xFF,  # STATUS_REQUEST
-}
-
-# Replay-adjustable opcodes (re-run signal processing)
-_REPLAY_ADJUSTABLE_OPCODES = {
-    0x21,  # CFAR_GUARD
-    0x22,  # CFAR_TRAIN
-    0x23,  # CFAR_ALPHA
-    0x24,  # CFAR_MODE
-    0x25,  # CFAR_ENABLE
-    0x26,  # MTI_ENABLE
-    0x27,  # DC_NOTCH_WIDTH
-}
-
-
-def _saturate(val: int, bits: int) -> int:
-    """Saturate signed value to fit in 'bits' width."""
-    max_pos = (1 << (bits - 1)) - 1
-    max_neg = -(1 << (bits - 1))
-    return max(max_neg, min(max_pos, int(val)))
-
-
-def _replay_dc_notch(doppler_i: np.ndarray, doppler_q: np.ndarray,
-                     width: int) -> tuple[np.ndarray, np.ndarray]:
-    """Bit-accurate DC notch filter (matches radar_system_top.v inline).
-
-    Dual sub-frame notch: doppler_bin[4:0] = {sub_frame, bin[3:0]}.
-    Each 16-bin sub-frame has its own DC at bin 0, so we zero bins
-    where ``bin_within_sf < width`` or ``bin_within_sf > (15 - width + 1)``.
-    """
-    out_i = doppler_i.copy()
-    out_q = doppler_q.copy()
-    if width == 0:
-        return out_i, out_q
-    n_doppler = doppler_i.shape[1]
-    for dbin in range(n_doppler):
-        bin_within_sf = dbin & 0xF
-        if bin_within_sf < width or bin_within_sf > (15 - width + 1):
-            out_i[:, dbin] = 0
-            out_q[:, dbin] = 0
-    return out_i, out_q
-
-
-def _replay_cfar(doppler_i: np.ndarray, doppler_q: np.ndarray,
-                 guard: int, train: int, alpha_q44: int,
-                 mode: int) -> tuple[np.ndarray, np.ndarray]:
-    """
-    Bit-accurate CA-CFAR detector (matches cfar_ca.v).
-    Returns (detect_flags, magnitudes) both (64, 32).
-    """
-    ALPHA_FRAC_BITS = 4
-    n_range, n_doppler = doppler_i.shape
-    if train == 0:
-        train = 1
-
-    # Compute magnitudes: |I| + |Q| (17-bit unsigned L1 norm)
-    magnitudes = np.zeros((n_range, n_doppler), dtype=np.int64)
-    for r in range(n_range):
-        for d in range(n_doppler):
-            i_val = int(doppler_i[r, d])
-            q_val = int(doppler_q[r, d])
-            abs_i = (-i_val) & 0xFFFF if i_val < 0 else i_val & 0xFFFF
-            abs_q = (-q_val) & 0xFFFF if q_val < 0 else q_val & 0xFFFF
-            magnitudes[r, d] = abs_i + abs_q
-
-    detect_flags = np.zeros((n_range, n_doppler), dtype=np.bool_)
-    MAX_MAG = (1 << 17) - 1
-
-    mode_names = {0: 'CA', 1: 'GO', 2: 'SO'}
-    mode_str = mode_names.get(mode, 'CA')
-
-    for dbin in range(n_doppler):
-        col = magnitudes[:, dbin]
-        for cut in range(n_range):
-            lead_sum, lead_cnt = 0, 0
-            for t in range(1, train + 1):
-                idx = cut - guard - t
-                if 0 <= idx < n_range:
-                    lead_sum += int(col[idx])
-                    lead_cnt += 1
-            lag_sum, lag_cnt = 0, 0
-            for t in range(1, train + 1):
-                idx = cut + guard + t
-                if 0 <= idx < n_range:
-                    lag_sum += int(col[idx])
-                    lag_cnt += 1
-
-            if mode_str == 'CA':
-                noise = lead_sum + lag_sum
-            elif mode_str == 'GO':
-                if lead_cnt > 0 and lag_cnt > 0:
-                    noise = lead_sum if lead_sum * lag_cnt > lag_sum * lead_cnt else lag_sum
-                else:
-                    noise = lead_sum if lead_cnt > 0 else lag_sum
-            elif mode_str == 'SO':
-                if lead_cnt > 0 and lag_cnt > 0:
-                    noise = lead_sum if lead_sum * lag_cnt < lag_sum * lead_cnt else lag_sum
-                else:
-                    noise = lead_sum if lead_cnt > 0 else lag_sum
-            else:
-                noise = lead_sum + lag_sum
-
-            thr = min((alpha_q44 * noise) >> ALPHA_FRAC_BITS, MAX_MAG)
-            if int(col[cut]) > thr:
-                detect_flags[cut, dbin] = True
-
-    return detect_flags, magnitudes
-
-
-class ReplayConnection:
-    """
-    Loads pre-computed .npy arrays (from golden_reference.py co-sim output)
-    and serves them as USB data packets to the dashboard, exercising the full
-    parsing pipeline with real ADI CN0566 radar data.
-
-    Signal processing parameters (CFAR guard/train/alpha/mode, MTI enable,
-    DC notch width) can be adjusted at runtime via write() — the connection
-    re-runs the bit-accurate processing pipeline and rebuilds packets.
-
-    Required npy directory layout (e.g. tb/cosim/real_data/hex/):
-      decimated_range_i.npy       (32, 64) int   — pre-Doppler range I
-      decimated_range_q.npy       (32, 64) int   — pre-Doppler range Q
-      doppler_map_i.npy           (64, 32) int   — Doppler I  (no MTI)
-      doppler_map_q.npy           (64, 32) int   — Doppler Q  (no MTI)
-      fullchain_mti_doppler_i.npy (64, 32) int   — Doppler I  (with MTI)
-      fullchain_mti_doppler_q.npy (64, 32) int   — Doppler Q  (with MTI)
-      fullchain_cfar_flags.npy    (64, 32) bool  — CFAR detections
-      fullchain_cfar_mag.npy      (64, 32) int   — CFAR |I|+|Q| magnitude
-    """
-
-    def __init__(self, npy_dir: str, use_mti: bool = True,
-                 replay_fps: float = 5.0):
-        self._npy_dir = npy_dir
-        self._use_mti = use_mti
-        self._replay_fps = max(replay_fps, 0.1)
-        self._lock = threading.Lock()
-        self.is_open = False
-        self._packets: bytes = b""
-        self._read_offset = 0
-        self._frame_len = 0
-        # Current signal-processing parameters
-        self._mti_enable: bool = use_mti
-        self._dc_notch_width: int = 2
-        self._cfar_guard: int = 2
-        self._cfar_train: int = 8
-        self._cfar_alpha: int = 0x30
-        self._cfar_mode: int = 0  # 0=CA, 1=GO, 2=SO
-        self._cfar_enable: bool = True
-        # Raw source arrays (loaded once, reprocessed on param change)
-        self._dop_mti_i: np.ndarray | None = None
-        self._dop_mti_q: np.ndarray | None = None
-        self._dop_nomti_i: np.ndarray | None = None
-        self._dop_nomti_q: np.ndarray | None = None
-        self._range_i_vec: np.ndarray | None = None
-        self._range_q_vec: np.ndarray | None = None
-        # Rebuild flag
-        self._needs_rebuild = False
-
-    def open(self, _device_index: int = 0) -> bool:
-        try:
-            self._load_arrays()
-            self._packets = self._build_packets()
-            self._frame_len = len(self._packets)
-            self._read_offset = 0
-            self.is_open = True
-            log.info(f"Replay connection opened: {self._npy_dir} "
-                     f"(MTI={'ON' if self._mti_enable else 'OFF'}, "
-                     f"{self._frame_len} bytes/frame)")
-            return True
-        except (OSError, ValueError, struct.error) as e:
-            log.error(f"Replay open failed: {e}")
-            return False
-
-    def close(self):
-        self.is_open = False
-
-    def read(self, size: int = 4096) -> bytes | None:
-        if not self.is_open:
-            return None
-        # Pace reads to target FPS (spread across ~64 reads per frame)
-        time.sleep((1.0 / self._replay_fps) / (NUM_CELLS / 32))
-        with self._lock:
-            # If params changed, rebuild packets
-            if self._needs_rebuild:
-                self._packets = self._build_packets()
-                self._frame_len = len(self._packets)
-                self._read_offset = 0
-                self._needs_rebuild = False
-            end = self._read_offset + size
-            if end <= self._frame_len:
-                chunk = self._packets[self._read_offset:end]
-                self._read_offset = end
-            else:
-                chunk = self._packets[self._read_offset:]
-                self._read_offset = 0
-            return chunk
-
-    def write(self, data: bytes) -> bool:
-        """
-        Handle host commands in replay mode.
-        Signal-processing params (CFAR, MTI, DC notch) trigger re-processing.
-        Hardware-only params are silently ignored.
-        """
-        if len(data) < 4:
-            return True
-        word = struct.unpack(">I", data[:4])[0]
-        opcode = (word >> 24) & 0xFF
-        value = word & 0xFFFF
-
-        if opcode in _REPLAY_ADJUSTABLE_OPCODES:
-            changed = False
-            with self._lock:
-                if opcode == 0x21:  # CFAR_GUARD
-                    if self._cfar_guard != value:
-                        self._cfar_guard = value
-                        changed = True
-                elif opcode == 0x22:  # CFAR_TRAIN
-                    if self._cfar_train != value:
-                        self._cfar_train = value
-                        changed = True
-                elif opcode == 0x23:  # CFAR_ALPHA
-                    if self._cfar_alpha != value:
-                        self._cfar_alpha = value
-                        changed = True
-                elif opcode == 0x24:  # CFAR_MODE
-                    if self._cfar_mode != value:
-                        self._cfar_mode = value
-                        changed = True
-                elif opcode == 0x25:  # CFAR_ENABLE
-                    new_en = bool(value)
-                    if self._cfar_enable != new_en:
-                        self._cfar_enable = new_en
-                        changed = True
-                elif opcode == 0x26:  # MTI_ENABLE
-                    new_en = bool(value)
-                    if self._mti_enable != new_en:
-                        self._mti_enable = new_en
-                        changed = True
-                elif opcode == 0x27 and self._dc_notch_width != value:  # DC_NOTCH_WIDTH
-                    self._dc_notch_width = value
-                    changed = True
-                if changed:
-                    self._needs_rebuild = True
-            if changed:
-                log.info(f"Replay param updated: opcode=0x{opcode:02X} "
-                         f"value={value} — will re-process")
-            else:
-                log.debug(f"Replay param unchanged: opcode=0x{opcode:02X} "
-                          f"value={value}")
-        elif opcode in _HARDWARE_ONLY_OPCODES:
-            log.debug(f"Replay: hardware-only opcode 0x{opcode:02X} "
-                      f"(ignored in replay mode)")
-        else:
-            log.debug(f"Replay: unknown opcode 0x{opcode:02X} (ignored)")
-        return True
-
-    def _load_arrays(self):
-        """Load source npy arrays once."""
-        npy = self._npy_dir
-        # MTI Doppler
-        self._dop_mti_i = np.load(
-            os.path.join(npy, "fullchain_mti_doppler_i.npy")).astype(np.int64)
-        self._dop_mti_q = np.load(
-            os.path.join(npy, "fullchain_mti_doppler_q.npy")).astype(np.int64)
-        # Non-MTI Doppler
-        self._dop_nomti_i = np.load(
-            os.path.join(npy, "doppler_map_i.npy")).astype(np.int64)
-        self._dop_nomti_q = np.load(
-            os.path.join(npy, "doppler_map_q.npy")).astype(np.int64)
-        # Range data
-        try:
-            range_i_all = np.load(
-                os.path.join(npy, "decimated_range_i.npy")).astype(np.int64)
-            range_q_all = np.load(
-                os.path.join(npy, "decimated_range_q.npy")).astype(np.int64)
-            self._range_i_vec = range_i_all[-1, :]  # last chirp
-            self._range_q_vec = range_q_all[-1, :]
-        except FileNotFoundError:
-            self._range_i_vec = np.zeros(NUM_RANGE_BINS, dtype=np.int64)
-            self._range_q_vec = np.zeros(NUM_RANGE_BINS, dtype=np.int64)
-
-    def _build_packets(self) -> bytes:
-        """Build a full frame of USB data packets from current params."""
-        # Select Doppler data based on MTI
-        if self._mti_enable:
-            dop_i = self._dop_mti_i
-            dop_q = self._dop_mti_q
-        else:
-            dop_i = self._dop_nomti_i
-            dop_q = self._dop_nomti_q
-
-        # Apply DC notch
-        dop_i, dop_q = _replay_dc_notch(dop_i, dop_q, self._dc_notch_width)
-
-        # Run CFAR
-        if self._cfar_enable:
-            det, _mag = _replay_cfar(
-                dop_i, dop_q,
-                guard=self._cfar_guard,
-                train=self._cfar_train,
-                alpha_q44=self._cfar_alpha,
-                mode=self._cfar_mode,
-            )
-        else:
-            det = np.zeros((NUM_RANGE_BINS, NUM_DOPPLER_BINS), dtype=bool)
-
-        det_count = int(det.sum())
-        log.info(f"Replay: rebuilt {NUM_CELLS} packets ("
-                 f"MTI={'ON' if self._mti_enable else 'OFF'}, "
-                 f"DC_notch={self._dc_notch_width}, "
-                 f"CFAR={'ON' if self._cfar_enable else 'OFF'} "
-                 f"G={self._cfar_guard} T={self._cfar_train} "
-                 f"a=0x{self._cfar_alpha:02X} m={self._cfar_mode}, "
-                 f"{det_count} detections)")
-
-        range_i = self._range_i_vec
-        range_q = self._range_q_vec
-
-        return self._build_packets_data(range_i, range_q, dop_i, dop_q, det)
-
-    def _build_packets_data(self, range_i, range_q, dop_i, dop_q, det) -> bytes:
-        """Build 11-byte data packets for FT2232H interface."""
-        buf = bytearray(NUM_CELLS * DATA_PACKET_SIZE)
-        pos = 0
-        for rbin in range(NUM_RANGE_BINS):
-            ri = int(np.clip(range_i[rbin], -32768, 32767))
-            rq = int(np.clip(range_q[rbin], -32768, 32767))
-            rq_bytes = struct.pack(">h", rq)
-            ri_bytes = struct.pack(">h", ri)
-            for dbin in range(NUM_DOPPLER_BINS):
-                di = int(np.clip(dop_i[rbin, dbin], -32768, 32767))
-                dq = int(np.clip(dop_q[rbin, dbin], -32768, 32767))
-                d = 1 if det[rbin, dbin] else 0
-
-                buf[pos] = HEADER_BYTE
-                pos += 1
-                buf[pos:pos+2] = rq_bytes
-                pos += 2
-                buf[pos:pos+2] = ri_bytes
-                pos += 2
-                buf[pos:pos+2] = struct.pack(">h", di)
-                pos += 2
-                buf[pos:pos+2] = struct.pack(">h", dq)
-                pos += 2
-                buf[pos] = d
-                pos += 1
-                buf[pos] = FOOTER_BYTE
-                pos += 1
-
-        return bytes(buf)
 
 
 # ============================================================================

9_Firmware/9_3_GUI/test_GUI_V65_Tk.py

@@ -3,8 +3,8 @@
 Tests for AERIS-10 Radar Dashboard protocol parsing, command building,
 data recording, and acquisition logic.
 
-Run: python -m pytest test_radar_dashboard.py -v
-  or: python test_radar_dashboard.py
+Run: python -m pytest test_GUI_V65_Tk.py -v
+  or: python test_GUI_V65_Tk.py
 """
 
 import struct
@@ -19,10 +19,10 @@ from radar_protocol import (
     RadarProtocol, FT2232HConnection, DataRecorder, RadarAcquisition,
     RadarFrame, StatusResponse, Opcode,
     HEADER_BYTE, FOOTER_BYTE, STATUS_HEADER_BYTE,
-    NUM_RANGE_BINS, NUM_DOPPLER_BINS, NUM_CELLS,
+    NUM_RANGE_BINS, NUM_DOPPLER_BINS,
     DATA_PACKET_SIZE,
-    _HARDWARE_ONLY_OPCODES,
 )
+from GUI_V65_Tk import DemoTarget, DemoSimulator, _ReplayController
 
 
 class TestRadarProtocol(unittest.TestCase):
@@ -125,7 +125,8 @@ class TestRadarProtocol(unittest.TestCase):
                             long_chirp=3000, long_listen=13700,
                             guard=17540, short_chirp=50,
                             short_listen=17450, chirps=32, range_mode=0,
-                            st_flags=0, st_detail=0, st_busy=0):
+                            st_flags=0, st_detail=0, st_busy=0,
+                            agc_gain=0, agc_peak=0, agc_sat=0, agc_enable=0):
         """Build a 26-byte status response matching FPGA format (Build 26)."""
         pkt = bytearray()
         pkt.append(STATUS_HEADER_BYTE)
@@ -146,8 +147,11 @@ class TestRadarProtocol(unittest.TestCase):
         w3 = ((short_listen & 0xFFFF) << 16) | (chirps & 0x3F)
         pkt += struct.pack(">I", w3)
 
-        # Word 4: {30'd0, range_mode[1:0]}
-        w4 = range_mode & 0x03
+        # Word 4: {agc_current_gain[3:0], agc_peak_magnitude[7:0],
+        #          agc_saturation_count[7:0], agc_enable, 9'd0, range_mode[1:0]}
+        w4 = (((agc_gain & 0x0F) << 28) | ((agc_peak & 0xFF) << 20) |
+              ((agc_sat & 0xFF) << 12) | ((agc_enable & 0x01) << 11) |
+              (range_mode & 0x03))
         pkt += struct.pack(">I", w4)
 
         # Word 5: {7'd0, self_test_busy, 8'd0, self_test_detail[7:0],
@@ -455,218 +459,6 @@ class TestEndToEnd(unittest.TestCase):
         self.assertEqual(result["detection"], 1)
 
 
-class TestReplayConnection(unittest.TestCase):
-    """Test ReplayConnection with real .npy data files."""
-
-    NPY_DIR = os.path.join(
-        os.path.dirname(__file__), "..", "9_2_FPGA", "tb", "cosim",
-        "real_data", "hex"
-    )
-
-    def _npy_available(self):
-        """Check if the npy data files exist."""
-        return os.path.isfile(os.path.join(self.NPY_DIR,
-                                            "fullchain_mti_doppler_i.npy"))
-
-    def test_replay_open_close(self):
-        """ReplayConnection opens and closes without error."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        self.assertTrue(conn.open())
-        self.assertTrue(conn.is_open)
-        conn.close()
-        self.assertFalse(conn.is_open)
-
-    def test_replay_packet_count(self):
-        """Replay builds exactly NUM_CELLS (2048) packets."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # Each packet is 11 bytes, total = 2048 * 11
-        expected_bytes = NUM_CELLS * DATA_PACKET_SIZE
-        self.assertEqual(conn._frame_len, expected_bytes)
-        conn.close()
-
-    def test_replay_packets_parseable(self):
-        """Every packet from replay can be parsed by RadarProtocol."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        raw = conn._packets
-        boundaries = RadarProtocol.find_packet_boundaries(raw)
-        self.assertEqual(len(boundaries), NUM_CELLS)
-        parsed_count = 0
-        det_count = 0
-        for start, end, ptype in boundaries:
-            self.assertEqual(ptype, "data")
-            result = RadarProtocol.parse_data_packet(raw[start:end])
-            self.assertIsNotNone(result)
-            parsed_count += 1
-            if result["detection"]:
-                det_count += 1
-        self.assertEqual(parsed_count, NUM_CELLS)
-        # Default: MTI=ON, DC_notch=2, CFAR CA g=2 t=8 a=0x30 → 4 detections
-        self.assertEqual(det_count, 4)
-        conn.close()
-
-    def test_replay_read_loops(self):
-        """Read returns data and loops back around."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True, replay_fps=1000)
-        conn.open()
-        total_read = 0
-        for _ in range(100):
-            chunk = conn.read(1024)
-            self.assertIsNotNone(chunk)
-            total_read += len(chunk)
-        self.assertGreater(total_read, 0)
-        conn.close()
-
-    def test_replay_no_mti(self):
-        """ReplayConnection works with use_mti=False (CFAR still runs)."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=False)
-        conn.open()
-        self.assertEqual(conn._frame_len, NUM_CELLS * DATA_PACKET_SIZE)
-        # No-MTI with DC notch=2 and default CFAR → 0 detections
-        raw = conn._packets
-        boundaries = RadarProtocol.find_packet_boundaries(raw)
-        det_count = sum(1 for s, e, t in boundaries
-                        if RadarProtocol.parse_data_packet(raw[s:e]).get("detection", 0))
-        self.assertEqual(det_count, 0)
-        conn.close()
-
-    def test_replay_write_returns_true(self):
-        """Write on replay connection returns True."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR)
-        conn.open()
-        self.assertTrue(conn.write(b"\x01\x00\x00\x01"))
-        conn.close()
-
-    def test_replay_adjustable_param_cfar_guard(self):
-        """Changing CFAR guard via write() triggers re-processing."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # Initial: guard=2 → 4 detections
-        self.assertFalse(conn._needs_rebuild)
-        # Send CFAR_GUARD=4
-        cmd = RadarProtocol.build_command(0x21, 4)
-        conn.write(cmd)
-        self.assertTrue(conn._needs_rebuild)
-        self.assertEqual(conn._cfar_guard, 4)
-        # Read triggers rebuild
-        conn.read(1024)
-        self.assertFalse(conn._needs_rebuild)
-        conn.close()
-
-    def test_replay_adjustable_param_mti_toggle(self):
-        """Toggling MTI via write() triggers re-processing."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # Disable MTI
-        cmd = RadarProtocol.build_command(0x26, 0)
-        conn.write(cmd)
-        self.assertTrue(conn._needs_rebuild)
-        self.assertFalse(conn._mti_enable)
-        # Read to trigger rebuild, then count detections
-        # Drain all packets after rebuild
-        conn.read(1024)  # triggers rebuild
-        raw = conn._packets
-        boundaries = RadarProtocol.find_packet_boundaries(raw)
-        det_count = sum(1 for s, e, t in boundaries
-                        if RadarProtocol.parse_data_packet(raw[s:e]).get("detection", 0))
-        # No-MTI with default CFAR → 0 detections
-        self.assertEqual(det_count, 0)
-        conn.close()
-
-    def test_replay_adjustable_param_dc_notch(self):
-        """Changing DC notch width via write() triggers re-processing."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # Change DC notch to 0 (no notch)
-        cmd = RadarProtocol.build_command(0x27, 0)
-        conn.write(cmd)
-        self.assertTrue(conn._needs_rebuild)
-        self.assertEqual(conn._dc_notch_width, 0)
-        conn.read(1024)  # triggers rebuild
-        raw = conn._packets
-        boundaries = RadarProtocol.find_packet_boundaries(raw)
-        det_count = sum(1 for s, e, t in boundaries
-                        if RadarProtocol.parse_data_packet(raw[s:e]).get("detection", 0))
-        # DC notch=0 with MTI → 6 detections (more noise passes through)
-        self.assertEqual(det_count, 6)
-        conn.close()
-
-    def test_replay_hardware_opcode_ignored(self):
-        """Hardware-only opcodes don't trigger rebuild."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # Send TRIGGER (hardware-only)
-        cmd = RadarProtocol.build_command(0x01, 1)
-        conn.write(cmd)
-        self.assertFalse(conn._needs_rebuild)
-        # Send STREAM_CONTROL (hardware-only, opcode 0x04)
-        cmd = RadarProtocol.build_command(0x04, 7)
-        conn.write(cmd)
-        self.assertFalse(conn._needs_rebuild)
-        conn.close()
-
-    def test_replay_same_value_no_rebuild(self):
-        """Setting same value as current doesn't trigger rebuild."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # CFAR guard already 2
-        cmd = RadarProtocol.build_command(0x21, 2)
-        conn.write(cmd)
-        self.assertFalse(conn._needs_rebuild)
-        conn.close()
-
-    def test_replay_self_test_opcodes_are_hardware_only(self):
-        """Self-test opcodes 0x30/0x31 are hardware-only (ignored in replay)."""
-        if not self._npy_available():
-            self.skipTest("npy data files not found")
-        from radar_protocol import ReplayConnection
-        conn = ReplayConnection(self.NPY_DIR, use_mti=True)
-        conn.open()
-        # Send self-test trigger
-        cmd = RadarProtocol.build_command(0x30, 1)
-        conn.write(cmd)
-        self.assertFalse(conn._needs_rebuild)
-        # Send self-test status request
-        cmd = RadarProtocol.build_command(0x31, 0)
-        conn.write(cmd)
-        self.assertFalse(conn._needs_rebuild)
-        conn.close()
-
-
 class TestOpcodeEnum(unittest.TestCase):
     """Verify Opcode enum matches RTL host register map (radar_system_top.v)."""
 
@@ -686,15 +478,6 @@ class TestOpcodeEnum(unittest.TestCase):
         """SELF_TEST_STATUS opcode must be 0x31."""
         self.assertEqual(Opcode.SELF_TEST_STATUS, 0x31)
 
-    def test_self_test_in_hardware_only(self):
-        """Self-test opcodes must be in _HARDWARE_ONLY_OPCODES."""
-        self.assertIn(0x30, _HARDWARE_ONLY_OPCODES)
-        self.assertIn(0x31, _HARDWARE_ONLY_OPCODES)
-
-    def test_0x16_in_hardware_only(self):
-        """GAIN_SHIFT 0x16 must be in _HARDWARE_ONLY_OPCODES."""
-        self.assertIn(0x16, _HARDWARE_ONLY_OPCODES)
-
     def test_stream_control_is_0x04(self):
         """STREAM_CONTROL must be 0x04 (matches radar_system_top.v:906)."""
         self.assertEqual(Opcode.STREAM_CONTROL, 0x04)
@@ -713,16 +496,12 @@ class TestOpcodeEnum(unittest.TestCase):
         self.assertEqual(Opcode.DETECT_THRESHOLD, 0x03)
         self.assertEqual(Opcode.STREAM_CONTROL, 0x04)
 
-    def test_stale_opcodes_not_in_hardware_only(self):
-        """Old wrong opcode values must not be in _HARDWARE_ONLY_OPCODES."""
-        self.assertNotIn(0x05, _HARDWARE_ONLY_OPCODES)  # was wrong STREAM_ENABLE
-        self.assertNotIn(0x06, _HARDWARE_ONLY_OPCODES)  # was wrong GAIN_SHIFT
-
     def test_all_rtl_opcodes_present(self):
         """Every RTL opcode (from radar_system_top.v) has a matching Opcode enum member."""
         expected = {0x01, 0x02, 0x03, 0x04,
                     0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16,
                     0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
+                    0x28, 0x29, 0x2A, 0x2B, 0x2C,
                     0x30, 0x31, 0xFF}
         enum_values = {int(m) for m in Opcode}
         for op in expected:
@@ -747,5 +526,393 @@ class TestStatusResponseDefaults(unittest.TestCase):
         self.assertEqual(sr.self_test_busy, 1)
 
 
+class TestAGCOpcodes(unittest.TestCase):
+    """Verify AGC opcode enum members match FPGA RTL (0x28-0x2C)."""
+
+    def test_agc_enable_opcode(self):
+        self.assertEqual(Opcode.AGC_ENABLE, 0x28)
+
+    def test_agc_target_opcode(self):
+        self.assertEqual(Opcode.AGC_TARGET, 0x29)
+
+    def test_agc_attack_opcode(self):
+        self.assertEqual(Opcode.AGC_ATTACK, 0x2A)
+
+    def test_agc_decay_opcode(self):
+        self.assertEqual(Opcode.AGC_DECAY, 0x2B)
+
+    def test_agc_holdoff_opcode(self):
+        self.assertEqual(Opcode.AGC_HOLDOFF, 0x2C)
+
+
+class TestAGCStatusParsing(unittest.TestCase):
+    """Verify AGC fields in status_words[4] are parsed correctly."""
+
+    def _make_status_packet(self, **kwargs):
+        """Delegate to TestRadarProtocol helper."""
+        helper = TestRadarProtocol()
+        return helper._make_status_packet(**kwargs)
+
+    def test_agc_fields_default_zero(self):
+        """With no AGC fields set, all should be 0."""
+        raw = self._make_status_packet()
+        sr = RadarProtocol.parse_status_packet(raw)
+        self.assertEqual(sr.agc_current_gain, 0)
+        self.assertEqual(sr.agc_peak_magnitude, 0)
+        self.assertEqual(sr.agc_saturation_count, 0)
+        self.assertEqual(sr.agc_enable, 0)
+
+    def test_agc_fields_nonzero(self):
+        """AGC fields round-trip through status packet."""
+        raw = self._make_status_packet(agc_gain=7, agc_peak=200,
+                                       agc_sat=15, agc_enable=1)
+        sr = RadarProtocol.parse_status_packet(raw)
+        self.assertEqual(sr.agc_current_gain, 7)
+        self.assertEqual(sr.agc_peak_magnitude, 200)
+        self.assertEqual(sr.agc_saturation_count, 15)
+        self.assertEqual(sr.agc_enable, 1)
+
+    def test_agc_max_values(self):
+        """AGC fields at max values."""
+        raw = self._make_status_packet(agc_gain=15, agc_peak=255,
+                                       agc_sat=255, agc_enable=1)
+        sr = RadarProtocol.parse_status_packet(raw)
+        self.assertEqual(sr.agc_current_gain, 15)
+        self.assertEqual(sr.agc_peak_magnitude, 255)
+        self.assertEqual(sr.agc_saturation_count, 255)
+        self.assertEqual(sr.agc_enable, 1)
+
+    def test_agc_and_range_mode_coexist(self):
+        """AGC fields and range_mode occupy the same word without conflict."""
+        raw = self._make_status_packet(agc_gain=5, agc_peak=128,
+                                       agc_sat=42, agc_enable=1,
+                                       range_mode=2)
+        sr = RadarProtocol.parse_status_packet(raw)
+        self.assertEqual(sr.agc_current_gain, 5)
+        self.assertEqual(sr.agc_peak_magnitude, 128)
+        self.assertEqual(sr.agc_saturation_count, 42)
+        self.assertEqual(sr.agc_enable, 1)
+        self.assertEqual(sr.range_mode, 2)
+
+
+class TestAGCStatusResponseDefaults(unittest.TestCase):
+    """Verify StatusResponse AGC field defaults."""
+
+    def test_default_agc_fields(self):
+        sr = StatusResponse()
+        self.assertEqual(sr.agc_current_gain, 0)
+        self.assertEqual(sr.agc_peak_magnitude, 0)
+        self.assertEqual(sr.agc_saturation_count, 0)
+        self.assertEqual(sr.agc_enable, 0)
+
+    def test_agc_fields_set(self):
+        sr = StatusResponse(agc_current_gain=7, agc_peak_magnitude=200,
+                            agc_saturation_count=15, agc_enable=1)
+        self.assertEqual(sr.agc_current_gain, 7)
+        self.assertEqual(sr.agc_peak_magnitude, 200)
+        self.assertEqual(sr.agc_saturation_count, 15)
+        self.assertEqual(sr.agc_enable, 1)
+
+
+# =============================================================================
+# AGC Visualization — ring buffer / data model tests
+# =============================================================================
+
+class TestAGCVisualizationHistory(unittest.TestCase):
+    """Test the AGC visualization ring buffer logic (no GUI required)."""
+
+    def _make_deque(self, maxlen=256):
+        from collections import deque
+        return deque(maxlen=maxlen)
+
+    def test_ring_buffer_maxlen(self):
+        """Ring buffer should evict oldest when full."""
+        d = self._make_deque(maxlen=4)
+        for i in range(6):
+            d.append(i)
+        self.assertEqual(list(d), [2, 3, 4, 5])
+        self.assertEqual(len(d), 4)
+
+    def test_gain_history_accumulation(self):
+        """Gain values accumulate correctly in a deque."""
+        gain_hist = self._make_deque(maxlen=256)
+        statuses = [
+            StatusResponse(agc_current_gain=g)
+            for g in [0, 3, 7, 15, 8, 2]
+        ]
+        for st in statuses:
+            gain_hist.append(st.agc_current_gain)
+        self.assertEqual(list(gain_hist), [0, 3, 7, 15, 8, 2])
+
+    def test_peak_history_accumulation(self):
+        """Peak magnitude values accumulate correctly."""
+        peak_hist = self._make_deque(maxlen=256)
+        for p in [0, 50, 200, 255, 128]:
+            peak_hist.append(p)
+        self.assertEqual(list(peak_hist), [0, 50, 200, 255, 128])
+
+    def test_saturation_total_computation(self):
+        """Sum of saturation ring buffer gives running total."""
+        sat_hist = self._make_deque(maxlen=256)
+        for s in [0, 0, 5, 0, 12, 3]:
+            sat_hist.append(s)
+        self.assertEqual(sum(sat_hist), 20)
+
+    def test_saturation_color_thresholds(self):
+        """Color logic: green=0, yellow=1-10, red>10."""
+        def sat_color(total):
+            if total > 10:
+                return "red"
+            if total > 0:
+                return "yellow"
+            return "green"
+        self.assertEqual(sat_color(0), "green")
+        self.assertEqual(sat_color(1), "yellow")
+        self.assertEqual(sat_color(10), "yellow")
+        self.assertEqual(sat_color(11), "red")
+        self.assertEqual(sat_color(255), "red")
+
+    def test_ring_buffer_eviction_preserves_latest(self):
+        """After overflow, only the most recent values remain."""
+        d = self._make_deque(maxlen=8)
+        for i in range(20):
+            d.append(i)
+        self.assertEqual(list(d), [12, 13, 14, 15, 16, 17, 18, 19])
+
+    def test_empty_history_safe(self):
+        """Empty ring buffer should be safe for max/sum."""
+        d = self._make_deque(maxlen=256)
+        self.assertEqual(sum(d), 0)
+        self.assertEqual(len(d), 0)
+        # max() on empty would raise — test the guard pattern used in viz code
+        max_sat = max(d) if d else 0
+        self.assertEqual(max_sat, 0)
+
+    def test_agc_mode_string(self):
+        """AGC mode display string from enable flag."""
+        self.assertEqual(
+            "AUTO" if StatusResponse(agc_enable=1).agc_enable else "MANUAL",
+            "AUTO")
+        self.assertEqual(
+            "AUTO" if StatusResponse(agc_enable=0).agc_enable else "MANUAL",
+            "MANUAL")
+
+    def test_xlim_scroll_logic(self):
+        """X-axis scroll: when n >= history_len, xlim should expand."""
+        history_len = 8
+        d = self._make_deque(maxlen=history_len)
+        for i in range(10):
+            d.append(i)
+        n = len(d)
+        # After 10 pushes into maxlen=8, n=8
+        self.assertEqual(n, history_len)
+        # xlim should be (0, n) for static or (n-history_len, n) for scrolling
+        self.assertEqual(max(0, n - history_len), 0)
+        self.assertEqual(n, 8)
+
+    def test_sat_autoscale_ylim(self):
+        """Saturation y-axis auto-scale: max(max_sat * 1.5, 5)."""
+        # No saturation
+        self.assertEqual(max(0 * 1.5, 5), 5)
+        # Some saturation
+        self.assertAlmostEqual(max(10 * 1.5, 5), 15.0)
+        # High saturation
+        self.assertAlmostEqual(max(200 * 1.5, 5), 300.0)
+
+
+# =====================================================================
+# Tests for DemoTarget, DemoSimulator, and _ReplayController
+# =====================================================================
+
+
+class TestDemoTarget(unittest.TestCase):
+    """Unit tests for DemoTarget kinematics."""
+
+    def test_initial_values_in_range(self):
+        t = DemoTarget(1)
+        self.assertEqual(t.id, 1)
+        self.assertGreaterEqual(t.range_m, 20)
+        self.assertLessEqual(t.range_m, DemoTarget._MAX_RANGE)
+        self.assertIn(t.classification, ["aircraft", "drone", "bird", "unknown"])
+
+    def test_step_returns_true_in_normal_range(self):
+        t = DemoTarget(2)
+        t.range_m = 150.0
+        t.velocity = 0.0
+        self.assertTrue(t.step())
+
+    def test_step_returns_false_when_out_of_range_high(self):
+        t = DemoTarget(3)
+        t.range_m = DemoTarget._MAX_RANGE + 1
+        t.velocity = -1.0  # moving away
+        self.assertFalse(t.step())
+
+    def test_step_returns_false_when_out_of_range_low(self):
+        t = DemoTarget(4)
+        t.range_m = 2.0
+        t.velocity = 1.0  # moving closer
+        self.assertFalse(t.step())
+
+    def test_velocity_clamped(self):
+        t = DemoTarget(5)
+        t.velocity = 19.0
+        t.range_m = 150.0
+        # Step many times — velocity should stay within [-20, 20]
+        for _ in range(100):
+            t.range_m = 150.0  # keep in range
+            t.step()
+        self.assertGreaterEqual(t.velocity, -20)
+        self.assertLessEqual(t.velocity, 20)
+
+    def test_snr_clamped(self):
+        t = DemoTarget(6)
+        t.snr = 49.5
+        t.range_m = 150.0
+        for _ in range(100):
+            t.range_m = 150.0
+            t.step()
+        self.assertGreaterEqual(t.snr, 0)
+        self.assertLessEqual(t.snr, 50)
+
+
+class TestDemoSimulatorNoTk(unittest.TestCase):
+    """Test DemoSimulator logic without a real Tk event loop.
+
+    We replace ``root.after`` with a mock to avoid needing a display.
+    """
+
+    def _make_simulator(self):
+        from unittest.mock import MagicMock
+
+        fq = queue.Queue(maxsize=100)
+        uq = queue.Queue(maxsize=100)
+        mock_root = MagicMock()
+        # root.after(ms, fn) should return an id (str)
+        mock_root.after.return_value = "mock_after_id"
+        sim = DemoSimulator(fq, uq, mock_root, interval_ms=100)
+        return sim, fq, uq, mock_root
+
+    def test_initial_targets_created(self):
+        sim, _fq, _uq, _root = self._make_simulator()
+        # Should seed 8 initial targets
+        self.assertEqual(len(sim._targets), 8)
+
+    def test_tick_produces_frame_and_targets(self):
+        sim, fq, uq, _root = self._make_simulator()
+        sim._tick()
+        # Should have a frame
+        self.assertFalse(fq.empty())
+        frame = fq.get_nowait()
+        self.assertIsInstance(frame, RadarFrame)
+        self.assertEqual(frame.frame_number, 1)
+        # Should have demo_targets in ui_queue
+        tag, payload = uq.get_nowait()
+        self.assertEqual(tag, "demo_targets")
+        self.assertIsInstance(payload, list)
+
+    def test_tick_produces_nonzero_detections(self):
+        """Demo targets should actually render into the range-Doppler grid."""
+        sim, fq, _uq, _root = self._make_simulator()
+        sim._tick()
+        frame = fq.get_nowait()
+        # At least some targets should produce magnitude > 0 and detections
+        self.assertGreater(frame.magnitude.sum(), 0,
+                           "Demo targets should render into range-Doppler grid")
+        self.assertGreater(frame.detection_count, 0,
+                           "Demo targets should produce detections")
+
+    def test_stop_cancels_after(self):
+        sim, _fq, _uq, mock_root = self._make_simulator()
+        sim._tick()  # sets _after_id
+        sim.stop()
+        mock_root.after_cancel.assert_called_once_with("mock_after_id")
+        self.assertIsNone(sim._after_id)
+
+
+class TestReplayController(unittest.TestCase):
+    """Unit tests for _ReplayController (no GUI required)."""
+
+    def test_initial_state(self):
+        fq = queue.Queue()
+        uq = queue.Queue()
+        ctrl = _ReplayController(fq, uq)
+        self.assertEqual(ctrl.total_frames, 0)
+        self.assertEqual(ctrl.current_index, 0)
+        self.assertFalse(ctrl.is_playing)
+        self.assertIsNone(ctrl.software_fpga)
+
+    def test_set_speed(self):
+        ctrl = _ReplayController(queue.Queue(), queue.Queue())
+        ctrl.set_speed("2x")
+        self.assertAlmostEqual(ctrl._frame_interval, 0.050)
+
+    def test_set_speed_unknown_falls_back(self):
+        ctrl = _ReplayController(queue.Queue(), queue.Queue())
+        ctrl.set_speed("99x")
+        self.assertAlmostEqual(ctrl._frame_interval, 0.100)
+
+    def test_set_loop(self):
+        ctrl = _ReplayController(queue.Queue(), queue.Queue())
+        ctrl.set_loop(True)
+        self.assertTrue(ctrl._loop)
+        ctrl.set_loop(False)
+        self.assertFalse(ctrl._loop)
+
+    def test_seek_increments_past_emitted(self):
+        """After seek(), _current_index should be one past the seeked frame."""
+        fq = queue.Queue(maxsize=100)
+        uq = queue.Queue(maxsize=100)
+        ctrl = _ReplayController(fq, uq)
+        # Manually set engine to a mock to allow seek
+        from unittest.mock import MagicMock
+        mock_engine = MagicMock()
+        mock_engine.total_frames = 10
+        mock_engine.get_frame.return_value = RadarFrame()
+        ctrl._engine = mock_engine
+        ctrl.seek(5)
+        # _current_index should be 6 (past the emitted frame)
+        self.assertEqual(ctrl._current_index, 6)
+        self.assertEqual(ctrl._last_emitted_index, 5)
+        # Frame should be in the queue
+        self.assertFalse(fq.empty())
+
+    def test_seek_clamps_to_bounds(self):
+        from unittest.mock import MagicMock
+
+        fq = queue.Queue(maxsize=100)
+        uq = queue.Queue(maxsize=100)
+        ctrl = _ReplayController(fq, uq)
+        mock_engine = MagicMock()
+        mock_engine.total_frames = 5
+        mock_engine.get_frame.return_value = RadarFrame()
+        ctrl._engine = mock_engine
+
+        ctrl.seek(100)
+        # Should clamp to last frame (index 4), then _current_index = 5
+        self.assertEqual(ctrl._last_emitted_index, 4)
+        self.assertEqual(ctrl._current_index, 5)
+
+        ctrl.seek(-10)
+        # Should clamp to 0, then _current_index = 1
+        self.assertEqual(ctrl._last_emitted_index, 0)
+        self.assertEqual(ctrl._current_index, 1)
+
+    def test_close_releases_engine(self):
+        from unittest.mock import MagicMock
+
+        fq = queue.Queue(maxsize=100)
+        uq = queue.Queue(maxsize=100)
+        ctrl = _ReplayController(fq, uq)
+        mock_engine = MagicMock()
+        mock_engine.total_frames = 5
+        mock_engine.get_frame.return_value = RadarFrame()
+        ctrl._engine = mock_engine
+
+        ctrl.close()
+        mock_engine.close.assert_called_once()
+        self.assertIsNone(ctrl._engine)
+        self.assertIsNone(ctrl.software_fpga)
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)

9_Firmware/9_3_GUI/test_v7.py

@@ -11,6 +11,7 @@ Does NOT require a running Qt event loop — only unit-testable components.
 Run with:  python -m unittest test_v7 -v
 """
 
+import os
 import struct
 import unittest
 from dataclasses import asdict
@@ -264,6 +265,15 @@ class TestUSBPacketParser(unittest.TestCase):
 # Test: v7.workers — polar_to_geographic
 # =============================================================================
 
+def _pyqt6_available():
+    try:
+        import PyQt6.QtCore  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+@unittest.skipUnless(_pyqt6_available(), "PyQt6 not installed")
 class TestPolarToGeographic(unittest.TestCase):
     def test_north_bearing(self):
         from v7.workers import polar_to_geographic
@@ -326,14 +336,638 @@ class TestV7Init(unittest.TestCase):
 
     def test_key_exports(self):
         import v7
+        # Core exports (no PyQt6 required)
         for name in ["RadarTarget", "RadarSettings", "GPSData",
                       "ProcessingConfig", "FT2232HConnection",
-                      "RadarProtocol", "RadarProcessor",
-                      "RadarDataWorker", "RadarMapWidget",
+                      "RadarProtocol", "RadarProcessor"]:
+            self.assertTrue(hasattr(v7, name), f"v7 missing export: {name}")
+        # PyQt6-dependent exports — only present when PyQt6 is installed
+        if _pyqt6_available():
+            for name in ["RadarDataWorker", "RadarMapWidget",
                           "RadarDashboard"]:
                 self.assertTrue(hasattr(v7, name), f"v7 missing export: {name}")
 
 
+# =============================================================================
+# Test: AGC Visualization data model
+# =============================================================================
+
+class TestAGCVisualizationV7(unittest.TestCase):
+    """AGC visualization ring buffer and data model tests (no Qt required)."""
+
+    def _make_deque(self, maxlen=256):
+        from collections import deque
+        return deque(maxlen=maxlen)
+
+    def test_ring_buffer_basics(self):
+        d = self._make_deque(maxlen=4)
+        for i in range(6):
+            d.append(i)
+        self.assertEqual(list(d), [2, 3, 4, 5])
+
+    def test_gain_range_4bit(self):
+        """AGC gain is 4-bit (0-15)."""
+        from radar_protocol import StatusResponse
+        for g in [0, 7, 15]:
+            sr = StatusResponse(agc_current_gain=g)
+            self.assertEqual(sr.agc_current_gain, g)
+
+    def test_peak_range_8bit(self):
+        """Peak magnitude is 8-bit (0-255)."""
+        from radar_protocol import StatusResponse
+        for p in [0, 128, 255]:
+            sr = StatusResponse(agc_peak_magnitude=p)
+            self.assertEqual(sr.agc_peak_magnitude, p)
+
+    def test_saturation_accumulation(self):
+        """Saturation ring buffer sum tracks total events."""
+        sat = self._make_deque(maxlen=256)
+        for s in [0, 5, 0, 10, 3]:
+            sat.append(s)
+        self.assertEqual(sum(sat), 18)
+
+    def test_mode_label_logic(self):
+        """AGC mode string from enable field."""
+        from radar_protocol import StatusResponse
+        self.assertEqual(
+            "AUTO" if StatusResponse(agc_enable=1).agc_enable else "MANUAL",
+            "AUTO")
+        self.assertEqual(
+            "AUTO" if StatusResponse(agc_enable=0).agc_enable else "MANUAL",
+            "MANUAL")
+
+    def test_history_len_default(self):
+        """Default history length should be 256."""
+        d = self._make_deque(maxlen=256)
+        self.assertEqual(d.maxlen, 256)
+
+    def test_color_thresholds(self):
+        """Saturation color: green=0, warning=1-10, error>10."""
+        from v7.models import DARK_SUCCESS, DARK_WARNING, DARK_ERROR
+        def pick_color(total):
+            if total > 10:
+                return DARK_ERROR
+            if total > 0:
+                return DARK_WARNING
+            return DARK_SUCCESS
+        self.assertEqual(pick_color(0), DARK_SUCCESS)
+        self.assertEqual(pick_color(5), DARK_WARNING)
+        self.assertEqual(pick_color(11), DARK_ERROR)
+
+
+# =============================================================================
+# Test: v7.models.WaveformConfig
+# =============================================================================
+
+class TestWaveformConfig(unittest.TestCase):
+    """WaveformConfig dataclass and derived physical properties."""
+
+    def test_defaults(self):
+        from v7.models import WaveformConfig
+        wc = WaveformConfig()
+        self.assertEqual(wc.sample_rate_hz, 4e6)
+        self.assertEqual(wc.bandwidth_hz, 500e6)
+        self.assertEqual(wc.chirp_duration_s, 300e-6)
+        self.assertEqual(wc.center_freq_hz, 10.525e9)
+        self.assertEqual(wc.n_range_bins, 64)
+        self.assertEqual(wc.n_doppler_bins, 32)
+        self.assertEqual(wc.fft_size, 1024)
+        self.assertEqual(wc.decimation_factor, 16)
+
+    def test_range_resolution(self):
+        """range_resolution_m should be ~5.62 m/bin with ADI defaults."""
+        from v7.models import WaveformConfig
+        wc = WaveformConfig()
+        self.assertAlmostEqual(wc.range_resolution_m, 5.621, places=1)
+
+    def test_velocity_resolution(self):
+        """velocity_resolution_mps should be ~1.484 m/s/bin."""
+        from v7.models import WaveformConfig
+        wc = WaveformConfig()
+        self.assertAlmostEqual(wc.velocity_resolution_mps, 1.484, places=2)
+
+    def test_max_range(self):
+        """max_range_m = range_resolution * n_range_bins."""
+        from v7.models import WaveformConfig
+        wc = WaveformConfig()
+        self.assertAlmostEqual(wc.max_range_m, wc.range_resolution_m * 64, places=1)
+
+    def test_max_velocity(self):
+        """max_velocity_mps = velocity_resolution * n_doppler_bins / 2."""
+        from v7.models import WaveformConfig
+        wc = WaveformConfig()
+        self.assertAlmostEqual(
+            wc.max_velocity_mps,
+            wc.velocity_resolution_mps * 16,
+            places=2,
+        )
+
+    def test_custom_params(self):
+        """Non-default parameters correctly change derived values."""
+        from v7.models import WaveformConfig
+        wc1 = WaveformConfig()
+        wc2 = WaveformConfig(bandwidth_hz=1e9)  # double BW → halve range res
+        self.assertAlmostEqual(wc2.range_resolution_m, wc1.range_resolution_m / 2, places=2)
+
+    def test_zero_center_freq_velocity(self):
+        """Zero center freq should cause ZeroDivisionError in velocity calc."""
+        from v7.models import WaveformConfig
+        wc = WaveformConfig(center_freq_hz=0.0)
+        with self.assertRaises(ZeroDivisionError):
+            _ = wc.velocity_resolution_mps
+
+
+# =============================================================================
+# Test: v7.software_fpga.SoftwareFPGA
+# =============================================================================
+
+class TestSoftwareFPGA(unittest.TestCase):
+    """SoftwareFPGA register interface and signal chain."""
+
+    def _make_fpga(self):
+        from v7.software_fpga import SoftwareFPGA
+        return SoftwareFPGA()
+
+    def test_reset_defaults(self):
+        """Register reset values match FPGA RTL (radar_system_top.v)."""
+        fpga = self._make_fpga()
+        self.assertEqual(fpga.detect_threshold, 10_000)
+        self.assertEqual(fpga.gain_shift, 0)
+        self.assertFalse(fpga.cfar_enable)
+        self.assertEqual(fpga.cfar_guard, 2)
+        self.assertEqual(fpga.cfar_train, 8)
+        self.assertEqual(fpga.cfar_alpha, 0x30)
+        self.assertEqual(fpga.cfar_mode, 0)
+        self.assertFalse(fpga.mti_enable)
+        self.assertEqual(fpga.dc_notch_width, 0)
+        self.assertFalse(fpga.agc_enable)
+        self.assertEqual(fpga.agc_target, 200)
+        self.assertEqual(fpga.agc_attack, 1)
+        self.assertEqual(fpga.agc_decay, 1)
+        self.assertEqual(fpga.agc_holdoff, 4)
+
+    def test_setter_detect_threshold(self):
+        fpga = self._make_fpga()
+        fpga.set_detect_threshold(5000)
+        self.assertEqual(fpga.detect_threshold, 5000)
+
+    def test_setter_detect_threshold_clamp_16bit(self):
+        fpga = self._make_fpga()
+        fpga.set_detect_threshold(0x1FFFF)  # 17-bit
+        self.assertEqual(fpga.detect_threshold, 0xFFFF)
+
+    def test_setter_gain_shift_clamp_4bit(self):
+        fpga = self._make_fpga()
+        fpga.set_gain_shift(0xFF)
+        self.assertEqual(fpga.gain_shift, 0x0F)
+
+    def test_setter_cfar_enable(self):
+        fpga = self._make_fpga()
+        fpga.set_cfar_enable(True)
+        self.assertTrue(fpga.cfar_enable)
+        fpga.set_cfar_enable(False)
+        self.assertFalse(fpga.cfar_enable)
+
+    def test_setter_cfar_guard_clamp_4bit(self):
+        fpga = self._make_fpga()
+        fpga.set_cfar_guard(0x1F)
+        self.assertEqual(fpga.cfar_guard, 0x0F)
+
+    def test_setter_cfar_train_min_1(self):
+        """CFAR train cells clamped to min 1."""
+        fpga = self._make_fpga()
+        fpga.set_cfar_train(0)
+        self.assertEqual(fpga.cfar_train, 1)
+
+    def test_setter_cfar_train_clamp_5bit(self):
+        fpga = self._make_fpga()
+        fpga.set_cfar_train(0x3F)
+        self.assertEqual(fpga.cfar_train, 0x1F)
+
+    def test_setter_cfar_alpha_clamp_8bit(self):
+        fpga = self._make_fpga()
+        fpga.set_cfar_alpha(0x1FF)
+        self.assertEqual(fpga.cfar_alpha, 0xFF)
+
+    def test_setter_cfar_mode_clamp_2bit(self):
+        fpga = self._make_fpga()
+        fpga.set_cfar_mode(7)
+        self.assertEqual(fpga.cfar_mode, 3)
+
+    def test_setter_mti_enable(self):
+        fpga = self._make_fpga()
+        fpga.set_mti_enable(True)
+        self.assertTrue(fpga.mti_enable)
+
+    def test_setter_dc_notch_clamp_3bit(self):
+        fpga = self._make_fpga()
+        fpga.set_dc_notch_width(0xFF)
+        self.assertEqual(fpga.dc_notch_width, 7)
+
+    def test_setter_agc_params_selective(self):
+        """set_agc_params only changes provided fields."""
+        fpga = self._make_fpga()
+        fpga.set_agc_params(target=100)
+        self.assertEqual(fpga.agc_target, 100)
+        self.assertEqual(fpga.agc_attack, 1)  # unchanged
+        fpga.set_agc_params(attack=3, decay=5)
+        self.assertEqual(fpga.agc_attack, 3)
+        self.assertEqual(fpga.agc_decay, 5)
+        self.assertEqual(fpga.agc_target, 100)  # unchanged
+
+    def test_setter_agc_params_clamp(self):
+        fpga = self._make_fpga()
+        fpga.set_agc_params(target=0xFFF, attack=0xFF, decay=0xFF, holdoff=0xFF)
+        self.assertEqual(fpga.agc_target, 0xFF)
+        self.assertEqual(fpga.agc_attack, 0x0F)
+        self.assertEqual(fpga.agc_decay, 0x0F)
+        self.assertEqual(fpga.agc_holdoff, 0x0F)
+
+
+class TestSoftwareFPGASignalChain(unittest.TestCase):
+    """SoftwareFPGA.process_chirps with real co-sim data."""
+
+    COSIM_DIR = os.path.join(
+        os.path.dirname(__file__), "..", "9_2_FPGA", "tb", "cosim",
+        "real_data", "hex"
+    )
+
+    def _cosim_available(self):
+        return os.path.isfile(os.path.join(self.COSIM_DIR, "doppler_map_i.npy"))
+
+    def test_process_chirps_returns_radar_frame(self):
+        """process_chirps produces a RadarFrame with correct shapes."""
+        if not self._cosim_available():
+            self.skipTest("co-sim data not found")
+        from v7.software_fpga import SoftwareFPGA
+        from radar_protocol import RadarFrame
+
+        # Load decimated range data as minimal input (32 chirps x 64 bins)
+        dec_i = np.load(os.path.join(self.COSIM_DIR, "decimated_range_i.npy"))
+        dec_q = np.load(os.path.join(self.COSIM_DIR, "decimated_range_q.npy"))
+
+        # Build fake 1024-sample chirps from decimated data (pad with zeros)
+        n_chirps = dec_i.shape[0]
+        iq_i = np.zeros((n_chirps, 1024), dtype=np.int64)
+        iq_q = np.zeros((n_chirps, 1024), dtype=np.int64)
+        # Put decimated data into first 64 bins so FFT has something
+        iq_i[:, :dec_i.shape[1]] = dec_i
+        iq_q[:, :dec_q.shape[1]] = dec_q
+
+        fpga = SoftwareFPGA()
+        frame = fpga.process_chirps(iq_i, iq_q, frame_number=42, timestamp=1.0)
+
+        self.assertIsInstance(frame, RadarFrame)
+        self.assertEqual(frame.frame_number, 42)
+        self.assertAlmostEqual(frame.timestamp, 1.0)
+        self.assertEqual(frame.range_doppler_i.shape, (64, 32))
+        self.assertEqual(frame.range_doppler_q.shape, (64, 32))
+        self.assertEqual(frame.magnitude.shape, (64, 32))
+        self.assertEqual(frame.detections.shape, (64, 32))
+        self.assertEqual(frame.range_profile.shape, (64,))
+        self.assertEqual(frame.detection_count, int(frame.detections.sum()))
+
+    def test_cfar_enable_changes_detections(self):
+        """Enabling CFAR vs simple threshold should yield different detection counts."""
+        if not self._cosim_available():
+            self.skipTest("co-sim data not found")
+        from v7.software_fpga import SoftwareFPGA
+
+        iq_i = np.zeros((32, 1024), dtype=np.int64)
+        iq_q = np.zeros((32, 1024), dtype=np.int64)
+        # Inject a single strong tone in bin 10 of every chirp
+        iq_i[:, 10] = 5000
+        iq_q[:, 10] = 3000
+
+        fpga_thresh = SoftwareFPGA()
+        fpga_thresh.set_detect_threshold(1)  # very low → many detections
+        frame_thresh = fpga_thresh.process_chirps(iq_i, iq_q)
+
+        fpga_cfar = SoftwareFPGA()
+        fpga_cfar.set_cfar_enable(True)
+        fpga_cfar.set_cfar_alpha(0x10)  # low alpha → more detections
+        frame_cfar = fpga_cfar.process_chirps(iq_i, iq_q)
+
+        # Just verify both produce valid frames — exact counts depend on chain
+        self.assertIsNotNone(frame_thresh)
+        self.assertIsNotNone(frame_cfar)
+        self.assertEqual(frame_thresh.magnitude.shape, (64, 32))
+        self.assertEqual(frame_cfar.magnitude.shape, (64, 32))
+
+
+class TestQuantizeRawIQ(unittest.TestCase):
+    """quantize_raw_iq utility function."""
+
+    def test_3d_input(self):
+        """3-D (frames, chirps, samples) → uses first frame."""
+        from v7.software_fpga import quantize_raw_iq
+        raw = np.random.randn(5, 32, 1024) + 1j * np.random.randn(5, 32, 1024)
+        iq_i, iq_q = quantize_raw_iq(raw)
+        self.assertEqual(iq_i.shape, (32, 1024))
+        self.assertEqual(iq_q.shape, (32, 1024))
+        self.assertTrue(np.all(np.abs(iq_i) <= 32767))
+        self.assertTrue(np.all(np.abs(iq_q) <= 32767))
+
+    def test_2d_input(self):
+        """2-D (chirps, samples) → works directly."""
+        from v7.software_fpga import quantize_raw_iq
+        raw = np.random.randn(32, 1024) + 1j * np.random.randn(32, 1024)
+        iq_i, _iq_q = quantize_raw_iq(raw)
+        self.assertEqual(iq_i.shape, (32, 1024))
+
+    def test_zero_input(self):
+        """All-zero complex input → all-zero output."""
+        from v7.software_fpga import quantize_raw_iq
+        raw = np.zeros((32, 1024), dtype=np.complex128)
+        iq_i, iq_q = quantize_raw_iq(raw)
+        self.assertTrue(np.all(iq_i == 0))
+        self.assertTrue(np.all(iq_q == 0))
+
+    def test_peak_target_scaling(self):
+        """Peak of output should be near peak_target."""
+        from v7.software_fpga import quantize_raw_iq
+        raw = np.zeros((32, 1024), dtype=np.complex128)
+        raw[0, 0] = 1.0 + 0j  # single peak
+        iq_i, _iq_q = quantize_raw_iq(raw, peak_target=500)
+        # The peak I value should be exactly 500 (sole max)
+        self.assertEqual(int(iq_i[0, 0]), 500)
+
+
+# =============================================================================
+# Test: v7.replay (ReplayEngine, detect_format)
+# =============================================================================
+
+class TestDetectFormat(unittest.TestCase):
+    """detect_format auto-detection logic."""
+
+    COSIM_DIR = os.path.join(
+        os.path.dirname(__file__), "..", "9_2_FPGA", "tb", "cosim",
+        "real_data", "hex"
+    )
+
+    def test_cosim_dir(self):
+        if not os.path.isdir(self.COSIM_DIR):
+            self.skipTest("co-sim dir not found")
+        from v7.replay import detect_format, ReplayFormat
+        self.assertEqual(detect_format(self.COSIM_DIR), ReplayFormat.COSIM_DIR)
+
+    def test_npy_file(self):
+        """A .npy file → RAW_IQ_NPY."""
+        from v7.replay import detect_format, ReplayFormat
+        import tempfile
+        with tempfile.NamedTemporaryFile(suffix=".npy", delete=False) as f:
+            np.save(f, np.zeros((2, 32, 1024), dtype=np.complex128))
+            tmp = f.name
+        try:
+            self.assertEqual(detect_format(tmp), ReplayFormat.RAW_IQ_NPY)
+        finally:
+            os.unlink(tmp)
+
+    def test_h5_file(self):
+        """A .h5 file → HDF5."""
+        from v7.replay import detect_format, ReplayFormat
+        self.assertEqual(detect_format("/tmp/fake_recording.h5"), ReplayFormat.HDF5)
+
+    def test_unknown_extension_raises(self):
+        from v7.replay import detect_format
+        with self.assertRaises(ValueError):
+            detect_format("/tmp/data.csv")
+
+    def test_empty_dir_raises(self):
+        """Directory without co-sim files → ValueError."""
+        from v7.replay import detect_format
+        import tempfile
+        with tempfile.TemporaryDirectory() as td, self.assertRaises(ValueError):
+            detect_format(td)
+
+
+class TestReplayEngineCosim(unittest.TestCase):
+    """ReplayEngine loading from FPGA co-sim directory."""
+
+    COSIM_DIR = os.path.join(
+        os.path.dirname(__file__), "..", "9_2_FPGA", "tb", "cosim",
+        "real_data", "hex"
+    )
+
+    def _available(self):
+        return os.path.isfile(os.path.join(self.COSIM_DIR, "doppler_map_i.npy"))
+
+    def test_load_cosim(self):
+        if not self._available():
+            self.skipTest("co-sim data not found")
+        from v7.replay import ReplayEngine, ReplayFormat
+        engine = ReplayEngine(self.COSIM_DIR)
+        self.assertEqual(engine.fmt, ReplayFormat.COSIM_DIR)
+        self.assertEqual(engine.total_frames, 1)
+
+    def test_get_frame_cosim(self):
+        if not self._available():
+            self.skipTest("co-sim data not found")
+        from v7.replay import ReplayEngine
+        from radar_protocol import RadarFrame
+        engine = ReplayEngine(self.COSIM_DIR)
+        frame = engine.get_frame(0)
+        self.assertIsInstance(frame, RadarFrame)
+        self.assertEqual(frame.range_doppler_i.shape, (64, 32))
+        self.assertEqual(frame.magnitude.shape, (64, 32))
+
+    def test_get_frame_out_of_range(self):
+        if not self._available():
+            self.skipTest("co-sim data not found")
+        from v7.replay import ReplayEngine
+        engine = ReplayEngine(self.COSIM_DIR)
+        with self.assertRaises(IndexError):
+            engine.get_frame(1)
+        with self.assertRaises(IndexError):
+            engine.get_frame(-1)
+
+
+class TestReplayEngineRawIQ(unittest.TestCase):
+    """ReplayEngine loading from raw IQ .npy cube."""
+
+    def test_load_raw_iq_synthetic(self):
+        """Synthetic raw IQ cube loads and produces correct frame count."""
+        import tempfile
+        from v7.replay import ReplayEngine, ReplayFormat
+        from v7.software_fpga import SoftwareFPGA
+
+        raw = np.random.randn(3, 32, 1024) + 1j * np.random.randn(3, 32, 1024)
+        with tempfile.NamedTemporaryFile(suffix=".npy", delete=False) as f:
+            np.save(f, raw)
+            tmp = f.name
+        try:
+            fpga = SoftwareFPGA()
+            engine = ReplayEngine(tmp, software_fpga=fpga)
+            self.assertEqual(engine.fmt, ReplayFormat.RAW_IQ_NPY)
+            self.assertEqual(engine.total_frames, 3)
+        finally:
+            os.unlink(tmp)
+
+    def test_get_frame_raw_iq_synthetic(self):
+        """get_frame on raw IQ runs SoftwareFPGA and returns RadarFrame."""
+        import tempfile
+        from v7.replay import ReplayEngine
+        from v7.software_fpga import SoftwareFPGA
+        from radar_protocol import RadarFrame
+
+        raw = np.random.randn(2, 32, 1024) + 1j * np.random.randn(2, 32, 1024)
+        with tempfile.NamedTemporaryFile(suffix=".npy", delete=False) as f:
+            np.save(f, raw)
+            tmp = f.name
+        try:
+            fpga = SoftwareFPGA()
+            engine = ReplayEngine(tmp, software_fpga=fpga)
+            frame = engine.get_frame(0)
+            self.assertIsInstance(frame, RadarFrame)
+            self.assertEqual(frame.range_doppler_i.shape, (64, 32))
+            self.assertEqual(frame.frame_number, 0)
+        finally:
+            os.unlink(tmp)
+
+    def test_raw_iq_no_fpga_raises(self):
+        """Raw IQ get_frame without SoftwareFPGA → RuntimeError."""
+        import tempfile
+        from v7.replay import ReplayEngine
+
+        raw = np.random.randn(1, 32, 1024) + 1j * np.random.randn(1, 32, 1024)
+        with tempfile.NamedTemporaryFile(suffix=".npy", delete=False) as f:
+            np.save(f, raw)
+            tmp = f.name
+        try:
+            engine = ReplayEngine(tmp)
+            with self.assertRaises(RuntimeError):
+                engine.get_frame(0)
+        finally:
+            os.unlink(tmp)
+
+
+class TestReplayEngineHDF5(unittest.TestCase):
+    """ReplayEngine loading from HDF5 recordings."""
+
+    def _skip_no_h5py(self):
+        try:
+            import h5py  # noqa: F401
+        except ImportError:
+            self.skipTest("h5py not installed")
+
+    def test_load_hdf5_synthetic(self):
+        """Synthetic HDF5 loads and iterates frames."""
+        self._skip_no_h5py()
+        import tempfile
+        import h5py
+        from v7.replay import ReplayEngine, ReplayFormat
+        from radar_protocol import RadarFrame
+
+        with tempfile.NamedTemporaryFile(suffix=".h5", delete=False) as f:
+            tmp = f.name
+
+        try:
+            with h5py.File(tmp, "w") as hf:
+                hf.attrs["creator"] = "test"
+                hf.attrs["range_bins"] = 64
+                hf.attrs["doppler_bins"] = 32
+                grp = hf.create_group("frames")
+                for i in range(3):
+                    fg = grp.create_group(f"frame_{i:06d}")
+                    fg.attrs["timestamp"] = float(i)
+                    fg.attrs["frame_number"] = i
+                    fg.attrs["detection_count"] = 0
+                    fg.create_dataset("range_doppler_i",
+                                      data=np.zeros((64, 32), dtype=np.int16))
+                    fg.create_dataset("range_doppler_q",
+                                      data=np.zeros((64, 32), dtype=np.int16))
+                    fg.create_dataset("magnitude",
+                                      data=np.zeros((64, 32), dtype=np.float64))
+                    fg.create_dataset("detections",
+                                      data=np.zeros((64, 32), dtype=np.uint8))
+                    fg.create_dataset("range_profile",
+                                      data=np.zeros(64, dtype=np.float64))
+
+            engine = ReplayEngine(tmp)
+            self.assertEqual(engine.fmt, ReplayFormat.HDF5)
+            self.assertEqual(engine.total_frames, 3)
+
+            frame = engine.get_frame(1)
+            self.assertIsInstance(frame, RadarFrame)
+            self.assertEqual(frame.frame_number, 1)
+            self.assertEqual(frame.range_doppler_i.shape, (64, 32))
+            engine.close()
+        finally:
+            os.unlink(tmp)
+
+
+# =============================================================================
+# Test: v7.processing.extract_targets_from_frame
+# =============================================================================
+
+class TestExtractTargetsFromFrame(unittest.TestCase):
+    """extract_targets_from_frame bin-to-physical conversion."""
+
+    def _make_frame(self, det_cells=None):
+        """Create a minimal RadarFrame with optional detection cells."""
+        from radar_protocol import RadarFrame
+        frame = RadarFrame()
+        if det_cells:
+            for rbin, dbin in det_cells:
+                frame.detections[rbin, dbin] = 1
+                frame.magnitude[rbin, dbin] = 1000.0
+        frame.detection_count = int(frame.detections.sum())
+        frame.timestamp = 1.0
+        return frame
+
+    def test_no_detections(self):
+        from v7.processing import extract_targets_from_frame
+        frame = self._make_frame()
+        targets = extract_targets_from_frame(frame)
+        self.assertEqual(len(targets), 0)
+
+    def test_single_detection_range(self):
+        """Detection at range bin 10 → range = 10 * range_resolution."""
+        from v7.processing import extract_targets_from_frame
+        frame = self._make_frame(det_cells=[(10, 16)])  # dbin=16 = center → vel=0
+        targets = extract_targets_from_frame(frame, range_resolution=5.621)
+        self.assertEqual(len(targets), 1)
+        self.assertAlmostEqual(targets[0].range, 10 * 5.621, places=2)
+        self.assertAlmostEqual(targets[0].velocity, 0.0, places=2)
+
+    def test_velocity_sign(self):
+        """Doppler bin < center → negative velocity, > center → positive."""
+        from v7.processing import extract_targets_from_frame
+        frame = self._make_frame(det_cells=[(5, 10), (5, 20)])
+        targets = extract_targets_from_frame(frame, velocity_resolution=1.484)
+        # dbin=10: vel = (10-16)*1.484 = -8.904  (approaching)
+        # dbin=20: vel = (20-16)*1.484 = +5.936  (receding)
+        self.assertLess(targets[0].velocity, 0)
+        self.assertGreater(targets[1].velocity, 0)
+
+    def test_snr_positive_for_nonzero_mag(self):
+        from v7.processing import extract_targets_from_frame
+        frame = self._make_frame(det_cells=[(3, 16)])
+        targets = extract_targets_from_frame(frame)
+        self.assertGreater(targets[0].snr, 0)
+
+    def test_gps_georef(self):
+        """With GPS data, targets get non-zero lat/lon."""
+        from v7.processing import extract_targets_from_frame
+        from v7.models import GPSData
+        gps = GPSData(latitude=41.9, longitude=12.5, altitude=0.0,
+                      pitch=0.0, heading=90.0)
+        frame = self._make_frame(det_cells=[(10, 16)])
+        targets = extract_targets_from_frame(
+            frame, range_resolution=100.0, gps=gps)
+        # Should be roughly east of radar position
+        self.assertAlmostEqual(targets[0].latitude, 41.9, places=2)
+        self.assertGreater(targets[0].longitude, 12.5)
+
+    def test_multiple_detections(self):
+        from v7.processing import extract_targets_from_frame
+        frame = self._make_frame(det_cells=[(0, 0), (10, 10), (63, 31)])
+        targets = extract_targets_from_frame(frame)
+        self.assertEqual(len(targets), 3)
+        # IDs should be sequential 0, 1, 2
+        self.assertEqual([t.id for t in targets], [0, 1, 2])
+
+
 # =============================================================================
 # Helper: lazy import of v7.models
 # =============================================================================

9_Firmware/9_3_GUI/v7/__init__.py

@@ -14,6 +14,7 @@ from .models import (
     GPSData,
     ProcessingConfig,
     TileServer,
+    WaveformConfig,
     DARK_BG, DARK_FG, DARK_ACCENT, DARK_HIGHLIGHT, DARK_BORDER,
     DARK_TEXT, DARK_BUTTON, DARK_BUTTON_HOVER,
     DARK_TREEVIEW, DARK_TREEVIEW_ALT,
@@ -25,7 +26,6 @@ from .models import (
 # Hardware interfaces — production protocol via radar_protocol.py
 from .hardware import (
     FT2232HConnection,
-    ReplayConnection,
     RadarProtocol,
     Opcode,
     RadarAcquisition,
@@ -40,31 +40,48 @@ from .processing import (
     RadarProcessor,
     USBPacketParser,
     apply_pitch_correction,
+    polar_to_geographic,
+    extract_targets_from_frame,
 )
 
-# Workers and simulator
-from .workers import (
+# Software FPGA (depends on golden_reference.py in FPGA cosim tree)
+try:  # noqa: SIM105
+    from .software_fpga import SoftwareFPGA, quantize_raw_iq
+except ImportError:  # golden_reference.py not available (e.g. deployment without FPGA tree)
+    pass
+
+# Replay engine (no PyQt6 dependency, but needs SoftwareFPGA for raw IQ path)
+try:  # noqa: SIM105
+    from .replay import ReplayEngine, ReplayFormat
+except ImportError:  # software_fpga unavailable → replay also unavailable
+    pass
+
+# Workers, map widget, and dashboard require PyQt6 — import lazily so that
+# tests/CI environments without PyQt6 can still access models/hardware/processing.
+try:
+    from .workers import (
         RadarDataWorker,
         GPSDataWorker,
         TargetSimulator,
-    polar_to_geographic,
-)
+        ReplayWorker,
+    )
 
-# Map widget
-from .map_widget import (
+    from .map_widget import (
         MapBridge,
         RadarMapWidget,
-)
+    )
 
-# Main dashboard
-from .dashboard import (
+    from .dashboard import (
         RadarDashboard,
         RangeDopplerCanvas,
-)
+    )
+except ImportError:  # PyQt6 not installed (e.g. CI headless runner)
+    pass
 
 __all__ = [  # noqa: RUF022
     # models
     "RadarTarget", "RadarSettings", "GPSData", "ProcessingConfig", "TileServer",
+    "WaveformConfig",
     "DARK_BG", "DARK_FG", "DARK_ACCENT", "DARK_HIGHLIGHT", "DARK_BORDER",
     "DARK_TEXT", "DARK_BUTTON", "DARK_BUTTON_HOVER",
     "DARK_TREEVIEW", "DARK_TREEVIEW_ALT",
@@ -72,15 +89,18 @@ __all__ = [  # noqa: RUF022
     "USB_AVAILABLE", "FTDI_AVAILABLE", "SCIPY_AVAILABLE",
     "SKLEARN_AVAILABLE", "FILTERPY_AVAILABLE",
     # hardware — production FPGA protocol
-    "FT2232HConnection", "ReplayConnection", "RadarProtocol", "Opcode",
+    "FT2232HConnection", "RadarProtocol", "Opcode",
     "RadarAcquisition", "RadarFrame", "StatusResponse", "DataRecorder",
     "STM32USBInterface",
     # processing
     "RadarProcessor", "USBPacketParser",
-    "apply_pitch_correction",
+    "apply_pitch_correction", "polar_to_geographic",
+    "extract_targets_from_frame",
+    # software FPGA + replay
+    "SoftwareFPGA", "quantize_raw_iq",
+    "ReplayEngine", "ReplayFormat",
     # workers
-    "RadarDataWorker", "GPSDataWorker", "TargetSimulator",
-    "polar_to_geographic",
+    "RadarDataWorker", "GPSDataWorker", "TargetSimulator", "ReplayWorker",
     # map
     "MapBridge", "RadarMapWidget",
     # dashboard

9_Firmware/9_3_GUI/v7/agc_sim.py

@@ -0,0 +1,222 @@
+"""
+v7.agc_sim -- Bit-accurate AGC simulation matching rx_gain_control.v.
+
+Provides stateful, frame-by-frame AGC processing for the Raw IQ Replay
+mode and offline analysis.  All gain encoding, clamping, and attack/decay/
+holdoff logic is identical to the FPGA RTL.
+
+Classes:
+  - AGCState       -- mutable internal AGC state (gain, holdoff counter)
+  - AGCFrameResult -- per-frame AGC metrics after processing
+
+Functions:
+  - signed_to_encoding  -- signed gain (-7..+7) -> 4-bit encoding
+  - encoding_to_signed  -- 4-bit encoding -> signed gain
+  - clamp_gain          -- clamp to [-7, +7]
+  - apply_gain_shift    -- apply gain_shift to 16-bit IQ arrays
+  - process_agc_frame   -- run one frame through AGC, update state
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# FPGA AGC parameters (rx_gain_control.v reset defaults)
+# ---------------------------------------------------------------------------
+AGC_TARGET_DEFAULT = 200   # host_agc_target (8-bit)
+AGC_ATTACK_DEFAULT = 1     # host_agc_attack (4-bit)
+AGC_DECAY_DEFAULT = 1      # host_agc_decay  (4-bit)
+AGC_HOLDOFF_DEFAULT = 4    # host_agc_holdoff (4-bit)
+
+
+# ---------------------------------------------------------------------------
+# Gain encoding helpers (match RTL signed_to_encoding / encoding_to_signed)
+# ---------------------------------------------------------------------------
+
+def signed_to_encoding(g: int) -> int:
+    """Convert signed gain (-7..+7) to gain_shift[3:0] encoding.
+
+    [3]=0, [2:0]=N  ->  amplify  (left shift) by N
+    [3]=1, [2:0]=N  ->  attenuate (right shift) by N
+    """
+    if g >= 0:
+        return g & 0x07
+    return 0x08 | ((-g) & 0x07)
+
+
+def encoding_to_signed(enc: int) -> int:
+    """Convert gain_shift[3:0] encoding to signed gain."""
+    if (enc & 0x08) == 0:
+        return enc & 0x07
+    return -(enc & 0x07)
+
+
+def clamp_gain(val: int) -> int:
+    """Clamp to [-7, +7] (matches RTL clamp_gain function)."""
+    return max(-7, min(7, val))
+
+
+# ---------------------------------------------------------------------------
+# Apply gain shift to IQ data (matches RTL combinational logic)
+# ---------------------------------------------------------------------------
+
+def apply_gain_shift(
+    frame_i: np.ndarray,
+    frame_q: np.ndarray,
+    gain_enc: int,
+) -> tuple[np.ndarray, np.ndarray, int]:
+    """Apply gain_shift encoding to 16-bit signed IQ arrays.
+
+    Returns (shifted_i, shifted_q, overflow_count).
+    Matches the RTL: left shift = amplify, right shift = attenuate,
+    saturate to +/-32767 on overflow.
+    """
+    direction = (gain_enc >> 3) & 1  # 0=amplify, 1=attenuate
+    amount = gain_enc & 0x07
+
+    if amount == 0:
+        return frame_i.copy(), frame_q.copy(), 0
+
+    if direction == 0:
+        # Left shift (amplify)
+        si = frame_i.astype(np.int64) * (1 << amount)
+        sq = frame_q.astype(np.int64) * (1 << amount)
+    else:
+        # Arithmetic right shift (attenuate)
+        si = frame_i.astype(np.int64) >> amount
+        sq = frame_q.astype(np.int64) >> amount
+
+    # Count overflows (post-shift values outside 16-bit signed range)
+    overflow_i = (si > 32767) | (si < -32768)
+    overflow_q = (sq > 32767) | (sq < -32768)
+    overflow_count = int((overflow_i | overflow_q).sum())
+
+    # Saturate to +/-32767
+    si = np.clip(si, -32768, 32767).astype(np.int16)
+    sq = np.clip(sq, -32768, 32767).astype(np.int16)
+
+    return si, sq, overflow_count
+
+
+# ---------------------------------------------------------------------------
+# AGC state and per-frame result dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AGCConfig:
+    """AGC tuning parameters (mirrors FPGA host registers 0x28-0x2C)."""
+
+    enabled: bool = False
+    target: int = AGC_TARGET_DEFAULT    # 8-bit peak target
+    attack: int = AGC_ATTACK_DEFAULT    # 4-bit attenuation step
+    decay: int = AGC_DECAY_DEFAULT      # 4-bit gain-up step
+    holdoff: int = AGC_HOLDOFF_DEFAULT  # 4-bit frames to hold
+
+
+@dataclass
+class AGCState:
+    """Mutable internal AGC state — persists across frames."""
+
+    gain: int = 0                # signed gain, -7..+7
+    holdoff_counter: int = 0     # frames remaining before gain-up allowed
+    was_enabled: bool = False    # tracks enable transitions
+
+
+@dataclass
+class AGCFrameResult:
+    """Per-frame AGC metrics returned by process_agc_frame()."""
+
+    gain_enc: int = 0         # gain_shift[3:0] encoding applied this frame
+    gain_signed: int = 0      # signed gain for display
+    peak_mag_8bit: int = 0    # pre-gain peak magnitude (upper 8 of 15 bits)
+    saturation_count: int = 0  # post-gain overflow count (clamped to 255)
+    overflow_raw: int = 0     # raw overflow count (unclamped)
+    shifted_i: np.ndarray = field(default_factory=lambda: np.array([], dtype=np.int16))
+    shifted_q: np.ndarray = field(default_factory=lambda: np.array([], dtype=np.int16))
+
+
+# ---------------------------------------------------------------------------
+# Per-frame AGC processing (bit-accurate to rx_gain_control.v)
+# ---------------------------------------------------------------------------
+
+def quantize_iq(frame: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Quantize complex IQ to 16-bit signed I and Q arrays.
+
+    Input: 2-D complex array (chirps x samples) — any complex dtype.
+    Output: (frame_i, frame_q) as int16.
+    """
+    frame_i = np.clip(np.round(frame.real), -32768, 32767).astype(np.int16)
+    frame_q = np.clip(np.round(frame.imag), -32768, 32767).astype(np.int16)
+    return frame_i, frame_q
+
+
+def process_agc_frame(
+    frame_i: np.ndarray,
+    frame_q: np.ndarray,
+    config: AGCConfig,
+    state: AGCState,
+) -> AGCFrameResult:
+    """Run one frame through the FPGA AGC inner loop.
+
+    Mutates *state* in place (gain and holdoff_counter).
+    Returns AGCFrameResult with metrics and shifted IQ data.
+
+    Parameters
+    ----------
+    frame_i, frame_q : int16 arrays (any shape, typically chirps x samples)
+    config : AGC tuning parameters
+    state  : mutable AGC state from previous frame
+    """
+    # --- PRE-gain peak measurement (RTL lines 133-135, 211-213) ---
+    abs_i = np.abs(frame_i.astype(np.int32))
+    abs_q = np.abs(frame_q.astype(np.int32))
+    max_iq = np.maximum(abs_i, abs_q)
+    frame_peak_15bit = int(max_iq.max()) if max_iq.size > 0 else 0
+    peak_8bit = (frame_peak_15bit >> 7) & 0xFF
+
+    # --- Handle AGC enable transition (RTL lines 250-253) ---
+    if config.enabled and not state.was_enabled:
+        state.gain = 0
+        state.holdoff_counter = config.holdoff
+    state.was_enabled = config.enabled
+
+    # --- Determine effective gain encoding ---
+    if config.enabled:
+        effective_enc = signed_to_encoding(state.gain)
+    else:
+        effective_enc = signed_to_encoding(state.gain)
+
+    # --- Apply gain shift + count POST-gain overflow ---
+    shifted_i, shifted_q, overflow_raw = apply_gain_shift(
+        frame_i, frame_q, effective_enc)
+    sat_count = min(255, overflow_raw)
+
+    # --- AGC update at frame boundary (RTL lines 226-246) ---
+    if config.enabled:
+        if sat_count > 0:
+            # Clipping: reduce gain immediately (attack)
+            state.gain = clamp_gain(state.gain - config.attack)
+            state.holdoff_counter = config.holdoff
+        elif peak_8bit < config.target:
+            # Signal too weak: increase gain after holdoff
+            if state.holdoff_counter == 0:
+                state.gain = clamp_gain(state.gain + config.decay)
+            else:
+                state.holdoff_counter -= 1
+        else:
+            # Good range (peak >= target, no sat): hold, reset holdoff
+            state.holdoff_counter = config.holdoff
+
+    return AGCFrameResult(
+        gain_enc=effective_enc,
+        gain_signed=state.gain if config.enabled else encoding_to_signed(effective_enc),
+        peak_mag_8bit=peak_8bit,
+        saturation_count=sat_count,
+        overflow_raw=overflow_raw,
+        shifted_i=shifted_i,
+        shifted_q=shifted_q,
+    )

9_Firmware/9_3_GUI/v7/dashboard.py

@@ -1,19 +1,20 @@
 """
 v7.dashboard — Main application window for the PLFM Radar GUI V7.
 
-RadarDashboard is a QMainWindow with five tabs:
+RadarDashboard is a QMainWindow with six tabs:
   1. Main View   — Range-Doppler matplotlib canvas (64x32), device combos,
                    Start/Stop, targets table
   2. Map View    — Embedded Leaflet map + sidebar
-  3. FPGA Control — Full FPGA register control panel (all 22 opcodes,
+  3. FPGA Control — Full FPGA register control panel (all 27 opcodes incl. AGC,
                     bit-width validation, grouped layout matching production)
-  4. Diagnostics — Connection indicators, packet stats, dependency status,
+  4. AGC Monitor — Real-time AGC strip charts (gain, peak magnitude, saturation)
+  5. Diagnostics — Connection indicators, packet stats, dependency status,
                    self-test results, log viewer
-  5. Settings    — Host-side DSP parameters + About section
+  6. Settings    — Host-side DSP parameters + About section
 
 Uses production radar_protocol.py for all FPGA communication:
   - FT2232HConnection for real hardware
-  - ReplayConnection for offline .npy replay
+  - Unified replay via SoftwareFPGA + ReplayEngine + ReplayWorker
   - Mock mode (FT2232HConnection(mock=True)) for development
 
 The old STM32 magic-packet start flow has been removed. FPGA registers
@@ -21,8 +22,12 @@ are controlled directly via 4-byte {opcode, addr, value_hi, value_lo}
 commands sent over FT2232H.
 """
 
+from __future__ import annotations
+
 import time
 import logging
+from collections import deque
+from typing import TYPE_CHECKING
 
 import numpy as np
 
@@ -30,11 +35,11 @@ from PyQt6.QtWidgets import (
     QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QGridLayout,
     QTabWidget, QSplitter, QGroupBox, QFrame, QScrollArea,
     QLabel, QPushButton, QComboBox, QCheckBox,
-    QDoubleSpinBox, QSpinBox, QLineEdit,
+    QDoubleSpinBox, QSpinBox, QLineEdit, QSlider, QFileDialog,
     QTableWidget, QTableWidgetItem, QHeaderView,
     QPlainTextEdit, QStatusBar, QMessageBox,
 )
-from PyQt6.QtCore import Qt, QTimer, pyqtSlot
+from PyQt6.QtCore import Qt, QLocale, QTimer, pyqtSignal, pyqtSlot, QObject
 
 from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg
 from matplotlib.figure import Figure
@@ -50,7 +55,6 @@ from .models import (
 )
 from .hardware import (
     FT2232HConnection,
-    ReplayConnection,
     RadarProtocol,
     RadarFrame,
     StatusResponse,
@@ -58,15 +62,30 @@ from .hardware import (
     STM32USBInterface,
 )
 from .processing import RadarProcessor, USBPacketParser
-from .workers import RadarDataWorker, GPSDataWorker, TargetSimulator
+from .workers import RadarDataWorker, GPSDataWorker, TargetSimulator, ReplayWorker
 from .map_widget import RadarMapWidget
 
+if TYPE_CHECKING:
+    from .software_fpga import SoftwareFPGA
+    from .replay import ReplayEngine
+
 logger = logging.getLogger(__name__)
 
 # Frame dimensions from FPGA
 NUM_RANGE_BINS = 64
 NUM_DOPPLER_BINS = 32
 
+# Force C locale (period as decimal separator) for all QDoubleSpinBox instances.
+_C_LOCALE = QLocale(QLocale.Language.C)
+_C_LOCALE.setNumberOptions(QLocale.NumberOption.RejectGroupSeparator)
+
+
+def _make_dspin() -> QDoubleSpinBox:
+    """Create a QDoubleSpinBox with C locale (no comma decimals)."""
+    sb = QDoubleSpinBox()
+    sb.setLocale(_C_LOCALE)
+    return sb
+
 
 # =============================================================================
 # Range-Doppler Canvas (matplotlib)
@@ -140,6 +159,12 @@ class RadarDashboard(QMainWindow):
         self._gps_worker: GPSDataWorker | None = None
         self._simulator: TargetSimulator | None = None
 
+        # Replay-specific objects (created when entering replay mode)
+        self._replay_worker: ReplayWorker | None = None
+        self._replay_engine: ReplayEngine | None = None
+        self._software_fpga: SoftwareFPGA | None = None
+        self._replay_mode = False
+
         # State
         self._running = False
         self._demo_mode = False
@@ -148,11 +173,20 @@ class RadarDashboard(QMainWindow):
         self._last_status: StatusResponse | None = None
         self._frame_count = 0
         self._gps_packet_count = 0
+        self._last_stats: dict = {}
         self._current_targets: list[RadarTarget] = []
 
         # FPGA control parameter widgets
         self._param_spins: dict = {}  # opcode_hex -> QSpinBox
 
+        # AGC visualization history (ring buffers)
+        self._agc_history_len = 256
+        self._agc_gain_history: deque[int] = deque(maxlen=self._agc_history_len)
+        self._agc_peak_history: deque[int] = deque(maxlen=self._agc_history_len)
+        self._agc_sat_history: deque[int] = deque(maxlen=self._agc_history_len)
+        self._agc_last_redraw: float = 0.0  # throttle chart redraws
+        self._AGC_REDRAW_INTERVAL: float = 0.5  # seconds between redraws
+
         # ---- Build UI ------------------------------------------------------
         self._apply_dark_theme()
         self._setup_ui()
@@ -163,8 +197,10 @@ class RadarDashboard(QMainWindow):
         self._gui_timer.timeout.connect(self._refresh_gui)
         self._gui_timer.start(100)
 
-        # Log handler for diagnostics
-        self._log_handler = _QtLogHandler(self._log_append)
+        # Log handler for diagnostics (thread-safe via Qt signal)
+        self._log_bridge = _LogSignalBridge(self)
+        self._log_bridge.log_message.connect(self._log_append)
+        self._log_handler = _QtLogHandler(self._log_bridge)
         self._log_handler.setLevel(logging.INFO)
         logging.getLogger().addHandler(self._log_handler)
 
@@ -306,6 +342,7 @@ class RadarDashboard(QMainWindow):
         self._create_main_tab()
         self._create_map_tab()
         self._create_fpga_control_tab()
+        self._create_agc_monitor_tab()
         self._create_diagnostics_tab()
         self._create_settings_tab()
 
@@ -327,7 +364,7 @@ class RadarDashboard(QMainWindow):
         # Row 0: connection mode + device combos + buttons
         ctrl_layout.addWidget(QLabel("Mode:"), 0, 0)
         self._mode_combo = QComboBox()
-        self._mode_combo.addItems(["Mock", "Live FT2232H", "Replay (.npy)"])
+        self._mode_combo.addItems(["Mock", "Live FT2232H", "Replay"])
         self._mode_combo.setCurrentIndex(0)
         ctrl_layout.addWidget(self._mode_combo, 0, 1)
 
@@ -376,6 +413,55 @@ class RadarDashboard(QMainWindow):
         self._status_label_main.setAlignment(Qt.AlignmentFlag.AlignRight)
         ctrl_layout.addWidget(self._status_label_main, 1, 5, 1, 5)
 
+        # Row 2: replay transport controls (hidden until replay mode)
+        self._replay_file_label = QLabel("No file loaded")
+        self._replay_file_label.setMinimumWidth(200)
+        ctrl_layout.addWidget(self._replay_file_label, 2, 0, 1, 2)
+
+        self._replay_browse_btn = QPushButton("Browse...")
+        self._replay_browse_btn.clicked.connect(self._browse_replay_file)
+        ctrl_layout.addWidget(self._replay_browse_btn, 2, 2)
+
+        self._replay_play_btn = QPushButton("Play")
+        self._replay_play_btn.clicked.connect(self._replay_play_pause)
+        ctrl_layout.addWidget(self._replay_play_btn, 2, 3)
+
+        self._replay_stop_btn = QPushButton("Stop")
+        self._replay_stop_btn.clicked.connect(self._replay_stop)
+        ctrl_layout.addWidget(self._replay_stop_btn, 2, 4)
+
+        self._replay_slider = QSlider(Qt.Orientation.Horizontal)
+        self._replay_slider.setMinimum(0)
+        self._replay_slider.setMaximum(0)
+        self._replay_slider.valueChanged.connect(self._replay_seek)
+        ctrl_layout.addWidget(self._replay_slider, 2, 5, 1, 2)
+
+        self._replay_frame_label = QLabel("0 / 0")
+        ctrl_layout.addWidget(self._replay_frame_label, 2, 7)
+
+        self._replay_speed_combo = QComboBox()
+        self._replay_speed_combo.addItems(["50 ms", "100 ms", "200 ms", "500 ms"])
+        self._replay_speed_combo.setCurrentIndex(1)
+        self._replay_speed_combo.currentIndexChanged.connect(self._replay_speed_changed)
+        ctrl_layout.addWidget(self._replay_speed_combo, 2, 8)
+
+        self._replay_loop_cb = QCheckBox("Loop")
+        self._replay_loop_cb.stateChanged.connect(self._replay_loop_changed)
+        ctrl_layout.addWidget(self._replay_loop_cb, 2, 9)
+
+        # Collect replay widgets to toggle visibility
+        self._replay_controls = [
+            self._replay_file_label, self._replay_browse_btn,
+            self._replay_play_btn, self._replay_stop_btn,
+            self._replay_slider, self._replay_frame_label,
+            self._replay_speed_combo, self._replay_loop_cb,
+        ]
+        for w in self._replay_controls:
+            w.setVisible(False)
+
+        # Show/hide replay row when mode changes
+        self._mode_combo.currentTextChanged.connect(self._on_mode_changed)
+
         layout.addWidget(ctrl)
 
         # ---- Display area (range-doppler + targets table) ------------------
@@ -392,7 +478,7 @@ class RadarDashboard(QMainWindow):
         self._targets_table_main = QTableWidget()
         self._targets_table_main.setColumnCount(5)
         self._targets_table_main.setHorizontalHeaderLabels([
-            "Range Bin", "Doppler Bin", "Magnitude", "SNR (dB)", "Track ID",
+            "Range (m)", "Velocity (m/s)", "Magnitude", "SNR (dB)", "Track ID",
         ])
         self._targets_table_main.setAlternatingRowColors(True)
         self._targets_table_main.setSelectionBehavior(
@@ -438,19 +524,19 @@ class RadarDashboard(QMainWindow):
         pos_group = QGroupBox("Radar Position")
         pos_layout = QGridLayout(pos_group)
 
-        self._lat_spin = QDoubleSpinBox()
+        self._lat_spin = _make_dspin()
         self._lat_spin.setRange(-90, 90)
         self._lat_spin.setDecimals(6)
         self._lat_spin.setValue(self._radar_position.latitude)
         self._lat_spin.valueChanged.connect(self._on_position_changed)
 
-        self._lon_spin = QDoubleSpinBox()
+        self._lon_spin = _make_dspin()
         self._lon_spin.setRange(-180, 180)
         self._lon_spin.setDecimals(6)
         self._lon_spin.setValue(self._radar_position.longitude)
         self._lon_spin.valueChanged.connect(self._on_position_changed)
 
-        self._alt_spin = QDoubleSpinBox()
+        self._alt_spin = _make_dspin()
         self._alt_spin.setRange(0, 50000)
         self._alt_spin.setDecimals(1)
         self._alt_spin.setValue(0.0)
@@ -469,7 +555,7 @@ class RadarDashboard(QMainWindow):
         cov_group = QGroupBox("Coverage")
         cov_layout = QGridLayout(cov_group)
 
-        self._coverage_spin = QDoubleSpinBox()
+        self._coverage_spin = _make_dspin()
         self._coverage_spin.setRange(1, 200)
         self._coverage_spin.setDecimals(1)
         self._coverage_spin.setValue(self._settings.coverage_radius / 1000)
@@ -681,6 +767,48 @@ class RadarDashboard(QMainWindow):
 
         right_layout.addWidget(grp_cfar)
 
+        # ── AGC (Automatic Gain Control) ──────────────────────────────
+        grp_agc = QGroupBox("AGC (Auto Gain)")
+        agc_layout = QVBoxLayout(grp_agc)
+
+        agc_params = [
+            ("AGC Enable",  0x28,   0,  1, "0=manual, 1=auto"),
+            ("AGC Target",  0x29, 200,  8, "0-255, peak target"),
+            ("AGC Attack",  0x2A,   1,  4, "0-15, atten step"),
+            ("AGC Decay",   0x2B,   1,  4, "0-15, gain-up step"),
+            ("AGC Holdoff", 0x2C,   4,  4, "0-15, frames"),
+        ]
+        for label, opcode, default, bits, hint in agc_params:
+            self._add_fpga_param_row(agc_layout, label, opcode, default, bits, hint)
+
+        # AGC quick toggles
+        agc_row = QHBoxLayout()
+        btn_agc_on = QPushButton("Enable AGC")
+        btn_agc_on.clicked.connect(lambda: self._send_fpga_cmd(0x28, 1))
+        agc_row.addWidget(btn_agc_on)
+        btn_agc_off = QPushButton("Disable AGC")
+        btn_agc_off.clicked.connect(lambda: self._send_fpga_cmd(0x28, 0))
+        agc_row.addWidget(btn_agc_off)
+        agc_layout.addLayout(agc_row)
+
+        # AGC status readback labels
+        agc_st_group = QGroupBox("AGC Status")
+        agc_st_layout = QVBoxLayout(agc_st_group)
+        self._agc_labels: dict[str, QLabel] = {}
+        for name, default_text in [
+            ("enable", "AGC: --"),
+            ("gain",   "Gain: --"),
+            ("peak",   "Peak: --"),
+            ("sat",    "Sat Count: --"),
+        ]:
+            lbl = QLabel(default_text)
+            lbl.setStyleSheet(f"color: {DARK_INFO}; font-size: 10px;")
+            agc_st_layout.addWidget(lbl)
+            self._agc_labels[name] = lbl
+        agc_layout.addWidget(agc_st_group)
+
+        right_layout.addWidget(grp_agc)
+
         # Custom Command
         grp_custom = QGroupBox("Custom Command")
         cust_layout = QGridLayout(grp_custom)
@@ -741,7 +869,122 @@ class RadarDashboard(QMainWindow):
         parent_layout.addLayout(row)
 
     # -----------------------------------------------------------------
-    # TAB 4: Diagnostics
+    # TAB 4: AGC Monitor
+    # -----------------------------------------------------------------
+
+    def _create_agc_monitor_tab(self):
+        """AGC Monitor — real-time strip charts for FPGA inner-loop AGC."""
+        tab = QWidget()
+        layout = QVBoxLayout(tab)
+        layout.setContentsMargins(8, 8, 8, 8)
+
+        # ---- Top indicator row ---------------------------------------------
+        indicator = QFrame()
+        indicator.setStyleSheet(
+            f"background-color: {DARK_ACCENT}; border-radius: 4px;")
+        ind_layout = QHBoxLayout(indicator)
+        ind_layout.setContentsMargins(12, 8, 12, 8)
+
+        self._agc_mode_lbl = QLabel("AGC: --")
+        self._agc_mode_lbl.setStyleSheet(
+            f"color: {DARK_FG}; font-size: 16px; font-weight: bold;")
+        ind_layout.addWidget(self._agc_mode_lbl)
+
+        self._agc_gain_lbl = QLabel("Gain: --")
+        self._agc_gain_lbl.setStyleSheet(
+            f"color: {DARK_INFO}; font-size: 14px;")
+        ind_layout.addWidget(self._agc_gain_lbl)
+
+        self._agc_peak_lbl = QLabel("Peak: --")
+        self._agc_peak_lbl.setStyleSheet(
+            f"color: {DARK_INFO}; font-size: 14px;")
+        ind_layout.addWidget(self._agc_peak_lbl)
+
+        self._agc_sat_total_lbl = QLabel("Total Saturations: 0")
+        self._agc_sat_total_lbl.setStyleSheet(
+            f"color: {DARK_SUCCESS}; font-size: 14px; font-weight: bold;")
+        ind_layout.addWidget(self._agc_sat_total_lbl)
+
+        ind_layout.addStretch()
+        layout.addWidget(indicator)
+
+        # ---- Matplotlib figure with 3 subplots -----------------------------
+        agc_fig = Figure(figsize=(12, 7), facecolor=DARK_BG)
+        agc_fig.subplots_adjust(
+            left=0.07, right=0.96, top=0.95, bottom=0.07,
+            hspace=0.32)
+
+        # Subplot 1: Gain history (4-bit, 0-15)
+        self._agc_ax_gain = agc_fig.add_subplot(3, 1, 1)
+        self._agc_ax_gain.set_facecolor(DARK_ACCENT)
+        self._agc_ax_gain.set_ylabel("Gain Code", color=DARK_FG, fontsize=10)
+        self._agc_ax_gain.set_title(
+            "FPGA Inner-Loop Gain (4-bit)", color=DARK_FG, fontsize=11)
+        self._agc_ax_gain.set_ylim(-0.5, 15.5)
+        self._agc_ax_gain.tick_params(colors=DARK_FG, labelsize=9)
+        self._agc_ax_gain.set_xlim(0, self._agc_history_len)
+        for spine in self._agc_ax_gain.spines.values():
+            spine.set_color(DARK_BORDER)
+        self._agc_gain_line, = self._agc_ax_gain.plot(
+            [], [], color="#89b4fa", linewidth=1.5, label="Gain")
+        self._agc_ax_gain.axhline(y=7.5, color=DARK_WARNING, linestyle="--",
+                                  linewidth=0.8, alpha=0.5, label="Midpoint")
+        self._agc_ax_gain.legend(
+            loc="upper right", fontsize=8,
+            facecolor=DARK_ACCENT, edgecolor=DARK_BORDER,
+            labelcolor=DARK_FG)
+
+        # Subplot 2: Peak magnitude (8-bit, 0-255)
+        self._agc_ax_peak = agc_fig.add_subplot(
+            3, 1, 2, sharex=self._agc_ax_gain)
+        self._agc_ax_peak.set_facecolor(DARK_ACCENT)
+        self._agc_ax_peak.set_ylabel("Peak Mag", color=DARK_FG, fontsize=10)
+        self._agc_ax_peak.set_title(
+            "ADC Peak Magnitude (8-bit)", color=DARK_FG, fontsize=11)
+        self._agc_ax_peak.set_ylim(-5, 260)
+        self._agc_ax_peak.tick_params(colors=DARK_FG, labelsize=9)
+        for spine in self._agc_ax_peak.spines.values():
+            spine.set_color(DARK_BORDER)
+        self._agc_peak_line, = self._agc_ax_peak.plot(
+            [], [], color=DARK_SUCCESS, linewidth=1.5, label="Peak")
+        self._agc_ax_peak.axhline(y=200, color=DARK_WARNING, linestyle="--",
+                                  linewidth=0.8, alpha=0.5,
+                                  label="Target (200)")
+        self._agc_ax_peak.axhspan(240, 255, alpha=0.15, color=DARK_ERROR,
+                                  label="Sat Zone")
+        self._agc_ax_peak.legend(
+            loc="upper right", fontsize=8,
+            facecolor=DARK_ACCENT, edgecolor=DARK_BORDER,
+            labelcolor=DARK_FG)
+
+        # Subplot 3: Saturation count per update (8-bit, 0-255)
+        self._agc_ax_sat = agc_fig.add_subplot(
+            3, 1, 3, sharex=self._agc_ax_gain)
+        self._agc_ax_sat.set_facecolor(DARK_ACCENT)
+        self._agc_ax_sat.set_ylabel("Sat Count", color=DARK_FG, fontsize=10)
+        self._agc_ax_sat.set_xlabel(
+            "Sample (newest right)", color=DARK_FG, fontsize=10)
+        self._agc_ax_sat.set_title(
+            "Saturation Events per Update", color=DARK_FG, fontsize=11)
+        self._agc_ax_sat.set_ylim(-1, 10)
+        self._agc_ax_sat.tick_params(colors=DARK_FG, labelsize=9)
+        for spine in self._agc_ax_sat.spines.values():
+            spine.set_color(DARK_BORDER)
+        self._agc_sat_line, = self._agc_ax_sat.plot(
+            [], [], color=DARK_ERROR, linewidth=1.0, label="Saturation")
+        self._agc_sat_fill_artist = None
+        self._agc_ax_sat.legend(
+            loc="upper right", fontsize=8,
+            facecolor=DARK_ACCENT, edgecolor=DARK_BORDER,
+            labelcolor=DARK_FG)
+
+        self._agc_canvas = FigureCanvasQTAgg(agc_fig)
+        layout.addWidget(self._agc_canvas, stretch=1)
+
+        self._tabs.addTab(tab, "AGC Monitor")
+
+    # -----------------------------------------------------------------
+    # TAB 5: Diagnostics
     # -----------------------------------------------------------------
 
     def _create_diagnostics_tab(self):
@@ -876,7 +1119,7 @@ class RadarDashboard(QMainWindow):
         row += 1
 
         p_layout.addWidget(QLabel("DBSCAN eps:"), row, 0)
-        self._cluster_eps_spin = QDoubleSpinBox()
+        self._cluster_eps_spin = _make_dspin()
         self._cluster_eps_spin.setRange(1.0, 5000.0)
         self._cluster_eps_spin.setDecimals(1)
         self._cluster_eps_spin.setValue(self._processing_config.clustering_eps)
@@ -993,7 +1236,11 @@ class RadarDashboard(QMainWindow):
             logger.error(f"Failed to send FPGA cmd: 0x{opcode:02X}")
 
     def _send_fpga_validated(self, opcode: int, value: int, bits: int):
-        """Clamp value to bit-width and send."""
+        """Clamp value to bit-width and send.
+
+        In replay mode, also dispatch to the SoftwareFPGA setter and
+        re-process the current frame so the user sees immediate effect.
+        """
         max_val = (1 << bits) - 1
         clamped = max(0, min(value, max_val))
         if clamped != value:
@@ -1003,7 +1250,18 @@ class RadarDashboard(QMainWindow):
             key = f"0x{opcode:02X}"
             if key in self._param_spins:
                 self._param_spins[key].setValue(clamped)
+
+        # Dispatch to real FPGA (live/mock mode)
+        if not self._replay_mode:
             self._send_fpga_cmd(opcode, clamped)
+            return
+
+        # Dispatch to SoftwareFPGA (replay mode)
+        if self._software_fpga is not None:
+            self._dispatch_to_software_fpga(opcode, clamped)
+            # Re-process current frame so the effect is visible immediately
+            if self._replay_worker is not None:
+                self._replay_worker.seek(self._replay_worker.current_index)
 
     def _send_custom_command(self):
         """Send custom opcode + value from the FPGA Control tab."""
@@ -1020,36 +1278,112 @@ class RadarDashboard(QMainWindow):
 
     def _start_radar(self):
         """Start radar data acquisition using production protocol."""
+        # Mutual exclusion: stop demo if running
+        if self._demo_mode:
+            self._stop_demo()
+
         try:
             mode = self._mode_combo.currentText()
 
             if "Mock" in mode:
+                self._replay_mode = False
                 self._connection = FT2232HConnection(mock=True)
                 if not self._connection.open():
                     QMessageBox.critical(self, "Error", "Failed to open mock connection.")
                     return
             elif "Live" in mode:
+                self._replay_mode = False
                 self._connection = FT2232HConnection(mock=False)
                 if not self._connection.open():
                     QMessageBox.critical(self, "Error",
                                          "Failed to open FT2232H. Check USB connection.")
                     return
             elif "Replay" in mode:
-                from PyQt6.QtWidgets import QFileDialog
-                npy_dir = QFileDialog.getExistingDirectory(
-                    self, "Select .npy replay directory")
-                if not npy_dir:
+                self._replay_mode = True
+                replay_path = self._replay_file_label.text()
+                if replay_path == "No file loaded" or not replay_path:
+                    QMessageBox.warning(
+                        self, "Replay",
+                        "Use 'Browse...' to select a replay"
+                        " file or directory first.")
                     return
-                self._connection = ReplayConnection(npy_dir)
-                if not self._connection.open():
-                    QMessageBox.critical(self, "Error",
-                                         "Failed to open replay connection.")
+
+                from .software_fpga import SoftwareFPGA
+                from .replay import ReplayEngine
+
+                self._software_fpga = SoftwareFPGA()
+                # Enable CFAR by default for raw IQ replay (avoids 2000+ detections)
+                self._software_fpga.set_cfar_enable(True)
+
+                try:
+                    self._replay_engine = ReplayEngine(
+                        replay_path, self._software_fpga)
+                except (OSError, ValueError, RuntimeError) as exc:
+                    QMessageBox.critical(self, "Replay Error",
+                                         f"Failed to open replay data:\n{exc}")
+                    self._software_fpga = None
+                    return
+
+                if self._replay_engine.total_frames == 0:
+                    QMessageBox.warning(self, "Replay", "No frames found in the selected source.")
+                    self._replay_engine.close()
+                    self._replay_engine = None
+                    self._software_fpga = None
+                    return
+
+                speed_map = {0: 50, 1: 100, 2: 200, 3: 500}
+                interval = speed_map.get(self._replay_speed_combo.currentIndex(), 100)
+
+                self._replay_worker = ReplayWorker(
+                    replay_engine=self._replay_engine,
+                    settings=self._settings,
+                    gps=self._radar_position,
+                    frame_interval_ms=interval,
+                )
+                self._replay_worker.frameReady.connect(self._on_frame_ready)
+                self._replay_worker.targetsUpdated.connect(self._on_radar_targets)
+                self._replay_worker.statsUpdated.connect(self._on_radar_stats)
+                self._replay_worker.errorOccurred.connect(self._on_worker_error)
+                self._replay_worker.playbackStateChanged.connect(
+                    self._on_playback_state_changed)
+                self._replay_worker.frameIndexChanged.connect(
+                    self._on_frame_index_changed)
+                self._replay_worker.set_loop(self._replay_loop_cb.isChecked())
+
+                self._replay_slider.setMaximum(
+                    self._replay_engine.total_frames - 1)
+                self._replay_slider.setValue(0)
+                self._replay_frame_label.setText(
+                    f"0 / {self._replay_engine.total_frames}")
+
+                self._replay_worker.start()
+                # Update CFAR enable spinbox to reflect default-on for replay
+                if "0x25" in self._param_spins:
+                    self._param_spins["0x25"].setValue(1)
+
+                # UI state
+                self._running = True
+                self._start_time = time.time()
+                self._frame_count = 0
+                self._start_btn.setEnabled(False)
+                self._stop_btn.setEnabled(True)
+                self._mode_combo.setEnabled(False)
+                self._demo_btn_main.setEnabled(False)
+                self._demo_btn_map.setEnabled(False)
+                n_frames = self._replay_engine.total_frames
+                self._status_label_main.setText(
+                    f"Status: Replay ({n_frames} frames)")
+                self._sb_status.setText(f"Replay ({n_frames} frames)")
+                self._sb_mode.setText("Replay")
+                logger.info(
+                    "Replay started: %s (%d frames)",
+                    replay_path, n_frames)
                 return
             else:
                 QMessageBox.warning(self, "Warning", "Unknown connection mode.")
                 return
 
-            # Start radar worker
+            # Start radar worker (mock / live — NOT replay)
             self._radar_worker = RadarDataWorker(
                 connection=self._connection,
                 processor=self._processor,
@@ -1083,6 +1417,8 @@ class RadarDashboard(QMainWindow):
             self._start_btn.setEnabled(False)
             self._stop_btn.setEnabled(True)
             self._mode_combo.setEnabled(False)
+            self._demo_btn_main.setEnabled(False)
+            self._demo_btn_map.setEnabled(False)
             self._status_label_main.setText(f"Status: Running ({mode})")
             self._sb_status.setText(f"Running ({mode})")
             self._sb_mode.setText(mode)
@@ -1100,6 +1436,18 @@ class RadarDashboard(QMainWindow):
             self._radar_worker.wait(2000)
             self._radar_worker = None
 
+        if self._replay_worker:
+            self._replay_worker.stop()
+            self._replay_worker.wait(2000)
+            self._replay_worker = None
+
+        if self._replay_engine:
+            self._replay_engine.close()
+            self._replay_engine = None
+
+        self._software_fpga = None
+        self._replay_mode = False
+
         if self._gps_worker:
             self._gps_worker.stop()
             self._gps_worker.wait(2000)
@@ -1114,11 +1462,120 @@ class RadarDashboard(QMainWindow):
         self._start_btn.setEnabled(True)
         self._stop_btn.setEnabled(False)
         self._mode_combo.setEnabled(True)
+        self._demo_btn_main.setEnabled(True)
+        self._demo_btn_map.setEnabled(True)
         self._status_label_main.setText("Status: Radar stopped")
         self._sb_status.setText("Radar stopped")
         self._sb_mode.setText("Idle")
         logger.info("Radar system stopped")
 
+    # =====================================================================
+    # Replay helpers
+    # =====================================================================
+
+    def _on_mode_changed(self, text: str):
+        """Show/hide replay transport controls based on mode selection."""
+        is_replay = "Replay" in text
+        for w in self._replay_controls:
+            w.setVisible(is_replay)
+
+    def _browse_replay_file(self):
+        """Open file/directory picker for replay source."""
+        path, _ = QFileDialog.getOpenFileName(
+            self, "Select replay file",
+            "",
+            "All supported (*.npy *.h5);;NumPy files (*.npy);;HDF5 files (*.h5);;All files (*)",
+        )
+        if path:
+            self._replay_file_label.setText(path)
+            return
+        # If no file selected, try directory (for co-sim)
+        dir_path = QFileDialog.getExistingDirectory(
+            self, "Select co-sim replay directory")
+        if dir_path:
+            self._replay_file_label.setText(dir_path)
+
+    def _replay_play_pause(self):
+        """Toggle play/pause on the replay worker."""
+        if self._replay_worker is None:
+            return
+        if self._replay_worker.is_playing:
+            self._replay_worker.pause()
+            self._replay_play_btn.setText("Play")
+        else:
+            self._replay_worker.play()
+            self._replay_play_btn.setText("Pause")
+
+    def _replay_stop(self):
+        """Stop replay playback (keeps data loaded)."""
+        if self._replay_worker is not None:
+            self._replay_worker.pause()
+            self._replay_worker.seek(0)
+            self._replay_play_btn.setText("Play")
+
+    def _replay_seek(self, value: int):
+        """Seek to a specific frame from the slider."""
+        if self._replay_worker is not None and not self._replay_worker.is_playing:
+            self._replay_worker.seek(value)
+
+    def _replay_speed_changed(self, index: int):
+        """Update replay frame interval from speed combo."""
+        speed_map = {0: 50, 1: 100, 2: 200, 3: 500}
+        ms = speed_map.get(index, 100)
+        if self._replay_worker is not None:
+            self._replay_worker.set_frame_interval(ms)
+
+    def _replay_loop_changed(self, state: int):
+        """Update replay loop setting."""
+        if self._replay_worker is not None:
+            self._replay_worker.set_loop(state == Qt.CheckState.Checked.value)
+
+    @pyqtSlot(str)
+    def _on_playback_state_changed(self, state: str):
+        """Update UI when replay playback state changes."""
+        if state == "playing":
+            self._replay_play_btn.setText("Pause")
+        elif state in ("paused", "stopped"):
+            self._replay_play_btn.setText("Play")
+        if state == "stopped" and self._replay_worker is not None:
+            self._status_label_main.setText("Status: Replay finished")
+
+    @pyqtSlot(int, int)
+    def _on_frame_index_changed(self, current: int, total: int):
+        """Update slider and frame label from replay worker."""
+        self._replay_slider.blockSignals(True)
+        self._replay_slider.setValue(current)
+        self._replay_slider.blockSignals(False)
+        self._replay_frame_label.setText(f"{current} / {total}")
+
+    def _dispatch_to_software_fpga(self, opcode: int, value: int):
+        """Route an FPGA opcode+value to the SoftwareFPGA setter."""
+        fpga = self._software_fpga
+        if fpga is None:
+            return
+        _opcode_dispatch = {
+            0x03: lambda v: fpga.set_detect_threshold(v),
+            0x16: lambda v: fpga.set_gain_shift(v),
+            0x21: lambda v: fpga.set_cfar_guard(v),
+            0x22: lambda v: fpga.set_cfar_train(v),
+            0x23: lambda v: fpga.set_cfar_alpha(v),
+            0x24: lambda v: fpga.set_cfar_mode(v),
+            0x25: lambda v: fpga.set_cfar_enable(bool(v)),
+            0x26: lambda v: fpga.set_mti_enable(bool(v)),
+            0x27: lambda v: fpga.set_dc_notch_width(v),
+            0x28: lambda v: fpga.set_agc_enable(bool(v)),
+            0x29: lambda v: fpga.set_agc_params(target=v),
+            0x2A: lambda v: fpga.set_agc_params(attack=v),
+            0x2B: lambda v: fpga.set_agc_params(decay=v),
+            0x2C: lambda v: fpga.set_agc_params(holdoff=v),
+        }
+        handler = _opcode_dispatch.get(opcode)
+        if handler is not None:
+            handler(value)
+            logger.info(f"SoftwareFPGA: 0x{opcode:02X} = {value}")
+        else:
+            logger.debug(f"SoftwareFPGA: opcode 0x{opcode:02X} not handled (no-op)")
+
     # =====================================================================
     # Demo mode
     # =====================================================================
@@ -1126,6 +1583,10 @@ class RadarDashboard(QMainWindow):
     def _start_demo(self):
         if self._simulator:
             return
+        # Mutual exclusion: do not start demo while radar/replay is running
+        if self._running:
+            logger.warning("Cannot start demo while radar is running")
+            return
         self._simulator = TargetSimulator(self._radar_position, self)
         self._simulator.targetsUpdated.connect(self._on_demo_targets)
         self._simulator.start(500)
@@ -1142,7 +1603,13 @@ class RadarDashboard(QMainWindow):
             self._simulator.stop()
             self._simulator = None
         self._demo_mode = False
-        self._sb_mode.setText("Idle" if not self._running else "Live")
+        if not self._running:
+            mode = "Idle"
+        elif self._replay_mode:
+            mode = "Replay"
+        else:
+            mode = "Live"
+        self._sb_mode.setText(mode)
         self._sb_status.setText("Demo stopped")
         self._demo_btn_main.setText("Start Demo")
         self._demo_btn_map.setText("Start Demo")
@@ -1189,7 +1656,7 @@ class RadarDashboard(QMainWindow):
 
     @pyqtSlot(dict)
     def _on_radar_stats(self, stats: dict):
-        pass  # Stats are displayed in _refresh_gui
+        self._last_stats = stats
 
     @pyqtSlot(str)
     def _on_worker_error(self, msg: str):
@@ -1276,6 +1743,97 @@ class RadarDashboard(QMainWindow):
             self._st_labels["t4"].setText(
                 f"T4 ADC:  {'PASS' if flags & 0x10 else 'FAIL'}")
 
+        # AGC status readback
+        if hasattr(self, '_agc_labels'):
+            agc_str = "AUTO" if st.agc_enable else "MANUAL"
+            agc_color = DARK_SUCCESS if st.agc_enable else DARK_INFO
+            self._agc_labels["enable"].setStyleSheet(
+                f"color: {agc_color}; font-weight: bold;")
+            self._agc_labels["enable"].setText(f"AGC: {agc_str}")
+            self._agc_labels["gain"].setText(
+                f"Gain: {st.agc_current_gain}")
+            self._agc_labels["peak"].setText(
+                f"Peak: {st.agc_peak_magnitude}")
+            sat_color = DARK_ERROR if st.agc_saturation_count > 0 else DARK_INFO
+            self._agc_labels["sat"].setStyleSheet(
+                f"color: {sat_color}; font-weight: bold;")
+            self._agc_labels["sat"].setText(
+                f"Sat Count: {st.agc_saturation_count}")
+
+        # AGC Monitor tab visualization
+        self._update_agc_visualization(st)
+
+    def _update_agc_visualization(self, st: StatusResponse):
+        """Push AGC metrics into ring buffers and redraw AGC Monitor charts.
+
+        Data is always accumulated (cheap), but matplotlib redraws are
+        throttled to ``_AGC_REDRAW_INTERVAL`` seconds to avoid saturating
+        the GUI event-loop when status packets arrive at 20 Hz.
+        """
+        if not hasattr(self, '_agc_canvas'):
+            return
+
+        # Push data into ring buffers (always — O(1))
+        self._agc_gain_history.append(st.agc_current_gain)
+        self._agc_peak_history.append(st.agc_peak_magnitude)
+        self._agc_sat_history.append(st.agc_saturation_count)
+
+        # Update indicator labels (cheap Qt calls)
+        agc_str = "AUTO" if st.agc_enable else "MANUAL"
+        agc_color = DARK_SUCCESS if st.agc_enable else DARK_INFO
+        self._agc_mode_lbl.setStyleSheet(
+            f"color: {agc_color}; font-size: 16px; font-weight: bold;")
+        self._agc_mode_lbl.setText(f"AGC: {agc_str}")
+        self._agc_gain_lbl.setText(f"Gain: {st.agc_current_gain}")
+        self._agc_peak_lbl.setText(f"Peak: {st.agc_peak_magnitude}")
+
+        total_sat = sum(self._agc_sat_history)
+        if total_sat > 10:
+            sat_color = DARK_ERROR
+        elif total_sat > 0:
+            sat_color = DARK_WARNING
+        else:
+            sat_color = DARK_SUCCESS
+        self._agc_sat_total_lbl.setStyleSheet(
+            f"color: {sat_color}; font-size: 14px; font-weight: bold;")
+        self._agc_sat_total_lbl.setText(f"Total Saturations: {total_sat}")
+
+        # ---- Throttle matplotlib redraws ---------------------------------
+        now = time.monotonic()
+        if now - self._agc_last_redraw < self._AGC_REDRAW_INTERVAL:
+            return
+        self._agc_last_redraw = now
+
+        n = len(self._agc_gain_history)
+        xs = list(range(n))
+
+        # Update line plots
+        gain_data = list(self._agc_gain_history)
+        peak_data = list(self._agc_peak_history)
+        sat_data = list(self._agc_sat_history)
+
+        self._agc_gain_line.set_data(xs, gain_data)
+        self._agc_peak_line.set_data(xs, peak_data)
+        self._agc_sat_line.set_data(xs, sat_data)
+
+        # Update saturation fill
+        if self._agc_sat_fill_artist is not None:
+            self._agc_sat_fill_artist.remove()
+        if n > 0:
+            self._agc_sat_fill_artist = self._agc_ax_sat.fill_between(
+                xs, sat_data, color=DARK_ERROR, alpha=0.4)
+        else:
+            self._agc_sat_fill_artist = None
+
+        # Auto-scale saturation y-axis
+        max_sat = max(sat_data) if sat_data else 1
+        self._agc_ax_sat.set_ylim(-1, max(max_sat * 1.3, 5))
+
+        # Scroll x-axis
+        self._agc_ax_gain.set_xlim(max(0, n - self._agc_history_len), n)
+
+        self._agc_canvas.draw_idle()
+
     # =====================================================================
     # Position / coverage callbacks (map sidebar)
     # =====================================================================
@@ -1409,7 +1967,7 @@ class RadarDashboard(QMainWindow):
             str(self._frame_count),
             str(det),
             str(gps_count),
-            "0",  # errors
+            str(self._last_stats.get("errors", 0)),
             f"{uptime:.0f}s",
             f"{frame_rate:.1f}/s",
         ]
@@ -1460,15 +2018,22 @@ class RadarDashboard(QMainWindow):
 
 
 # =============================================================================
-# Qt-compatible log handler (routes Python logging -> QTextEdit)
+# Qt-compatible log handler (routes Python logging -> QTextEdit via signal)
 # =============================================================================
 
-class _QtLogHandler(logging.Handler):
-    """Sends log records to a callback (called on the thread that emitted)."""
 
-    def __init__(self, callback):
+class _LogSignalBridge(QObject):
+    """Thread-safe bridge: emits a Qt signal so the slot runs on the GUI thread."""
+
+    log_message = pyqtSignal(str)
+
+
+class _QtLogHandler(logging.Handler):
+    """Sends log records to a QObject signal (safe from any thread)."""
+
+    def __init__(self, bridge: _LogSignalBridge):
         super().__init__()
-        self._callback = callback
+        self._bridge = bridge
         self.setFormatter(logging.Formatter(
             "%(asctime)s  %(levelname)-8s  %(message)s",
             datefmt="%H:%M:%S",
@@ -1477,6 +2042,6 @@ class _QtLogHandler(logging.Handler):
     def emit(self, record):
         try:
             msg = self.format(record)
-            self._callback(msg)
+            self._bridge.log_message.emit(msg)
         except RuntimeError:
             pass

9_Firmware/9_3_GUI/v7/hardware.py

@@ -3,14 +3,11 @@ v7.hardware — Hardware interface classes for the PLFM Radar GUI V7.
 
 Provides:
   - FT2232H radar data + command interface via production radar_protocol module
-  - ReplayConnection for offline .npy replay via production radar_protocol module
   - STM32USBInterface for GPS data only (USB CDC)
 
 The FT2232H interface uses the production protocol layer (radar_protocol.py)
 which sends 4-byte {opcode, addr, value_hi, value_lo} register commands and
-parses 0xAA data / 0xBB status packets from the FPGA. The old magic-packet
-and 'SET'...'END' binary settings protocol has been removed — it was
-incompatible with the FPGA register interface.
+parses 0xAA data / 0xBB status packets from the FPGA.
 """
 
 import sys
@@ -28,7 +25,6 @@ if USB_AVAILABLE:
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 from radar_protocol import (  # noqa: F401 — re-exported for v7 package
     FT2232HConnection,
-    ReplayConnection,
     RadarProtocol,
     Opcode,
     RadarAcquisition,

9_Firmware/9_3_GUI/v7/map_widget.py

@@ -17,7 +17,8 @@ from PyQt6.QtWidgets import (
     QWidget, QVBoxLayout, QHBoxLayout, QFrame,
     QComboBox, QCheckBox, QPushButton, QLabel,
 )
-from PyQt6.QtCore import Qt, pyqtSignal, pyqtSlot, QObject
+from PyQt6.QtCore import Qt, QUrl, pyqtSignal, pyqtSlot, QObject
+from PyQt6.QtWebEngineCore import QWebEngineSettings
 from PyQt6.QtWebEngineWidgets import QWebEngineView
 from PyQt6.QtWebChannel import QWebChannel
 
@@ -517,8 +518,20 @@ document.addEventListener('DOMContentLoaded', function() {{
     # ---- load / helpers ----------------------------------------------------
 
     def _load_map(self):
-        self._web_view.setHtml(self._get_map_html())
-        logger.info("Leaflet map HTML loaded")
+        # Enable remote resource access so Leaflet CDN scripts/tiles can load.
+        settings = self._web_view.page().settings()
+        settings.setAttribute(
+            QWebEngineSettings.WebAttribute.LocalContentCanAccessRemoteUrls,
+            True,
+        )
+        # Provide an HTTP base URL so the page has a proper origin;
+        # without this, setHtml() defaults to about:blank which blocks
+        # external resource loading in modern Chromium.
+        self._web_view.setHtml(
+            self._get_map_html(),
+            QUrl("http://localhost/radar_map"),
+        )
+        logger.info("Leaflet map HTML loaded (with HTTP base URL)")
 
     def _on_map_ready(self):
         self._status_label.setText(f"Map ready - {len(self._targets)} targets")

9_Firmware/9_3_GUI/v7/models.py

@@ -186,3 +186,59 @@ class TileServer(Enum):
     GOOGLE_SATELLITE = "google_sat"
     GOOGLE_HYBRID = "google_hybrid"
     ESRI_SATELLITE = "esri_sat"
+
+
+# ---------------------------------------------------------------------------
+# Waveform configuration (physical parameters for bin→unit conversion)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class WaveformConfig:
+    """Physical waveform parameters for converting bins to SI units.
+
+    Encapsulates the radar waveform so that range/velocity resolution
+    can be derived automatically instead of hardcoded in RadarSettings.
+
+    Defaults match the ADI CN0566 Phaser capture parameters used in
+    the golden_reference cosim (4 MSPS, 500 MHz BW, 300 us chirp).
+    """
+
+    sample_rate_hz: float = 4e6          # ADC sample rate
+    bandwidth_hz: float = 500e6          # Chirp bandwidth
+    chirp_duration_s: float = 300e-6     # Chirp ramp time
+    center_freq_hz: float = 10.525e9     # Carrier frequency
+    n_range_bins: int = 64               # After decimation
+    n_doppler_bins: int = 32             # After Doppler FFT
+    fft_size: int = 1024                 # Pre-decimation FFT length
+    decimation_factor: int = 16          # 1024 → 64
+
+    @property
+    def range_resolution_m(self) -> float:
+        """Meters per decimated range bin (FMCW deramped baseband).
+
+        For deramped FMCW: bin spacing = c * Fs * T / (2 * N_FFT * BW).
+        After decimation the bin spacing grows by *decimation_factor*.
+        """
+        c = 299_792_458.0
+        raw_bin = (
+            c * self.sample_rate_hz * self.chirp_duration_s
+            / (2.0 * self.fft_size * self.bandwidth_hz)
+        )
+        return raw_bin * self.decimation_factor
+
+    @property
+    def velocity_resolution_mps(self) -> float:
+        """m/s per Doppler bin.  lambda / (2 * n_doppler * chirp_duration)."""
+        c = 299_792_458.0
+        wavelength = c / self.center_freq_hz
+        return wavelength / (2.0 * self.n_doppler_bins * self.chirp_duration_s)
+
+    @property
+    def max_range_m(self) -> float:
+        """Maximum unambiguous range in meters."""
+        return self.range_resolution_m * self.n_range_bins
+
+    @property
+    def max_velocity_mps(self) -> float:
+        """Maximum unambiguous velocity (±) in m/s."""
+        return self.velocity_resolution_mps * self.n_doppler_bins / 2.0

9_Firmware/9_3_GUI/v7/processing.py

@@ -451,3 +451,103 @@ class USBPacketParser:
         except (ValueError, struct.error) as e:
             logger.error(f"Error parsing binary GPS: {e}")
             return None
+
+
+# ============================================================================
+# Utility: polar → geographic coordinate conversion
+# ============================================================================
+
+def polar_to_geographic(
+    radar_lat: float,
+    radar_lon: float,
+    range_m: float,
+    azimuth_deg: float,
+) -> tuple:
+    """Convert polar (range, azimuth) relative to radar → (lat, lon).
+
+    azimuth_deg: 0 = North, clockwise.
+    """
+    r_earth = 6_371_000.0  # Earth radius in metres
+
+    lat1 = math.radians(radar_lat)
+    lon1 = math.radians(radar_lon)
+    bearing = math.radians(azimuth_deg)
+
+    lat2 = math.asin(
+        math.sin(lat1) * math.cos(range_m / r_earth)
+        + math.cos(lat1) * math.sin(range_m / r_earth) * math.cos(bearing)
+    )
+    lon2 = lon1 + math.atan2(
+        math.sin(bearing) * math.sin(range_m / r_earth) * math.cos(lat1),
+        math.cos(range_m / r_earth) - math.sin(lat1) * math.sin(lat2),
+    )
+    return (math.degrees(lat2), math.degrees(lon2))
+
+
+# ============================================================================
+# Shared target extraction (used by both RadarDataWorker and ReplayWorker)
+# ============================================================================
+
+def extract_targets_from_frame(
+    frame,
+    range_resolution: float = 1.0,
+    velocity_resolution: float = 1.0,
+    gps: GPSData | None = None,
+) -> list[RadarTarget]:
+    """Extract RadarTarget list from a RadarFrame's detection mask.
+
+    This is the bin-to-physical conversion + geo-mapping shared between
+    the live and replay data paths.
+
+    Parameters
+    ----------
+    frame : RadarFrame
+        Frame with populated ``detections``, ``magnitude``, ``range_doppler_i/q``.
+    range_resolution : float
+        Meters per range bin.
+    velocity_resolution : float
+        m/s per Doppler bin.
+    gps : GPSData | None
+        GPS position for geo-mapping (latitude/longitude).
+
+    Returns
+    -------
+    list[RadarTarget]
+        One target per detection cell.
+    """
+    det_indices = np.argwhere(frame.detections > 0)
+    n_doppler = frame.detections.shape[1] if frame.detections.ndim == 2 else 32
+    doppler_center = n_doppler // 2
+
+    targets: list[RadarTarget] = []
+    for idx in det_indices:
+        rbin, dbin = int(idx[0]), int(idx[1])
+        mag = float(frame.magnitude[rbin, dbin])
+        snr = 10.0 * math.log10(max(mag, 1.0)) if mag > 0 else 0.0
+
+        range_m = float(rbin) * range_resolution
+        velocity_ms = float(dbin - doppler_center) * velocity_resolution
+
+        lat, lon, azimuth, elevation = 0.0, 0.0, 0.0, 0.0
+        if gps is not None:
+            azimuth = gps.heading
+            # Spread detections across ±15° sector for single-beam radar
+            if len(det_indices) > 1:
+                spread = (dbin - doppler_center) / max(doppler_center, 1) * 15.0
+                azimuth = gps.heading + spread
+            lat, lon = polar_to_geographic(
+                gps.latitude, gps.longitude, range_m, azimuth,
+            )
+
+        targets.append(RadarTarget(
+            id=len(targets),
+            range=range_m,
+            velocity=velocity_ms,
+            azimuth=azimuth,
+            elevation=elevation,
+            latitude=lat,
+            longitude=lon,
+            snr=snr,
+            timestamp=frame.timestamp,
+        ))
+    return targets

9_Firmware/9_3_GUI/v7/replay.py

@@ -0,0 +1,288 @@
+"""
+v7.replay — ReplayEngine: auto-detect format, load, and iterate RadarFrames.
+
+Supports three data sources:
+  1. **FPGA co-sim directory** — pre-computed ``.npy`` files from golden_reference
+  2. **Raw IQ cube** ``.npy`` — complex baseband capture (e.g. ADI Phaser)
+  3. **HDF5 recording** ``.h5`` — frames captured by ``DataRecorder``
+
+For raw IQ data the engine uses :class:`SoftwareFPGA` to run the full
+bit-accurate signal chain, so changing FPGA control registers in the
+dashboard re-processes the data.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from enum import Enum, auto
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from .software_fpga import SoftwareFPGA
+
+# radar_protocol is a sibling module (not inside v7/)
+import sys as _sys
+
+_GUI_DIR = str(Path(__file__).resolve().parent.parent)
+if _GUI_DIR not in _sys.path:
+    _sys.path.insert(0, _GUI_DIR)
+from radar_protocol import RadarFrame  # noqa: E402
+
+log = logging.getLogger(__name__)
+
+# Lazy import — h5py is optional
+try:
+    import h5py
+
+    HDF5_AVAILABLE = True
+except ImportError:
+    HDF5_AVAILABLE = False
+
+
+class ReplayFormat(Enum):
+    """Detected input format."""
+
+    COSIM_DIR = auto()
+    RAW_IQ_NPY = auto()
+    HDF5 = auto()
+
+
+# ───────────────────────────────────────────────────────────────────
+# Format detection
+# ───────────────────────────────────────────────────────────────────
+
+_COSIM_REQUIRED = {"doppler_map_i.npy", "doppler_map_q.npy"}
+
+
+def detect_format(path: str) -> ReplayFormat:
+    """Auto-detect the replay data format from *path*.
+
+    Raises
+    ------
+    ValueError
+        If the format cannot be determined.
+    """
+    p = Path(path)
+
+    if p.is_dir():
+        children = {f.name for f in p.iterdir()}
+        if _COSIM_REQUIRED.issubset(children):
+            return ReplayFormat.COSIM_DIR
+        msg = f"Directory {p} does not contain required co-sim files: {_COSIM_REQUIRED - children}"
+        raise ValueError(msg)
+
+    if p.suffix == ".h5":
+        return ReplayFormat.HDF5
+
+    if p.suffix == ".npy":
+        return ReplayFormat.RAW_IQ_NPY
+
+    msg = f"Cannot determine replay format for: {p}"
+    raise ValueError(msg)
+
+
+# ───────────────────────────────────────────────────────────────────
+# ReplayEngine
+# ───────────────────────────────────────────────────────────────────
+
+class ReplayEngine:
+    """Load replay data and serve RadarFrames on demand.
+
+    Parameters
+    ----------
+    path : str
+        File or directory path to load.
+    software_fpga : SoftwareFPGA | None
+        Required only for ``RAW_IQ_NPY`` format.  For other formats the
+        data is already processed and the FPGA instance is ignored.
+    """
+
+    def __init__(self, path: str, software_fpga: SoftwareFPGA | None = None) -> None:
+        self.path = path
+        self.fmt = detect_format(path)
+        self.software_fpga = software_fpga
+
+        # Populated by _load_*
+        self._total_frames: int = 0
+        self._raw_iq: np.ndarray | None = None   # for RAW_IQ_NPY
+        self._h5_file = None
+        self._h5_keys: list[str] = []
+        self._cosim_frame = None  # single RadarFrame for co-sim
+
+        self._load()
+
+    # ------------------------------------------------------------------
+    # Loading
+    # ------------------------------------------------------------------
+
+    def _load(self) -> None:
+        if self.fmt is ReplayFormat.COSIM_DIR:
+            self._load_cosim()
+        elif self.fmt is ReplayFormat.RAW_IQ_NPY:
+            self._load_raw_iq()
+        elif self.fmt is ReplayFormat.HDF5:
+            self._load_hdf5()
+
+    def _load_cosim(self) -> None:
+        """Load FPGA co-sim directory (already-processed .npy arrays).
+
+        Prefers fullchain (MTI-enabled) files when CFAR outputs are present,
+        so that I/Q data is consistent with the detection mask.  Falls back
+        to the non-MTI ``doppler_map`` files when fullchain data is absent.
+        """
+        d = Path(self.path)
+
+        # CFAR outputs (from the MTI→Doppler→DC-notch→CFAR chain)
+        cfar_flags = d / "fullchain_cfar_flags.npy"
+        cfar_mag = d / "fullchain_cfar_mag.npy"
+        has_cfar = cfar_flags.exists() and cfar_mag.exists()
+
+        # MTI-consistent I/Q (same chain that produced CFAR outputs)
+        mti_dop_i = d / "fullchain_mti_doppler_i.npy"
+        mti_dop_q = d / "fullchain_mti_doppler_q.npy"
+        has_mti_doppler = mti_dop_i.exists() and mti_dop_q.exists()
+
+        # Choose I/Q: prefer MTI-chain when CFAR data comes from that chain
+        if has_cfar and has_mti_doppler:
+            dop_i = np.load(mti_dop_i).astype(np.int16)
+            dop_q = np.load(mti_dop_q).astype(np.int16)
+            log.info("Co-sim: using fullchain MTI+Doppler I/Q (matches CFAR chain)")
+        else:
+            dop_i = np.load(d / "doppler_map_i.npy").astype(np.int16)
+            dop_q = np.load(d / "doppler_map_q.npy").astype(np.int16)
+            log.info("Co-sim: using non-MTI doppler_map I/Q")
+
+        frame = RadarFrame()
+        frame.range_doppler_i = dop_i
+        frame.range_doppler_q = dop_q
+
+        if has_cfar:
+            frame.detections = np.load(cfar_flags).astype(np.uint8)
+            frame.magnitude = np.load(cfar_mag).astype(np.float64)
+        else:
+            frame.magnitude = np.sqrt(
+                dop_i.astype(np.float64) ** 2 + dop_q.astype(np.float64) ** 2
+            )
+            frame.detections = np.zeros_like(dop_i, dtype=np.uint8)
+
+        frame.range_profile = frame.magnitude[:, 0]
+        frame.detection_count = int(frame.detections.sum())
+        frame.frame_number = 0
+        frame.timestamp = time.time()
+
+        self._cosim_frame = frame
+        self._total_frames = 1
+        log.info("Loaded co-sim directory: %s (1 frame)", self.path)
+
+    def _load_raw_iq(self) -> None:
+        """Load raw complex IQ cube (.npy)."""
+        data = np.load(self.path, mmap_mode="r")
+        if data.ndim == 2:
+            # (chirps, samples) — single frame
+            data = data[np.newaxis, ...]
+        if data.ndim != 3:
+            msg = f"Expected 3-D array (frames, chirps, samples), got shape {data.shape}"
+            raise ValueError(msg)
+        self._raw_iq = data
+        self._total_frames = data.shape[0]
+        log.info(
+            "Loaded raw IQ: %s, shape %s (%d frames)",
+            self.path,
+            data.shape,
+            self._total_frames,
+        )
+
+    def _load_hdf5(self) -> None:
+        """Load HDF5 recording (.h5)."""
+        if not HDF5_AVAILABLE:
+            msg = "h5py is required to load HDF5 recordings"
+            raise ImportError(msg)
+        self._h5_file = h5py.File(self.path, "r")
+        frames_grp = self._h5_file.get("frames")
+        if frames_grp is None:
+            msg = f"HDF5 file {self.path} has no 'frames' group"
+            raise ValueError(msg)
+        self._h5_keys = sorted(frames_grp.keys())
+        self._total_frames = len(self._h5_keys)
+        log.info("Loaded HDF5: %s (%d frames)", self.path, self._total_frames)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def total_frames(self) -> int:
+        return self._total_frames
+
+    def get_frame(self, index: int) -> RadarFrame:
+        """Return the RadarFrame at *index* (0-based).
+
+        For ``RAW_IQ_NPY`` format, this runs the SoftwareFPGA chain
+        on the requested frame's chirps.
+        """
+        if index < 0 or index >= self._total_frames:
+            msg = f"Frame index {index} out of range [0, {self._total_frames})"
+            raise IndexError(msg)
+
+        if self.fmt is ReplayFormat.COSIM_DIR:
+            return self._get_cosim(index)
+        if self.fmt is ReplayFormat.RAW_IQ_NPY:
+            return self._get_raw_iq(index)
+        return self._get_hdf5(index)
+
+    def close(self) -> None:
+        """Release any open file handles."""
+        if self._h5_file is not None:
+            self._h5_file.close()
+            self._h5_file = None
+
+    # ------------------------------------------------------------------
+    # Per-format frame getters
+    # ------------------------------------------------------------------
+
+    def _get_cosim(self, _index: int) -> RadarFrame:
+        """Co-sim: single static frame (index ignored).
+
+        Uses deepcopy so numpy arrays are not shared with the source,
+        preventing in-place mutation from corrupting cached data.
+        """
+        import copy
+        frame = copy.deepcopy(self._cosim_frame)
+        frame.timestamp = time.time()
+        return frame
+
+    def _get_raw_iq(self, index: int) -> RadarFrame:
+        """Raw IQ: quantize one frame and run through SoftwareFPGA."""
+        if self.software_fpga is None:
+            msg = "SoftwareFPGA is required for raw IQ replay"
+            raise RuntimeError(msg)
+
+        from .software_fpga import quantize_raw_iq
+
+        raw = self._raw_iq[index]  # (chirps, samples) complex
+        iq_i, iq_q = quantize_raw_iq(raw[np.newaxis, ...])
+        return self.software_fpga.process_chirps(
+            iq_i, iq_q, frame_number=index, timestamp=time.time()
+        )
+
+    def _get_hdf5(self, index: int) -> RadarFrame:
+        """HDF5: reconstruct RadarFrame from stored datasets."""
+        key = self._h5_keys[index]
+        grp = self._h5_file["frames"][key]
+
+        frame = RadarFrame()
+        frame.timestamp = float(grp.attrs.get("timestamp", time.time()))
+        frame.frame_number = int(grp.attrs.get("frame_number", index))
+        frame.detection_count = int(grp.attrs.get("detection_count", 0))
+
+        frame.range_doppler_i = np.array(grp["range_doppler_i"], dtype=np.int16)
+        frame.range_doppler_q = np.array(grp["range_doppler_q"], dtype=np.int16)
+        frame.magnitude = np.array(grp["magnitude"], dtype=np.float64)
+        frame.detections = np.array(grp["detections"], dtype=np.uint8)
+        frame.range_profile = np.array(grp["range_profile"], dtype=np.float64)
+
+        return frame

9_Firmware/9_3_GUI/v7/software_fpga.py

@@ -0,0 +1,287 @@
+"""
+v7.software_fpga — Bit-accurate software replica of the AERIS-10 FPGA signal chain.
+
+Imports processing functions directly from golden_reference.py (Option A)
+to avoid code duplication.  Every stage is toggleable via the same host
+register interface the real FPGA exposes, so the dashboard spinboxes can
+drive either backend transparently.
+
+Signal chain order (matching RTL):
+    quantize → range_fft → decimator → MTI → doppler_fft → dc_notch → CFAR → RadarFrame
+
+Usage:
+    fpga = SoftwareFPGA()
+    fpga.set_cfar_enable(True)
+    frame = fpga.process_chirps(iq_i, iq_q, frame_number=0)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# Import golden_reference by adding the cosim path to sys.path
+# ---------------------------------------------------------------------------
+_GOLDEN_REF_DIR = str(
+    Path(__file__).resolve().parents[2]  # 9_Firmware/
+    / "9_2_FPGA" / "tb" / "cosim" / "real_data"
+)
+if _GOLDEN_REF_DIR not in sys.path:
+    sys.path.insert(0, _GOLDEN_REF_DIR)
+
+from golden_reference import (  # noqa: E402
+    run_range_fft,
+    run_range_bin_decimator,
+    run_mti_canceller,
+    run_doppler_fft,
+    run_dc_notch,
+    run_cfar_ca,
+    run_detection,
+    FFT_SIZE,
+    DOPPLER_CHIRPS,
+)
+
+# RadarFrame lives in radar_protocol (no circular dep — protocol has no GUI)
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from radar_protocol import RadarFrame  # noqa: E402
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Twiddle factor file paths (relative to FPGA root)
+# ---------------------------------------------------------------------------
+_FPGA_DIR = Path(__file__).resolve().parents[2] / "9_2_FPGA"
+TWIDDLE_1024 = str(_FPGA_DIR / "fft_twiddle_1024.mem")
+TWIDDLE_16 = str(_FPGA_DIR / "fft_twiddle_16.mem")
+
+# CFAR mode int→string mapping (FPGA register 0x24: 0=CA, 1=GO, 2=SO)
+_CFAR_MODE_MAP = {0: "CA", 1: "GO", 2: "SO", 3: "CA"}
+
+
+class SoftwareFPGA:
+    """Bit-accurate replica of the AERIS-10 FPGA signal processing chain.
+
+    All registers mirror FPGA reset defaults from ``radar_system_top.v``.
+    Setters accept the same integer values as the FPGA host commands.
+    """
+
+    def __init__(self) -> None:
+        # --- FPGA register mirror (reset defaults) ---
+        # Detection
+        self.detect_threshold: int = 10_000   # 0x03
+        self.gain_shift: int = 0              # 0x16
+
+        # CFAR
+        self.cfar_enable: bool = False         # 0x25
+        self.cfar_guard: int = 2               # 0x21
+        self.cfar_train: int = 8               # 0x22
+        self.cfar_alpha: int = 0x30            # 0x23  Q4.4
+        self.cfar_mode: int = 0                # 0x24  0=CA,1=GO,2=SO
+
+        # MTI
+        self.mti_enable: bool = False          # 0x26
+
+        # DC notch
+        self.dc_notch_width: int = 0           # 0x27
+
+        # AGC (tracked but not applied in software chain — AGC operates
+        # on the analog front-end gain, which doesn't exist in replay)
+        self.agc_enable: bool = False          # 0x28
+        self.agc_target: int = 200             # 0x29
+        self.agc_attack: int = 1               # 0x2A
+        self.agc_decay: int = 1                # 0x2B
+        self.agc_holdoff: int = 4              # 0x2C
+
+    # ------------------------------------------------------------------
+    # Register setters (same interface as UART commands to real FPGA)
+    # ------------------------------------------------------------------
+    def set_detect_threshold(self, val: int) -> None:
+        self.detect_threshold = int(val) & 0xFFFF
+
+    def set_gain_shift(self, val: int) -> None:
+        self.gain_shift = int(val) & 0x0F
+
+    def set_cfar_enable(self, val: bool) -> None:
+        self.cfar_enable = bool(val)
+
+    def set_cfar_guard(self, val: int) -> None:
+        self.cfar_guard = int(val) & 0x0F
+
+    def set_cfar_train(self, val: int) -> None:
+        self.cfar_train = max(1, int(val) & 0x1F)
+
+    def set_cfar_alpha(self, val: int) -> None:
+        self.cfar_alpha = int(val) & 0xFF
+
+    def set_cfar_mode(self, val: int) -> None:
+        self.cfar_mode = int(val) & 0x03
+
+    def set_mti_enable(self, val: bool) -> None:
+        self.mti_enable = bool(val)
+
+    def set_dc_notch_width(self, val: int) -> None:
+        self.dc_notch_width = int(val) & 0x07
+
+    def set_agc_enable(self, val: bool) -> None:
+        self.agc_enable = bool(val)
+
+    def set_agc_params(
+        self,
+        target: int | None = None,
+        attack: int | None = None,
+        decay: int | None = None,
+        holdoff: int | None = None,
+    ) -> None:
+        if target is not None:
+            self.agc_target = int(target) & 0xFF
+        if attack is not None:
+            self.agc_attack = int(attack) & 0x0F
+        if decay is not None:
+            self.agc_decay = int(decay) & 0x0F
+        if holdoff is not None:
+            self.agc_holdoff = int(holdoff) & 0x0F
+
+    # ------------------------------------------------------------------
+    # Core processing: raw IQ chirps → RadarFrame
+    # ------------------------------------------------------------------
+    def process_chirps(
+        self,
+        iq_i: np.ndarray,
+        iq_q: np.ndarray,
+        frame_number: int = 0,
+        timestamp: float = 0.0,
+    ) -> RadarFrame:
+        """Run the full FPGA signal chain on pre-quantized 16-bit I/Q chirps.
+
+        Parameters
+        ----------
+        iq_i, iq_q : ndarray, shape (n_chirps, n_samples), int16/int64
+            Post-DDC I/Q samples.  For ADI phaser data, use
+            ``quantize_raw_iq()`` first.
+        frame_number : int
+            Frame counter for the output RadarFrame.
+        timestamp : float
+            Timestamp for the output RadarFrame.
+
+        Returns
+        -------
+        RadarFrame
+            Populated frame identical to what the real FPGA would produce.
+        """
+        n_chirps = iq_i.shape[0]
+        n_samples = iq_i.shape[1]
+
+        # --- Stage 1: Range FFT (per chirp) ---
+        range_i = np.zeros((n_chirps, n_samples), dtype=np.int64)
+        range_q = np.zeros((n_chirps, n_samples), dtype=np.int64)
+        twiddle_1024 = TWIDDLE_1024 if os.path.exists(TWIDDLE_1024) else None
+        for c in range(n_chirps):
+            range_i[c], range_q[c] = run_range_fft(
+                iq_i[c].astype(np.int64),
+                iq_q[c].astype(np.int64),
+                twiddle_file=twiddle_1024,
+            )
+
+        # --- Stage 2: Range bin decimation (1024 → 64) ---
+        decim_i, decim_q = run_range_bin_decimator(range_i, range_q)
+
+        # --- Stage 3: MTI canceller (pre-Doppler, per-chirp) ---
+        mti_i, mti_q = run_mti_canceller(decim_i, decim_q, enable=self.mti_enable)
+
+        # --- Stage 4: Doppler FFT (dual 16-pt Hamming) ---
+        twiddle_16 = TWIDDLE_16 if os.path.exists(TWIDDLE_16) else None
+        doppler_i, doppler_q = run_doppler_fft(mti_i, mti_q, twiddle_file_16=twiddle_16)
+
+        # --- Stage 5: DC notch (bin zeroing) ---
+        notch_i, notch_q = run_dc_notch(doppler_i, doppler_q, width=self.dc_notch_width)
+
+        # --- Stage 6: Detection ---
+        if self.cfar_enable:
+            mode_str = _CFAR_MODE_MAP.get(self.cfar_mode, "CA")
+            detect_flags, magnitudes, _thresholds = run_cfar_ca(
+                notch_i,
+                notch_q,
+                guard=self.cfar_guard,
+                train=self.cfar_train,
+                alpha_q44=self.cfar_alpha,
+                mode=mode_str,
+            )
+            det_mask = detect_flags.astype(np.uint8)
+            mag = magnitudes.astype(np.float64)
+        else:
+            mag_raw, det_indices = run_detection(
+                notch_i, notch_q, threshold=self.detect_threshold
+            )
+            mag = mag_raw.astype(np.float64)
+            det_mask = np.zeros_like(mag, dtype=np.uint8)
+            for idx in det_indices:
+                det_mask[idx[0], idx[1]] = 1
+
+        # --- Assemble RadarFrame ---
+        frame = RadarFrame()
+        frame.timestamp = timestamp
+        frame.frame_number = frame_number
+        frame.range_doppler_i = np.clip(notch_i, -32768, 32767).astype(np.int16)
+        frame.range_doppler_q = np.clip(notch_q, -32768, 32767).astype(np.int16)
+        frame.magnitude = mag
+        frame.detections = det_mask
+        frame.range_profile = np.sqrt(
+            notch_i[:, 0].astype(np.float64) ** 2
+            + notch_q[:, 0].astype(np.float64) ** 2
+        )
+        frame.detection_count = int(det_mask.sum())
+        return frame
+
+
+# ---------------------------------------------------------------------------
+# Utility: quantize arbitrary complex IQ to 16-bit post-DDC format
+# ---------------------------------------------------------------------------
+def quantize_raw_iq(
+    raw_complex: np.ndarray,
+    n_chirps: int = DOPPLER_CHIRPS,
+    n_samples: int = FFT_SIZE,
+    peak_target: int = 200,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Quantize complex IQ data to 16-bit signed, matching DDC output level.
+
+    Parameters
+    ----------
+    raw_complex : ndarray, shape (chirps, samples) or (frames, chirps, samples)
+        Complex64/128 baseband IQ from SDR capture.  If 3-D, the first
+        axis is treated as frame index and only the first frame is used.
+    n_chirps : int
+        Number of chirps to keep (default 32, matching FPGA).
+    n_samples : int
+        Number of samples per chirp to keep (default 1024, matching FFT).
+    peak_target : int
+        Target peak magnitude after scaling (default 200, matching
+        golden_reference INPUT_PEAK_TARGET).
+
+    Returns
+    -------
+    iq_i, iq_q : ndarray, each (n_chirps, n_samples) int64
+    """
+    if raw_complex.ndim == 3:
+        # (frames, chirps, samples) — take first frame
+        raw_complex = raw_complex[0]
+
+    # Truncate to FPGA dimensions
+    block = raw_complex[:n_chirps, :n_samples]
+
+    max_abs = np.max(np.abs(block))
+    if max_abs == 0:
+        return (
+            np.zeros((n_chirps, n_samples), dtype=np.int64),
+            np.zeros((n_chirps, n_samples), dtype=np.int64),
+        )
+
+    scale = peak_target / max_abs
+    scaled = block * scale
+    iq_i = np.clip(np.round(np.real(scaled)).astype(np.int64), -32768, 32767)
+    iq_q = np.clip(np.round(np.imag(scaled)).astype(np.int64), -32768, 32767)
+    return iq_i, iq_q

9_Firmware/9_3_GUI/v7/workers.py

@@ -13,7 +13,6 @@ All packet parsing now uses the production radar_protocol.py which matches
 the actual FPGA packet format (0xAA data 11-byte, 0xBB status 26-byte).
 """
 
-import math
 import time
 import random
 import queue
@@ -36,58 +35,25 @@ from .processing import (
     RadarProcessor,
     USBPacketParser,
     apply_pitch_correction,
+    polar_to_geographic,
 )
 
 logger = logging.getLogger(__name__)
 
 
-# =============================================================================
-# Utility: polar → geographic
-# =============================================================================
-
-def polar_to_geographic(
-    radar_lat: float,
-    radar_lon: float,
-    range_m: float,
-    azimuth_deg: float,
-) -> tuple:
-    """
-    Convert polar coordinates (range, azimuth) relative to radar
-    to geographic (latitude, longitude).
-
-    azimuth_deg: 0 = North, clockwise.
-    Returns (lat, lon).
-    """
-    R = 6_371_000  # Earth radius in meters
-
-    lat1 = math.radians(radar_lat)
-    lon1 = math.radians(radar_lon)
-    bearing = math.radians(azimuth_deg)
-
-    lat2 = math.asin(
-        math.sin(lat1) * math.cos(range_m / R)
-        + math.cos(lat1) * math.sin(range_m / R) * math.cos(bearing)
-    )
-    lon2 = lon1 + math.atan2(
-        math.sin(bearing) * math.sin(range_m / R) * math.cos(lat1),
-        math.cos(range_m / R) - math.sin(lat1) * math.sin(lat2),
-    )
-    return (math.degrees(lat2), math.degrees(lon2))
-
-
 # =============================================================================
 # Radar Data Worker (QThread) — production protocol
 # =============================================================================
 
 class RadarDataWorker(QThread):
     """
-    Background worker that reads radar data from FT2232H (or ReplayConnection),
-    parses 0xAA/0xBB packets via production RadarAcquisition, runs optional
-    host-side DSP, and emits PyQt signals with results.
+    Background worker that reads radar data from FT2232H, parses 0xAA/0xBB
+    packets via production RadarAcquisition, runs optional host-side DSP,
+    and emits PyQt signals with results.
 
-    This replaces the old V7 worker which used an incompatible packet format.
-    Now uses production radar_protocol.py for all packet parsing and frame
+    Uses production radar_protocol.py for all packet parsing and frame
     assembly (11-byte 0xAA data packets → 64x32 RadarFrame).
+    For replay, use ReplayWorker instead.
 
     Signals:
         frameReady(RadarFrame)    — a complete 64x32 radar frame
@@ -105,7 +71,7 @@ class RadarDataWorker(QThread):
 
     def __init__(
         self,
-        connection,  # FT2232HConnection or ReplayConnection
+        connection,  # FT2232HConnection
         processor: RadarProcessor | None = None,
         recorder: DataRecorder | None = None,
         gps_data_ref: GPSData | None = None,
@@ -436,3 +402,172 @@ class TargetSimulator(QObject):
 
         self._targets = updated
         self.targetsUpdated.emit(updated)
+
+
+# =============================================================================
+# Replay Worker (QThread) — unified replay playback
+# =============================================================================
+
+class ReplayWorker(QThread):
+    """Background worker for replay data playback.
+
+    Emits the same signals as ``RadarDataWorker`` so the dashboard
+    treats live and replay identically.  Additionally emits playback
+    state and frame-index signals for the transport controls.
+
+    Signals
+    -------
+    frameReady(object)           RadarFrame
+    targetsUpdated(list)         list[RadarTarget]
+    statsUpdated(dict)           processing stats
+    errorOccurred(str)           error message
+    playbackStateChanged(str)    "playing" | "paused" | "stopped"
+    frameIndexChanged(int, int)  (current_index, total_frames)
+    """
+
+    frameReady = pyqtSignal(object)
+    targetsUpdated = pyqtSignal(list)
+    statsUpdated = pyqtSignal(dict)
+    errorOccurred = pyqtSignal(str)
+    playbackStateChanged = pyqtSignal(str)
+    frameIndexChanged = pyqtSignal(int, int)
+
+    def __init__(
+        self,
+        replay_engine,
+        settings: RadarSettings | None = None,
+        gps: GPSData | None = None,
+        frame_interval_ms: int = 100,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        import threading
+
+        from .processing import extract_targets_from_frame
+        from .models import WaveformConfig
+
+        self._engine = replay_engine
+        self._settings = settings or RadarSettings()
+        self._gps = gps
+        self._waveform = WaveformConfig()
+        self._frame_interval_ms = frame_interval_ms
+        self._extract_targets = extract_targets_from_frame
+
+        self._current_index = 0
+        self._last_emitted_index = 0
+        self._playing = False
+        self._stop_flag = False
+        self._loop = False
+        self._lock = threading.Lock()  # guards _current_index and _emit_frame
+
+    # -- Public control API --
+
+    @property
+    def current_index(self) -> int:
+        """Index of the last frame emitted (for re-seek on param change)."""
+        return self._last_emitted_index
+
+    @property
+    def total_frames(self) -> int:
+        return self._engine.total_frames
+
+    def set_gps(self, gps: GPSData | None) -> None:
+        self._gps = gps
+
+    def set_waveform(self, wf) -> None:
+        self._waveform = wf
+
+    def set_loop(self, loop: bool) -> None:
+        self._loop = loop
+
+    def set_frame_interval(self, ms: int) -> None:
+        self._frame_interval_ms = max(10, ms)
+
+    def play(self) -> None:
+        self._playing = True
+        # If at EOF, rewind so play actually does something
+        with self._lock:
+            if self._current_index >= self._engine.total_frames:
+                self._current_index = 0
+        self.playbackStateChanged.emit("playing")
+
+    def pause(self) -> None:
+        self._playing = False
+        self.playbackStateChanged.emit("paused")
+
+    def stop(self) -> None:
+        self._playing = False
+        self._stop_flag = True
+        self.playbackStateChanged.emit("stopped")
+
+    @property
+    def is_playing(self) -> bool:
+        """Thread-safe read of playback state (for GUI queries)."""
+        return self._playing
+
+    def seek(self, index: int) -> None:
+        """Jump to a specific frame and emit it (thread-safe)."""
+        with self._lock:
+            idx = max(0, min(index, self._engine.total_frames - 1))
+            self._current_index = idx
+            self._emit_frame(idx)
+            self._last_emitted_index = idx
+
+    # -- Thread entry --
+
+    def run(self) -> None:
+        self._stop_flag = False
+        self._playing = True
+        self.playbackStateChanged.emit("playing")
+
+        try:
+            while not self._stop_flag:
+                if self._playing:
+                    with self._lock:
+                        if self._current_index < self._engine.total_frames:
+                            self._emit_frame(self._current_index)
+                            self._last_emitted_index = self._current_index
+                            self._current_index += 1
+
+                            # Loop or pause at end
+                            if self._current_index >= self._engine.total_frames:
+                                if self._loop:
+                                    self._current_index = 0
+                                else:
+                                    # Pause — keep thread alive for restart
+                                    self._playing = False
+                                    self.playbackStateChanged.emit("stopped")
+
+                self.msleep(self._frame_interval_ms)
+        except (OSError, ValueError, RuntimeError, IndexError) as exc:
+            self.errorOccurred.emit(str(exc))
+
+        self.playbackStateChanged.emit("stopped")
+
+    # -- Internal --
+
+    def _emit_frame(self, index: int) -> None:
+        try:
+            frame = self._engine.get_frame(index)
+        except (OSError, ValueError, RuntimeError, IndexError) as exc:
+            self.errorOccurred.emit(f"Frame {index}: {exc}")
+            return
+
+        self.frameReady.emit(frame)
+        self.frameIndexChanged.emit(index, self._engine.total_frames)
+
+        # Target extraction
+        targets = self._extract_targets(
+            frame,
+            range_resolution=self._waveform.range_resolution_m,
+            velocity_resolution=self._waveform.velocity_resolution_mps,
+            gps=self._gps,
+        )
+        self.targetsUpdated.emit(targets)
+        self.statsUpdated.emit({
+            "frame_number": frame.frame_number,
+            "detection_count": frame.detection_count,
+            "target_count": len(targets),
+            "replay_index": index,
+            "replay_total": self._engine.total_frames,
+        })

9_Firmware/tests/cross_layer/contract_parser.py

@@ -527,6 +527,8 @@ def parse_verilog_status_word_concats(
     ):
         idx = int(m.group(1))
         expr = m.group(2)
+        # Strip single-line comments before normalizing whitespace
+        expr = re.sub(r'//[^\n]*', '', expr)
         # Normalize whitespace
         expr = re.sub(r'\s+', ' ', expr).strip()
         results[idx] = expr

9_Firmware/tests/cross_layer/tb_cross_layer_ft2232h.v

@@ -86,6 +86,10 @@ module tb_cross_layer_ft2232h;
     reg  [4:0]  status_self_test_flags;
     reg  [7:0]  status_self_test_detail;
     reg         status_self_test_busy;
+    reg  [3:0]  status_agc_current_gain;
+    reg  [7:0]  status_agc_peak_magnitude;
+    reg  [7:0]  status_agc_saturation_count;
+    reg         status_agc_enable;
 
     // ---- Clock generators ----
     always #(CLK_PERIOD / 2)    clk    = ~clk;
@@ -130,7 +134,11 @@ module tb_cross_layer_ft2232h;
         .status_range_mode      (status_range_mode),
         .status_self_test_flags (status_self_test_flags),
         .status_self_test_detail(status_self_test_detail),
-        .status_self_test_busy  (status_self_test_busy)
+        .status_self_test_busy  (status_self_test_busy),
+        .status_agc_current_gain    (status_agc_current_gain),
+        .status_agc_peak_magnitude  (status_agc_peak_magnitude),
+        .status_agc_saturation_count(status_agc_saturation_count),
+        .status_agc_enable          (status_agc_enable)
     );
 
     // ---- Test bookkeeping ----
@@ -188,6 +196,10 @@ module tb_cross_layer_ft2232h;
             status_self_test_flags  = 5'b00000;
             status_self_test_detail = 8'd0;
             status_self_test_busy   = 1'b0;
+            status_agc_current_gain     = 4'd0;
+            status_agc_peak_magnitude   = 8'd0;
+            status_agc_saturation_count = 8'd0;
+            status_agc_enable           = 1'b0;
             repeat (6) @(posedge ft_clk);
             reset_n    = 1;
             ft_reset_n = 1;
@@ -492,6 +504,37 @@ module tb_cross_layer_ft2232h;
         check(cmd_opcode === 8'h27 && cmd_value === 16'h0003,
               "Cmd 0x27: DC_NOTCH_WIDTH=3");
 
+        // AGC registers (0x28-0x2C)
+        send_command_ft2232h(8'h28, 8'h00, 8'h00, 8'h01);  // AGC_ENABLE=1
+        $fwrite(cmd_file, "%02x %02x %04x %02x %02x %04x\n",
+                8'h28, 8'h00, 16'h0001, cmd_opcode, cmd_addr, cmd_value);
+        check(cmd_opcode === 8'h28 && cmd_value === 16'h0001,
+              "Cmd 0x28: AGC_ENABLE=1");
+
+        send_command_ft2232h(8'h29, 8'h00, 8'h00, 8'hC8);  // AGC_TARGET=200
+        $fwrite(cmd_file, "%02x %02x %04x %02x %02x %04x\n",
+                8'h29, 8'h00, 16'h00C8, cmd_opcode, cmd_addr, cmd_value);
+        check(cmd_opcode === 8'h29 && cmd_value === 16'h00C8,
+              "Cmd 0x29: AGC_TARGET=200");
+
+        send_command_ft2232h(8'h2A, 8'h00, 8'h00, 8'h02);  // AGC_ATTACK=2
+        $fwrite(cmd_file, "%02x %02x %04x %02x %02x %04x\n",
+                8'h2A, 8'h00, 16'h0002, cmd_opcode, cmd_addr, cmd_value);
+        check(cmd_opcode === 8'h2A && cmd_value === 16'h0002,
+              "Cmd 0x2A: AGC_ATTACK=2");
+
+        send_command_ft2232h(8'h2B, 8'h00, 8'h00, 8'h03);  // AGC_DECAY=3
+        $fwrite(cmd_file, "%02x %02x %04x %02x %02x %04x\n",
+                8'h2B, 8'h00, 16'h0003, cmd_opcode, cmd_addr, cmd_value);
+        check(cmd_opcode === 8'h2B && cmd_value === 16'h0003,
+              "Cmd 0x2B: AGC_DECAY=3");
+
+        send_command_ft2232h(8'h2C, 8'h00, 8'h00, 8'h06);  // AGC_HOLDOFF=6
+        $fwrite(cmd_file, "%02x %02x %04x %02x %02x %04x\n",
+                8'h2C, 8'h00, 16'h0006, cmd_opcode, cmd_addr, cmd_value);
+        check(cmd_opcode === 8'h2C && cmd_value === 16'h0006,
+              "Cmd 0x2C: AGC_HOLDOFF=6");
+
         // Self-test / status
         send_command_ft2232h(8'h30, 8'h00, 8'h00, 8'h01);  // SELF_TEST_TRIGGER
         $fwrite(cmd_file, "%02x %02x %04x %02x %02x %04x\n",
@@ -605,6 +648,10 @@ module tb_cross_layer_ft2232h;
         status_self_test_flags  = 5'b10101;
         status_self_test_detail = 8'hA5;
         status_self_test_busy   = 1'b1;
+        status_agc_current_gain     = 4'd7;
+        status_agc_peak_magnitude   = 8'd200;
+        status_agc_saturation_count = 8'd15;
+        status_agc_enable           = 1'b1;
 
         // Pulse status_request and capture bytes IN PARALLEL
         // (same reason as Exercise B — write FSM starts before CDC wait ends)

9_Firmware/tests/cross_layer/test_cross_layer_contract.py

@@ -100,6 +100,11 @@ GROUND_TRUTH_OPCODES = {
     0x25: ("host_cfar_enable", 1),
     0x26: ("host_mti_enable", 1),
     0x27: ("host_dc_notch_width", 3),
+    0x28: ("host_agc_enable", 1),
+    0x29: ("host_agc_target", 8),
+    0x2A: ("host_agc_attack", 4),
+    0x2B: ("host_agc_decay", 4),
+    0x2C: ("host_agc_holdoff", 4),
     0x30: ("host_self_test_trigger", 1),  # pulse
     0x31: ("host_status_request", 1),     # pulse
     0xFF: ("host_status_request", 1),     # alias, pulse
@@ -124,6 +129,11 @@ GROUND_TRUTH_RESET_DEFAULTS = {
     "host_cfar_enable": 0,
     "host_mti_enable": 0,
     "host_dc_notch_width": 0,
+    "host_agc_enable": 0,
+    "host_agc_target": 200,
+    "host_agc_attack": 1,
+    "host_agc_decay": 1,
+    "host_agc_holdoff": 4,
 }
 
 GROUND_TRUTH_PACKET_CONSTANTS = {
@@ -604,6 +614,10 @@ class TestTier2VerilogCosim:
         #   status_self_test_flags = 5'b10101 = 21
         #   status_self_test_detail = 0xA5
         #   status_self_test_busy = 1
+        #   status_agc_current_gain = 7
+        #   status_agc_peak_magnitude = 200
+        #   status_agc_saturation_count = 15
+        #   status_agc_enable = 1
 
         # Words 1-5 should be correct (no truncation bug)
         assert sr.cfar_threshold == 0xABCD, f"cfar_threshold: 0x{sr.cfar_threshold:04X}"
@@ -618,6 +632,12 @@ class TestTier2VerilogCosim:
         assert sr.self_test_detail == 0xA5, f"self_test_detail: 0x{sr.self_test_detail:02X}"
         assert sr.self_test_busy == 1, f"self_test_busy: {sr.self_test_busy}"
 
+        # AGC fields (word 4)
+        assert sr.agc_current_gain == 7, f"agc_current_gain: {sr.agc_current_gain}"
+        assert sr.agc_peak_magnitude == 200, f"agc_peak_magnitude: {sr.agc_peak_magnitude}"
+        assert sr.agc_saturation_count == 15, f"agc_saturation_count: {sr.agc_saturation_count}"
+        assert sr.agc_enable == 1, f"agc_enable: {sr.agc_enable}"
+
         # Word 0: stream_ctrl should be 5 (3'b101)
         assert sr.stream_ctrl == 5, (
             f"stream_ctrl: {sr.stream_ctrl} != 5. "

CONTRIBUTING.md

@@ -78,9 +78,9 @@ Every test binary must exit 0.
 
 ```bash
 cd 9_Firmware/9_3_GUI
-python3 -m pytest test_radar_dashboard.py -v
+python3 -m pytest test_GUI_V65_Tk.py -v
 # or without pytest:
-python3 -m unittest test_radar_dashboard -v
+python3 -m unittest test_GUI_V65_Tk -v
 ```
 
 57+ protocol and rendering tests. The `test_record_and_stop` test
@@ -130,7 +130,7 @@ Before pushing, confirm:
 
 1. `bash run_regression.sh` — all phases pass
 2. `make all` (MCU tests) — 20/20 pass
-3. `python3 -m unittest test_radar_dashboard -v` — all pass
+3. `python3 -m unittest test_GUI_V65_Tk -v` — all pass
 4. `python3 validate_mem_files.py` — all checks pass
 5. `python3 compare.py dc && python3 compare_doppler.py stationary && python3 compare_mf.py all`
 6. `git diff --check` — no whitespace issues