Merge pull request #108 from NawfalMotii79/fix/adar1000-channel-rotation

fix(adar1000): correct 1-based channel indexing in setters (issue #90)
fix(adar1000): correct 1-based channel indexing in setters (issue #90 )
2026-04-18 06:00:52 +03:00 · 2026-04-18 06:39:07 +05:45 · 2026-04-18 02:02:07 +05:45 · 2026-04-17 19:31:31 +03:00 · 2026-04-17 22:12:26 +05:45 · 2026-04-17 17:21:59 +03:00
25 changed files with 7895 additions and 7170 deletions
@@ -550,7 +550,7 @@
 <text x="3.085225" y="81.68279375" size="1.778" layer="51">GND</text>
 <text x="2.3" y="53.85" size="1.778" layer="51">GND</text>
 <text x="3.336225" y="42.247028125" size="1.778" layer="51">GND</text>
-<text x="2.25" y="11.75" size="1.778" layer="51">GND</text>
+<text x="2.99881875" y="12.58869375" size="1.778" layer="51">GND</text>
 <text x="21.75" y="12.15" size="1.778" layer="51" rot="R90">GND</text>
 <text x="37.45" y="10.05" size="1.778" layer="51" rot="R90">GND</text>
 <text x="60.5" y="9.4" size="1.778" layer="51" rot="R90">GND</text>
@@ -589,11 +589,11 @@
 <text x="248.95" y="49.2" size="1.778" layer="51" rot="R180">GND</text>
 <text x="248.85" y="66.55" size="1.778" layer="51" rot="R180">GND</text>
 <text x="248.8" y="82.9" size="1.778" layer="51" rot="R180">GND</text>
-<text x="256.35" y="101.95" size="1.778" layer="51" rot="R180">GND</text>
+<text x="253.964015625" y="102.099125" size="1.778" layer="51" rot="R180">GND</text>
-<text x="249.4" y="112.5" size="1.778" layer="51" rot="R180">GND</text>
+<text x="249.054865625" y="112.111771875" size="1.778" layer="51" rot="R180">GND</text>
 <text x="237.75" y="280.1" size="1.778" layer="51" rot="R270">GND</text>
 <text x="199.75" y="273.55" size="1.778" layer="51" rot="R270">GND</text>
-<text x="188.45" y="272.75" size="1.778" layer="51" rot="R270">GND</text>
+<text x="188.539503125" y="273.018421875" size="1.778" layer="51" rot="R270">GND</text>
 <text x="177.95" y="272.75" size="1.778" layer="51" rot="R270">GND</text>
 <text x="113.4" y="281.65" size="1.778" layer="51" rot="R270">GND</text>
 <text x="2.992190625" y="248.58331875" size="1.778" layer="51">GND</text>
@@ -635,13 +635,13 @@
 <wire x1="161.6" y1="158.7" x2="156.95" y2="163.4" width="2.54" layer="29"/>
 <wire x1="170.1" y1="150.2" x2="165.45" y2="154.9" width="2.54" layer="29"/>
 <text x="125.137784375" y="269.740521875" size="1.778" layer="51" rot="R90">+5V0_PA_1</text>
-<text x="185.45" y="267.2" size="1.778" layer="51" rot="R90">-3V4</text>
+<text x="182.675396875" y="267.73684375" size="1.778" layer="51" rot="R90">-3V4</text>
-<text x="196.5" y="267.4" size="1.778" layer="51" rot="R90">+3V4</text>
+<text x="193.277878125" y="266.86315625" size="1.778" layer="51" rot="R90">+3V4</text>
 <text x="207.4" y="267.85" size="1.778" layer="51" rot="R90">-5V0_ADAR12</text>
 <text x="188.75" y="289.05" size="1.3" layer="51" rot="R45">+3V3_ADAR12</text>
 <text x="248.25" y="270.6" size="1.778" layer="51" rot="R90">+5V0_PA_2</text>
-<text x="242.8" y="98.7" size="1.778" layer="51" rot="R180">+3V4</text>
+<text x="249.695853125" y="96.471690625" size="1.778" layer="51" rot="R180">+3V4</text>
-<text x="242.9" y="106.65" size="1.778" layer="51" rot="R180">-3V4</text>
+<text x="249.232640625" y="104.692303125" size="1.778" layer="51" rot="R180">-3V4</text>
 <text x="181.4" y="99.15" size="1.778" layer="51" rot="R270">-5V0_ADAR34</text>
 <text x="185.3" y="75.15" size="1.778" layer="51" rot="R270">+3V3_ADAR34</text>
 <text x="238.95" y="72.8" size="1.778" layer="51">+3V3_VDD_SW</text>
@@ -714,8 +714,8 @@
 <text x="147.05" y="25.3" size="1.778" layer="51" rot="R180">CHAN14</text>
 <text x="157.1" y="25.25" size="1.778" layer="51" rot="R180">CHAN15</text>
 <text x="167.15" y="25.35" size="1.778" layer="51" rot="R180">CHAN16</text>
-<text x="50.15" y="131.25" size="1.778" layer="51" rot="R180">SV1</text>
+<text x="51.802165625" y="131.052934375" size="1.778" layer="51" rot="R180">SV1</text>
-<text x="43.25" y="128.5" size="1.778" layer="51" rot="R270">VOLTAGE SEQUENCING</text>
+<text x="35.60243125" y="132.092775" size="1.778" layer="51" rot="R270">VOLTAGE SEQUENCING</text>
 <text x="105.55" y="106.9" size="1.2" layer="51" rot="R90">AD9523_EEPROM_SEL</text>
 <text x="107.2" y="101.85" size="1.2" layer="51" rot="R45">AD9523_STATUS0</text>
 <text x="107.25" y="99.35" size="1.2" layer="51" rot="R45">STM32_MOSI4</text>
@@ -728,20 +728,19 @@
 <text x="99.8" y="100.75" size="1.2" layer="51" rot="R225">STM32_MISO4</text>
 <text x="99.8" y="103.4" size="1.2" layer="51" rot="R225">AD9523_STATUS1</text>
 <text x="99.7" y="105.85" size="1.2" layer="51" rot="R225">GND</text>
-<text x="68.7" y="82.55" size="1.778" layer="51">JP4</text>
+<text x="68.73355625" y="72.201796875" size="1.778" layer="51">JP4</text>
-<text x="64.25" y="73.85" size="1.778" layer="51" rot="R270">GND</text>
+<text x="62.77508125" y="75.956934375" size="1" layer="51" rot="R225">GND</text>
 <text x="56.95" y="82.75" size="1.778" layer="51">JP9</text>
-<text x="37.85" y="78.6" size="1.778" layer="51" rot="R90">JP2</text>
+<text x="45.798875" y="84.61879375" size="1.778" layer="51" rot="R180">JP2</text>
-<text x="43.95" y="88.9" size="1.778" layer="51">JP8</text>
+<text x="43.09716875" y="85.33433125" size="1.778" layer="51" rot="R90">JP8</text>
-<text x="29.1" y="93.2" size="1.778" layer="51">JP7</text>
+<text x="29.1" y="93.2" size="1.778" layer="51">IMU</text>
-<text x="21.75" y="85.35" size="1.778" layer="51">JP18</text>
+<text x="27.568784375" y="88.61074375" size="1.778" layer="51">JP18</text>
 <text x="89.3" y="75.5" size="1.778" layer="51" rot="R180">JP13</text>
 <text x="75.2" y="77" size="1.778" layer="51" rot="R270">GND</text>
-<text x="69.6" y="74.1" size="1.778" layer="51" rot="R270">GND</text>
+<text x="62.1909375" y="71.621040625" size="1.778" layer="51">JP10</text>
-<text x="62.9" y="82.75" size="1.778" layer="51">JP10</text>
+<text x="54.996875" y="70.359128125" size="1.2" layer="51">STEPPER</text>
-<text x="53.75" y="64.4" size="1.2" layer="51" rot="R45">STEPPER_CLK+</text>
+<text x="43.9" y="78.65" size="1.27" layer="51" rot="R270">GND</text>
-<text x="43.9" y="78.65" size="1.778" layer="51" rot="R270">GND</text>
+<text x="52.61158125" y="88.897171875" size="1.016" layer="51" rot="R90">GND</text>
 <text x="53.95" y="86.4" size="1.778" layer="51">GND</text>
 <text x="31.3" y="84.75" size="1.778" layer="51" rot="R270">GND</text>
 <text x="40.45" y="95.9" size="1.778" layer="51" rot="R90">GND</text>
 <rectangle x1="12.8295" y1="256.5735" x2="15.6235" y2="256.7005" layer="51"/>
@@ -5387,6 +5386,56 @@
 <text x="122.221528125" y="146.5440625" size="1.27" layer="51" rot="R315">RX 3_4</text>
 <text x="145.05015" y="114.518025" size="1.27" layer="51" rot="R45">RX 4_4</text>
 <text x="150.25345625" y="4.79933125" size="5.4864" layer="51" font="vector">www.abac-industry.com</text>
 <text x="47.269546875" y="127.64274375" size="1.27" layer="51" rot="R135">+1V0_FPGA</text>
 <text x="47.220515625" y="125.152134375" size="1.27" layer="51" rot="R135">+1V8_FPGA</text>
 <text x="47.270815625" y="122.549565625" size="1.27" layer="51" rot="R135">+3V3_FPGA</text>
 <text x="47.317503125" y="119.8292125" size="1.27" layer="51" rot="R135">+5V0_ADAR</text>
 <text x="47.30423125" y="117.319196875" size="1.27" layer="51" rot="R135">+3V3_ADAR12</text>
 <text x="47.2552" y="114.8285875" size="1.27" layer="51" rot="R135">+3V3_ADAR34</text>
 <text x="47.3055" y="112.22601875" size="1.27" layer="51" rot="R135">+3V3_ADTR</text>
 <text x="47.3521875" y="109.505665625" size="1.27" layer="51" rot="R135">+3V3_SW</text>
 <text x="47.262328125" y="107.0494875" size="1.27" layer="51" rot="R135">+3V3_VDD_SW</text>
 <text x="47.262328125" y="104.6232625" size="1.27" layer="51" rot="R135">+5V0_PA1</text>
 <text x="52.848896875" y="114.716634375" size="1.27" layer="51" rot="R315">GND</text>
 <text x="52.897928125" y="117.20724375" size="1.27" layer="51" rot="R315">+3V3_CLOCK</text>
 <text x="52.847628125" y="119.8098125" size="1.27" layer="51" rot="R315">+1V8_CLOCK</text>
 <text x="52.800940625" y="122.530165625" size="1.27" layer="51" rot="R315">+5V5_PA</text>
 <text x="52.8908" y="124.98634375" size="1.27" layer="51" rot="R315">+5V0_PA3</text>
 <text x="52.8908" y="127.41256875" size="1.27" layer="51" rot="R315">+5V0_PA2</text>
 <text x="52.866228125" y="112.238071875" size="1.27" layer="51" rot="R315">GND</text>
 <text x="52.79689375" y="109.7075125" size="1.27" layer="51" rot="R315">GND</text>
 <text x="52.7795625" y="107.038290625" size="1.27" layer="51" rot="R315">GND</text>
 <text x="52.762228125" y="104.50773125" size="1.27" layer="51" rot="R315">GND</text>
 <text x="37.741834375" y="95.9444" size="1.778" layer="51" rot="R90">+3V3</text>
 <text x="43.11376875" y="95.9444" size="1.778" layer="51" rot="R90">SCL3</text>
 <text x="45.64435" y="95.9888" size="1.778" layer="51" rot="R90">SDA3</text>
 <text x="48.232090625" y="95.98181875" size="1.016" layer="51" rot="R90">MAG_DRDY</text>
 <text x="50.801084375" y="95.879059375" size="1.016" layer="51" rot="R90">ACC_INT</text>
 <text x="52.907659375" y="95.95613125" size="1.016" layer="51" rot="R90">GYR_INT</text>
 <text x="54.502678125" y="92.739546875" size="1.778" layer="51">JP7</text>
 <text x="30.45236875" y="78.6816375" size="1.778" layer="51" rot="R90">+3V3</text>
 <text x="35.56853125" y="79.257065625" size="1.778" layer="51" rot="R90">SCL3</text>
 <text x="38.227" y="78.789975" size="1.778" layer="51" rot="R90">SDA3</text>
 <text x="39.282209375" y="78.488071875" size="1.27" layer="51" rot="R270">+3V3</text>
 <text x="41.4419875" y="78.63334375" size="1.27" layer="51" rot="R270">STM32_SWCLK</text>
 <text x="46.663971875" y="78.473509375" size="1.27" layer="51" rot="R270">STM32_SWDIO</text>
 <text x="49.16839375" y="78.5267875" size="1.27" layer="51" rot="R270">STM32_NRST</text>
 <text x="51.7793875" y="78.473509375" size="1.27" layer="51" rot="R270">STM32_SWO</text>
 <text x="53.6100625" y="82.81805625" size="1.27" layer="51" rot="R315">GND</text>
 <text x="53.75804375" y="77.6019375" size="1.27" layer="51" rot="R315">GND</text>
 <text x="53.809425" y="80.29940625" size="1.27" layer="51" rot="R315">CW+</text>
 <text x="53.520859375" y="75.467190625" size="1.27" layer="51" rot="R315">CLK+</text>
 <text x="50.081" y="88.941571875" size="1.016" layer="51" rot="R90">RX5</text>
 <text x="47.417228125" y="88.985971875" size="1.016" layer="51" rot="R90">TX5</text>
 <text x="45.019834375" y="88.675175" size="1.016" layer="51" rot="R90">+3V3</text>
 <text x="53.525646875" y="86.07393125" size="1.778" layer="51">GPS</text>
 <text x="62.34479375" y="80.785540625" size="0.9" layer="51" rot="R45">EN/DIS_RFPA_VDD</text>
 <text x="68.0472625" y="76.328084375" size="1" layer="51" rot="R225">GND</text>
 <text x="67.5982" y="80.711553125" size="0.9" layer="51" rot="R45">EN/DIS_COOLING</text>
 <text x="78.325053125" y="83.140434375" size="1.778" layer="51">ADF4382</text>
 <text x="92.67903125" y="80.894575" size="1.016" layer="51">1</text>
 <text x="92.77235625" y="78.2390125" size="1.016" layer="51">2</text>
 <text x="73.362715625" y="77.945809375" size="1.016" layer="51">14</text>
 </plain>
 <libraries>
 <library name="eagle-ltspice">
@@ -24576,8 +24625,8 @@ Your PCBWay Team
 <vertex x="114" y="112" curve="-180"/>
 </polygon>
 <polygon width="0.254" layer="1" spacing="5.08">
-<vertex x="258.75" y="116" curve="-180"/>
+<vertex x="258.9164" y="116.0208" curve="-180"/>
-<vertex x="254.75" y="112" curve="-180"/>
+<vertex x="254.9164" y="112.0208" curve="-180"/>
 </polygon>
 <polygon width="0.254" layer="1" spacing="5.08">
 <vertex x="260" y="300"/>
@@ -18,7 +18,7 @@ ADAR1000_AGC::ADAR1000_AGC()
    , min_gain(0)
    , max_gain(127)
    , holdoff_frames(4)
-    , enabled(true)
+    , enabled(false)
    , holdoff_counter(0)
    , last_saturated(false)
    , saturation_event_count(0)
@@ -20,18 +20,71 @@ static const struct {
    {ADAR_4_CS_3V3_GPIO_Port, ADAR_4_CS_3V3_Pin}  // ADAR1000 #4
 };
-// Vector Modulator lookup tables
+// ADAR1000 Vector Modulator lookup tables (128-state phase grid, 2.8125 deg step).
 //
 // Source: Analog Devices ADAR1000 datasheet Rev. B, Tables 13-16, page 34
 //   (7_Components Datasheets and Application notes/ADAR1000.pdf)
 // Cross-checked against the ADI Linux mainline driver (GPL-2.0, NOT vendored):
 //   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/
 //     drivers/iio/beamformer/adar1000.c  (adar1000_phase_values[])
 // The 128 byte values themselves are factual data from the datasheet and are
 // not subject to copyright; only the ADI driver code is GPL.
 //
 // Byte format (per datasheet):
 //   bit  [7:6] reserved (0)
 //   bit  [5]   polarity:  1 = positive lobe (sign(I) or sign(Q) >= 0)
 //                          0 = negative lobe
 //   bits [4:0] 5-bit unsigned magnitude (0..31)
 // At magnitude=0 the polarity bit is physically meaningless; the datasheet
 // uses POL=1 (e.g. VM_Q at 0 deg = 0x20, VM_I at 90 deg = 0x21).
 //
 // Index mapping is uniform: VM_I[k] / VM_Q[k] correspond to phase angle
 // k * 360/128 = k * 2.8125 degrees.  Callers index as VM_*[phase % 128].
 const uint8_t ADAR1000Manager::VM_I[128] = {
-    // ... (same as in your original file)
+    0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3E, 0x3E, 0x3D,  // [  0]   0.0000 deg
    0x3D, 0x3C, 0x3C, 0x3B, 0x3A, 0x39, 0x38, 0x37,  // [  8]  22.5000 deg
    0x36, 0x35, 0x34, 0x33, 0x32, 0x30, 0x2F, 0x2E,  // [ 16]  45.0000 deg
    0x2C, 0x2B, 0x2A, 0x28, 0x27, 0x25, 0x24, 0x22,  // [ 24]  67.5000 deg
    0x21, 0x01, 0x03, 0x04, 0x06, 0x07, 0x08, 0x0A,  // [ 32]  90.0000 deg
    0x0B, 0x0D, 0x0E, 0x0F, 0x11, 0x12, 0x13, 0x14,  // [ 40] 112.5000 deg
    0x16, 0x17, 0x18, 0x19, 0x19, 0x1A, 0x1B, 0x1C,  // [ 48] 135.0000 deg
    0x1C, 0x1D, 0x1E, 0x1E, 0x1E, 0x1F, 0x1F, 0x1F,  // [ 56] 157.5000 deg
    0x1F, 0x1F, 0x1F, 0x1F, 0x1F, 0x1E, 0x1E, 0x1D,  // [ 64] 180.0000 deg
    0x1D, 0x1C, 0x1C, 0x1B, 0x1A, 0x19, 0x18, 0x17,  // [ 72] 202.5000 deg
    0x16, 0x15, 0x14, 0x13, 0x12, 0x10, 0x0F, 0x0E,  // [ 80] 225.0000 deg
    0x0C, 0x0B, 0x0A, 0x08, 0x07, 0x05, 0x04, 0x02,  // [ 88] 247.5000 deg
    0x01, 0x21, 0x23, 0x24, 0x26, 0x27, 0x28, 0x2A,  // [ 96] 270.0000 deg
    0x2B, 0x2D, 0x2E, 0x2F, 0x31, 0x32, 0x33, 0x34,  // [104] 292.5000 deg
    0x36, 0x37, 0x38, 0x39, 0x39, 0x3A, 0x3B, 0x3C,  // [112] 315.0000 deg
    0x3C, 0x3D, 0x3E, 0x3E, 0x3E, 0x3F, 0x3F, 0x3F,  // [120] 337.5000 deg
 };
 const uint8_t ADAR1000Manager::VM_Q[128] = {
-    // ... (same as in your original file)
+    0x20, 0x21, 0x23, 0x24, 0x26, 0x27, 0x28, 0x2A,  // [  0]   0.0000 deg
    0x2B, 0x2D, 0x2E, 0x2F, 0x30, 0x31, 0x33, 0x34,  // [  8]  22.5000 deg
    0x35, 0x36, 0x37, 0x38, 0x38, 0x39, 0x3A, 0x3A,  // [ 16]  45.0000 deg
    0x3B, 0x3C, 0x3C, 0x3C, 0x3D, 0x3D, 0x3D, 0x3D,  // [ 24]  67.5000 deg
    0x3D, 0x3D, 0x3D, 0x3D, 0x3D, 0x3C, 0x3C, 0x3C,  // [ 32]  90.0000 deg
    0x3B, 0x3A, 0x3A, 0x39, 0x38, 0x38, 0x37, 0x36,  // [ 40] 112.5000 deg
    0x35, 0x34, 0x33, 0x31, 0x30, 0x2F, 0x2E, 0x2D,  // [ 48] 135.0000 deg
    0x2B, 0x2A, 0x28, 0x27, 0x26, 0x24, 0x23, 0x21,  // [ 56] 157.5000 deg
    0x20, 0x01, 0x03, 0x04, 0x06, 0x07, 0x08, 0x0A,  // [ 64] 180.0000 deg
    0x0B, 0x0D, 0x0E, 0x0F, 0x10, 0x11, 0x13, 0x14,  // [ 72] 202.5000 deg
    0x15, 0x16, 0x17, 0x18, 0x18, 0x19, 0x1A, 0x1A,  // [ 80] 225.0000 deg
    0x1B, 0x1C, 0x1C, 0x1C, 0x1D, 0x1D, 0x1D, 0x1D,  // [ 88] 247.5000 deg
    0x1D, 0x1D, 0x1D, 0x1D, 0x1D, 0x1C, 0x1C, 0x1C,  // [ 96] 270.0000 deg
    0x1B, 0x1A, 0x1A, 0x19, 0x18, 0x18, 0x17, 0x16,  // [104] 292.5000 deg
    0x15, 0x14, 0x13, 0x11, 0x10, 0x0F, 0x0E, 0x0D,  // [112] 315.0000 deg
    0x0B, 0x0A, 0x08, 0x07, 0x06, 0x04, 0x03, 0x01,  // [120] 337.5000 deg
 };
-const uint8_t ADAR1000Manager::VM_GAIN[128] = {
+// NOTE: a VM_GAIN[128] table previously existed here as a placeholder but was
-    // ... (same as in your original file)
+// never populated and never read.  The ADAR1000 vector modulator has no
-};
+// separate gain register: phase-state magnitude is encoded directly in
 // bits [4:0] of the VM_I/VM_Q bytes above.  Per-channel VGA gain is a
 // distinct register (CHx_RX_GAIN at 0x10-0x13, CHx_TX_GAIN at 0x1C-0x1F)
 // written with the user-supplied byte directly by adarSetRxVgaGain() /
 // adarSetTxVgaGain().  Do not reintroduce a VM_GAIN[] array.
 ADAR1000Manager::ADAR1000Manager() {
    for (int i = 0; i < 4; ++i) {
@@ -815,11 +868,22 @@ void ADAR1000Manager::adarSetRamBypass(uint8_t deviceIndex, uint8_t broadcast) {
 }
 void ADAR1000Manager::adarSetRxPhase(uint8_t deviceIndex, uint8_t channel, uint8_t phase, uint8_t broadcast) {
    // channel is 1-based (CH1..CH4) per API contract documented in
    // ADAR1000_AGC.cpp and matching ADI datasheet terminology.
    // Reject out-of-range early so a stale 0-based caller does not
    // silently wrap to ((0-1) & 0x03) == 3 and write to CH4.
    // See issue #90.
    if (channel < 1 || channel > 4) {
        DIAG("BF", "adarSetRxPhase: channel %u out of range [1..4], ignored", channel);
        return;
    }
    uint8_t i_val = VM_I[phase % 128];
    uint8_t q_val = VM_Q[phase % 128];
-    uint32_t mem_addr_i = REG_CH1_RX_PHS_I + (channel & 0x03) * 2;
+    // Subtract 1 to convert 1-based channel to 0-based register offset
-    uint32_t mem_addr_q = REG_CH1_RX_PHS_Q + (channel & 0x03) * 2;
+    // before masking. See issue #90.
    uint32_t mem_addr_i = REG_CH1_RX_PHS_I + ((channel - 1) & 0x03) * 2;
    uint32_t mem_addr_q = REG_CH1_RX_PHS_Q + ((channel - 1) & 0x03) * 2;
    adarWrite(deviceIndex, mem_addr_i, i_val, broadcast);
    adarWrite(deviceIndex, mem_addr_q, q_val, broadcast);
@@ -827,11 +891,16 @@ void ADAR1000Manager::adarSetRxPhase(uint8_t deviceIndex, uint8_t channel, uint8
 }
 void ADAR1000Manager::adarSetTxPhase(uint8_t deviceIndex, uint8_t channel, uint8_t phase, uint8_t broadcast) {
    // channel is 1-based (CH1..CH4). See issue #90.
    if (channel < 1 || channel > 4) {
        DIAG("BF", "adarSetTxPhase: channel %u out of range [1..4], ignored", channel);
        return;
    }
    uint8_t i_val = VM_I[phase % 128];
    uint8_t q_val = VM_Q[phase % 128];
-    uint32_t mem_addr_i = REG_CH1_TX_PHS_I + (channel & 0x03) * 2;
+    uint32_t mem_addr_i = REG_CH1_TX_PHS_I + ((channel - 1) & 0x03) * 2;
-    uint32_t mem_addr_q = REG_CH1_TX_PHS_Q + (channel & 0x03) * 2;
+    uint32_t mem_addr_q = REG_CH1_TX_PHS_Q + ((channel - 1) & 0x03) * 2;
    adarWrite(deviceIndex, mem_addr_i, i_val, broadcast);
    adarWrite(deviceIndex, mem_addr_q, q_val, broadcast);
@@ -839,13 +908,23 @@ void ADAR1000Manager::adarSetTxPhase(uint8_t deviceIndex, uint8_t channel, uint8
 }
 void ADAR1000Manager::adarSetRxVgaGain(uint8_t deviceIndex, uint8_t channel, uint8_t gain, uint8_t broadcast) {
-    uint32_t mem_addr = REG_CH1_RX_GAIN + (channel & 0x03);
+    // channel is 1-based (CH1..CH4). See issue #90.
    if (channel < 1 || channel > 4) {
        DIAG("BF", "adarSetRxVgaGain: channel %u out of range [1..4], ignored", channel);
        return;
    }
    uint32_t mem_addr = REG_CH1_RX_GAIN + ((channel - 1) & 0x03);
    adarWrite(deviceIndex, mem_addr, gain, broadcast);
    adarWrite(deviceIndex, REG_LOAD_WORKING, 0x1, broadcast);
 }
 void ADAR1000Manager::adarSetTxVgaGain(uint8_t deviceIndex, uint8_t channel, uint8_t gain, uint8_t broadcast) {
-    uint32_t mem_addr = REG_CH1_TX_GAIN + (channel & 0x03);
+    // channel is 1-based (CH1..CH4). See issue #90.
    if (channel < 1 || channel > 4) {
        DIAG("BF", "adarSetTxVgaGain: channel %u out of range [1..4], ignored", channel);
        return;
    }
    uint32_t mem_addr = REG_CH1_TX_GAIN + ((channel - 1) & 0x03);
    adarWrite(deviceIndex, mem_addr, gain, broadcast);
    adarWrite(deviceIndex, REG_LOAD_WORKING, LD_WRK_REGS_LDTX_OVERRIDE, broadcast);
 }
@@ -116,10 +116,12 @@ public:
    bool beam_sweeping_active_ = false;
    uint32_t last_beam_update_time_ = 0;
-    // Lookup tables
+    // Vector Modulator lookup tables (see ADAR1000_Manager.cpp for provenance).
-    static const uint8_t VM_I[128];
+    // Indexed as VM_*[phase % 128] on a uniform 2.8125 deg grid.
    // No VM_GAIN[] table exists: VM magnitude is bits [4:0] of the I/Q bytes
    // themselves; per-channel VGA gain uses a separate register.
    static const uint8_t VM_I[128];
    static const uint8_t VM_Q[128];
    static const uint8_t VM_GAIN[128];
    // Named defaults for the ADTR1107 and ADAR1000 power sequence.
    static constexpr uint8_t kDefaultTxVgaGain = 0x7F;
@@ -1,693 +0,0 @@
 /**
 * MIT License
 * 
 * Copyright (c) 2020 Jimmy Pentz
 *
 * Reach me at: github.com/jgpentz, jpentz1(at)gmail.com
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sells
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
 /* ADAR1000 4-Channel, X Band and Ku Band Beamformer */
 // ----------------------------------------------------------------------------
 // Includes
 // ----------------------------------------------------------------------------
 #include "main.h"
 #include "stm32f7xx_hal.h"
 #include "stm32f7xx_hal_spi.h"
 #include "stm32f7xx_hal_gpio.h"
 #include "adar1000.h"
 // ----------------------------------------------------------------------------
 // Preprocessor Definitions and Constants
 // ----------------------------------------------------------------------------
 // VM_GAIN is 15 dB of gain in 128 steps. ~0.12 dB per step.
 // A 15 dB attenuator can be applied on top of these values.
 const uint8_t VM_GAIN[128] = {
 	0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
 	0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
 	0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f,
 	0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
 	0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f,
 	0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5d, 0x5e, 0x5f,
 	0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6d, 0x6e, 0x6f,
 	0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
 };
 // VM_I and VM_Q are the settings for the vector modulator. 128 steps in 360 degrees. ~2.813 degrees per step.
 const uint8_t VM_I[128] = {
 	0x3F, 0x3F, 0x3F, 0x3F, 0x3F, 0x3E, 0x3E, 0x3D, 0x3D, 0x3C, 0x3C, 0x3B, 0x3A, 0x39, 0x38, 0x37,
 	0x36, 0x35, 0x34, 0x33, 0x32, 0x30, 0x2F, 0x2E, 0x2C, 0x2B, 0x2A, 0x28, 0x27, 0x25, 0x24, 0x22,
 	0x21, 0x01, 0x03, 0x04, 0x06, 0x07, 0x08, 0x0A, 0x0B, 0x0D, 0x0E, 0x0F, 0x11, 0x12, 0x13, 0x14,
 	0x16, 0x17, 0x18, 0x19, 0x19, 0x1A, 0x1B, 0x1C, 0x1C, 0x1D, 0x1E, 0x1E, 0x1E, 0x1F, 0x1F, 0x1F,
 	0x1F, 0x1F, 0x1F, 0x1F, 0x1F, 0x1E, 0x1E, 0x1D, 0x1D, 0x1C, 0x1C, 0x1B, 0x1A, 0x19, 0x18, 0x17,
 	0x16, 0x15, 0x14, 0x13, 0x12, 0x10, 0x0F, 0x0E, 0x0C, 0x0B, 0x0A, 0x08, 0x07, 0x05, 0x04, 0x02,
 	0x01, 0x21, 0x23, 0x24, 0x26, 0x27, 0x28, 0x2A, 0x2B, 0x2D, 0x2E, 0x2F, 0x31, 0x32, 0x33, 0x34,
 	0x36, 0x37, 0x38, 0x39, 0x39, 0x3A, 0x3B, 0x3C, 0x3C, 0x3D, 0x3E, 0x3E, 0x3E, 0x3F, 0x3F, 0x3F,
 };
 const uint8_t VM_Q[128] = {
 	0x20, 0x21, 0x23, 0x24, 0x26, 0x27, 0x28, 0x2A, 0x2B, 0x2D, 0x2E, 0x2F, 0x30, 0x31, 0x33, 0x34,
 	0x35, 0x36, 0x37, 0x38, 0x38, 0x39, 0x3A, 0x3A, 0x3B, 0x3C, 0x3C, 0x3C, 0x3D, 0x3D, 0x3D, 0x3D,
 	0x3D, 0x3D, 0x3D, 0x3D, 0x3D, 0x3C, 0x3C, 0x3C, 0x3B, 0x3A, 0x3A, 0x39, 0x38, 0x38, 0x37, 0x36,
 	0x35, 0x34, 0x33, 0x31, 0x30, 0x2F, 0x2E, 0x2D, 0x2B, 0x2A, 0x28, 0x27, 0x26, 0x24, 0x23, 0x21,
 	0x20, 0x01, 0x03, 0x04, 0x06, 0x07, 0x08, 0x0A, 0x0B, 0x0D, 0x0E, 0x0F, 0x10, 0x11, 0x13, 0x14,
 	0x15, 0x16, 0x17, 0x18, 0x18, 0x19, 0x1A, 0x1A, 0x1B, 0x1C, 0x1C, 0x1C, 0x1D, 0x1D, 0x1D, 0x1D,
 	0x1D, 0x1D, 0x1D, 0x1D, 0x1D, 0x1C, 0x1C, 0x1C, 0x1B, 0x1A, 0x1A, 0x19, 0x18, 0x18, 0x17, 0x16,
 	0x15, 0x14, 0x13, 0x11, 0x10, 0x0F, 0x0E, 0x0D, 0x0B, 0x0A, 0x08, 0x07, 0x06, 0x04, 0x03, 0x01,
 };
 // ----------------------------------------------------------------------------
 // Function Definitions
 // ----------------------------------------------------------------------------
 /**
 * @brief	Initialize the ADC on the ADAR by setting the ADC with a 2 MHz clk, 
 *			and then enable it.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @warning	This is setup to only read temperature sensor data, not the power detectors.
 */
 void Adar_AdcInit(const AdarDevice * p_adar, uint8_t broadcast)
 {
 	uint8_t data;
 	data = ADAR1000_ADC_2MHZ_CLK | ADAR1000_ADC_EN;
 	Adar_Write(p_adar, REG_ADC_CONTROL, data, broadcast);
 }
 /**
 * @brief	Read a byte of data from the ADAR.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return	Returns a byte of data that has been converted from the temperature sensor.
 *
 * @warning	This is setup to only read temperature sensor data, not the power detectors.
 */
 uint8_t Adar_AdcRead(const AdarDevice * p_adar, uint8_t broadcast)
 {
 	uint8_t data;
    // Start the ADC conversion
 	Adar_Write(p_adar, REG_ADC_CONTROL, ADAR1000_ADC_ST_CONV, broadcast);
    // This is blocking for now... wait until data is converted, then read it
 	while (!(Adar_Read(p_adar, REG_ADC_CONTROL) & 0x01))
 	{
 	}
 	data = Adar_Read(p_adar, REG_ADC_OUT);
 	return(data);
 }
 /**
 * @brief	Requests the device info from a specific ADAR and stores it in the
 *			provided AdarDeviceInfo struct.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param   info[out]	Struct that contains the device info fields.
 *
 * @return	Returns ADAR_ERROR_NOERROR if information was successfully received and stored in the struct.
 */
 uint8_t Adar_GetDeviceInfo(const AdarDevice * p_adar, AdarDeviceInfo * info)
 {
 	*((uint8_t *)info) = Adar_Read(p_adar, 0x002);
 	info->chip_type = Adar_Read(p_adar, 0x003);
 	info->product_id = ((uint16_t)Adar_Read(p_adar, 0x004)) << 8;
 	info->product_id |= ((uint16_t)Adar_Read(p_adar, 0x005)) & 0x00ff;
 	info->scratchpad = Adar_Read(p_adar, 0x00A);
 	info->spi_rev = Adar_Read(p_adar, 0x00B);
 	info->vendor_id = ((uint16_t)Adar_Read(p_adar, 0x00C)) << 8;
 	info->vendor_id |= ((uint16_t)Adar_Read(p_adar, 0x00D)) & 0x00ff;
 	info->rev_id = Adar_Read(p_adar, 0x045);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Read the data that is stored in a single ADAR register.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param	mem_addr	Memory address of the register you wish to read from.
 *
 * @return	Returns the byte of data that is stored in the desired register.
 *
 * @warning	This function will clear ADDR_ASCN bits.
 * @warning The ADAR does not allow for block reads.
 */
 uint8_t Adar_Read(const AdarDevice * p_adar, uint32_t mem_addr)
 {
 	uint8_t instruction[3];
    // Set SDO active
 	Adar_Write(p_adar, REG_INTERFACE_CONFIG_A, INTERFACE_CONFIG_A_SDO_ACTIVE, 0);
 	instruction[0] = 0x80 | ((p_adar->dev_addr & 0x03) << 5);
 	instruction[0] |= ((0xff00 & mem_addr) >> 8);
 	instruction[1] = (0xff & mem_addr);
 	instruction[2] = 0x00;
 	p_adar->Transfer(instruction, p_adar->p_rx_buffer, ADAR1000_RD_SIZE);
    // Set SDO Inactive
 	Adar_Write(p_adar, REG_INTERFACE_CONFIG_A, 0, 0);
 	return(p_adar->p_rx_buffer[2]);
 }
 /**
 * @brief	Block memory write to an ADAR device.
 *
 * @pre		ADDR_ASCN bits in register zero must be set!
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param	mem_addr  	Memory address of the register you wish to read from.
 * @param	p_data    	Pointer to block of data to transfer (must have two unused bytes preceding the data for instruction).
 * @param	size      	Size of data in bytes, including the two additional leading bytes.
 *
 * @warning First two bytes of data will be corrupted if you do not provide two unused leading bytes!
 */
 void Adar_ReadBlock(const AdarDevice * p_adar, uint16_t mem_addr, uint8_t * p_data, uint32_t size)
 {
    // Set SDO active
 	Adar_Write(p_adar, REG_INTERFACE_CONFIG_A, INTERFACE_CONFIG_A_SDO_ACTIVE | INTERFACE_CONFIG_A_ADDR_ASCN, 0);
    // Prepare command
 	p_data[0] = 0x80 | ((p_adar->dev_addr & 0x03) << 5);
 	p_data[0] |= ((mem_addr) >> 8) & 0x1F;
 	p_data[1] = (0xFF & mem_addr);
    // Start the transfer
 	p_adar->Transfer(p_data, p_data, size);
 	Adar_Write(p_adar, REG_INTERFACE_CONFIG_A, 0, 0);
    // Return nothing since we assume this is non-blocking and won't wait around
 }
 /**
 * @brief	Sets the Rx/Tx bias currents for the LNA, VM, and VGA to be in either
 *			low power setting or nominal setting.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param	p_bias[in]	An AdarBiasCurrents struct filled with bias settings
 *						as seen in the datasheet Table 6. SPI Settings for 
 *						Different Power	Modules
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return	Returns ADAR_ERR_NOERROR if the bias currents were set 
 */
 uint8_t Adar_SetBiasCurrents(const AdarDevice * p_adar, AdarBiasCurrents * p_bias, uint8_t broadcast)
 {
 	uint8_t bias = 0;
    // RX LNA/VGA/VM bias
 	bias = (p_bias->rx_lna & 0x0f);
 	Adar_Write(p_adar, REG_BIAS_CURRENT_RX_LNA, bias, broadcast); // RX LNA bias
 	bias = (p_bias->rx_vga & 0x07 << 3) | (p_bias->rx_vm & 0x07);
 	Adar_Write(p_adar, REG_BIAS_CURRENT_RX, bias, broadcast);     // RX VM/VGA bias
    // TX VGA/VM/DRV bias
 	bias = (p_bias->tx_vga & 0x07 << 3) | (p_bias->tx_vm & 0x07);
 	Adar_Write(p_adar, REG_BIAS_CURRENT_TX, bias, broadcast);     // TX VM/VGA bias
 	bias = (p_bias->tx_drv & 0x07);
 	Adar_Write(p_adar, REG_BIAS_CURRENT_TX_DRV, bias, broadcast); // TX DRV bias
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Set the bias ON and bias OFF voltages for the four PA's and one LNA.
 *
 * @pre		This will set all 5 bias ON values and all 5 bias OFF values at once.
 * 			To enable these bias values, please see the data sheet and ensure that the BIAS_CTRL,
 * 			LNA_BIAS_OUT_EN, TR_SOURCE, TX_EN, RX_EN, TR (input to chip), and PA_ON (input to chip)
 * 			bits have all been properly set.
 *
 * @param	p_adar[in]		Adar pointer Which specifies the device and what function 
 *							to use for SPI transfer.
 * @param 	bias_on_voltage   Array that contains the bias ON voltages.
 * @param 	bias_off_voltage  Array that contains the bias OFF voltages.
 *
 * @return	Returns ADAR_ERR_NOERROR if the bias currents were set 
 */
 uint8_t Adar_SetBiasVoltages(const AdarDevice * p_adar, uint8_t bias_on_voltage[5], uint8_t bias_off_voltage[5])
 {
 	Adar_SetBit(p_adar, 0x30, 6, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x31, 2, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x38, 5, BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH1_BIAS_ON,bias_on_voltage[0], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH2_BIAS_ON,bias_on_voltage[1], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH3_BIAS_ON,bias_on_voltage[2], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH4_BIAS_ON,bias_on_voltage[3], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH1_BIAS_OFF,bias_off_voltage[0], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH2_BIAS_OFF,bias_off_voltage[1], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH3_BIAS_OFF,bias_off_voltage[2], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_PA_CH4_BIAS_OFF,bias_off_voltage[3], BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x30, 4, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x30, 6, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x31, 2, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x38, 5, BROADCAST_OFF);
 	Adar_Write(p_adar, REG_LNA_BIAS_ON,bias_on_voltage[4], BROADCAST_OFF);
 	Adar_Write(p_adar, REG_LNA_BIAS_OFF,bias_off_voltage[4], BROADCAST_OFF);
 	Adar_ResetBit(p_adar, 0x30, 7, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x31, 2, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x31, 4, BROADCAST_OFF);
 	Adar_SetBit(p_adar, 0x31, 7, BROADCAST_OFF);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Setup the ADAR to use settings that are transferred over SPI.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return	Returns ADAR_ERR_NOERROR if the bias currents were set 
 */
 uint8_t Adar_SetRamBypass(const AdarDevice * p_adar, uint8_t broadcast)
 {
 	uint8_t data;
 	data = (MEM_CTRL_BIAS_RAM_BYPASS | MEM_CTRL_BEAM_RAM_BYPASS);
 	Adar_Write(p_adar, REG_MEM_CTL, data, broadcast);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Set the VGA gain value of a Receive channel in dB.
 *
 * @param	p_adar[in]		Adar pointer Which specifies the device and what function 
 *							to use for SPI transfer.
 * @param 	channel			Channel in which to set the gain (1-4).
 * @param 	vga_gain_db		Gain to be applied to the channel, ranging from 0 - 30 dB. 
 *							(Intended operation >16 dB).
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return 	Returns ADAR_ERROR_NOERROR if the gain was successfully set. 
 * 					ADAR_ERROR_FAILED if an invalid channel was selected.
 *
 * @warning 0 dB or 15 dB step attenuator may also be turned on, which is why intended operation is >16 dB.
 */
 uint8_t Adar_SetRxVgaGain(const AdarDevice * p_adar, uint8_t channel, uint8_t vga_gain_db, uint8_t broadcast)
 {
 	uint8_t	 vga_gain_bits = (uint8_t)(255*vga_gain_db/16);
 	uint32_t mem_addr = 0;
 	if((channel == 0) || (channel > 4))
 	{
 		return(ADAR_ERROR_FAILED);
 	}
 	mem_addr = REG_CH1_RX_GAIN + (channel & 0x03);
    // Set gain
 	Adar_Write(p_adar, mem_addr, vga_gain_bits, broadcast);
    // Load the new setting
 	Adar_Write(p_adar, REG_LOAD_WORKING, 0x1, broadcast);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Set the phase of a given receive channel using the I/Q vector modulator.
 *
 * @pre		According to the given @param phase, this sets the polarity (bit 5) and gain (bits 4-0)
 * 			of the @param channel, and then loads them into the working register.
 * 			A vector modulator I/Q look-up table has been provided at the beginning of this library.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param	channel   	Channel in which to set the gain (1-4).
 * @param	phase     	Byte that is used to set the polarity (bit 5) and gain (bits 4-0).
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return 	Returns ADAR_ERROR_NOERROR if the phase was successfully set. 
 * 					ADAR_ERROR_FAILED if an invalid channel was selected.
 *
 * @note    To obtain your phase:
 *          phase = degrees * 128;
 *          phase /= 360;
 */
 uint8_t Adar_SetRxPhase(const AdarDevice * p_adar, uint8_t channel, uint8_t phase, uint8_t broadcast)
 {
 	uint8_t	 i_val = 0;
 	uint8_t	 q_val = 0;
 	uint32_t mem_addr_i, mem_addr_q;
 	if((channel == 0) || (channel > 4))
 	{
 		return(ADAR_ERROR_FAILED);
 	}
 	//phase = phase % 128;
 	i_val = VM_I[phase];
 	q_val = VM_Q[phase];
 	mem_addr_i = REG_CH1_RX_PHS_I + (channel & 0x03) * 2;
 	mem_addr_q = REG_CH1_RX_PHS_Q + (channel & 0x03) * 2;
 	Adar_Write(p_adar, mem_addr_i, i_val, broadcast);
 	Adar_Write(p_adar, mem_addr_q, q_val, broadcast);
 	Adar_Write(p_adar, REG_LOAD_WORKING, 0x1, broadcast);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Set the VGA gain value of a Tx channel in dB.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return 	Returns ADAR_ERROR_NOERROR if the bias was successfully set. 
 * 					ADAR_ERROR_FAILED if an invalid channel was selected.
 *
 * @warning 0 dB or 15 dB step attenuator may also be turned on, which is why intended operation is >16 dB.
 */
 uint8_t Adar_SetTxBias(const AdarDevice * p_adar, uint8_t broadcast)
 {
 	uint8_t	 vga_bias_bits;
 	uint8_t	 drv_bias_bits;
 	uint32_t mem_vga_bias;
 	uint32_t mem_drv_bias;
 	mem_vga_bias = REG_BIAS_CURRENT_TX;
 	mem_drv_bias = REG_BIAS_CURRENT_TX_DRV;
    // Set bias to nom
 	vga_bias_bits = 0x2D;
 	drv_bias_bits = 0x06;
    // Set bias
 	Adar_Write(p_adar, mem_vga_bias, vga_bias_bits, broadcast);
    // Set bias
 	Adar_Write(p_adar, mem_drv_bias, drv_bias_bits, broadcast);
    // Load the new setting
 	Adar_Write(p_adar, REG_LOAD_WORKING, 0x2, broadcast);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief	Set the VGA gain value of a Tx channel.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	channel     Tx channel in which to set the gain, ranging from 1 - 4.
 * @param 	gain   		Gain to be applied to the channel, ranging from 0 - 127,
 *						plus the MSb 15dB attenuator (Intended operation >16 dB).
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return 	Returns ADAR_ERROR_NOERROR if the gain was successfully set. 
 * 					ADAR_ERROR_FAILED if an invalid channel was selected.
 *
 * @warning 0 dB or 15 dB step attenuator may also be turned on, which is why intended operation is >16 dB.
 */
 uint8_t Adar_SetTxVgaGain(const AdarDevice * p_adar, uint8_t channel, uint8_t gain, uint8_t broadcast)
 {
 	uint32_t mem_addr;
 	if((channel == 0) || (channel > 4))
 	{
 		return(ADAR_ERROR_FAILED);
 	}
 	mem_addr = REG_CH1_TX_GAIN + (channel & 0x03);
    // Set gain
 	Adar_Write(p_adar, mem_addr, gain, broadcast);
    // Load the new setting
 	Adar_Write(p_adar, REG_LOAD_WORKING, LD_WRK_REGS_LDTX_OVERRIDE, broadcast);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief 	Set the phase of a given transmit channel using the I/Q vector modulator.
 *
 * @pre		According to the given @param phase, this sets the polarity (bit 5) and gain (bits 4-0)
 * 			of the @param channel, and then loads them into the working register.
 * 			A vector modulator I/Q look-up table has been provided at the beginning of this library.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	channel   	Channel in which to set the gain (1-4).
 * @param 	phase     	Byte that is used to set the polarity (bit 5) and gain (bits 4-0).
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 *
 * @return 	Returns ADAR_ERROR_NOERROR if the phase was successfully set. 
 * 					ADAR_ERROR_FAILED if an invalid channel was selected.
 *
 * @note    To obtain your phase:
 *          phase = degrees * 128;
 *          phase /= 360;
 */
 uint8_t Adar_SetTxPhase(const AdarDevice * p_adar, uint8_t channel, uint8_t phase, uint8_t broadcast)
 {
 	uint8_t	 i_val = 0;
 	uint8_t	 q_val = 0;
 	uint32_t mem_addr_i, mem_addr_q;
 	if((channel == 0) || (channel > 4))
 	{
 		return(ADAR_ERROR_FAILED);
 	}
 	//phase = phase % 128;
 	i_val = VM_I[phase];
 	q_val = VM_Q[phase];
 	mem_addr_i = REG_CH1_TX_PHS_I + (channel & 0x03) * 2;
 	mem_addr_q = REG_CH1_TX_PHS_Q + (channel & 0x03) * 2;
 	Adar_Write(p_adar, mem_addr_i, i_val, broadcast);
 	Adar_Write(p_adar, mem_addr_q, q_val, broadcast);
 	Adar_Write(p_adar, REG_LOAD_WORKING, 0x1, broadcast);
 	return(ADAR_ERROR_NOERROR);
 }
 /**
 * @brief 	Reset the whole ADAR device.
 *
 * @param	p_adar[in]	ADAR pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 */
 void Adar_SoftReset(const AdarDevice * p_adar)
 {
 	uint8_t instruction[3];
 	instruction[0] = ((p_adar->dev_addr & 0x03) << 5);
 	instruction[1] = 0x00;
 	instruction[2] = 0x81;
 	p_adar->Transfer(instruction, NULL, sizeof(instruction));
 }
 /**
 * @brief 	Reset ALL ADAR devices in the SPI chain.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 */
 void Adar_SoftResetAll(const AdarDevice * p_adar)
 {
 	uint8_t instruction[3];
 	instruction[0] = 0x08;
 	instruction[1] = 0x00;
 	instruction[2] = 0x81;
 	p_adar->Transfer(instruction, NULL, sizeof(instruction));
 }
 /**
 * @brief 	Write a byte of @param data to the register located at @param mem_addr.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	mem_addr  	Memory address of the register you wish to read from.
 * @param 	data      	Byte of data to be stored in the register.
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 						if this set to BROADCAST_ON.
 *
 * @warning If writing the same data to multiple registers, use ADAR_WriteBlock.
 */
 void Adar_Write(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t data, uint8_t broadcast)
 {
 	uint8_t instruction[3];
 	if (broadcast)
 	{
 		instruction[0] = 0x08;
 	}
 	else
 	{
 		instruction[0] = ((p_adar->dev_addr & 0x03) << 5);
 	}
 	instruction[0] |= (0x1F00 & mem_addr) >> 8;
 	instruction[1] = (0xFF & mem_addr);
 	instruction[2] = data;
 	p_adar->Transfer(instruction, NULL, sizeof(instruction));
 }
 /**
 * @brief 	Block memory write to an ADAR device.
 *
 * @pre 	ADDR_ASCN BITS IN REGISTER ZERO MUST BE SET!
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param	mem_addr 	Memory address of the register you wish to read from.
 * @param	p_data[in]  Pointer to block of data to transfer (must have two unused bytes 
 						preceding the data for instruction).
 * @param	size      	Size of data in bytes, including the two additional leading bytes.
 *
 * @warning First two bytes of data will be corrupted if you do not provide two unused leading bytes!
 */
 void Adar_WriteBlock(const AdarDevice * p_adar, uint16_t mem_addr, uint8_t * p_data, uint32_t size)
 {
    // Prepare command
 	p_data[0] = ((p_adar->dev_addr & 0x03) << 5);
 	p_data[0] |= ((mem_addr) >> 8) & 0x1F;
 	p_data[1] = (0xFF & mem_addr);
    // Start the transfer
 	p_adar->Transfer(p_data, NULL, size);
    // Return nothing since we assume this is non-blocking and won't wait around
 }
 /**
 * @brief	Set contents of the INTERFACE_CONFIG_A register.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	flags     	#INTERFACE_CONFIG_A_SOFTRESET, #INTERFACE_CONFIG_A_LSB_FIRST,
 *                  	#INTERFACE_CONFIG_A_ADDR_ASCN, #INTERFACE_CONFIG_A_SDO_ACTIVE
 * @param 	broadcast	Send the message as a broadcast to all ADARs in the SPI chain
 *						if this set to BROADCAST_ON.
 */
 void Adar_WriteConfigA(const AdarDevice * p_adar, uint8_t flags, uint8_t broadcast)
 {
 	Adar_Write(p_adar, 0x00, flags, broadcast);
 }
 /**
 * @brief 	Write a byte of @param data to the register located at @param mem_addr and
 *			then read from the device and verify that the register was correctly set.
 *
 * @param	p_adar[in]	Adar pointer Which specifies the device and what function 
 *						to use for SPI transfer.
 * @param 	mem_addr  	Memory address of the register you wish to read from.
 * @param 	data      	Byte of data to be stored in the register.
 *
 * @return	Returns the number of attempts that it took to successfully write to a register,
 *			starting from zero.
 * @warning This function currently only supports writes to a single regiter in a single ADAR.
 */
 uint8_t Adar_WriteVerify(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t data)
 {
 	uint8_t rx_data;
 	for (uint8_t ii = 0; ii < 3; ii++)
 	{
 		Adar_Write(p_adar, mem_addr, data, 0);
 		// Can't read back from an ADAR with HW address 0
 		if (!((p_adar->dev_addr) % 4))
 		{
 			return(ADAR_ERROR_INVALIDADDR);
 		}
 		rx_data = Adar_Read(p_adar, mem_addr);
 		if (rx_data == data)
 		{
 			return(ii);
 		}
 	}
 	return(ADAR_ERROR_FAILED);
 }
 void Adar_SetBit(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t bit, uint8_t broadcast)
 	{
 		uint8_t temp = Adar_Read(p_adar, mem_addr);
 		uint8_t data = temp|(1<<bit);
 		Adar_Write(p_adar,mem_addr, data,broadcast);
 	}
 void Adar_ResetBit(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t bit, uint8_t broadcast)
 	{
 		uint8_t temp = Adar_Read(p_adar, mem_addr);
 		uint8_t data = temp&~(1<<bit);
 		Adar_Write(p_adar,mem_addr, data,broadcast);
 	}
@@ -1,294 +0,0 @@
 /**
 * MIT License
 * 
 * Copyright (c) 2020 Jimmy Pentz
 *
 * Reach me at: github.com/jgpentz, jpentz1( at )gmail.com
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sells
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
 /* ADAR1000 4-Channel, X Band and Ku Band Beamformer */
 #ifndef LIB_ADAR1000_H_
 #define LIB_ADAR1000_H_
 #ifndef NULL
 #define NULL    (0)
 #endif
 // ----------------------------------------------------------------------------
 // Includes
 // ----------------------------------------------------------------------------
 #include "main.h"
 #include "stm32f7xx_hal.h"
 #include "stm32f7xx_hal_spi.h"
 #include "stm32f7xx_hal_gpio.h"
 #include <stdbool.h>
 #include <stdint.h>
 #include <string.h>
 #ifdef __cplusplus
 extern "C" {  // Prevent C++ name mangling
 #endif
 // ----------------------------------------------------------------------------
 // Datatypes
 // ----------------------------------------------------------------------------
 extern SPI_HandleTypeDef hspi1;
 extern const uint8_t VM_GAIN[128];
 extern const uint8_t VM_I[128];
 extern const uint8_t VM_Q[128];
 /// A function pointer prototype for a SPI transfer, the 3 parameters would be
 /// p_txData, p_rxData, and size (number of bytes to transfer), respectively.
 typedef uint32_t (*Adar_SpiTransfer)( uint8_t *, uint8_t *, uint32_t);
 typedef struct
 {
 	uint8_t			 dev_addr; 		///< 2-bit device hardware address, 0x00, 0x01, 0x10, 0x11
 	Adar_SpiTransfer Transfer;		///< Function pointer to the function used for SPI transfers
 	uint8_t *		 p_rx_buffer;	///< Data buffer to store received bytes into
 }const AdarDevice;
 /// Use this to store bias current values into, as seen in the datasheet 
 /// Table 6. SPI Settings for Different Power Modules
 typedef struct
 {
 	uint8_t rx_lna;		///< nominal:  8, low power: 5
 	uint8_t rx_vm;		///< nominal:  5, low power: 2
 	uint8_t rx_vga;		///< nominal: 10, low power: 3
 	uint8_t tx_vm;		///< nominal:  5, low power: 2
 	uint8_t tx_vga;		///< nominal:  5, low power: 5
 	uint8_t tx_drv;		///< nominal:  6, low power: 3
 } AdarBiasCurrents;
 /// Useful for queries regarding the device info
 typedef struct
 {
 	uint8_t	 norm_operating_mode : 2;
 	uint8_t	 cust_operating_mode : 2;
 	uint8_t	 dev_status : 4;
 	uint8_t	 chip_type;
 	uint16_t product_id;
 	uint8_t	 scratchpad;
 	uint8_t	 spi_rev;
 	uint16_t vendor_id;
 	uint8_t	 rev_id;
 } AdarDeviceInfo;
 /// Return types for functions in this library
 typedef enum {
 	ADAR_ERROR_NOERROR		= 0,
 	ADAR_ERROR_FAILED		= 1,
 	ADAR_ERROR_INVALIDADDR	= 2,
 } AdarErrorCodes;
 // ----------------------------------------------------------------------------
 // Function Prototypes
 // ----------------------------------------------------------------------------
 void Adar_AdcInit(const AdarDevice * p_adar, uint8_t broadcast_bit);
 uint8_t Adar_AdcRead(const AdarDevice * p_adar, uint8_t broadcast_bit);
 uint8_t Adar_GetDeviceInfo(const AdarDevice * p_adar, AdarDeviceInfo * info);
 uint8_t Adar_Read(const AdarDevice * p_adar, uint32_t mem_addr);
 void Adar_ReadBlock(const AdarDevice * p_adar, uint16_t mem_addr, uint8_t * p_data, uint32_t size);
 uint8_t Adar_SetBiasCurrents(const AdarDevice * p_adar, AdarBiasCurrents * p_bias, uint8_t broadcast_bit);
 uint8_t Adar_SetBiasVoltages(const AdarDevice * p_adar, uint8_t bias_on_voltage[5], uint8_t bias_off_voltage[5]);
 uint8_t Adar_SetRamBypass(const AdarDevice * p_adar, uint8_t broadcast_bit);
 uint8_t Adar_SetRxVgaGain(const AdarDevice * p_adar, uint8_t channel, uint8_t vga_gain_db, uint8_t broadcast_bit);
 uint8_t Adar_SetRxPhase(const AdarDevice * p_adar, uint8_t channel, uint8_t phase, uint8_t broadcast_bit);
 uint8_t Adar_SetTxBias(const AdarDevice * p_adar, uint8_t broadcast_bit);
 uint8_t Adar_SetTxVgaGain(const AdarDevice * p_adar, uint8_t channel, uint8_t vga_gain_db, uint8_t broadcast_bit);
 uint8_t Adar_SetTxPhase(const AdarDevice * p_adar, uint8_t channel, uint8_t phase, uint8_t broadcast_bit);
 void Adar_SoftReset(const AdarDevice * p_adar);
 void Adar_SoftResetAll(const AdarDevice * p_adar);
 void Adar_Write(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t data, uint8_t broadcast_bit);
 void Adar_WriteBlock(const AdarDevice * p_adar, uint16_t mem_addr, uint8_t * p_data, uint32_t size);
 void Adar_WriteConfigA(const AdarDevice * p_adar, uint8_t flags, uint8_t broadcast);
 uint8_t Adar_WriteVerify(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t data);
 void Adar_SetBit(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t bit, uint8_t broadcast);
 void Adar_ResetBit(const AdarDevice * p_adar, uint32_t mem_addr, uint8_t bit, uint8_t broadcast);
 // ----------------------------------------------------------------------------
 // Preprocessor Definitions and Constants
 // ----------------------------------------------------------------------------
 // Using BROADCAST_ON will send a command to all ADARs that share a bus
 #define BROADCAST_OFF					 0
 #define BROADCAST_ON					 1
 // The minimum size of a read from the ADARs consists of 3 bytes
 #define ADAR1000_RD_SIZE				 3
 // Address at which the TX RAM starts
 #define ADAR_TX_RAM_START_ADDR			 0x1800
 // ADC Defines
 #define ADAR1000_ADC_2MHZ_CLK			 0x00
 #define ADAR1000_ADC_EN					 0x60
 #define ADAR1000_ADC_ST_CONV			 0x70
 /* REGISTER DEFINITIONS */
 #define REG_INTERFACE_CONFIG_A			 0x000
 #define REG_INTERFACE_CONFIG_B			 0x001
 #define REG_DEV_CONFIG					 0x002
 #define REG_SCRATCHPAD					 0x00A
 #define REG_TRANSFER					 0x00F
 #define REG_CH1_RX_GAIN					 0x010
 #define REG_CH2_RX_GAIN					 0x011
 #define REG_CH3_RX_GAIN					 0x012
 #define REG_CH4_RX_GAIN					 0x013
 #define REG_CH1_RX_PHS_I				 0x014
 #define REG_CH1_RX_PHS_Q				 0x015
 #define REG_CH2_RX_PHS_I				 0x016
 #define REG_CH2_RX_PHS_Q				 0x017
 #define REG_CH3_RX_PHS_I				 0x018
 #define REG_CH3_RX_PHS_Q				 0x019
 #define REG_CH4_RX_PHS_I				 0x01A
 #define REG_CH4_RX_PHS_Q				 0x01B
 #define REG_CH1_TX_GAIN					 0x01C
 #define REG_CH2_TX_GAIN					 0x01D
 #define REG_CH3_TX_GAIN					 0x01E
 #define REG_CH4_TX_GAIN					 0x01F
 #define REG_CH1_TX_PHS_I				 0x020
 #define REG_CH1_TX_PHS_Q				 0x021
 #define REG_CH2_TX_PHS_I				 0x022
 #define REG_CH2_TX_PHS_Q				 0x023
 #define REG_CH3_TX_PHS_I				 0x024
 #define REG_CH3_TX_PHS_Q				 0x025
 #define REG_CH4_TX_PHS_I				 0x026
 #define REG_CH4_TX_PHS_Q				 0x027
 #define REG_LOAD_WORKING				 0x028
 #define REG_PA_CH1_BIAS_ON				 0x029
 #define REG_PA_CH2_BIAS_ON				 0x02A
 #define REG_PA_CH3_BIAS_ON				 0x02B
 #define REG_PA_CH4_BIAS_ON				 0x02C
 #define REG_LNA_BIAS_ON					 0x02D
 #define REG_RX_ENABLES					 0x02E
 #define REG_TX_ENABLES					 0x02F
 #define REG_MISC_ENABLES				 0x030
 #define REG_SW_CONTROL					 0x031
 #define REG_ADC_CONTROL					 0x032
 #define REG_ADC_CONTROL_TEMP_EN			 0xf0
 #define REG_ADC_OUT						 0x033
 #define REG_BIAS_CURRENT_RX_LNA			 0x034
 #define REG_BIAS_CURRENT_RX				 0x035
 #define REG_BIAS_CURRENT_TX				 0x036
 #define REG_BIAS_CURRENT_TX_DRV			 0x037
 #define REG_MEM_CTL						 0x038
 #define REG_RX_CHX_MEM					 0x039
 #define REG_TX_CHX_MEM					 0x03A
 #define REG_RX_CH1_MEM					 0x03D
 #define REG_RX_CH2_MEM					 0x03E
 #define REG_RX_CH3_MEM					 0x03F
 #define REG_RX_CH4_MEM					 0x040
 #define REG_TX_CH1_MEM					 0x041
 #define REG_TX_CH2_MEM					 0x042
 #define REG_TX_CH3_MEM					 0x043
 #define REG_TX_CH4_MEM					 0x044
 #define REG_PA_CH1_BIAS_OFF				 0x046
 #define REG_PA_CH2_BIAS_OFF				 0x047
 #define REG_PA_CH3_BIAS_OFF				 0x048
 #define REG_PA_CH4_BIAS_OFF				 0x049
 #define REG_LNA_BIAS_OFF				 0x04A
 #define REG_TX_BEAM_STEP_START			 0x04D
 #define REG_TX_BEAM_STEP_STOP			 0x04E
 #define REG_RX_BEAM_STEP_START			 0x04F
 #define REG_RX_BEAM_STEP_STOP			 0x050
 // REGISTER CONSTANTS
 #define INTERFACE_CONFIG_A_SOFTRESET	 	((1 << 7) | (1 << 0))
 #define INTERFACE_CONFIG_A_LSB_FIRST	 	((1 << 6) | (1 << 1))
 #define INTERFACE_CONFIG_A_ADDR_ASCN	 	((1 << 5) | (1 << 2))
 #define INTERFACE_CONFIG_A_SDO_ACTIVE		((1 << 4) | (1 << 3))
 #define LD_WRK_REGS_LDRX_OVERRIDE		   	(1 << 0)
 #define LD_WRK_REGS_LDTX_OVERRIDE		   	(1 << 1)
 #define RX_ENABLES_TX_VGA_EN			   	(1 << 0)
 #define RX_ENABLES_TX_VM_EN				   	(1 << 1)
 #define RX_ENABLES_TX_DRV_EN			   	(1 << 2)
 #define RX_ENABLES_CH3_TX_EN			   	(1 << 3)
 #define RX_ENABLES_CH2_TX_EN			   	(1 << 4)
 #define RX_ENABLES_CH1_TX_EN			   	(1 << 5)
 #define RX_ENABLES_CH0_TX_EN			   	(1 << 6)
 #define TX_ENABLES_TX_VGA_EN			   	(1 << 0)
 #define TX_ENABLES_TX_VM_EN				   	(1 << 1)
 #define TX_ENABLES_TX_DRV_EN			   	(1 << 2)
 #define TX_ENABLES_CH3_TX_EN			   	(1 << 3)
 #define TX_ENABLES_CH2_TX_EN			   	(1 << 4)
 #define TX_ENABLES_CH1_TX_EN			   	(1 << 5)
 #define TX_ENABLES_CH0_TX_EN			   	(1 << 6)
 #define MISC_ENABLES_CH4_DET_EN			   	(1 << 0)
 #define MISC_ENABLES_CH3_DET_EN			   	(1 << 1)
 #define MISC_ENABLES_CH2_DET_EN			   	(1 << 2)
 #define MISC_ENABLES_CH1_DET_EN			   	(1 << 3)
 #define MISC_ENABLES_LNA_BIAS_OUT_EN	   	(1 << 4)
 #define MISC_ENABLES_BIAS_EN			   	(1 << 5)
 #define MISC_ENABLES_BIAS_CTRL			   	(1 << 6)
 #define MISC_ENABLES_SW_DRV_TR_MODE_SEL	   	(1 << 7)
 #define SW_CTRL_POL						   	(1 << 0)
 #define SW_CTRL_TR_SPI					   	(1 << 1)
 #define SW_CTRL_TR_SOURCE				   	(1 << 2)
 #define SW_CTRL_SW_DRV_EN_POL			   	(1 << 3)
 #define SW_CTRL_SW_DRV_EN_TR			   	(1 << 4)
 #define SW_CTRL_RX_EN					   	(1 << 5)
 #define SW_CTRL_TX_EN					   	(1 << 6)
 #define SW_CTRL_SW_DRV_TR_STATE			   	(1 << 7)
 #define MEM_CTRL_RX_CHX_RAM_BYPASS		   	(1 << 0)
 #define MEM_CTRL_TX_CHX_RAM_BYPASS		   	(1 << 1)
 #define MEM_CTRL_RX_BEAM_STEP_EN		   	(1 << 2)
 #define MEM_CTRL_TX_BEAM_STEP_EN		   	(1 << 3)
 #define MEM_CTRL_BIAS_RAM_BYPASS		   	(1 << 5)
 #define MEM_CTRL_BEAM_RAM_BYPASS		   	(1 << 6)
 #define MEM_CTRL_SCAN_MODE_EN			   	(1 << 7)
 #ifdef __cplusplus
 }  // End extern "C"
 #endif
 #endif /* LIB_ADAR1000_H_ */
@@ -21,7 +21,6 @@
 #include "usb_device.h"
 #include "USBHandler.h"
 #include "usbd_cdc_if.h"
 #include "adar1000.h"
 #include "ADAR1000_Manager.h"
 #include "ADAR1000_AGC.h"
 extern "C" {
@@ -2180,9 +2179,24 @@ int main(void)
      runRadarPulseSequence();
-      /* [AGC] Outer-loop AGC: read FPGA saturation flag (DIG_5 / PD13),
+      /* [AGC] Outer-loop AGC: sync enable from FPGA via DIG_6 (PD14),
-       * adjust ADAR1000 VGA common gain once per radar frame (~258 ms).
+       * then read saturation flag (DIG_5 / PD13) and adjust ADAR1000 VGA
-       * Only run when AGC is enabled — otherwise leave VGA gains untouched. */
+       * common gain once per radar frame (~258 ms).
       * FPGA register host_agc_enable is the single source of truth —
       * DIG_6 propagates it to MCU every frame.
       * 2-frame confirmation debounce: only change outerAgc.enabled when
       * two consecutive frames read the same DIG_6 value. Prevents a
       * single-sample glitch from causing a spurious AGC state transition.
       * Added latency: 1 extra frame (~258 ms), acceptable for control plane. */
      {
          bool dig6_now = (HAL_GPIO_ReadPin(FPGA_DIG6_GPIO_Port,
                                            FPGA_DIG6_Pin) == GPIO_PIN_SET);
          static bool dig6_prev = false;  // matches boot default (AGC off)
          if (dig6_now == dig6_prev) {
              outerAgc.enabled = dig6_now;
          }
          dig6_prev = dig6_now;
      }
      if (outerAgc.enabled) {
          bool sat = HAL_GPIO_ReadPin(FPGA_DIG5_SAT_GPIO_Port,
                                      FPGA_DIG5_SAT_Pin) == GPIO_PIN_SET;
@@ -50,7 +50,7 @@ static void test_defaults()
    assert(agc.min_gain == 0);
    assert(agc.max_gain == 127);
    assert(agc.holdoff_frames == 4);
-    assert(agc.enabled == true);
+    assert(agc.enabled == false);  // disabled by default — FPGA DIG_6 is source of truth
    assert(agc.holdoff_counter == 0);
    assert(agc.last_saturated == false);
    assert(agc.saturation_event_count == 0);
@@ -67,6 +67,7 @@ static void test_defaults()
 static void test_saturation_reduces_gain()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    uint8_t initial = agc.agc_base_gain;  // 30
    agc.update(true);  // saturation
@@ -82,6 +83,7 @@ static void test_saturation_reduces_gain()
 static void test_holdoff_prevents_early_gain_up()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    agc.update(true);  // saturate once -> gain = 26
    uint8_t after_sat = agc.agc_base_gain;
@@ -101,6 +103,7 @@ static void test_holdoff_prevents_early_gain_up()
 static void test_recovery_after_holdoff()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    agc.update(true);  // saturate -> gain = 26
    uint8_t after_sat = agc.agc_base_gain;
@@ -119,6 +122,7 @@ static void test_recovery_after_holdoff()
 static void test_min_gain_clamp()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    agc.min_gain = 10;
    agc.agc_base_gain = 12;
    agc.gain_step_down = 4;
@@ -136,6 +140,7 @@ static void test_min_gain_clamp()
 static void test_max_gain_clamp()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    agc.max_gain = 32;
    agc.agc_base_gain = 31;
    agc.gain_step_up = 2;
@@ -226,6 +231,7 @@ static void test_apply_gain_spi()
 static void test_reset_preserves_config()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    agc.agc_base_gain = 42;
    agc.gain_step_down = 8;
    agc.cal_offset[3] = -5;
@@ -255,6 +261,7 @@ static void test_reset_preserves_config()
 static void test_saturation_counter()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    for (int i = 0; i < 10; ++i) {
        agc.update(true);
@@ -274,6 +281,7 @@ static void test_saturation_counter()
 static void test_mixed_sequence()
 {
    ADAR1000_AGC agc;
    agc.enabled = true;  // default is OFF; enable for this test
    agc.agc_base_gain = 30;
    agc.gain_step_down = 4;
    agc.gain_step_up = 1;
@@ -137,145 +137,6 @@ module cdc_adc_to_processing #(
 endmodule
 // ============================================================================
 // ASYNC FIFO FOR CONTINUOUS SAMPLE STREAMS
 // ============================================================================
 // Replaces cdc_adc_to_processing for the DDC path where the CIC decimator
 // produces samples at ~100 MSPS from a 400 MHz clock and the consumer runs
 // at 100 MHz. Gray-coded read/write pointers (the only valid use of Gray
 // encoding across clock domains) ensure no data corruption or loss.
 //
 // Depth must be a power of 2. Default 8 entries gives comfortable margin
 // for the 4:1 decimated stream (1 sample per 4 src clocks, 1 consumer
 // clock per sample).
 // ============================================================================
 module cdc_async_fifo #(
    parameter WIDTH = 18,
    parameter DEPTH = 8,            // Must be power of 2
    parameter ADDR_BITS = 3         // log2(DEPTH)
 )(
    // Write (source) domain
    input  wire              wr_clk,
    input  wire              wr_reset_n,
    input  wire [WIDTH-1:0]  wr_data,
    input  wire              wr_en,
    output wire              wr_full,
    // Read (destination) domain
    input  wire              rd_clk,
    input  wire              rd_reset_n,
    output wire [WIDTH-1:0]  rd_data,
    output wire              rd_valid,
    input  wire              rd_ack     // Consumer asserts to pop
 );
    // Gray code conversion functions
    function [ADDR_BITS:0] bin2gray;
        input [ADDR_BITS:0] bin;
        bin2gray = bin ^ (bin >> 1);
    endfunction
    function [ADDR_BITS:0] gray2bin;
        input [ADDR_BITS:0] gray;
        reg [ADDR_BITS:0] bin;
        integer k;
    begin
        bin[ADDR_BITS] = gray[ADDR_BITS];
        for (k = ADDR_BITS-1; k >= 0; k = k - 1)
            bin[k] = bin[k+1] ^ gray[k];
        gray2bin = bin;
    end
    endfunction
    // ------- Pointer declarations (both domains, before use) -------
    // Write domain pointers
    reg [ADDR_BITS:0] wr_ptr_bin  = 0;   // Extra bit for full/empty
    reg [ADDR_BITS:0] wr_ptr_gray = 0;
    // Read domain pointers (declared here so write domain can synchronize them)
    reg [ADDR_BITS:0] rd_ptr_bin  = 0;
    reg [ADDR_BITS:0] rd_ptr_gray = 0;
    // ------- Write domain -------
    // Synchronized read pointer in write domain (scalar regs, not memory
    // arrays — avoids iverilog sensitivity/NBA bugs on array elements and
    // gives synthesis explicit flop names for ASYNC_REG constraints)
    (* ASYNC_REG = "TRUE" *) reg [ADDR_BITS:0] rd_ptr_gray_sync0 = 0;
    (* ASYNC_REG = "TRUE" *) reg [ADDR_BITS:0] rd_ptr_gray_sync1 = 0;
    // FIFO memory (inferred as distributed RAM — small depth)
    reg [WIDTH-1:0] mem [0:DEPTH-1];
    wire wr_addr_match = (wr_ptr_gray == rd_ptr_gray_sync1);
    wire wr_wrap_match = (wr_ptr_gray[ADDR_BITS] != rd_ptr_gray_sync1[ADDR_BITS]) &&
                         (wr_ptr_gray[ADDR_BITS-1] != rd_ptr_gray_sync1[ADDR_BITS-1]) &&
                         (wr_ptr_gray[ADDR_BITS-2:0] == rd_ptr_gray_sync1[ADDR_BITS-2:0]);
    assign wr_full = wr_wrap_match;
    always @(posedge wr_clk) begin
        if (!wr_reset_n) begin
            wr_ptr_bin       <= 0;
            wr_ptr_gray      <= 0;
            rd_ptr_gray_sync0 <= 0;
            rd_ptr_gray_sync1 <= 0;
        end else begin
            // Synchronize read pointer into write domain
            rd_ptr_gray_sync0 <= rd_ptr_gray;
            rd_ptr_gray_sync1 <= rd_ptr_gray_sync0;
            // Write
            if (wr_en && !wr_full) begin
                mem[wr_ptr_bin[ADDR_BITS-1:0]] <= wr_data;
                wr_ptr_bin  <= wr_ptr_bin + 1;
                wr_ptr_gray <= bin2gray(wr_ptr_bin + 1);
            end
        end
    end
    // ------- Read domain -------
    // Synchronized write pointer in read domain (scalar regs — see above)
    (* ASYNC_REG = "TRUE" *) reg [ADDR_BITS:0] wr_ptr_gray_sync0 = 0;
    (* ASYNC_REG = "TRUE" *) reg [ADDR_BITS:0] wr_ptr_gray_sync1 = 0;
    wire rd_empty = (rd_ptr_gray == wr_ptr_gray_sync1);
    // Output register — holds data until consumed
    reg [WIDTH-1:0] rd_data_reg = 0;
    reg rd_valid_reg = 0;
    always @(posedge rd_clk) begin
        if (!rd_reset_n) begin
            rd_ptr_bin        <= 0;
            rd_ptr_gray       <= 0;
            wr_ptr_gray_sync0 <= 0;
            wr_ptr_gray_sync1 <= 0;
            rd_data_reg       <= 0;
            rd_valid_reg      <= 0;
        end else begin
            // Synchronize write pointer into read domain
            wr_ptr_gray_sync0 <= wr_ptr_gray;
            wr_ptr_gray_sync1 <= wr_ptr_gray_sync0;
            // Pop logic: present data when FIFO not empty
            if (!rd_empty && (!rd_valid_reg || rd_ack)) begin
                rd_data_reg <= mem[rd_ptr_bin[ADDR_BITS-1:0]];
                rd_valid_reg <= 1'b1;
                rd_ptr_bin  <= rd_ptr_bin + 1;
                rd_ptr_gray <= bin2gray(rd_ptr_bin + 1);
            end else if (rd_valid_reg && rd_ack) begin
                // Consumer took data but FIFO is empty now
                rd_valid_reg <= 1'b0;
            end
        end
    end
    assign rd_data  = rd_data_reg;
    assign rd_valid = rd_valid_reg;
 endmodule
 // ============================================================================
 // CDC FOR SINGLE BIT SIGNALS
 // Uses synchronous reset on sync chain to avoid metastability on reset
@@ -224,7 +224,7 @@ set_property IOSTANDARD LVCMOS33 [get_ports {stm32_mixers_enable}]
 # 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_6: AGC enable flag (PD14) — mirrors FPGA host_agc_enable to STM32
 # DIG_7: reserved (PD15)
 set_property PACKAGE_PIN H11 [get_ports {gpio_dig5}]
 set_property PACKAGE_PIN G12 [get_ports {gpio_dig6}]
@@ -584,59 +584,41 @@ cic_decimator_4x_enhanced cic_q_inst (
 assign cic_valid = cic_valid_i & cic_valid_q;
 // ============================================================================
-// Clock Domain Crossing: 400 MHz CIC output → 100 MHz FIR input
+// Enhanced FIR Filters with FIXED valid signal handling
-// ============================================================================
+// NOTE: Wire declarations moved BEFORE CDC instances to fix forward-reference
-// The CIC decimates 4:1, producing one sample per 4 clk_400m cycles (~100 MSPS).
+//       error in Icarus Verilog (was originally after CDC instantiation)
 // The FIR runs at clk_100m (100 MHz). The two clocks have unknown phase
 // relationship, so a proper asynchronous FIFO with Gray-coded pointers is
 // required. The old cdc_adc_to_processing module Gray-encoded the sample
 // DATA which is invalid (Gray encoding only guarantees single-bit transitions
 // for monotonically incrementing counters, not arbitrary sample values).
 //
 // Depth 8 provides margin: worst case, 2 samples can be in flight before
 // the read side pops, well within a depth-8 budget.
 // ============================================================================
 wire fir_in_valid_i, fir_in_valid_q;
 wire fir_valid_i, fir_valid_q;
 wire fir_i_ready, fir_q_ready;
-wire [17:0] fir_d_in_i, fir_d_in_q;
+wire [17:0] fir_d_in_i, fir_d_in_q; 
-// I-channel CDC: async FIFO, 400 MHz write → 100 MHz read
+cdc_adc_to_processing #(
-cdc_async_fifo #(
+    .WIDTH(18),
-    .WIDTH(18),
+    .STAGES(3)
-    .DEPTH(8),
+)CDC_FIR_i(
-    .ADDR_BITS(3)
+    .src_clk(clk_400m),
-) CDC_FIR_i (
+    .dst_clk(clk_100m),
-    .wr_clk(clk_400m),
+    .src_reset_n(reset_n_400m),
-    .wr_reset_n(reset_n_400m),
+    .dst_reset_n(reset_n),
-    .wr_data(cic_i_out),
+    .src_data(cic_i_out),
-    .wr_en(cic_valid_i),
+    .src_valid(cic_valid_i),
-    .wr_full(),   // At 1:1 data rate, overflow should not occur
+    .dst_data(fir_d_in_i),
-
+    .dst_valid(fir_in_valid_i)
    .rd_clk(clk_100m),
    .rd_reset_n(reset_n),
    .rd_data(fir_d_in_i),
    .rd_valid(fir_in_valid_i),
    .rd_ack(fir_in_valid_i)   // Auto-pop: consume every valid sample
 );
-// Q-channel CDC: async FIFO, 400 MHz write → 100 MHz read
+cdc_adc_to_processing #(
-cdc_async_fifo #(
+    .WIDTH(18),
-    .WIDTH(18),
+    .STAGES(3)
-    .DEPTH(8),
+)CDC_FIR_q(
-    .ADDR_BITS(3)
+    .src_clk(clk_400m),
-) CDC_FIR_q (
+    .dst_clk(clk_100m),
-    .wr_clk(clk_400m),
+    .src_reset_n(reset_n_400m),
-    .wr_reset_n(reset_n_400m),
+    .dst_reset_n(reset_n),
-    .wr_data(cic_q_out),
+    .src_data(cic_q_out),
-    .wr_en(cic_valid_q),
+    .src_valid(cic_valid_q),
-    .wr_full(),
+    .dst_data(fir_d_in_q),
-
+    .dst_valid(fir_in_valid_q)
    .rd_clk(clk_100m),
    .rd_reset_n(reset_n),
    .rd_data(fir_d_in_q),
    .rd_valid(fir_in_valid_q),
    .rd_ack(fir_in_valid_q)
 );
 // ============================================================================
@@ -531,23 +531,6 @@ xfft_16 fft_inst (
 // Status Outputs
 // ==============================================
 assign processing_active = (state != S_IDLE);
-
+assign frame_complete = (state == S_IDLE && frame_buffer_full == 0);
 // frame_complete must be a single-cycle pulse, not a level.
 // The AGC (rx_gain_control) uses this as frame_boundary to snapshot
 // per-frame metrics and update gain. If held high continuously,
 // the AGC would re-evaluate every clock with zeroed accumulators,
 // collapsing saturation_count/peak_magnitude to zero.
 //
 // Detect the falling edge of processing_active: the exact clock
 // when the Doppler processor finishes all sub-frame FFTs and
 // returns to S_IDLE with the frame buffer drained.
 reg processing_active_prev;
 always @(posedge clk or negedge reset_n) begin
    if (!reset_n)
        processing_active_prev <= 1'b0;
    else
        processing_active_prev <= processing_active;
 end
 assign frame_complete = (~processing_active & processing_active_prev);
 endmodule
@@ -77,7 +77,6 @@ reg signed [15:0] buf_rdata_i, buf_rdata_q;
 // State machine
 reg [3:0] state;
 localparam ST_IDLE = 0;
 localparam ST_WAIT_LISTEN = 9;   // Wait for TX chirp to end before collecting
 localparam ST_COLLECT_DATA = 1;
 localparam ST_ZERO_PAD = 2;
 localparam ST_WAIT_REF = 3;
@@ -99,22 +98,11 @@ reg signed [15:0] overlap_cache_i [0:OVERLAP_SAMPLES-1];
 reg signed [15:0] overlap_cache_q [0:OVERLAP_SAMPLES-1];
 reg [7:0] overlap_copy_count;
 // Listen-window delay counter: skip TX chirp duration before collecting echoes.
 // The chirp_start_pulse fires at the beginning of TX, but the matched filter
 // must collect receive-window samples (echoes), not TX leakage.
 // For long chirp: skip LONG_CHIRP_SAMPLES (3000) ddc_valid counts
 // For short chirp: skip SHORT_CHIRP_SAMPLES (50) ddc_valid counts
 reg [15:0] listen_delay_count;
 reg [15:0] listen_delay_target;
 // Microcontroller sync detection
 // mc_new_chirp/elevation/azimuth are TOGGLE signals from radar_mode_controller:
 // they invert on every event. Detect ANY transition (XOR with previous value),
 // not just rising edge, otherwise every other chirp/elevation/azimuth is missed.
 reg mc_new_chirp_prev, mc_new_elevation_prev, mc_new_azimuth_prev;
-wire chirp_start_pulse = mc_new_chirp ^ mc_new_chirp_prev;
+wire chirp_start_pulse = mc_new_chirp && !mc_new_chirp_prev;
-wire elevation_change_pulse = mc_new_elevation ^ mc_new_elevation_prev;
+wire elevation_change_pulse = mc_new_elevation && !mc_new_elevation_prev;
-wire azimuth_change_pulse = mc_new_azimuth ^ mc_new_azimuth_prev;
+wire azimuth_change_pulse = mc_new_azimuth && !mc_new_azimuth_prev;
 // Processing chain signals
 wire [15:0] fft_pc_i, fft_pc_q;
@@ -196,8 +184,6 @@ always @(posedge clk or negedge reset_n) begin
        buf_wdata_q <= 0;
        buf_raddr <= 0;
        overlap_copy_count <= 0;
        listen_delay_count <= 0;
        listen_delay_target <= 0;
    end else begin
        pc_valid <= 0;
        mem_request <= 0;
@@ -219,45 +205,19 @@ always @(posedge clk or negedge reset_n) begin
                // Wait for chirp start from microcontroller
                if (chirp_start_pulse) begin
                    state <= ST_COLLECT_DATA;
                    total_segments <= use_long_chirp ? LONG_SEGMENTS[2:0] : SHORT_SEGMENTS[2:0];
                    // Delay collection until the listen window opens.
                    // chirp_start_pulse fires at TX start; echoes only arrive
                    // after the chirp finishes. Skip the TX duration by
                    // counting ddc_valid pulses before entering ST_COLLECT_DATA.
                    listen_delay_count <= 0;
                    listen_delay_target <= use_long_chirp ? LONG_CHIRP_SAMPLES[15:0]
                                                         : SHORT_CHIRP_SAMPLES[15:0];
                    state <= ST_WAIT_LISTEN;
                    `ifdef SIMULATION
-                    $display("[MULTI_SEG_FIXED] Chirp start detected, waiting for listen window (%0d samples)",
+                    $display("[MULTI_SEG_FIXED] Starting %s chirp, segments: %d",
-                             use_long_chirp ? LONG_CHIRP_SAMPLES : SHORT_CHIRP_SAMPLES);
+                             use_long_chirp ? "LONG" : "SHORT", 
                             use_long_chirp ? LONG_SEGMENTS : SHORT_SEGMENTS);
                    $display("[MULTI_SEG_FIXED] Overlap: %d samples, Advance: %d samples",
                             OVERLAP_SAMPLES, SEGMENT_ADVANCE);
                    `endif
                end
            end
            ST_WAIT_LISTEN: begin
                // Skip TX chirp duration — count ddc_valid pulses until the
                // listen window opens. This ensures we only collect echo data,
                // not TX leakage or dead time.
                if (ddc_valid) begin
                    if (listen_delay_count >= listen_delay_target - 1) begin
                        // Listen window is now open — begin data collection
                        state <= ST_COLLECT_DATA;
                        `ifdef SIMULATION
                        $display("[MULTI_SEG_FIXED] Listen window open after %0d TX samples, starting %s chirp collection",
                                 listen_delay_count + 1,
                                 use_long_chirp ? "LONG" : "SHORT");
                        $display("[MULTI_SEG_FIXED] Overlap: %d samples, Advance: %d samples",
                                 OVERLAP_SAMPLES, SEGMENT_ADVANCE);
                        `endif
                    end else begin
                        listen_delay_count <= listen_delay_count + 1;
                    end
                end
            end
            ST_COLLECT_DATA: begin
                // Collect samples for current segment with overlap-save
                if (ddc_valid && buffer_write_ptr < BUFFER_SIZE) begin
@@ -574,36 +534,9 @@ always @(posedge clk or negedge reset_n) begin
 end
 `endif
-// ========== OUTPUT CONNECTIONS — OVERLAP-SAVE TRIM ==========
+// ========== OUTPUT CONNECTIONS ==========
 // In overlap-save processing, the first OVERLAP_SAMPLES (128) output bins
 // of each segment after segment 0 are corrupted by circular convolution
 // wrap-around. These must be discarded. Only the SEGMENT_ADVANCE (896)
 // valid bins per segment are forwarded downstream.
 //
 // For segment 0: all 1024 output bins are valid (no prior overlap).
 // For segments 1+: bins [0..127] are artifacts, bins [128..1023] are valid.
 //
 // We count fft_pc_valid pulses per segment and suppress output during
 // the overlap region.
 reg [10:0] output_bin_count;
 wire output_in_overlap = (current_segment != 0) &&
                         (output_bin_count < OVERLAP_SAMPLES);
 always @(posedge clk or negedge reset_n) begin
    if (!reset_n) begin
        output_bin_count <= 0;
    end else begin
        if (state == ST_PROCESSING && buffer_read_ptr == 0) begin
            // Reset counter at start of each segment's processing
            output_bin_count <= 0;
        end else if (fft_pc_valid) begin
            output_bin_count <= output_bin_count + 1;
        end
    end
 end
 assign pc_i_w = fft_pc_i;
 assign pc_q_w = fft_pc_q;
-assign pc_valid_w = fft_pc_valid & ~output_in_overlap;
+assign pc_valid_w = fft_pc_valid;
 endmodule
@@ -130,7 +130,7 @@ module radar_system_top (
    // 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_dig6,          // DIG_6 (G12→PD14): AGC enable flag (mirrors host_agc_enable)
    output wire gpio_dig7           // DIG_7 (H12→PD15): reserved (tied low)
 );
@@ -1037,9 +1037,11 @@ assign system_status = status_reg;
 // ============================================================================
 // 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).
+// DIG_6: AGC enable flag — mirrors host_agc_enable so STM32 outer-loop AGC
 //        tracks the FPGA register as single source of truth.
 // DIG_7: Reserved (tied low for future use).
 assign gpio_dig5 = (rx_agc_saturation_count != 8'd0);
-assign gpio_dig6 = 1'b0;
+assign gpio_dig6 = host_agc_enable;
 assign gpio_dig7 = 1'b0;
 // ============================================================================
@@ -526,25 +526,6 @@ run_test "Radar Mode Controller" \
 echo ""
 # ===========================================================================
 # PHASE 5: P0 ADVERSARIAL TESTS — Invariant Violation Fixes
 # ===========================================================================
 echo "--- PHASE 5: P0 Adversarial Tests ---"
 run_test "P0 Fix #1: Async FIFO CDC (show-ahead, overflow, reset)" \
    tb/tb_p0_async_fifo.vvp \
    tb/tb_p0_async_fifo.v cdc_modules.v
 run_test "P0 Fixes #2/#3/#4: Matched Filter (toggle, listen, overlap)" \
    tb/tb_p0_mf_adversarial.vvp \
    tb/tb_p0_mf_adversarial.v matched_filter_multi_segment.v
 run_test "P0 Fix #7: Frame Complete Pulse (falling-edge)" \
    tb/tb_p0_frame_pulse.vvp \
    tb/tb_p0_frame_pulse.v
 echo ""
 # ===========================================================================
 # SUMMARY
 # ===========================================================================
@@ -1,558 +0,0 @@
 `timescale 1ns / 1ps
 // ============================================================================
 // ADVERSARIAL TESTBENCH: cdc_async_fifo (P0 Fix #1)
 // ============================================================================
 // Actively tries to BREAK the async FIFO that replaced the flawed
 // Gray-encoded CDC for the DDC 400→100 MHz sample path.
 //
 // Attack vectors:
 //   1. Read on empty FIFO — no spurious rd_valid
 //   2. Single write/read — basic data integrity
 //   3. Fill to capacity — wr_full asserts correctly
 //   4. Overflow — write-when-full must be rejected, no corruption
 //   5. Ordered streaming — FIFO order preserved under sustained load
 //   6. Reset mid-transfer — clean recovery, no stale data
 //   7. Burst writes at max wr_clk rate — stress back-pressure
 //   8. wr_full deasserts promptly after read
 //   9. Alternating single-entry traffic — throughput = 1
 //  10. Pathological data patterns — all-ones, alternating bits
 // ============================================================================
 module tb_p0_async_fifo;
    localparam WR_PERIOD = 2.5;     // 400 MHz source clock
    localparam RD_PERIOD = 10.0;    // 100 MHz destination clock
    localparam WIDTH = 18;
    localparam DEPTH = 8;
    // ── Test bookkeeping ─────────────────────────────────────
    integer pass_count = 0;
    integer fail_count = 0;
    integer test_num   = 0;
    integer i, j;
    task check;
        input cond;
        input [511:0] label;
    begin
        test_num = test_num + 1;
        if (cond) begin
            $display("[PASS] Test %0d: %0s", test_num, label);
            pass_count = pass_count + 1;
        end else begin
            $display("[FAIL] Test %0d: %0s", test_num, label);
            fail_count = fail_count + 1;
        end
    end
    endtask
    // ── DUT signals ──────────────────────────────────────────
    reg              wr_clk = 0;
    reg              rd_clk = 0;
    reg              wr_reset_n = 0;
    reg              rd_reset_n = 0;
    reg  [WIDTH-1:0] wr_data = 0;
    reg              wr_en = 0;
    wire             wr_full;
    wire [WIDTH-1:0] rd_data;
    wire             rd_valid;
    reg              rd_ack = 0;
    always #(WR_PERIOD/2) wr_clk = ~wr_clk;
    always #(RD_PERIOD/2) rd_clk = ~rd_clk;
    cdc_async_fifo #(
        .WIDTH(WIDTH), .DEPTH(DEPTH), .ADDR_BITS(3)
    ) dut (
        .wr_clk(wr_clk),   .wr_reset_n(wr_reset_n),
        .wr_data(wr_data),  .wr_en(wr_en),  .wr_full(wr_full),
        .rd_clk(rd_clk),    .rd_reset_n(rd_reset_n),
        .rd_data(rd_data),  .rd_valid(rd_valid), .rd_ack(rd_ack)
    );
    // ── Helper tasks ─────────────────────────────────────────
    task do_reset;
    begin
        wr_en = 0; rd_ack = 0; wr_data = 0;
        wr_reset_n = 0; rd_reset_n = 0;
        #100;
        wr_reset_n = 1; rd_reset_n = 1;
        #50;
    end
    endtask
    task wait_wr_n;
        input integer n;
        integer k;
    begin
        for (k = 0; k < n; k = k + 1) @(posedge wr_clk);
    end
    endtask
    task wait_rd_n;
        input integer n;
        integer k;
    begin
        for (k = 0; k < n; k = k + 1) @(posedge rd_clk);
    end
    endtask
    // ── Read one entry with timeout ──────────────────────────
    reg [WIDTH-1:0] read_result;
    reg read_ok;
    task read_one;
        output [WIDTH-1:0] data_out;
        output             valid_out;
        integer timeout;
    begin
        rd_ack = 1;
        valid_out = 0;
        data_out = {WIDTH{1'bx}};
        for (timeout = 0; timeout < 20; timeout = timeout + 1) begin
            @(posedge rd_clk);
            if (rd_valid) begin
                data_out  = rd_data;
                valid_out = 1;
                timeout   = 999; // break
            end
        end
        @(posedge rd_clk);
        rd_ack = 0;
    end
    endtask
    // ── Drain FIFO, return count of entries read ─────────────
    integer drain_count;
    reg [WIDTH-1:0] drain_buf [0:15];
    task drain_fifo;
        output integer count;
        integer t;
    begin
        count = 0;
        rd_ack = 1;
        for (t = 0; t < 60; t = t + 1) begin
            @(posedge rd_clk);
            if (rd_valid && count < 16) begin
                drain_buf[count] = rd_data;
                count = count + 1;
            end
        end
        rd_ack = 0;
        wait_rd_n(3);
    end
    endtask
    // ══════════════════════════════════════════════════════════
    // MAIN TEST SEQUENCE
    // ══════════════════════════════════════════════════════════
    initial begin
        $dumpfile("tb_p0_async_fifo.vcd");
        $dumpvars(0, tb_p0_async_fifo);
        do_reset;
        // ──────────────────────────────────────────────────────
        // GROUP 1: Empty FIFO — no spurious rd_valid
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 1: Empty FIFO behavior ===");
        // 1a: rd_valid must be 0 when nothing written
        wait_rd_n(10);
        check(rd_valid == 0, "Empty FIFO: rd_valid is 0 (no writes)");
        // 1b: rd_ack on empty must not produce spurious valid
        rd_ack = 1;
        wait_rd_n(10);
        check(rd_valid == 0, "Empty FIFO: rd_ack on empty produces no valid");
        rd_ack = 0;
        wait_rd_n(3);
        // ──────────────────────────────────────────────────────
        // GROUP 2: Single write/read
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 2: Single write/read ===");
        @(posedge wr_clk); #1;
        wr_data = 18'h2ABCD;
        wr_en   = 1;
        @(posedge wr_clk); #1;
        wr_en = 0;
        // Wait for CDC propagation
        wait_rd_n(6);
        check(rd_valid == 1, "Single write: rd_valid asserted");
        check(rd_data == 18'h2ABCD, "Single write: data integrity");
        // ACK and verify deassert
        #1; rd_ack = 1;
        @(posedge rd_clk); #1;
        rd_ack = 0;
        wait_rd_n(6);
        check(rd_valid == 0, "Single write: rd_valid deasserts after ack+empty");
        // ──────────────────────────────────────────────────────
        // GROUP 3: Fill to capacity
        // ──────────────────────────────────────────────────────
        // NOTE: This FIFO uses a pre-fetch show-ahead architecture.
        // When the FIFO goes from empty to non-empty, the read domain
        // auto-presents the first entry into rd_data_reg, advancing
        // rd_ptr by 1.  This frees one slot in the underlying memory,
        // so wr_full requires DEPTH+1 writes (DEPTH in mem + 1 in the
        // output register).  This is necessary because a combinational
        // read from mem across clock domains would be CDC-unsafe.
        $display("\n=== GROUP 3: Fill to capacity ===");
        do_reset;
        // Write DEPTH entries
        for (i = 0; i < DEPTH; i = i + 1) begin
            @(posedge wr_clk); #1;
            wr_data = i[17:0] + 18'h100;
            wr_en   = 1;
        end
        @(posedge wr_clk); #1;
        wr_en = 0;
        // Wait for auto-present round-trip through both synchronizers
        wait_wr_n(12);
        // After auto-present, rd_ptr advanced by 1 → 1 slot freed → not full yet
        check(wr_full == 0, "Pre-fetch show-ahead: DEPTH writes, 1 auto-present frees slot");
        // Write one more entry into the freed slot → now truly full
        @(posedge wr_clk); #1;
        wr_data = 18'hFACE;
        wr_en   = 1;
        @(posedge wr_clk); #1;
        wr_en = 0;
        wait_wr_n(6);
        check(wr_full == 1, "Fill-to-full: wr_full asserted after DEPTH+1 writes");
        // ──────────────────────────────────────────────────────
        // GROUP 4: Overflow — write when full
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 4: Overflow protection ===");
        // Attempt to write 3 more entries while full
        for (i = 0; i < 3; i = i + 1) begin
            @(posedge wr_clk); #1;
            wr_data = 18'h3DEAD + i[17:0];
            wr_en   = 1;
        end
        @(posedge wr_clk); #1;
        wr_en = 0;
        // Drain and verify DEPTH+1 entries (DEPTH mem + 1 output register)
        drain_fifo(drain_count);
        check(drain_count == DEPTH + 1, "Overflow: exactly DEPTH+1 entries (overflow rejected)");
        // Verify data integrity — check first DEPTH entries + the extra FACE entry
        begin : overflow_data_check
            reg data_ok;
            data_ok = 1;
            // First entry is the auto-presented one (index 0 from Group 3)
            if (drain_buf[0] !== 18'h100) begin
                $display("  overflow corruption at [0]: expected %h, got %h",
                         18'h100, drain_buf[0]);
                data_ok = 0;
            end
            // Next DEPTH-1 entries are indices 1..DEPTH-1
            for (i = 1; i < DEPTH; i = i + 1) begin
                if (drain_buf[i] !== i[17:0] + 18'h100) begin
                    $display("  overflow corruption at [%0d]: expected %h, got %h",
                             i, i[17:0] + 18'h100, drain_buf[i]);
                    data_ok = 0;
                end
            end
            // Last entry is the FACE entry from the +1 write
            if (drain_buf[DEPTH] !== 18'hFACE) begin
                $display("  overflow corruption at [%0d]: expected %h, got %h",
                         DEPTH, 18'hFACE, drain_buf[DEPTH]);
                data_ok = 0;
            end
            check(data_ok, "Overflow: all DEPTH+1 entries data intact (no corruption)");
        end
        // ──────────────────────────────────────────────────────
        // GROUP 5: Data ordering under sustained streaming
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 5: Sustained streaming order ===");
        do_reset;
        // Simulate CIC-decimated DDC output: 1 sample per 4 wr_clks
        // Reader continuously ACKs (rate-matched at 100 MHz)
        begin : stream_test
            reg [WIDTH-1:0] expected_val;
            integer read_idx;
            reg ordering_ok;
            ordering_ok = 1;
            read_idx   = 0;
            fork
                // Writer: 32 samples, 1 per 4 wr_clks (rate-matched to rd_clk)
                begin : stream_writer
                    integer w;
                    for (w = 0; w < 32; w = w + 1) begin
                        @(posedge wr_clk); #1;
                        wr_data = w[17:0] + 18'h1000;
                        wr_en   = 1;
                        @(posedge wr_clk); #1;
                        wr_en = 0;
                        wait_wr_n(2); // 4 wr_clks total per sample
                    end
                end
                // Reader: continuously consume at rd_clk rate
                begin : stream_reader
                    integer rd_t;
                    rd_ack = 1;
                    for (rd_t = 0; rd_t < 500 && read_idx < 32; rd_t = rd_t + 1) begin
                        @(posedge rd_clk);
                        if (rd_valid) begin
                            expected_val = read_idx[17:0] + 18'h1000;
                            if (rd_data !== expected_val) begin
                                $display("  stream order error at [%0d]: expected %h, got %h",
                                         read_idx, expected_val, rd_data);
                                ordering_ok = 0;
                            end
                            read_idx = read_idx + 1;
                        end
                    end
                    #1; rd_ack = 0;
                end
            join
            check(read_idx == 32, "Streaming: all 32 samples received");
            check(ordering_ok,    "Streaming: FIFO order preserved");
        end
        // ──────────────────────────────────────────────────────
        // GROUP 6: Reset mid-transfer
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 6: Reset mid-transfer ===");
        do_reset;
        // Write 4 entries
        for (i = 0; i < 4; i = i + 1) begin
            @(posedge wr_clk); #1;
            wr_data = i[17:0] + 18'hAA00;
            wr_en   = 1;
        end
        @(posedge wr_clk); #1;
        wr_en = 0;
        wait_wr_n(3);
        // Assert reset while data is in FIFO
        wr_reset_n = 0; rd_reset_n = 0;
        #50;
        wr_reset_n = 1; rd_reset_n = 1;
        #50;
        // 6a: FIFO must be empty after reset
        wait_rd_n(10);
        check(rd_valid == 0, "Reset mid-xfer: FIFO empty (no stale data)");
        check(wr_full == 0,  "Reset mid-xfer: wr_full deasserted");
        // 6b: New write after reset must work
        @(posedge wr_clk); #1;
        wr_data = 18'h3CAFE;
        wr_en   = 1;
        @(posedge wr_clk); #1;
        wr_en = 0;
        wait_rd_n(6);
        check(rd_valid == 1,           "Reset recovery: rd_valid for new write");
        check(rd_data == 18'h3CAFE,    "Reset recovery: correct data");
        #1; rd_ack = 1; @(posedge rd_clk); #1; rd_ack = 0;
        wait_rd_n(5);
        // ──────────────────────────────────────────────────────
        // GROUP 7: Burst writes at max wr_clk rate
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 7: Max-rate burst ===");
        do_reset;
        // Write 7 entries back-to-back (1 per wr_clk, no decimation)
        for (i = 0; i < 7; i = i + 1) begin
            @(posedge wr_clk); #1;
            wr_data = i[17:0] + 18'hB000;
            wr_en   = 1;
        end
        @(posedge wr_clk); #1;
        wr_en = 0;
        // Drain and count
        drain_fifo(drain_count);
        check(drain_count == 7, "Burst: all 7 entries received (no drops)");
        // ──────────────────────────────────────────────────────
        // GROUP 8: wr_full deasserts after read
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 8: wr_full release ===");
        do_reset;
        // Fill FIFO: DEPTH entries first
        for (i = 0; i < DEPTH; i = i + 1) begin
            @(posedge wr_clk); #1;
            wr_data = i[17:0];
            wr_en   = 1;
        end
        @(posedge wr_clk); #1;
        wr_en = 0;
        // Wait for auto-present round-trip
        wait_wr_n(12);
        // Write the +1 entry (into the slot freed by auto-present)
        @(posedge wr_clk); #1;
        wr_data = 18'h3BEEF;
        wr_en   = 1;
        @(posedge wr_clk); #1;
        wr_en = 0;
        wait_wr_n(6);
        check(wr_full == 1, "wr_full release: initially full (DEPTH+1 writes)");
        // Read one entry (ACK the auto-presented data)
        #1; rd_ack = 1;
        wait_rd_n(2);
        #1; rd_ack = 0;
        // Wait for rd_ptr sync back to wr domain (2 wr_clk cycles + margin)
        wait_wr_n(10);
        check(wr_full == 0, "wr_full release: deasserts after 1 read");
        // Drain rest
        drain_fifo(drain_count);
        wait_rd_n(5);
        // ──────────────────────────────────────────────────────
        // GROUP 9: Alternating single-entry throughput
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 9: Alternating single-entry ===");
        do_reset;
        begin : alt_test
            reg alt_ok;
            reg alt_got_valid;
            integer rd_w;
            alt_ok = 1;
            for (i = 0; i < 12; i = i + 1) begin
                // Write 1
                @(posedge wr_clk); #1;
                wr_data = i[17:0] + 18'hC000;
                wr_en   = 1;
                @(posedge wr_clk); #1;
                wr_en = 0;
                // Read 1 — wait for auto-present with rd_ack=0, then pulse ack
                rd_ack = 0;
                alt_got_valid = 0;
                for (rd_w = 0; rd_w < 20; rd_w = rd_w + 1) begin
                    @(posedge rd_clk);
                    if (rd_valid && !alt_got_valid) begin
                        alt_got_valid = 1;
                        if (rd_data !== i[17:0] + 18'hC000) begin
                            $display("  alt[%0d]: data mismatch", i);
                            alt_ok = 0;
                        end
                        rd_w = 999; // break
                    end
                end
                if (!alt_got_valid) begin
                    $display("  alt[%0d]: no rd_valid after write", i);
                    alt_ok = 0;
                end
                // Consume the entry
                #1; rd_ack = 1;
                @(posedge rd_clk); #1;
                rd_ack = 0;
                wait_rd_n(2);
            end
            check(alt_ok, "Alternating: 12 single-entry cycles all correct");
        end
        // ──────────────────────────────────────────────────────
        // GROUP 10: Pathological data patterns
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP 10: Pathological data patterns ===");
        do_reset;
        begin : patho_test
            reg patho_ok;
            reg patho_seen;
            reg [WIDTH-1:0] patterns [0:4];
            integer rd_w;
            patterns[0] = 18'h3FFFF;   // all ones
            patterns[1] = 18'h00000;   // all zeros
            patterns[2] = 18'h2AAAA;   // alternating 10...
            patterns[3] = 18'h15555;   // alternating 01...
            patterns[4] = 18'h20001;   // MSB + LSB set
            patho_ok = 1;
            // Write all 5 patterns
            for (i = 0; i < 5; i = i + 1) begin
                @(posedge wr_clk); #1;
                wr_data = patterns[i];
                wr_en   = 1;
            end
            @(posedge wr_clk); #1;
            wr_en = 0;
            // Read one at a time: wait for auto-present, check, ack
            rd_ack = 0;
            for (i = 0; i < 5; i = i + 1) begin
                patho_seen = 0;
                for (rd_w = 0; rd_w < 30; rd_w = rd_w + 1) begin
                    @(posedge rd_clk);
                    if (rd_valid && !patho_seen) begin
                        patho_seen = 1;
                        if (rd_data !== patterns[i]) begin
                            $display("  pattern[%0d]: expected %h got %h",
                                     i, patterns[i], rd_data);
                            patho_ok = 0;
                        end
                        rd_w = 999; // break
                    end
                end
                if (!patho_seen) begin
                    $display("  pattern[%0d]: no valid", i);
                    patho_ok = 0;
                end
                // Consume the entry
                #1; rd_ack = 1;
                @(posedge rd_clk); #1;
                rd_ack = 0;
            end
            check(patho_ok, "Pathological: all 5 bit-patterns survive CDC");
        end
        // ══════════════════════════════════════════════════════
        // SUMMARY
        // ══════════════════════════════════════════════════════
        $display("\n============================================");
        $display("  P0 Fix #1: Async FIFO Adversarial Tests");
        $display("============================================");
        $display("  PASSED: %0d", pass_count);
        $display("  FAILED: %0d", fail_count);
        $display("============================================");
        if (fail_count > 0)
            $display("RESULT: FAIL");
        else
            $display("RESULT: PASS");
        $finish;
    end
    // Timeout watchdog
    initial begin
        #1000000;
        $display("[FAIL] TIMEOUT: simulation exceeded 1ms");
        $finish;
    end
 endmodule
@@ -1,361 +0,0 @@
 `timescale 1ns / 1ps
 // ============================================================================
 // ADVERSARIAL TESTBENCH: frame_complete Pulse Width (P0 Fix #7)
 // ============================================================================
 // Tests the falling-edge pulse detection pattern used in doppler_processor.v
 // (lines 533-551) for the frame_complete signal.
 //
 // The OLD code held frame_complete as a continuous level whenever the
 // Doppler processor was idle. This caused the AGC (rx_gain_control) to
 // re-evaluate every clock with zeroed accumulators, collapsing gain control.
 //
 // The FIX detects the falling edge of processing_active:
 //   assign processing_active = (state != S_IDLE);
 //   reg processing_active_prev;
 //   always @(posedge clk or negedge reset_n)
 //       processing_active_prev <= processing_active;
 //   assign frame_complete = (~processing_active & processing_active_prev);
 //
 // This DUT wrapper replicates the EXACT pattern from doppler_processor.v.
 // The adversarial tests drive the state input and verify:
 //   - Pulse width is EXACTLY 1 clock cycle
 //   - No pulse during extended idle
 //   - No pulse on reset deassertion
 //   - Back-to-back frame completions produce distinct pulses
 //   - State transitions not touching S_IDLE produce no pulse
 //   - OLD behavior (continuous level) is regressed
 // ============================================================================
 // ── DUT: Exact replica of doppler_processor.v frame_complete logic ──
 module frame_complete_dut (
    input wire clk,
    input wire reset_n,
    input wire [3:0] state,         // Mimic doppler FSM state input
    output wire processing_active,
    output wire frame_complete
 );
    // S_IDLE encoding from doppler_processor_optimized
    localparam [3:0] S_IDLE = 4'd0;
    assign processing_active = (state != S_IDLE);
    reg processing_active_prev;
    always @(posedge clk or negedge reset_n) begin
        if (!reset_n)
            processing_active_prev <= 1'b0;
        else
            processing_active_prev <= processing_active;
    end
    assign frame_complete = (~processing_active & processing_active_prev);
 endmodule
 // ── TESTBENCH ────────────────────────────────────────────────
 module tb_p0_frame_pulse;
    localparam CLK_PERIOD = 10.0;   // 100 MHz
    // Doppler FSM state encodings (from doppler_processor_optimized)
    localparam [3:0] S_IDLE       = 4'd0;
    localparam [3:0] S_ACCUMULATE = 4'd1;
    localparam [3:0] S_WINDOW     = 4'd2;
    localparam [3:0] S_FFT        = 4'd3;
    localparam [3:0] S_OUTPUT     = 4'd4;
    localparam [3:0] S_NEXT_BIN   = 4'd5;
    // ── Test bookkeeping ─────────────────────────────────────
    integer pass_count = 0;
    integer fail_count = 0;
    integer test_num   = 0;
    integer i;
    task check;
        input cond;
        input [511:0] label;
    begin
        test_num = test_num + 1;
        if (cond) begin
            $display("[PASS] Test %0d: %0s", test_num, label);
            pass_count = pass_count + 1;
        end else begin
            $display("[FAIL] Test %0d: %0s", test_num, label);
            fail_count = fail_count + 1;
        end
    end
    endtask
    // ── DUT signals ──────────────────────────────────────────
    reg        clk = 0;
    reg        reset_n = 0;
    reg  [3:0] state = S_IDLE;
    wire       processing_active;
    wire       frame_complete;
    always #(CLK_PERIOD/2) clk = ~clk;
    frame_complete_dut dut (
        .clk(clk),
        .reset_n(reset_n),
        .state(state),
        .processing_active(processing_active),
        .frame_complete(frame_complete)
    );
    // ── Helper ───────────────────────────────────────────────
    task wait_n;
        input integer n;
        integer k;
    begin
        for (k = 0; k < n; k = k + 1) @(posedge clk);
    end
    endtask
    // ── Count frame_complete pulses over N clocks ────────────
    integer pulse_count;
    task count_pulses;
        input integer n_clocks;
        output integer count;
        integer c;
    begin
        count = 0;
        for (c = 0; c < n_clocks; c = c + 1) begin
            @(posedge clk);
            if (frame_complete) count = count + 1;
        end
    end
    endtask
    // ══════════════════════════════════════════════════════════
    // MAIN TEST SEQUENCE
    // ══════════════════════════════════════════════════════════
    initial begin
        $dumpfile("tb_p0_frame_pulse.vcd");
        $dumpvars(0, tb_p0_frame_pulse);
        // ── RESET ────────────────────────────────────────────
        state   = S_IDLE;
        reset_n = 0;
        #100;
        reset_n = 1;
        @(posedge clk);
        @(posedge clk);
        // ──────────────────────────────────────────────────────
        // TEST 1: No pulse on reset deassertion
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 1: Reset deassertion ===");
        // processing_active = 0 (state = S_IDLE)
        // processing_active_prev was reset to 0
        // frame_complete = ~0 & 0 = 0
        check(frame_complete == 0, "No pulse on reset deassertion (both 0)");
        // ──────────────────────────────────────────────────────
        // TEST 2: No pulse during extended idle
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 2: Extended idle ===");
        count_pulses(200, pulse_count);
        check(pulse_count == 0, "No pulse during 200 clocks of continuous idle");
        // ──────────────────────────────────────────────────────
        // TEST 3: Single frame completion — pulse width = 1
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 3: Single frame completion ===");
        // Enter active state
        @(posedge clk); #1;
        state = S_ACCUMULATE;
        wait_n(5);
        check(processing_active == 1, "Active: processing_active = 1");
        check(frame_complete == 0,    "Active: no frame_complete while active");
        // Stay active for 50 clocks (various states)
        #1; state = S_WINDOW;   wait_n(10);
        #1; state = S_FFT;      wait_n(10);
        #1; state = S_OUTPUT;   wait_n(10);
        #1; state = S_NEXT_BIN; wait_n(10);
        check(frame_complete == 0, "Active (multi-state): no frame_complete");
        // Return to idle — should produce exactly 1 pulse
        #1; state = S_IDLE;
        @(posedge clk);
        // On this edge: processing_active = 0, processing_active_prev = 1
        // frame_complete = ~0 & 1 = 1
        check(frame_complete == 1, "Completion: frame_complete fires");
        @(posedge clk);
        // Now: processing_active_prev catches up to 0
        // frame_complete = ~0 & 0 = 0
        check(frame_complete == 0, "Completion: pulse is EXACTLY 1 cycle wide");
        // Verify no more pulses
        count_pulses(100, pulse_count);
        check(pulse_count == 0, "Post-completion: no re-fire during idle");
        // ──────────────────────────────────────────────────────
        // TEST 4: Back-to-back frame completions
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 4: Back-to-back completions ===");
        begin : backtoback_test
            integer total_pulses;
            total_pulses = 0;
            // Do 5 rapid frame cycles
            for (i = 0; i < 5; i = i + 1) begin
                // Go active
                @(posedge clk); #1;
                state = S_ACCUMULATE;
                wait_n(3);
                // Return to idle
                #1; state = S_IDLE;
                @(posedge clk);
                if (frame_complete) total_pulses = total_pulses + 1;
                @(posedge clk); // pulse should be gone
                if (frame_complete) begin
                    $display("  [WARN] frame %0d: pulse persisted > 1 cycle", i);
                end
            end
            check(total_pulses == 5, "Back-to-back: exactly 5 pulses for 5 completions");
        end
        // ──────────────────────────────────────────────────────
        // TEST 5: State transitions not touching S_IDLE
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 5: Non-idle transitions ===");
        @(posedge clk); #1;
        state = S_ACCUMULATE;
        wait_n(3);
        // Cycle through active states without returning to idle
        begin : nonidle_test
            integer nonidle_pulses;
            nonidle_pulses = 0;
            #1; state = S_WINDOW;
            @(posedge clk);
            if (frame_complete) nonidle_pulses = nonidle_pulses + 1;
            #1; state = S_FFT;
            @(posedge clk);
            if (frame_complete) nonidle_pulses = nonidle_pulses + 1;
            #1; state = S_OUTPUT;
            @(posedge clk);
            if (frame_complete) nonidle_pulses = nonidle_pulses + 1;
            #1; state = S_NEXT_BIN;
            @(posedge clk);
            if (frame_complete) nonidle_pulses = nonidle_pulses + 1;
            #1; state = S_ACCUMULATE;
            wait_n(10);
            count_pulses(10, pulse_count);
            nonidle_pulses = nonidle_pulses + pulse_count;
            check(nonidle_pulses == 0,
                  "Non-idle transitions: zero pulses (all states active)");
        end
        // Return to idle (one pulse expected)
        #1; state = S_IDLE;
        @(posedge clk);
        check(frame_complete == 1, "Cleanup: pulse on final idle transition");
        @(posedge clk);
        // ──────────────────────────────────────────────────────
        // TEST 6: Long active period — no premature pulse
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 6: Long active period ===");
        @(posedge clk); #1;
        state = S_FFT;
        count_pulses(500, pulse_count);
        check(pulse_count == 0, "Long active (500 clocks): no premature pulse");
        #1; state = S_IDLE;
        @(posedge clk);
        check(frame_complete == 1, "Long active → idle: pulse fires");
        @(posedge clk);
        check(frame_complete == 0, "Long active → idle: single cycle only");
        // ──────────────────────────────────────────────────────
        // TEST 7: Reset during active state
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 7: Reset during active ===");
        @(posedge clk); #1;
        state = S_ACCUMULATE;
        wait_n(5);
        // Assert reset while active
        reset_n = 0;
        #50;
        // During reset: processing_active_prev forced to 0
        // state still = S_ACCUMULATE, processing_active = 1
        reset_n = 1;
        @(posedge clk);
        @(posedge clk);
        // After reset release: prev = 0, active = 1
        // frame_complete = ~1 & 0 = 0 (no spurious pulse)
        check(frame_complete == 0, "Reset during active: no spurious pulse");
        // Now go idle — should pulse
        #1; state = S_IDLE;
        @(posedge clk);
        check(frame_complete == 1, "Reset recovery: pulse on idle after active");
        @(posedge clk);
        // ──────────────────────────────────────────────────────
        // TEST 8: REGRESSION — old continuous-level behavior
        // ──────────────────────────────────────────────────────
        $display("\n=== TEST 8: REGRESSION ===");
        // OLD code: frame_complete = (state == S_IDLE && frame_buffer_full == 0)
        // This held frame_complete HIGH for the entire idle period.
        // With AGC sampling frame_complete, this caused re-evaluation every clock.
        //
        // The FIX produces a 1-cycle pulse. We've proven:
        //   - Pulse width = 1 cycle (Test 3)
        //   - No re-fire during idle (Test 2, 3)
        //   - Old behavior would have frame_complete = 1 for 200+ clocks (Test 2)
        //
        // Quantify: old code would produce 200 "events" over 200 idle clocks.
        // New code produces 0. This is the fix.
        state = S_IDLE;
        count_pulses(200, pulse_count);
        check(pulse_count == 0,
              "REGRESSION: 0 pulses in 200 idle clocks (old code: 200)");
        // ══════════════════════════════════════════════════════
        // SUMMARY
        // ══════════════════════════════════════════════════════
        $display("\n============================================");
        $display("  P0 Fix #7: frame_complete Pulse Tests");
        $display("============================================");
        $display("  PASSED: %0d", pass_count);
        $display("  FAILED: %0d", fail_count);
        $display("============================================");
        if (fail_count > 0)
            $display("RESULT: FAIL");
        else
            $display("RESULT: PASS");
        $finish;
    end
    // Timeout watchdog
    initial begin
        #500000;
        $display("[FAIL] TIMEOUT: simulation exceeded 500us");
        $finish;
    end
 endmodule
@@ -1,602 +0,0 @@
 `timescale 1ns / 1ps
 // ============================================================================
 // ADVERSARIAL TESTBENCH: Matched Filter Fixes (P0 Fixes #2, #3, #4)
 // ============================================================================
 // Tests three critical signal-processing invariant fixes in
 // matched_filter_multi_segment.v:
 //
 //   Fix #2 — Toggle detection: XOR replaces AND+NOT so both edges of
 //            mc_new_chirp generate chirp_start_pulse (not just 0→1).
 //
 //   Fix #3 — Listen delay: ST_WAIT_LISTEN state skips TX chirp duration
 //            (counting ddc_valid pulses) before collecting echo samples.
 //
 //   Fix #4 — Overlap-save trim: First 128 output bins of segments 1+
 //            are suppressed (circular convolution artifacts).
 //
 // A STUB processing chain replaces the real FFT pipeline, providing
 // controlled timing for state machine verification.
 // ============================================================================
 // ============================================================================
 // STUB: matched_filter_processing_chain
 // ============================================================================
 // Same port signature as the real module. Accepts 1024 adc_valid samples,
 // simulates a short processing delay, then outputs 1024 range_profile_valid
 // pulses with incrementing data. chain_state reports 0 when idle.
 // ============================================================================
 module matched_filter_processing_chain (
    input wire clk,
    input wire reset_n,
    input wire [15:0] adc_data_i,
    input wire [15:0] adc_data_q,
    input wire adc_valid,
    input wire [5:0] chirp_counter,
    input wire [15:0] long_chirp_real,
    input wire [15:0] long_chirp_imag,
    input wire [15:0] short_chirp_real,
    input wire [15:0] short_chirp_imag,
    output reg signed [15:0] range_profile_i,
    output reg signed [15:0] range_profile_q,
    output reg range_profile_valid,
    output wire [3:0] chain_state
 );
    localparam [3:0] ST_IDLE       = 4'd0;
    localparam [3:0] ST_COLLECTING = 4'd1;
    localparam [3:0] ST_DELAY      = 4'd2;
    localparam [3:0] ST_OUTPUTTING = 4'd3;
    localparam [3:0] ST_DONE       = 4'd9;
    reg [3:0] state = ST_IDLE;
    reg [10:0] count = 0;
    assign chain_state = state;
    always @(posedge clk or negedge reset_n) begin
        if (!reset_n) begin
            state              <= ST_IDLE;
            count              <= 0;
            range_profile_valid <= 0;
            range_profile_i    <= 0;
            range_profile_q    <= 0;
        end else begin
            range_profile_valid <= 0;
            case (state)
                ST_IDLE: begin
                    count <= 0;
                    if (adc_valid) begin
                        state <= ST_COLLECTING;
                        count <= 1;
                    end
                end
                ST_COLLECTING: begin
                    if (adc_valid) begin
                        count <= count + 1;
                        if (count >= 11'd1023) begin
                            state <= ST_DELAY;
                            count <= 0;
                        end
                    end
                end
                ST_DELAY: begin
                    // Simulate processing latency (8 clocks)
                    count <= count + 1;
                    if (count >= 11'd7) begin
                        state <= ST_OUTPUTTING;
                        count <= 0;
                    end
                end
                ST_OUTPUTTING: begin
                    range_profile_valid <= 1;
                    range_profile_i     <= count[15:0];
                    range_profile_q     <= ~count[15:0];
                    count               <= count + 1;
                    if (count >= 11'd1023) begin
                        state <= ST_DONE;
                    end
                end
                ST_DONE: begin
                    state <= ST_IDLE;
                end
                default: state <= ST_IDLE;
            endcase
        end
    end
 endmodule
 // ============================================================================
 // TESTBENCH
 // ============================================================================
 module tb_p0_mf_adversarial;
    localparam CLK_PERIOD = 10.0;   // 100 MHz
    // Override matched_filter parameters for fast simulation
    localparam TB_LONG_CHIRP   = 2000;  // echo samples + listen delay target
    localparam TB_SHORT_CHIRP  = 10;
    localparam TB_LONG_SEGS    = 3;
    localparam TB_SHORT_SEGS   = 1;
    localparam TB_OVERLAP      = 128;
    localparam TB_BUF_SIZE     = 1024;
    localparam TB_SEG_ADVANCE  = TB_BUF_SIZE - TB_OVERLAP; // 896
    // ── Test bookkeeping ─────────────────────────────────────
    integer pass_count = 0;
    integer fail_count = 0;
    integer test_num   = 0;
    integer i;
    task check;
        input cond;
        input [511:0] label;
    begin
        test_num = test_num + 1;
        if (cond) begin
            $display("[PASS] Test %0d: %0s", test_num, label);
            pass_count = pass_count + 1;
        end else begin
            $display("[FAIL] Test %0d: %0s", test_num, label);
            fail_count = fail_count + 1;
        end
    end
    endtask
    // ── DUT signals ──────────────────────────────────────────
    reg         clk = 0;
    reg         reset_n = 0;
    reg  signed [17:0] ddc_i = 0;
    reg  signed [17:0] ddc_q = 0;
    reg         ddc_valid = 0;
    reg         use_long_chirp = 0;
    reg  [5:0]  chirp_counter = 0;
    reg         mc_new_chirp = 0;
    reg         mc_new_elevation = 0;
    reg         mc_new_azimuth = 0;
    reg  [15:0] long_chirp_real = 0;
    reg  [15:0] long_chirp_imag = 0;
    reg  [15:0] short_chirp_real = 0;
    reg  [15:0] short_chirp_imag = 0;
    reg         mem_ready = 1;      // Always ready (stub memory)
    wire [1:0]  segment_request;
    wire [9:0]  sample_addr_out;
    wire        mem_request_w;
    wire signed [15:0] pc_i_w;
    wire signed [15:0] pc_q_w;
    wire        pc_valid_w;
    wire [3:0]  status;
    always #(CLK_PERIOD/2) clk = ~clk;
    matched_filter_multi_segment #(
        .BUFFER_SIZE(TB_BUF_SIZE),
        .LONG_CHIRP_SAMPLES(TB_LONG_CHIRP),
        .SHORT_CHIRP_SAMPLES(TB_SHORT_CHIRP),
        .OVERLAP_SAMPLES(TB_OVERLAP),
        .SEGMENT_ADVANCE(TB_SEG_ADVANCE),
        .LONG_SEGMENTS(TB_LONG_SEGS),
        .SHORT_SEGMENTS(TB_SHORT_SEGS),
        .DEBUG(0)
    ) dut (
        .clk(clk),
        .reset_n(reset_n),
        .ddc_i(ddc_i),
        .ddc_q(ddc_q),
        .ddc_valid(ddc_valid),
        .use_long_chirp(use_long_chirp),
        .chirp_counter(chirp_counter),
        .mc_new_chirp(mc_new_chirp),
        .mc_new_elevation(mc_new_elevation),
        .mc_new_azimuth(mc_new_azimuth),
        .long_chirp_real(long_chirp_real),
        .long_chirp_imag(long_chirp_imag),
        .short_chirp_real(short_chirp_real),
        .short_chirp_imag(short_chirp_imag),
        .segment_request(segment_request),
        .sample_addr_out(sample_addr_out),
        .mem_request(mem_request_w),
        .mem_ready(mem_ready),
        .pc_i_w(pc_i_w),
        .pc_q_w(pc_q_w),
        .pc_valid_w(pc_valid_w),
        .status(status)
    );
    // ── Hierarchical refs for observability ──────────────────
    wire [3:0] dut_state          = dut.state;
    wire       dut_chirp_pulse    = dut.chirp_start_pulse;
    wire       dut_elev_pulse     = dut.elevation_change_pulse;
    wire       dut_azim_pulse     = dut.azimuth_change_pulse;
    wire [15:0] dut_listen_count  = dut.listen_delay_count;
    wire [15:0] dut_listen_target = dut.listen_delay_target;
    wire [2:0] dut_segment        = dut.current_segment;
    wire [10:0] dut_out_bin_count = dut.output_bin_count;
    wire       dut_overlap_gate   = dut.output_in_overlap;
    // State constants (mirror matched_filter_multi_segment localparams)
    localparam [3:0] ST_IDLE         = 4'd0;
    localparam [3:0] ST_COLLECT_DATA = 4'd1;
    localparam [3:0] ST_ZERO_PAD     = 4'd2;
    localparam [3:0] ST_WAIT_REF     = 4'd3;
    localparam [3:0] ST_PROCESSING   = 4'd4;
    localparam [3:0] ST_WAIT_FFT     = 4'd5;
    localparam [3:0] ST_OUTPUT       = 4'd6;
    localparam [3:0] ST_NEXT_SEG     = 4'd7;
    localparam [3:0] ST_OVERLAP_COPY = 4'd8;
    localparam [3:0] ST_WAIT_LISTEN  = 4'd9;
    // ── Helper tasks ─────────────────────────────────────────
    task do_reset;
    begin
        reset_n = 0;
        mc_new_chirp = 0;
        mc_new_elevation = 0;
        mc_new_azimuth = 0;
        ddc_valid = 0;
        ddc_i = 0;
        ddc_q = 0;
        use_long_chirp = 0;
        #100;
        reset_n = 1;
        @(posedge clk);
        @(posedge clk); // Let mc_new_chirp_prev settle to 0
    end
    endtask
    task wait_n;
        input integer n;
        integer k;
    begin
        for (k = 0; k < n; k = k + 1) @(posedge clk);
    end
    endtask
    // Provide N ddc_valid pulses (continuous, every clock)
    task provide_samples;
        input integer n;
        integer k;
    begin
        for (k = 0; k < n; k = k + 1) begin
            @(posedge clk);
            ddc_i     <= k[17:0];
            ddc_q     <= ~k[17:0];
            ddc_valid <= 1;
        end
        @(posedge clk);
        ddc_valid <= 0;
    end
    endtask
    // Wait for DUT to reach a specific state (with timeout)
    task wait_for_state;
        input [3:0] target;
        input integer timeout_clks;
        integer t;
    begin
        for (t = 0; t < timeout_clks; t = t + 1) begin
            @(posedge clk);
            if (dut_state == target) t = timeout_clks + 1; // break
        end
    end
    endtask
    // ══════════════════════════════════════════════════════════
    // MAIN TEST SEQUENCE
    // ══════════════════════════════════════════════════════════
    // Counters for overlap trim verification
    integer seg0_valid_count;
    integer seg1_valid_count;
    reg     seg0_counting, seg1_counting;
    reg     bin127_suppressed, bin128_passed;
    initial begin
        $dumpfile("tb_p0_mf_adversarial.vcd");
        $dumpvars(0, tb_p0_mf_adversarial);
        seg0_valid_count = 0;
        seg1_valid_count = 0;
        seg0_counting    = 0;
        seg1_counting    = 0;
        bin127_suppressed = 0;
        bin128_passed     = 0;
        do_reset;
        // ──────────────────────────────────────────────────────
        // GROUP A: TOGGLE DETECTION (Fix #2)
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP A: Toggle Detection (Fix #2) ===");
        // A1: Rising edge (0→1) generates chirp_start_pulse
        @(posedge clk);
        check(dut_chirp_pulse == 0, "A1 pre: no pulse before toggle");
        #1; mc_new_chirp = 1;   // 0→1
        @(posedge clk);     // pulse should fire (combinational on new vs prev)
        check(dut_chirp_pulse == 1, "A1: rising edge (0->1) generates pulse");
        // Pulse must be 1 cycle wide
        @(posedge clk);     // mc_new_chirp_prev updates to 1
        check(dut_chirp_pulse == 0, "A1: pulse is single-cycle (gone on next clock)");
        // Let state machine settle (it entered ST_WAIT_LISTEN)
        do_reset;
        // A2: Falling edge (1→0) generates pulse — THIS IS THE FIX
        #1; mc_new_chirp = 1;
        @(posedge clk);     // prev catches up to 1
        @(posedge clk);     // prev = 1, mc_new_chirp = 1, XOR = 0
        check(dut_chirp_pulse == 0, "A2 pre: no pulse when stable high");
        #1; mc_new_chirp = 0;   // 1→0
        @(posedge clk);     // XOR: 0 ^ 1 = 1
        check(dut_chirp_pulse == 1, "A2: falling edge (1->0) generates pulse (FIX!)");
        @(posedge clk);
        check(dut_chirp_pulse == 0, "A2: pulse ends after 1 cycle");
        do_reset;
        // A3: Stable low — no spurious pulses over 50 clocks
        begin : stable_low_test
            reg any_pulse;
            any_pulse = 0;
            for (i = 0; i < 50; i = i + 1) begin
                @(posedge clk);
                if (dut_chirp_pulse) any_pulse = 1;
            end
            check(!any_pulse, "A3: stable low for 50 clocks — no spurious pulse");
        end
        // A4: Elevation and azimuth toggles also detected
        #1; mc_new_elevation = 1;  // 0→1
        @(posedge clk);
        check(dut_elev_pulse == 1, "A4a: elevation toggle 0->1 detected");
        @(posedge clk);
        #1; mc_new_elevation = 0;  // 1→0
        @(posedge clk);
        check(dut_elev_pulse == 1, "A4b: elevation toggle 1->0 detected");
        #1; mc_new_azimuth = 1;
        @(posedge clk);
        check(dut_azim_pulse == 1, "A4c: azimuth toggle 0->1 detected");
        @(posedge clk);
        #1; mc_new_azimuth = 0;
        @(posedge clk);
        check(dut_azim_pulse == 1, "A4d: azimuth toggle 1->0 detected");
        // A5: REGRESSION — verify OLD behavior would have failed
        // Old code: chirp_start_pulse = mc_new_chirp && !mc_new_chirp_prev
        // This is a rising-edge detector. On 1→0: 0 && !1 = 0 (missed!)
        // The NEW XOR code: 0 ^ 1 = 1 (detected!)
        // We already proved this works in A2. Document the regression:
        $display("  [INFO] A5 REGRESSION: old AND+NOT code produced 0 for 1->0 transition");
        $display("  [INFO]   old: mc_new_chirp(0) && !mc_new_chirp_prev(1) = 0 && 0 = 0 MISSED");
        $display("  [INFO]   new: mc_new_chirp(0) ^   mc_new_chirp_prev(1) = 0 ^ 1 = 1 DETECTED");
        check(1, "A5: REGRESSION documented — falling edge was missed by old code");
        do_reset;
        // ──────────────────────────────────────────────────────
        // GROUP B: LISTEN DELAY (Fix #3)
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP B: Listen Delay (Fix #3) ===");
        // Use SHORT chirp: listen_delay_target = TB_SHORT_CHIRP = 10
        #1; use_long_chirp = 0;
        // B1: Chirp start → enters ST_WAIT_LISTEN (not ST_COLLECT_DATA)
        mc_new_chirp = 1;   // toggle 0→1
        @(posedge clk);     // pulse fires, state machine acts
        @(posedge clk);     // non-blocking assignment settles
        check(dut_state == ST_WAIT_LISTEN, "B1: enters ST_WAIT_LISTEN (not COLLECT_DATA)");
        check(dut_listen_target == TB_SHORT_CHIRP,
              "B1: listen_delay_target = SHORT_CHIRP_SAMPLES");
        // B2: Counter increments only on ddc_valid
        // Provide 5 valid pulses, then 5 clocks without valid, then 5 more valid
        for (i = 0; i < 5; i = i + 1) begin
            @(posedge clk);
            ddc_valid <= 1;
            ddc_i <= i[17:0];
            ddc_q <= 0;
        end
        @(posedge clk);
        ddc_valid <= 0;
        // Counter should be 5 after 5 valid pulses
        @(posedge clk);
        check(dut_listen_count == 5, "B2a: counter = 5 after 5 valid pulses");
        check(dut_state == ST_WAIT_LISTEN, "B2a: still in ST_WAIT_LISTEN");
        // B3: 5 clocks with no valid — counter must NOT advance
        wait_n(5);
        check(dut_listen_count == 5, "B3: counter stays 5 during ddc_valid gaps");
        check(dut_state == ST_WAIT_LISTEN, "B3: still in ST_WAIT_LISTEN");
        // B4: Provide remaining pulses to hit boundary
        // Need 5 more valid pulses (total 10 = TB_SHORT_CHIRP)
        // Counter transitions at >= target-1 = 9, so pulse 10 triggers
        for (i = 0; i < 4; i = i + 1) begin
            @(posedge clk);
            ddc_valid <= 1;
            ddc_i <= (i + 5);
            ddc_q <= 0;
        end
        // After 4 more: count = 9 = target-1 → transition happens on THIS valid
        @(posedge clk);
        ddc_valid <= 1;  // 10th pulse
        @(posedge clk);
        ddc_valid <= 0;
        @(posedge clk); // Let non-blocking assignments settle
        check(dut_state == ST_COLLECT_DATA,
              "B4: transitions to ST_COLLECT_DATA after exact delay count");
        // B5: First sample collected is the one AFTER the delay
        // The module is now in ST_COLLECT_DATA. Provide a sample and verify
        // it gets written to the buffer (buffer_write_ptr should advance)
        begin : first_sample_check
            reg [10:0] ptr_before;
            ptr_before = dut.buffer_write_ptr;
            @(posedge clk);
            ddc_valid <= 1;
            ddc_i <= 18'h1FACE;
            ddc_q <= 18'h1BEEF;
            @(posedge clk);
            ddc_valid <= 0;
            @(posedge clk);
            check(dut.buffer_write_ptr == ptr_before + 1,
                  "B5: first echo sample collected (write_ptr advanced)");
        end
        do_reset;
        // ──────────────────────────────────────────────────────
        // GROUP C: OVERLAP-SAVE OUTPUT TRIM (Fix #4)
        // ──────────────────────────────────────────────────────
        $display("\n=== GROUP C: Overlap-Save Output Trim (Fix #4) ===");
        // Use LONG chirp with 2+ segments for overlap trim testing
        #1; use_long_chirp = 1;
        seg0_valid_count = 0;
        seg1_valid_count = 0;
        // C-SETUP: Trigger chirp, pass through listen delay, process 2 segments
        mc_new_chirp = 1;   // toggle 0→1
        @(posedge clk);
        @(posedge clk);
        check(dut_state == ST_WAIT_LISTEN, "C-setup: entered ST_WAIT_LISTEN");
        check(dut_listen_target == TB_LONG_CHIRP,
              "C-setup: listen target = LONG_CHIRP_SAMPLES");
        // Pass through listen delay: provide TB_LONG_CHIRP (2000) ddc_valid pulses
        $display("  [INFO] Providing %0d listen-delay samples...", TB_LONG_CHIRP);
        provide_samples(TB_LONG_CHIRP);
        // Should now be in ST_COLLECT_DATA
        @(posedge clk);
        check(dut_state == ST_COLLECT_DATA,
              "C-setup: in ST_COLLECT_DATA after listen delay");
        // ── SEGMENT 0: Collect 1024 samples ──
        $display("  [INFO] Providing 1024 echo samples for segment 0...");
        provide_samples(TB_BUF_SIZE);
        // Should transition through WAIT_REF → PROCESSING → WAIT_FFT
        // mem_ready is always 1, so WAIT_REF passes immediately
        wait_for_state(ST_WAIT_FFT, 2000);
        check(dut_state == ST_WAIT_FFT, "C-setup: seg0 reached ST_WAIT_FFT");
        check(dut_segment == 0, "C-setup: processing segment 0");
        // During ST_WAIT_FFT, the stub chain outputs 1024 fft_pc_valid pulses.
        // Count pc_valid_w (the gated output) for segment 0.
        seg0_counting = 1;
        wait_for_state(ST_OUTPUT, 2000);
        seg0_counting = 0;
        // C1: Segment 0 — ALL output bins should pass (no trim)
        check(seg0_valid_count == TB_BUF_SIZE,
              "C1: segment 0 — all 1024 output bins pass (no trim)");
        // Let state machine proceed to next segment
        wait_for_state(ST_COLLECT_DATA, 500);
        check(dut_segment == 1, "C-setup: advanced to segment 1");
        // ── SEGMENT 1: Collect 896 samples (buffer starts at 128 from overlap) ──
        $display("  [INFO] Providing %0d echo samples for segment 1...", TB_SEG_ADVANCE);
        provide_samples(TB_SEG_ADVANCE);
        // Wait for seg 1 processing
        wait_for_state(ST_WAIT_FFT, 2000);
        check(dut_state == ST_WAIT_FFT, "C-setup: seg1 reached ST_WAIT_FFT");
        // Count pc_valid_w during segment 1 output
        seg1_counting = 1;
        bin127_suppressed = 0;
        bin128_passed     = 0;
        // Monitor specific boundary bins during chain output
        begin : seg1_output_monitor
            integer wait_count;
            for (wait_count = 0; wait_count < 2000; wait_count = wait_count + 1) begin
                @(posedge clk);
                // Check boundary: bin 127 should be suppressed
                if (dut_out_bin_count == 127 && dut.fft_pc_valid) begin
                    if (pc_valid_w == 0) bin127_suppressed = 1;
                end
                // Check boundary: bin 128 should pass
                if (dut_out_bin_count == 128 && dut.fft_pc_valid) begin
                    if (pc_valid_w == 1) bin128_passed = 1;
                end
                if (dut_state == ST_OUTPUT) begin
                    wait_count = 9999; // break
                end
            end
        end
        seg1_counting = 0;
        // C2: Segment 1 — first 128 bins suppressed, 896 pass
        check(seg1_valid_count == TB_SEG_ADVANCE,
              "C2: segment 1 — exactly 896 output bins pass (128 trimmed)");
        // C3: Boundary bin accuracy
        check(bin127_suppressed, "C3a: bin 127 suppressed (overlap artifact)");
        check(bin128_passed,     "C3b: bin 128 passes (first valid bin)");
        // C4: Overlap gate signal logic
        // For segment != 0, output_in_overlap should be true when bin_count < 128
        check(dut_segment == 1, "C4 pre: still on segment 1");
        // (Gate was already verified implicitly by C2/C3 counts)
        check(1, "C4: overlap gate correctly suppresses bins [0..127] on seg 1+");
        // ══════════════════════════════════════════════════════
        // SUMMARY
        // ══════════════════════════════════════════════════════
        $display("\n============================================");
        $display("  P0 Fixes #2/#3/#4: MF Adversarial Tests");
        $display("============================================");
        $display("  PASSED: %0d", pass_count);
        $display("  FAILED: %0d", fail_count);
        $display("============================================");
        if (fail_count > 0)
            $display("RESULT: FAIL");
        else
            $display("RESULT: PASS");
        $finish;
    end
    // ── Continuous counters for overlap trim verification ────
    always @(posedge clk) begin
        if (seg0_counting && pc_valid_w)
            seg0_valid_count <= seg0_valid_count + 1;
        if (seg1_counting && pc_valid_w)
            seg1_valid_count <= seg1_valid_count + 1;
    end
    // Timeout watchdog (generous for 2000-sample listen delay + 2 segments)
    initial begin
        #5000000;
        $display("[FAIL] TIMEOUT: simulation exceeded 5ms");
        $finish;
    end
 endmodule
@@ -0,0 +1,216 @@
 """ADAR1000 vector-modulator ground-truth table and firmware parser.
 This module is a pure data + helpers library imported by the cross-layer
 test suite (`9_Firmware/tests/cross_layer/test_cross_layer_contract.py`,
 class `TestTier2Adar1000VmTableGroundTruth`). It has no CLI entry point
 and no side effects on import beyond the structural assertion on the
 table length.
 Ground-truth source
 -------------------
 The 128-entry `(I, Q)` byte pairs below are transcribed from the ADAR1000
 datasheet Rev. B, Tables 13-16, page 34 ("Phase Shifter Programming"),
 which is the primary normative reference. The same values appear in the
 Analog Devices Linux beamformer driver
 (`drivers/iio/beamformer/adar1000.c`, `adar1000_phase_values[]`) and were
 cross-checked against that driver as a secondary, independent
 transcription. The byte values are factual data (5-bit unsigned magnitude
 in bits[4:0], polarity bit at bit[5], bits[7:6] reserved zero); no
 copyrightable creative expression. Only the datasheet is the
 licensing-relevant source.
 PLFM_RADAR firmware indexing convention
 ---------------------------------------
 `adarSetRxPhase` / `adarSetTxPhase` in
 `9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/ADAR1000_Manager.cpp`
 write `VM_I[phase % 128]` and `VM_Q[phase % 128]` to the chip. Each index
 N corresponds to commanded beam phase `N * 360/128 = N * 2.8125 deg`. The
 ADI table is also on a uniform 2.8125 deg grid (verified by
 `check_uniform_2p8125_deg_step` below), so a 1:1 mapping is correct:
 PLFM index N == ADI table row N.
 """
 from __future__ import annotations
 import re
 # ----------------------------------------------------------------------------
 # Ground truth: ADAR1000 datasheet Rev. B Tables 13-16 p.34
 # Each entry: (angle_int_deg, angle_frac_x10000, vm_byte_I, vm_byte_Q)
 # ----------------------------------------------------------------------------
 GROUND_TRUTH: list[tuple[int, int, int, int]] = [
    (0, 0, 0x3F, 0x20), (2, 8125, 0x3F, 0x21), (5, 6250, 0x3F, 0x23),
    (8, 4375, 0x3F, 0x24), (11, 2500, 0x3F, 0x26), (14, 625, 0x3E, 0x27),
    (16, 8750, 0x3E, 0x28), (19, 6875, 0x3D, 0x2A), (22, 5000, 0x3D, 0x2B),
    (25, 3125, 0x3C, 0x2D), (28, 1250, 0x3C, 0x2E), (30, 9375, 0x3B, 0x2F),
    (33, 7500, 0x3A, 0x30), (36, 5625, 0x39, 0x31), (39, 3750, 0x38, 0x33),
    (42, 1875, 0x37, 0x34), (45, 0, 0x36, 0x35), (47, 8125, 0x35, 0x36),
    (50, 6250, 0x34, 0x37), (53, 4375, 0x33, 0x38), (56, 2500, 0x32, 0x38),
    (59, 625, 0x30, 0x39), (61, 8750, 0x2F, 0x3A), (64, 6875, 0x2E, 0x3A),
    (67, 5000, 0x2C, 0x3B), (70, 3125, 0x2B, 0x3C), (73, 1250, 0x2A, 0x3C),
    (75, 9375, 0x28, 0x3C), (78, 7500, 0x27, 0x3D), (81, 5625, 0x25, 0x3D),
    (84, 3750, 0x24, 0x3D), (87, 1875, 0x22, 0x3D), (90, 0, 0x21, 0x3D),
    (92, 8125, 0x01, 0x3D), (95, 6250, 0x03, 0x3D), (98, 4375, 0x04, 0x3D),
    (101, 2500, 0x06, 0x3D), (104, 625, 0x07, 0x3C), (106, 8750, 0x08, 0x3C),
    (109, 6875, 0x0A, 0x3C), (112, 5000, 0x0B, 0x3B), (115, 3125, 0x0D, 0x3A),
    (118, 1250, 0x0E, 0x3A), (120, 9375, 0x0F, 0x39), (123, 7500, 0x11, 0x38),
    (126, 5625, 0x12, 0x38), (129, 3750, 0x13, 0x37), (132, 1875, 0x14, 0x36),
    (135, 0, 0x16, 0x35), (137, 8125, 0x17, 0x34), (140, 6250, 0x18, 0x33),
    (143, 4375, 0x19, 0x31), (146, 2500, 0x19, 0x30), (149, 625, 0x1A, 0x2F),
    (151, 8750, 0x1B, 0x2E), (154, 6875, 0x1C, 0x2D), (157, 5000, 0x1C, 0x2B),
    (160, 3125, 0x1D, 0x2A), (163, 1250, 0x1E, 0x28), (165, 9375, 0x1E, 0x27),
    (168, 7500, 0x1E, 0x26), (171, 5625, 0x1F, 0x24), (174, 3750, 0x1F, 0x23),
    (177, 1875, 0x1F, 0x21), (180, 0, 0x1F, 0x20), (182, 8125, 0x1F, 0x01),
    (185, 6250, 0x1F, 0x03), (188, 4375, 0x1F, 0x04), (191, 2500, 0x1F, 0x06),
    (194, 625, 0x1E, 0x07), (196, 8750, 0x1E, 0x08), (199, 6875, 0x1D, 0x0A),
    (202, 5000, 0x1D, 0x0B), (205, 3125, 0x1C, 0x0D), (208, 1250, 0x1C, 0x0E),
    (210, 9375, 0x1B, 0x0F), (213, 7500, 0x1A, 0x10), (216, 5625, 0x19, 0x11),
    (219, 3750, 0x18, 0x13), (222, 1875, 0x17, 0x14), (225, 0, 0x16, 0x15),
    (227, 8125, 0x15, 0x16), (230, 6250, 0x14, 0x17), (233, 4375, 0x13, 0x18),
    (236, 2500, 0x12, 0x18), (239, 625, 0x10, 0x19), (241, 8750, 0x0F, 0x1A),
    (244, 6875, 0x0E, 0x1A), (247, 5000, 0x0C, 0x1B), (250, 3125, 0x0B, 0x1C),
    (253, 1250, 0x0A, 0x1C), (255, 9375, 0x08, 0x1C), (258, 7500, 0x07, 0x1D),
    (261, 5625, 0x05, 0x1D), (264, 3750, 0x04, 0x1D), (267, 1875, 0x02, 0x1D),
    (270, 0, 0x01, 0x1D), (272, 8125, 0x21, 0x1D), (275, 6250, 0x23, 0x1D),
    (278, 4375, 0x24, 0x1D), (281, 2500, 0x26, 0x1D), (284, 625, 0x27, 0x1C),
    (286, 8750, 0x28, 0x1C), (289, 6875, 0x2A, 0x1C), (292, 5000, 0x2B, 0x1B),
    (295, 3125, 0x2D, 0x1A), (298, 1250, 0x2E, 0x1A), (300, 9375, 0x2F, 0x19),
    (303, 7500, 0x31, 0x18), (306, 5625, 0x32, 0x18), (309, 3750, 0x33, 0x17),
    (312, 1875, 0x34, 0x16), (315, 0, 0x36, 0x15), (317, 8125, 0x37, 0x14),
    (320, 6250, 0x38, 0x13), (323, 4375, 0x39, 0x11), (326, 2500, 0x39, 0x10),
    (329, 625, 0x3A, 0x0F), (331, 8750, 0x3B, 0x0E), (334, 6875, 0x3C, 0x0D),
    (337, 5000, 0x3C, 0x0B), (340, 3125, 0x3D, 0x0A), (343, 1250, 0x3E, 0x08),
    (345, 9375, 0x3E, 0x07), (348, 7500, 0x3E, 0x06), (351, 5625, 0x3F, 0x04),
    (354, 3750, 0x3F, 0x03), (357, 1875, 0x3F, 0x01),
 ]
 assert len(GROUND_TRUTH) == 128, f"GROUND_TRUTH must have 128 entries, has {len(GROUND_TRUTH)}"
 VM_I_REF: list[int] = [row[2] for row in GROUND_TRUTH]
 VM_Q_REF: list[int] = [row[3] for row in GROUND_TRUTH]
 # ----------------------------------------------------------------------------
 # Structural-invariant checks on the embedded ground-truth transcription.
 # These defend against typos during the copy-paste from the datasheet / ADI
 # driver. Each function returns a list of error strings (empty == pass) so
 # callers (the pytest class) can assert-on-empty with a useful message.
 # ----------------------------------------------------------------------------
 def check_byte_format(label: str, table: list[int]) -> list[str]:
    """Each byte must have bits[7:6] == 0 (reserved)."""
    errors = []
    for i, byte in enumerate(table):
        if byte & 0xC0:
            errors.append(f"{label}[{i}]=0x{byte:02X}: reserved bits[7:6] non-zero")
    return errors
 def check_uniform_2p8125_deg_step() -> list[str]:
    """Angles must form a uniform 2.8125 deg grid: angle[N] == N * 2.8125."""
    errors = []
    for i, (deg_int, deg_frac, _, _) in enumerate(GROUND_TRUTH):
        # angle in units of 1/10000 degree; 2.8125 deg = 28125/10000 exactly
        angle_e4 = deg_int * 10000 + deg_frac
        expected_e4 = i * 28125
        if angle_e4 != expected_e4:
            errors.append(
                f"GROUND_TRUTH[{i}]: angle {deg_int}.{deg_frac:04d} deg "
                f"(={angle_e4}/10000) != expected {expected_e4}/10000 "
                f"(=i*2.8125)"
            )
    return errors
 def check_quadrant_symmetry() -> list[str]:
    """Angle and angle+180 deg must have inverted polarity bits but identical
    magnitudes. Index offset 64 corresponds to 180 deg on the 128-step grid.
    Exemption: when magnitude is zero the polarity bit is physically
    meaningless (sign of zero is undefined for the IQ phasor projection).
    The datasheet uses POL=1 for both 0 and 180 deg Q components (both
    encode Q=0). Skip the polarity assertion for zero-magnitude entries.
    """
    errors = []
    POL = 0x20
    MAG = 0x1F
    for i in range(64):
        j = i + 64
        mag_i_a, mag_i_b = VM_I_REF[i] & MAG, VM_I_REF[j] & MAG
        if mag_i_a != mag_i_b:
            errors.append(
                f"VM_I[{i}]=0x{VM_I_REF[i]:02X} vs VM_I[{j}]=0x{VM_I_REF[j]:02X}: "
                f"180 deg pair has different magnitude"
            )
        if mag_i_a != 0 and (VM_I_REF[i] & POL) == (VM_I_REF[j] & POL):
            errors.append(
                f"VM_I[{i}]=0x{VM_I_REF[i]:02X} vs VM_I[{j}]=0x{VM_I_REF[j]:02X}: "
                f"180 deg pair has same polarity (should be inverted, mag={mag_i_a})"
            )
        mag_q_a, mag_q_b = VM_Q_REF[i] & MAG, VM_Q_REF[j] & MAG
        if mag_q_a != mag_q_b:
            errors.append(
                f"VM_Q[{i}]=0x{VM_Q_REF[i]:02X} vs VM_Q[{j}]=0x{VM_Q_REF[j]:02X}: "
                f"180 deg pair has different magnitude"
            )
        if mag_q_a != 0 and (VM_Q_REF[i] & POL) == (VM_Q_REF[j] & POL):
            errors.append(
                f"VM_Q[{i}]=0x{VM_Q_REF[i]:02X} vs VM_Q[{j}]=0x{VM_Q_REF[j]:02X}: "
                f"180 deg pair has same polarity (should be inverted, mag={mag_q_a})"
            )
    return errors
 def check_cardinal_points() -> list[str]:
    """Spot-check cardinal phase points against datasheet expectations."""
    errors = []
    expectations = [
        (0,  0x3F, 0x20, "0 deg: max +I, ~zero Q"),
        (32, 0x21, 0x3D, "90 deg: ~zero I, max +Q"),
        (64, 0x1F, 0x20, "180 deg: max -I, ~zero Q"),
        (96, 0x01, 0x1D, "270 deg: ~zero I, max -Q"),
    ]
    for idx, exp_i, exp_q, desc in expectations:
        if VM_I_REF[idx] != exp_i or VM_Q_REF[idx] != exp_q:
            errors.append(
                f"index {idx} ({desc}): expected (0x{exp_i:02X}, 0x{exp_q:02X}), "
                f"got (0x{VM_I_REF[idx]:02X}, 0x{VM_Q_REF[idx]:02X})"
            )
    return errors
 # ----------------------------------------------------------------------------
 # Parse VM_I[] / VM_Q[] from firmware C++ source.
 # ----------------------------------------------------------------------------
 ARRAY_RE = re.compile(
    r"const\s+uint8_t\s+ADAR1000Manager::(?P<name>VM_I|VM_Q|VM_GAIN)\s*"
    r"\[\s*128\s*\]\s*=\s*\{(?P<body>[^}]*)\}\s*;",
    re.DOTALL,
 )
 HEX_RE = re.compile(r"0[xX][0-9a-fA-F]{1,2}")
 def parse_array(source: str, name: str) -> list[int] | None:
    """Extract a 128-entry uint8_t array from C++ source by name.
    Returns None if the array is not found. Returns a list (possibly shorter
    than 128) of the parsed bytes if found; caller is responsible for length
    validation.
    LIMITATION (intentional, see PR fix/adar1000-vm-tables review finding #2):
    ARRAY_RE uses `[^}]*` for the body, which terminates at the first `}`.
    This is sufficient for the *flat* `const uint8_t NAME[128] = { ... };`
    declarations VM_I/VM_Q use today, but it would mis-parse if the array
    body ever contained nested braces (e.g. designated initialisers, struct
    aggregates, or macro-expansions producing braces). If the firmware ever
    needs such a form for the VM tables, replace ARRAY_RE with a balanced
    brace-counting parser. Until then, the current regex is preferred for
    its simplicity and the round-trip tests will catch any silent breakage.
    """
    for m in ARRAY_RE.finditer(source):
        if m.group("name") != name:
            continue
        body = m.group("body")
        body = re.sub(r"//[^\n]*", "", body)
        body = re.sub(r"/\*.*?\*/", "", body, flags=re.DOTALL)
        return [int(tok, 16) for tok in HEX_RE.findall(body)]
    return None
@@ -26,11 +26,14 @@ layers agree (because both could be wrong).
 from __future__ import annotations
 import ast
 import os
 import re
 import struct
 import subprocess
 import tempfile
 from pathlib import Path
 from typing import ClassVar
 import pytest
@@ -40,6 +43,7 @@ import sys
 THIS_DIR = Path(__file__).resolve().parent
 sys.path.insert(0, str(THIS_DIR))
 import contract_parser as cp  # noqa: E402
 import adar1000_vm_reference as adar_vm  # noqa: E402
 # Also add the GUI dir to import radar_protocol
 sys.path.insert(0, str(cp.GUI_DIR))
@@ -76,6 +80,78 @@ if _in_ci:
        )
 def _strip_cxx_comments_and_strings(src: str) -> str:
    """Return src with all C/C++ comments and string/char literals removed.
    Tokenising state machine with four states:
      * CODE              — default; watches for `"`, `'`, `//`, `/*`
      * STRING ("...")    — handles `\\"` and `\\\\` escapes
      * CHAR   ('...')    — handles `\\'` and `\\\\` escapes
      * LINE_COMMENT      — until next `\\n`
      * BLOCK_COMMENT     — until next `*/`
    Used by test_vm_gain_table_is_not_reintroduced to ensure the substring
    "VM_GAIN" appearing only inside an explanatory comment or a string
    literal does NOT count as code reintroduction. We replace stripped
    regions with a single space so token boundaries (and line counts, by
    approximation — newlines preserved) are not collapsed.
    """
    out: list[str] = []
    i = 0
    n = len(src)
    CODE, STRING, CHAR, LINE_C, BLOCK_C = 0, 1, 2, 3, 4
    state = CODE
    while i < n:
        c = src[i]
        nxt = src[i + 1] if i + 1 < n else ""
        if state == CODE:
            if c == "/" and nxt == "/":
                state = LINE_C
                i += 2
            elif c == "/" and nxt == "*":
                state = BLOCK_C
                i += 2
            elif c == '"':
                state = STRING
                i += 1
            elif c == "'":
                state = CHAR
                i += 1
            else:
                out.append(c)
                i += 1
        elif state == STRING:
            if c == "\\" and i + 1 < n:
                i += 2  # skip escape pair (handles \" and \\)
            elif c == '"':
                state = CODE
                i += 1
            else:
                i += 1
        elif state == CHAR:
            if c == "\\" and i + 1 < n:
                i += 2
            elif c == "'":
                state = CODE
                i += 1
            else:
                i += 1
        elif state == LINE_C:
            if c == "\n":
                out.append("\n")  # preserve line numbering
                state = CODE
            i += 1
        elif state == BLOCK_C:
            if c == "*" and nxt == "/":
                state = CODE
                i += 2
            else:
                if c == "\n":
                    out.append("\n")
                i += 1
    return "".join(out)
 def _parse_hex_results(text: str) -> list[dict[str, str]]:
    """Parse space-separated hex lines from TB output files."""
    rows = []
@@ -369,6 +445,602 @@ class TestTier1ResetDefaults:
            )
 class TestTier1AgcCrossLayerInvariant:
    """
    Verify AGC enable/disable is consistent across FPGA, MCU, and GUI layers.
    System-level invariant: the FPGA register host_agc_enable is the single
    source of truth for AGC state. It propagates to MCU via DIG_6 GPIO and
    to GUI via status word 4 bit[11]. At boot, all layers must agree AGC=OFF.
    At runtime, the MCU must read DIG_6 every frame to sync its outer-loop AGC.
    """
    def test_fpga_dig6_drives_agc_enable(self):
        """FPGA must drive gpio_dig6 from host_agc_enable, NOT tied low."""
        rtl = (cp.FPGA_DIR / "radar_system_top.v").read_text()
        # Must find: assign gpio_dig6 = host_agc_enable;
        assert re.search(
            r'assign\s+gpio_dig6\s*=\s*host_agc_enable\s*;', rtl
        ), "gpio_dig6 must be driven by host_agc_enable (not tied low)"
        # Must NOT have the old tied-low pattern
        assert not re.search(
            r"assign\s+gpio_dig6\s*=\s*1'b0\s*;", rtl
        ), "gpio_dig6 must NOT be tied low — it carries AGC enable"
    def test_fpga_agc_enable_boot_default_off(self):
        """FPGA host_agc_enable must reset to 0 (AGC off at boot)."""
        v_defaults = cp.parse_verilog_reset_defaults()
        assert "host_agc_enable" in v_defaults, (
            "host_agc_enable not found in reset block"
        )
        assert v_defaults["host_agc_enable"] == 0, (
            f"host_agc_enable reset default is {v_defaults['host_agc_enable']}, "
            "expected 0 (AGC off at boot)"
        )
    def test_mcu_agc_constructor_default_off(self):
        """MCU ADAR1000_AGC constructor must default enabled=false."""
        agc_cpp = (cp.MCU_LIB_DIR / "ADAR1000_AGC.cpp").read_text()
        # The constructor initializer list must have enabled(false)
        assert re.search(
            r'enabled\s*\(\s*false\s*\)', agc_cpp
        ), "ADAR1000_AGC constructor must initialize enabled(false)"
        assert not re.search(
            r'enabled\s*\(\s*true\s*\)', agc_cpp
        ), "ADAR1000_AGC constructor must NOT initialize enabled(true)"
    def test_mcu_reads_dig6_before_agc_gate(self):
        """MCU main loop must read DIG_6 GPIO to sync outerAgc.enabled."""
        main_cpp = (cp.MCU_CODE_DIR / "main.cpp").read_text()
        # DIG_6 must be read via HAL_GPIO_ReadPin
        assert re.search(
            r'HAL_GPIO_ReadPin\s*\(\s*FPGA_DIG6', main_cpp,
        ), "main.cpp must read DIG_6 GPIO via HAL_GPIO_ReadPin"
        # outerAgc.enabled must be assigned from the DIG_6 reading
        # (may be indirect via debounce variable like dig6_now)
        assert re.search(
            r'outerAgc\.enabled\s*=', main_cpp,
        ), "main.cpp must assign outerAgc.enabled from DIG_6 state"
    def test_boot_invariant_all_layers_agc_off(self):
        """
        At boot, all three layers must agree: AGC is OFF.
        - FPGA: host_agc_enable resets to 0 -> DIG_6 low
        - MCU: ADAR1000_AGC.enabled defaults to false
        - GUI: reads status word 4 bit[11] = 0 -> reports MANUAL
        """
        # FPGA
        v_defaults = cp.parse_verilog_reset_defaults()
        assert v_defaults.get("host_agc_enable") == 0
        # MCU
        agc_cpp = (cp.MCU_LIB_DIR / "ADAR1000_AGC.cpp").read_text()
        assert re.search(r'enabled\s*\(\s*false\s*\)', agc_cpp)
        # GUI: status word 4 bit[11] is host_agc_enable, which resets to 0.
        # Verify the GUI parses bit[11] of status word 4 as the AGC flag.
        gui_py = (cp.GUI_DIR / "radar_protocol.py").read_text()
        assert re.search(
            r'words\[4\].*>>\s*11|status_words\[4\].*>>\s*11',
            gui_py,
        ), "GUI must parse AGC status from words[4] bit[11]"
    def test_status_word4_agc_bit_matches_dig6_source(self):
        """
        Status word 4 bit[11] and DIG_6 must both derive from host_agc_enable.
        This guarantees the GUI status display can never lie about MCU AGC state.
        """
        rtl = (cp.FPGA_DIR / "radar_system_top.v").read_text()
        # DIG_6 driven by host_agc_enable
        assert re.search(
            r'assign\s+gpio_dig6\s*=\s*host_agc_enable\s*;', rtl
        )
        # Status word 4 must contain host_agc_enable (may be named
        # status_agc_enable at the USB interface port boundary).
        # Also verify the top-level wiring connects them.
        usb_ft2232h = (cp.FPGA_DIR / "usb_data_interface_ft2232h.v").read_text()
        usb_ft601 = (cp.FPGA_DIR / "usb_data_interface.v").read_text()
        # USB interfaces use the port name status_agc_enable
        found_in_ft2232h = "status_agc_enable" in usb_ft2232h
        found_in_ft601 = "status_agc_enable" in usb_ft601
        assert found_in_ft2232h or found_in_ft601, (
            "status_agc_enable must appear in at least one USB interface's "
            "status word to guarantee GUI status matches DIG_6"
        )
        # Verify top-level wiring: status_agc_enable port is connected
        # to host_agc_enable (same signal that drives DIG_6)
        assert re.search(
            r'\.status_agc_enable\s*\(\s*host_agc_enable\s*\)', rtl
        ), (
            "Top-level must wire .status_agc_enable(host_agc_enable) "
            "so status word and DIG_6 derive from the same signal"
        )
    def test_mcu_dig6_debounce_guards_enable_assignment(self):
        """
        MCU must apply a 2-frame confirmation debounce before mutating
        outerAgc.enabled from DIG_6 reads. A naive assignment straight from
        the latest GPIO sample would let a single-cycle glitch flip the AGC
        state for one frame — defeating the debounce claim in the PR body.
        """
        main_cpp = (cp.MCU_CODE_DIR / "main.cpp").read_text()
        # (1) Current-frame DIG_6 sample must be captured in a local variable
        # so it can be compared against the previous-frame value.
        now_match = re.search(
            r'(bool|int|uint8_t)\s+(\w*dig6\w*)\s*=\s*[^;]*?'
            r'HAL_GPIO_ReadPin\s*\(\s*FPGA_DIG6[^;]*;',
            main_cpp,
            re.DOTALL,
        )
        assert now_match, (
            "DIG_6 read must be stored in a local variable (e.g. `dig6_now`) "
            "so the current sample can be compared against the previous frame"
        )
        now_var = now_match.group(2)
        # (2) Previous-frame state must persist across iterations via static
        # storage, and must default to false (matches FPGA boot: AGC off).
        prev_match = re.search(
            r'static\s+(bool|int|uint8_t)\s+(\w*dig6\w*)\s*=\s*(false|0)\s*;',
            main_cpp,
        )
        assert prev_match, (
            "A static previous-frame variable (e.g. "
            "`static bool dig6_prev = false;`) must exist, initialized to "
            "false so the debounce starts in sync with the FPGA boot default"
        )
        prev_var = prev_match.group(2)
        assert prev_var != now_var, (
            f"Current and previous DIG_6 variables must be distinct "
            f"(both are '{now_var}')"
        )
        # (3) outerAgc.enabled assignment must be gated by now == prev.
        guarded_assign = re.search(
            rf'if\s*\(\s*{now_var}\s*==\s*{prev_var}\s*\)\s*\{{[^}}]*?'
            rf'outerAgc\.enabled\s*=\s*{now_var}\s*;',
            main_cpp,
            re.DOTALL,
        )
        assert guarded_assign, (
            f"`outerAgc.enabled = {now_var};` must be inside "
            f"`if ({now_var} == {prev_var}) {{ ... }}` — the confirmation "
            "guard that absorbs single-sample GPIO glitches. A naive "
            "assignment without this guard reintroduces the glitch bug."
        )
        # (4) Previous-frame variable must advance each frame.
        prev_update = re.search(
            rf'{prev_var}\s*=\s*{now_var}\s*;',
            main_cpp,
        )
        assert prev_update, (
            f"`{prev_var} = {now_var};` must run each frame so the "
            "debounce window slides forward; without it the guard is "
            "stuck and enable changes never confirm"
        )
 # ===================================================================
 # ADAR1000 channel→register round-trip invariant (issue #90)
 # ===================================================================
 #
 # Ground-truth invariant crossing three system layers:
 #   Chip (datasheet) -> Driver (MCU helpers) -> Application (callers).
 #
 # For every logical element ch in {0,1,2,3} (hardware channels CH1..CH4),
 # the round-trip
 #     caller_expr(ch) --> helper_offset(channel) * stride --> base + off
 # must land on the physical register REG_CH{ch+1}_* defined in the ADI
 # ADAR1000 register map parsed from ADAR1000_Manager.h.
 #
 # Catches:
 #   * #90 channel rotation regardless of which side is fixed (caller OR helper).
 #   * Wrong stride (e.g. phase written with stride 1 instead of 2).
 #   * Bad mask (e.g. `channel & 0x07`, `channel & 0x01`).
 #   * Wrong base register in a helper.
 #   * New setter added with mismatched convention.
 #   * Caller moved to a file the test no longer scans (fails loudly).
 #
 # Cannot be defeated by:
 #   * Renaming/refactoring helper layout: the setter coverage test
 #     (`test_helper_sites_exist_for_all_setters`) catches missing parse.
 #   * Changing 0x03 to 3 or adding a named constant: the offset is
 #     evaluated symbolically via AST, not matched by regex.
 def _parse_adar_register_map(header_text):
    """Extract `#define REG_CHn_(RX|TX)_(GAIN|PHS_I|PHS_Q)` values."""
    regs = {}
    for m in re.finditer(
        r"^#define\s+(REG_CH[1-4]_(?:RX|TX)_(?:GAIN|PHS_I|PHS_Q))\s+(0x[0-9A-Fa-f]+)",
        header_text,
        re.MULTILINE,
    ):
        regs[m.group(1)] = int(m.group(2), 16)
    return regs
 def _safe_eval_int_expr(expr, **variables):
    """
    Evaluate a small integer expression with +, -, *, &, |, ^, ~, <<, >>.
    Python's & / | / ^ / ~ / << / >> have the same semantics as C for the
    operand widths we care about here (uint8_t after the mask makes the
    result fit in 0..3). No floating point, no function calls, no names
    outside ``variables``.
    SECURITY: ``expr`` MUST come from a trusted source -- specifically,
    C/C++ source text under version control in this repository (e.g.
    arguments parsed out of ``main.cpp``/``ADAR1000_AGC.cpp``).  Although
    the AST whitelist below rejects function calls, attribute access,
    subscripts, and any name not in ``variables``, ``eval`` is still
    invoked on the compiled tree.  Do NOT pass user-supplied / network /
    GUI input here.
    """
    tree = ast.parse(expr, mode="eval")
    allowed = (
        ast.Expression, ast.BinOp, ast.UnaryOp, ast.Constant,
        ast.Name, ast.Load,
        ast.Add, ast.Sub, ast.Mult, ast.Mod, ast.FloorDiv,
        ast.BitAnd, ast.BitOr, ast.BitXor,
        ast.USub, ast.UAdd, ast.Invert,
        ast.LShift, ast.RShift,
    )
    for node in ast.walk(tree):
        if not isinstance(node, allowed):
            raise ValueError(
                f"disallowed AST node {type(node).__name__!s} in `{expr}`"
            )
    return eval(
        compile(tree, "<expr>", "eval"),
        {"__builtins__": {}},
        variables,
    )
 def _extract_adar_helper_sites(manager_cpp, setter_names):
    """
    For each setter, locate the body of ``void ADAR1000Manager::<setter>``
    and return a list of (setter, base_register, offset_expr_c, stride)
    for every ``REG_CHn_XXX + <expr>`` memory-address assignment.
    """
    sites = []
    for setter in setter_names:
        m = re.search(
            rf"void\s+ADAR1000Manager::{setter}\s*\([^)]*\)\s*\{{(.+?)^\}}",
            manager_cpp,
            re.MULTILINE | re.DOTALL,
        )
        if not m:
            continue
        body = m.group(1)
        for access in re.finditer(
            r"=\s*(REG_CH[1-4]_(?:RX|TX)_(?:GAIN|PHS_I|PHS_Q))\s*\+\s*([^;]+);",
            body,
        ):
            base = access.group(1)
            rhs = access.group(2).strip()
            # Trailing `* <integer>` = stride multiplier (2 for phase I/Q).
            stride_match = re.match(r"(.+?)\s*\*\s*(\d+)\s*$", rhs)
            if stride_match:
                offset_expr = stride_match.group(1).strip()
                stride = int(stride_match.group(2))
            else:
                offset_expr = rhs
                stride = 1
            sites.append((setter, base, offset_expr, stride))
    return sites
 # Method-definition line pattern: `[qualifier...] <ret-type> <Class>::<setter>(`
 # Covers: plain `void X::f(`, `inline void X::f(`, `static bool X::f(`, etc.
 _DEFN_RE = re.compile(
    r"^\s*(?:inline\s+|static\s+|virtual\s+|constexpr\s+|explicit\s+)*"
    r"(?:void|bool|uint\w+|int\w*|auto)\s+\S+::\w+\s*\("
 )
 def _extract_adar_caller_sites(sources, setter):
    """
    Find every call ``<obj>.<setter>(dev, <channel_expr>, ...)`` across
    ``sources = [(filename, text), ...]``. Returns (filename, line_no,
    channel_expr) for each. Skips function declarations/definitions.
    Arg list up to matching `)`: restricted to a single line. All existing
    call sites fit on one line; a future multi-line refactor would drop
    callers from the scan, which the round-trip test surfaces loudly via
    `assert callers` (rather than silently missing a site).
    """
    out = []
    call_re = re.compile(rf"\b{setter}\s*\(([^;]*?)\)\s*;")
    for filename, text in sources:
        for line_no, line in enumerate(text.splitlines(), start=1):
            # Skip method definition / declaration lines.
            if _DEFN_RE.match(line):
                continue
            cm = call_re.search(line)
            if not cm:
                continue
            args = _split_top_level_commas(cm.group(1))
            if len(args) < 2:
                continue
            channel_expr = args[1].strip()
            out.append((filename, line_no, channel_expr))
    return out
 def _split_top_level_commas(text):
    """Split on commas that sit at paren-depth 0 (ignores nested calls)."""
    parts, depth, cur = [], 0, []
    for ch in text:
        if ch == "(":
            depth += 1
            cur.append(ch)
        elif ch == ")":
            depth -= 1
            cur.append(ch)
        elif ch == "," and depth == 0:
            parts.append("".join(cur))
            cur = []
        else:
            cur.append(ch)
    if cur:
        parts.append("".join(cur))
    return parts
 class TestTier1Adar1000ChannelRegisterRoundTrip:
    """
    Cross-layer round-trip: caller channel expr -> helper offset formula
    -> physical register address must equal REG_CH{ch+1}_* for every
    caller and every ch in {0,1,2,3}.
    See module-level block comment above and upstream issue #90.
    """
    _SETTERS = (
        "adarSetRxPhase",
        "adarSetTxPhase",
        "adarSetRxVgaGain",
        "adarSetTxVgaGain",
    )
    # Register base -> stride override. Parsed values of stride are
    # trusted; this table is the independent ground truth for cross-check.
    _EXPECTED_STRIDE: ClassVar[dict[str, int]] = {
        "REG_CH1_RX_GAIN": 1,
        "REG_CH1_TX_GAIN": 1,
        "REG_CH1_RX_PHS_I": 2,
        "REG_CH1_RX_PHS_Q": 2,
        "REG_CH1_TX_PHS_I": 2,
        "REG_CH1_TX_PHS_Q": 2,
    }
    @classmethod
    def setup_class(cls):
        cls.header_txt = (cp.MCU_LIB_DIR / "ADAR1000_Manager.h").read_text()
        cls.manager_txt = (cp.MCU_LIB_DIR / "ADAR1000_Manager.cpp").read_text()
        cls.reg_map = _parse_adar_register_map(cls.header_txt)
        cls.helper_sites = _extract_adar_helper_sites(
            cls.manager_txt, cls._SETTERS,
        )
        # Auto-discover every C++ TU under the MCU tree so a new caller
        # added to e.g. a future ``ADAR1000_Calibration.cpp`` cannot
        # silently escape the round-trip check (issue #90 reviewer note).
        # Exclude any path containing a ``tests`` segment so this test
        # does not parse its own fixtures.  The resulting list is
        # deterministic (sorted) for reproducible parametrization.
        scanned = []
        seen = set()
        for root in (cp.MCU_LIB_DIR, cp.MCU_CODE_DIR):
            for path in sorted(root.rglob("*.cpp")):
                if "tests" in path.parts:
                    continue
                if path in seen:
                    continue
                seen.add(path)
                scanned.append((path.name, path.read_text()))
        cls.sources = scanned
        # Sanity: the two TUs known to call ADAR1000 setters at the time
        # of issue #90 must be in scope.  If a future refactor renames or
        # moves them this assert fires loudly rather than silently
        # passing an empty round-trip.
        scanned_names = {n for (n, _) in scanned}
        for required in ("ADAR1000_AGC.cpp", "main.cpp", "ADAR1000_Manager.cpp"):
            assert required in scanned_names, (
                f"Auto-discovery missed `{required}`; check MCU_LIB_DIR / "
                f"MCU_CODE_DIR roots in contract_parser.py."
            )
    # ---------- Tier A: chip ground truth ----------------------------
    def test_register_map_gain_stride_is_one_per_channel(self):
        """Datasheet invariant: RX/TX VGA gain registers are 1 byte apart."""
        for kind in ("RX_GAIN", "TX_GAIN"):
            for n in range(1, 4):
                delta = (
                    self.reg_map[f"REG_CH{n+1}_{kind}"]
                    - self.reg_map[f"REG_CH{n}_{kind}"]
                )
                assert delta == 1, (
                    f"ADAR1000 register map invariant broken: "
                    f"REG_CH{n+1}_{kind} - REG_CH{n}_{kind} = {delta}, "
                    f"datasheet says 1. Either the header was mis-edited "
                    f"or ADI released a part with a different map."
                )
    def test_register_map_phase_stride_is_two_per_channel(self):
        """Datasheet invariant: phase I/Q pairs occupy 2 bytes per channel."""
        for kind in ("RX_PHS_I", "RX_PHS_Q", "TX_PHS_I", "TX_PHS_Q"):
            for n in range(1, 4):
                delta = (
                    self.reg_map[f"REG_CH{n+1}_{kind}"]
                    - self.reg_map[f"REG_CH{n}_{kind}"]
                )
                assert delta == 2, (
                    f"ADAR1000 register map invariant broken: "
                    f"REG_CH{n+1}_{kind} - REG_CH{n}_{kind} = {delta}, "
                    f"datasheet says 2."
                )
    # ---------- Tier B: driver parses cleanly -------------------------
    def test_helper_sites_exist_for_all_setters(self):
        """Every channel-indexed setter must parse at least one register access."""
        found = {s for (s, _, _, _) in self.helper_sites}
        missing = set(self._SETTERS) - found
        assert not missing, (
            f"Helper parse failed for: {sorted(missing)}. "
            f"Either a setter was renamed (update _SETTERS), moved out of "
            f"ADAR1000_Manager.cpp (extend scan scope), or the register-"
            f"access form changed beyond `REG_CHn_XXX + <expr>`. "
            f"DO NOT weaken this test without reviewing issue #90."
        )
    def test_helper_parsed_stride_matches_datasheet(self):
        """Parsed helper strides must match the datasheet register spacing."""
        for setter, base, offset_expr, stride in self.helper_sites:
            expected = self._EXPECTED_STRIDE.get(base)
            assert expected is not None, (
                f"{setter} writes to unrecognised base `{base}`. "
                f"If ADI added a new channel-indexed register block, "
                f"extend _EXPECTED_STRIDE with its datasheet stride."
            )
            assert stride == expected, (
                f"{setter} helper uses stride {stride} for `{base}` "
                f"(`{offset_expr} * {stride}`), datasheet says {expected}. "
                f"Writes will overlap or skip channels."
            )
    # ---------- Tier C: round-trip to physical register ---------------
    def test_all_callers_pass_one_based_channel(self):
        """
        INVARIANT: every caller's channel argument must, for ch in
        {0,1,2,3}, evaluate to a 1-based ADI channel index in {1,2,3,4}.
        The bug fixed in #90 was that helpers used ``channel & 0x03``
        directly, so a caller passing bare ``ch`` (0..3) appeared to
        work for ch=0..2 and silently aliased ch=3 onto CH4-then-CH1.
        After the fix, helpers do ``(channel - 1) & 0x03`` and reject
        ``channel < 1 || channel > 4``.  A future caller written as
        ``adarSetRxPhase(dev, ch, ...)`` (bare 0-based) or
        ``adarSetRxPhase(dev, 0, ...)`` (literal 0) would silently be
        dropped by the bounds-check at runtime; this test catches it at
        CI time instead.
        The check intentionally lives one tier above the round-trip test
        so the failure message points the reader at the API contract
        (1-based per ADI datasheet & ADAR1000_AGC.cpp:76) rather than at
        a register-arithmetic mismatch.
        """
        offenders = []
        for setter in self._SETTERS:
            callers = _extract_adar_caller_sites(self.sources, setter)
            for filename, line_no, ch_expr in callers:
                for ch in range(4):
                    try:
                        channel_val = _safe_eval_int_expr(ch_expr, ch=ch)
                    except (NameError, KeyError, ValueError) as e:
                        offenders.append(
                            f"  - {filename}:{line_no} {setter}("
                            f"…, `{ch_expr}`, …) -- ch={ch}: "
                            f"unparseable ({e})"
                        )
                        continue
                    if channel_val not in (1, 2, 3, 4):
                        offenders.append(
                            f"  - {filename}:{line_no} {setter}("
                            f"…, `{ch_expr}`, …) -- ch={ch}: "
                            f"channel={channel_val}, expected 1..4"
                        )
        assert not offenders, (
            "ADAR1000 1-based channel API contract violated. The fix "
            "for issue #90 requires every caller to pass channel in "
            "{1,2,3,4} (CH1..CH4 per ADI datasheet). Bare 0-based ch "
            "or a literal 0 will be silently dropped by the helper's "
            "bounds check.  Offenders:\n" + "\n".join(offenders)
        )
    @pytest.mark.parametrize(
        "setter",
        [
            "adarSetRxPhase",
            "adarSetTxPhase",
            "adarSetRxVgaGain",
            "adarSetTxVgaGain",
        ],
    )
    def test_round_trip_lands_on_intended_physical_channel(self, setter):
        """
        INVARIANT: for every caller of ``<setter>`` and every logical ch
        in {0,1,2,3}, the effective register address equals
        REG_CH{ch+1}_*. Catches #90 regardless of fix direction.
        """
        callers = _extract_adar_caller_sites(self.sources, setter)
        assert callers, (
            f"No callers of `{setter}` found. Either the test scope is "
            f"incomplete (extend `setup_class.sources`) or the symbol was "
            f"inlined/removed. A blind test is a dangerous test — "
            f"investigate before weakening."
        )
        helpers = [
            (b, e, s) for (nm, b, e, s) in self.helper_sites if nm == setter
        ]
        assert helpers, f"helper body for `{setter}` not parseable"
        errors = []
        for filename, line_no, ch_expr in callers:
            for ch in range(4):
                try:
                    channel_val = _safe_eval_int_expr(ch_expr, ch=ch)
                except (NameError, KeyError, ValueError) as e:
                    pytest.fail(
                        f"{filename}:{line_no}: caller channel expression "
                        f"`{ch_expr}` uses symbol outside {{ch}} or a "
                        f"disallowed operator ({e}). Extend "
                        f"_safe_eval_int_expr variables or rewrite the "
                        f"call site with a supported expression."
                    )
                for base_sym, offset_expr, stride in helpers:
                    try:
                        offset = _safe_eval_int_expr(
                            offset_expr, channel=channel_val,
                        )
                    except (NameError, KeyError, ValueError) as e:
                        pytest.fail(
                            f"helper `{setter}` offset expr "
                            f"`{offset_expr}` uses symbol outside "
                            f"{{channel}} or a disallowed operator ({e}). "
                            f"Extend _safe_eval_int_expr variables if new "
                            f"driver state is introduced."
                        )
                    final = self.reg_map[base_sym] + offset * stride
                    expected_sym = base_sym.replace("CH1", f"CH{ch + 1}")
                    expected = self.reg_map[expected_sym]
                    if final != expected:
                        errors.append(
                            f"  - {filename}:{line_no} {setter} "
                            f"caller `{ch_expr}` | ch={ch} -> "
                            f"channel={channel_val} -> "
                            f"`{base_sym} + ({offset_expr})"
                            f"{' * ' + str(stride) if stride != 1 else ''}`"
                            f" = 0x{final:03X} "
                            f"(expected {expected_sym} = 0x{expected:03X})"
                        )
        assert not errors, (
            f"ADAR1000 channel round-trip FAILED for {setter} "
            f"({len(errors)} mismatches) — writes routed to wrong physical "
            f"channel. This is issue #90.\n" + "\n".join(errors)
        )
 class TestTier1DataPacketLayout:
    """Verify data packet byte layout matches between Python and Verilog."""
@@ -482,6 +1154,204 @@ class TestTier1STM32SettingsPacket:
        assert flag == [23, 46, 158, 237], f"Start flag: {flag}"
 # ===================================================================
 # TIER 2: ADAR1000 Vector Modulator Lookup-Table Ground Truth
 # ===================================================================
 #
 # Cross-layer contract: the firmware constants
 #   ADAR1000Manager::VM_I[128] / VM_Q[128]
 # (in 9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/ADAR1000_Manager.cpp)
 # MUST equal the byte values published in the ADAR1000 datasheet Rev. B,
 # Tables 13-16 page 34 ("Phase Shifter Programming"), on a uniform 2.8125 deg
 # grid (index N == phase N * 360/128 deg).
 #
 # Independent ground truth lives in tools/verify_adar1000_vm_tables.py
 # (transcribed from the datasheet, cross-checked against the ADI Linux
 # beamformer driver as a secondary source). This test imports that
 # reference and asserts a byte-exact match.
 #
 # Historical bug guarded against: from initial commit through PR #94 the
 # arrays shipped as empty placeholders ("// ... (same as in your original
 # file)"), so every adarSetRxPhase / adarSetTxPhase call wrote I=Q=0 and
 # beam steering was non-functional. A separate VM_GAIN[128] table was
 # declared but never read anywhere; this test also enforces its removal so
 # it cannot be reintroduced and silently shadow real bugs.
 class TestTier2Adar1000VmTableGroundTruth:
    """Firmware ADAR1000 VM_I/VM_Q must match datasheet ground truth byte-exact."""
    @pytest.fixture(scope="class")
    def cpp_source(self):
        path = (
            cp.REPO_ROOT
            / "9_Firmware"
            / "9_1_Microcontroller"
            / "9_1_1_C_Cpp_Libraries"
            / "ADAR1000_Manager.cpp"
        )
        assert path.is_file(), f"Firmware source missing: {path}"
        return path.read_text()
    def test_ground_truth_table_shape(self):
        """Sanity-check the imported reference (defends against import-path mishap)."""
        gt = adar_vm.GROUND_TRUTH
        assert len(gt) == 128, "Ground-truth table must have exactly 128 entries"
        # Each row is (deg_int, deg_frac_e4, vm_i_byte, vm_q_byte)
        for k, row in enumerate(gt):
            assert len(row) == 4, f"Row {k} malformed: {row}"
            assert 0 <= row[2] <= 0xFF, f"VM_I[{k}] out of byte range: {row[2]:#x}"
            assert 0 <= row[3] <= 0xFF, f"VM_Q[{k}] out of byte range: {row[3]:#x}"
            # Byte format: bits[7:6] reserved zero, bits[5] polarity, bits[4:0] mag
            assert (row[2] & 0xC0) == 0, f"VM_I[{k}] reserved bits set: {row[2]:#x}"
            assert (row[3] & 0xC0) == 0, f"VM_Q[{k}] reserved bits set: {row[3]:#x}"
    def test_ground_truth_byte_format(self):
        """Transcription self-check: every VM_I/VM_Q byte has reserved bits clear."""
        errors = adar_vm.check_byte_format("VM_I_REF", adar_vm.VM_I_REF)
        errors += adar_vm.check_byte_format("VM_Q_REF", adar_vm.VM_Q_REF)
        assert not errors, (
            "Byte-format violations in embedded GROUND_TRUTH (likely transcription "
            "typo from ADAR1000 datasheet Tables 13-16):\n  " + "\n  ".join(errors)
        )
    def test_ground_truth_uniform_2p8125_deg_grid(self):
        """Transcription self-check: angles form a uniform 2.8125 deg grid.
        This is the assumption that lets the firmware use `VM_*[phase % 128]`
        as a direct index (no nearest-neighbour search). If the embedded
        angles drift off the grid, the firmware's indexing model is wrong.
        """
        errors = adar_vm.check_uniform_2p8125_deg_step()
        assert not errors, (
            "Non-uniform angle grid in GROUND_TRUTH:\n  " + "\n  ".join(errors)
        )
    def test_ground_truth_quadrant_symmetry(self):
        """Transcription self-check: phi and phi+180 deg have same magnitude,
        opposite polarity. Catches swapped/rotated rows in the table.
        """
        errors = adar_vm.check_quadrant_symmetry()
        assert not errors, (
            "Quadrant-symmetry violation in GROUND_TRUTH (table rows may be "
            "transposed or mis-transcribed):\n  " + "\n  ".join(errors)
        )
    def test_ground_truth_cardinal_points(self):
        """Transcription self-check: the four cardinal phases (0, 90, 180,
        270 deg) match the datasheet-published extrema exactly.
        """
        errors = adar_vm.check_cardinal_points()
        assert not errors, (
            "Cardinal-point mismatch in GROUND_TRUTH vs ADAR1000 datasheet "
            "Tables 13-16:\n  " + "\n  ".join(errors)
        )
    def test_firmware_vm_i_matches_datasheet(self, cpp_source):
        gt = adar_vm.GROUND_TRUTH
        firmware = adar_vm.parse_array(cpp_source, "VM_I")
        assert firmware is not None, (
            "Could not parse VM_I[128] from ADAR1000_Manager.cpp; "
            "definition pattern may have drifted"
        )
        assert len(firmware) == 128, (
            f"VM_I has {len(firmware)} entries, expected 128. "
            "Empty placeholder regression — every phase write would emit I=0 "
            "and beam steering would be silently broken."
        )
        mismatches = [
            (k, firmware[k], gt[k][2])
            for k in range(128)
            if firmware[k] != gt[k][2]
        ]
        assert not mismatches, (
            f"VM_I diverges from datasheet at {len(mismatches)} indices; "
            f"first 5: {mismatches[:5]}"
        )
    def test_firmware_vm_q_matches_datasheet(self, cpp_source):
        gt = adar_vm.GROUND_TRUTH
        firmware = adar_vm.parse_array(cpp_source, "VM_Q")
        assert firmware is not None, (
            "Could not parse VM_Q[128] from ADAR1000_Manager.cpp; "
            "definition pattern may have drifted"
        )
        assert len(firmware) == 128, (
            f"VM_Q has {len(firmware)} entries, expected 128. "
            "Empty placeholder regression — every phase write would emit Q=0."
        )
        mismatches = [
            (k, firmware[k], gt[k][3])
            for k in range(128)
            if firmware[k] != gt[k][3]
        ]
        assert not mismatches, (
            f"VM_Q diverges from datasheet at {len(mismatches)} indices; "
            f"first 5: {mismatches[:5]}"
        )
    def test_vm_gain_table_is_not_reintroduced(self, cpp_source):
        """Dead-code regression guard: VM_GAIN[128] must not exist as code.
        The ADAR1000 vector modulator has no separate gain register; magnitude
        is bits[4:0] of the I/Q bytes themselves. Per-channel VGA gain uses
        registers CHx_RX_GAIN (0x10-0x13) / CHx_TX_GAIN (0x1C-0x1F) written
        directly by adarSetRxVgaGain / adarSetTxVgaGain. A VM_GAIN[] array
        was declared in early development, never populated, never read, and
        was removed in PR fix/adar1000-vm-tables. Reintroducing it would
        suggest (falsely) that an extra lookup is needed and could mask the
        real signal path.
        Uses a tokenising comment/string stripper so that the historical
        explanation comment in the cpp file, as well as any string literal
        containing the substring "VM_GAIN", does not trip the check.
        """
        stripped = _strip_cxx_comments_and_strings(cpp_source)
        assert "VM_GAIN" not in stripped, (
            "VM_GAIN symbol reappeared in ADAR1000_Manager.cpp executable code. "
            "This array has no hardware backing and must not be reintroduced. "
            "If you need to scale phase-state magnitude, modify VM_I/VM_Q "
            "bits[4:0] directly per the datasheet."
        )
    def test_adversarial_corruption_is_detected(self):
        """Adversarial self-test: a flipped byte in firmware MUST fail comparison.
        Defends against silent bypass — e.g. a future refactor that mocks
        parse_array() or compares len() only. We synthesise a corrupted cpp
        source string, run the same parser, and assert mismatch is detected.
        """
        gt = adar_vm.GROUND_TRUTH
        # Build a minimal valid-looking cpp snippet with one corrupted byte.
        good_i = ", ".join(f"0x{gt[k][2]:02X}" for k in range(128))
        good_q = ", ".join(f"0x{gt[k][3]:02X}" for k in range(128))
        snippet_good = (
            f"const uint8_t ADAR1000Manager::VM_I[128] = {{ {good_i} }};\n"
            f"const uint8_t ADAR1000Manager::VM_Q[128] = {{ {good_q} }};\n"
        )
        # Sanity: the unmodified snippet must parse and match.
        parsed_i = adar_vm.parse_array(snippet_good, "VM_I")
        assert parsed_i is not None and len(parsed_i) == 128
        assert all(parsed_i[k] == gt[k][2] for k in range(128)), (
            "Self-test setup error: golden snippet does not match GROUND_TRUTH"
        )
        # Now flip the low bit of VM_I[42] and confirm detection.
        corrupted_byte = gt[42][2] ^ 0x01
        bad_i = ", ".join(
            f"0x{(corrupted_byte if k == 42 else gt[k][2]):02X}"
            for k in range(128)
        )
        snippet_bad = (
            f"const uint8_t ADAR1000Manager::VM_I[128] = {{ {bad_i} }};\n"
            f"const uint8_t ADAR1000Manager::VM_Q[128] = {{ {good_q} }};\n"
        )
        parsed_bad = adar_vm.parse_array(snippet_bad, "VM_I")
        assert parsed_bad is not None and len(parsed_bad) == 128
        assert parsed_bad[42] != gt[42][2], (
            "Adversarial self-test FAILED: corrupted byte at index 42 was "
            "not detected by parse_array. The cross-layer test is bypassable."
        )
 # ===================================================================
 # TIER 2: Verilog Cosimulation
 # ===================================================================
@@ -68,13 +68,13 @@ The AERIS-10 main sub-systems are:
      - Clock Generator (AD9523-1)
      - 2x Frequency Synthesizers (ADF4382)
      - 4x 4-Channel Phase Shifters (ADAR1000) for RADAR pulse sequencing
-      - 2x ADS7830 ADCs (on Power Amplifier Boards) for Idq measurement
+      - 2x ADS7830 8-channel I²C ADCs (Main Board, U88 @ 0x48 / U89 @ 0x4A) for 16x Idq measurement, one per PA channel, each sensed through a 5 mΩ shunt on the PA board and an INA241A3 current-sense amplifier (x50) on the Main Board
-      - 2x DAC5578 (on Power Amplifier Boards) for Vg control
+      - 2x DAC5578 8-channel I²C DACs (Main Board, U7 @ 0x48 / U69 @ 0x49) for 16x Vg control, one per PA channel; closed-loop calibrated at boot to the target Idq
-      - GPS module for GUI map centering
+      - GPS module (UM982) for GUI map centering and per-detection position tagging
      - GY-85 IMU for pitch/roll correction of target coordinates
      - BMP180 Barometer
      - Stepper Motor
-      - 8x ADS7830 Temperature Sensors for cooling fan control
+      - 1x ADS7830 8-channel I²C ADC (Main Board, U10) reading 8 thermistors for thermal monitoring; a single GPIO (EN_DIS_COOLING) switches the cooling fans on when any channel exceeds the threshold
      - RF switches
 - **16x Power Amplifier Boards** - Used only for AERIS-10E version, featuring 10Watt QPA2962 GaN amplifier for extended range
Author	SHA1	Message	Date
Jason	27b55f37dc	Merge pull request #108 from NawfalMotii79/fix/adar1000-channel-rotation fix(adar1000): correct 1-based channel indexing in setters (issue #90)	2026-04-18 06:00:52 +03:00
Jason	582476fa0d	fix(adar1000): correct 1-based channel indexing in setters (issue #90 ) The four channel-indexed ADAR1000 setters (adarSetRxPhase, adarSetTxPhase, adarSetRxVgaGain, adarSetTxVgaGain) computed their register offset as `(channel & 0x03) * stride`, which silently aliased CH4 (channel=4 -> mask=0) onto CH1 and shifted CH1..CH3 by one. The API contract (1-based CH1..CH4) is documented in ADAR1000_AGC.cpp:76 and matches the ADI datasheet; every existing caller already passes `ch + 1`. Fix: subtract 1 before masking -- `((channel - 1) & 0x03) * stride` -- and reject `channel < 1 \|\| channel > 4` early with a DIAG message so a future stale 0-based caller fails loudly instead of writing to CH4. Adds TestTier1Adar1000ChannelRegisterRoundTrip (9 tests) which closes the loop independently of the driver: - parses the ADI register map directly from ADAR1000_Manager.h, - verifies the datasheet stride invariants (gain=1, phase=2), - auto-discovers every C++ TU under MCU_LIB_DIR / MCU_CODE_DIR so a new caller cannot silently escape the round-trip check, - asserts every caller's channel argument evaluates to {1,2,3,4} for ch in {0,1,2,3} (catches bare 0-based or literal-0 callers at CI time before the runtime bounds-check would silently drop them), - round-trips each (caller, ch) through the helper arithmetic and checks the final address equals REG_CH{ch+1}_*. Adversarially validated: reverting any one helper, all four helpers, corrupting the parsed register map, injecting a bare-ch caller, and auto-discovering a literal-0 caller in a fresh TU each cause the expected (and only the expected) test to fail. Stacked on fix/adar1000-vm-tables (PR #107).	2026-04-18 06:39:07 +05:45
Jason	7c91a3e0b9	fix(adar1000): populate VM_I/VM_Q phase tables; remove dead VM_GAIN The ADAR1000 vector-modulator I/Q lookup tables VM_I[128] and VM_Q[128] were declared but defined as empty initialiser lists since the first commit (`5fbe97f`). Every call to adarSetRxPhase / adarSetTxPhase therefore wrote (I=0x00, Q=0x00) to registers 0x21/0x23 (Rx) and 0x32/0x34 (Tx) regardless of the requested phase state, leaving beam steering completely non-functional in firmware. This commit: * Populates VM_I[128] and VM_Q[128] from ADAR1000 datasheet Rev. B Tables 13-16 (p.34) on a uniform 2.8125 deg grid (360 / 128 states). Byte format: bits[7:6] reserved 0, bit[5] polarity (1 = positive lobe), bits[4:0] 5-bit unsigned magnitude - exactly as specified. * Removes VM_GAIN[128] declaration and (empty) definition. The ADAR1000 has no separate VM gain register; per-channel VGA gain is set via CHx_RX_GAIN (0x10-0x13) / CHx_TX_GAIN (0x1C-0x1F) by adarSetRxVgaGain / adarSetTxVgaGain. VM_GAIN was never populated, never read anywhere in the firmware, and its presence falsely suggested a missing scaling step in the signal path. * Adds 9_Firmware/tests/cross_layer/adar1000_vm_reference.py: an independently-derived ground-truth module containing the full datasheet table plus byte-format / uniform-grid / quadrant-symmetry / cardinal-point invariant checkers and a tolerant C array parser. * Adds TestTier2Adar1000VmTableGroundTruth (9 tests) to test_cross_layer_contract.py, including a tokenising C/C++ comment+string stripper used by the VM_GAIN reintroduction guard, and an adversarial self-test that corrupts one byte and asserts the comparison detects it (defends against silent bypass via future fixture/parser refactors). Adversarially validated: removing the firmware definitions, flipping a single byte, or reintroducing VM_GAIN as code each cause the suite to fail; restoring causes it to pass. VM_GAIN appearing inside string literals or comments correctly does NOT trip the guard. Closes the empty-table half of the ADAR1000 phase-control bug class. The separate channel-rotation issue (#90) will be addressed in a follow-up PR. Refs: 7_Components Datasheets and Application notes/ADAR1000.pdf Rev. B Tables 13-16 p.34	2026-04-18 02:02:07 +05:45
Jason	fd6cff5b2b	Merge pull request #102 from JJassonn69/chore/sync-main-into-develop chore: sync main → develop (schematic updates + README + project doc)	2026-04-17 19:31:31 +03:00
Jason	964f1903f3	chore: sync main → develop (schematic updates, README, project doc) Brings in main-only commits that never reached develop: `754d919` Added silk screen and headers description (MainBoard .brd) `0443516` Added thermal vias (RF_PA .brd) `5fbe051` Added ABAC INDUSTRY web site (Project_Description.docx) `12b549d` / `5d5e9ff` Merge PR #101: README BOM sensor counts fix No conflicts expected: develop has not touched any of these paths.	2026-04-17 22:12:26 +05:45
Jason	12b549dafb	Merge pull request #101 from JJassonn69/fix/readme-bom-sensor-counts docs(readme): correct STM32 peripheral counts and locations to match production BOM	2026-04-17 17:21:59 +03:00
Jason	5d5e9ff297	docs(readme): correct BOM sensor counts and locations The STM32 peripheral list in the README disagreed with the production BOM (4_7_Production Files/Gerber_Main_Board/RADAR_Main_Board_BOM_csv) and with the firmware (9_1_Microcontroller/.../main.cpp). Corrections based on origin/main commit `754d919`: - ADS7830 Idq ADCs: placed on the Main Board (U88 @ 0x48, U89 @ 0x4A), not on the Power Amplifier Boards. Added the INA241A3 (x50) and 5 mOhm shunt detail that completes the current-sense chain. - DAC5578 Vg DACs: placed on the Main Board (U7 @ 0x48, U69 @ 0x49), not on the Power Amplifier Boards. Noted closed-loop Idq calibration at boot (main.cpp powerUpSequence). - Temperature sensors: 1x ADS7830 (U10) with 8 single-ended channels reading 8 thermistors -- not 8 separate ADS7830 chips. Cooling is a single GPIO (EN_DIS_COOLING), bang-bang, not PWM. - GPS: reflect the UM982 driver merged in #79 and its role in per-detection position tagging beyond map centering. Counts now match the 3x ADS7830 / 2x DAC5578 / 16x INA241A3 population in the production BOM.	2026-04-17 20:04:01 +05:45
NawfalMotii79	754d919e44	Added silk screen and headers description	2026-04-16 23:48:23 +01:00
NawfalMotii79	0443516cc9	Added thermal vias	2026-04-16 23:47:24 +01:00
NawfalMotii79	5fbe0513b5	Added ABAC INDUSTRY web site	2026-04-16 23:46:08 +01:00
Jason	c3db8a9122	Merge pull request #96 from joyshmitz/chore/remove-dead-adar1000-c-api chore(mcu): remove dead C-style adar1000 driver	2026-04-16 23:51:22 +03:00
Jason	ec8256e25a	Merge pull request #95 from joyshmitz/test/agc-debounce-enforce test(cross-layer): enforce 2-frame DIG_6 debounce guard on outerAgc.enabled (follow-up to #93)	2026-04-16 23:42:12 +03:00
Serhii	8e1b3f22d2	chore(mcu): remove dead C-style adar1000 driver The firmware uses the C++ ADAR1000_Manager class exclusively. The C-style driver pair (adar1000.c, 693 LoC; adar1000.h, 294 LoC) has no external call sites: grep -rn "Adar_Set\|Adar_Read\|Adar_Write\|Adar_Soft" 9_Firmware grep -rn "AdarDevice\|AdarBiasCurrents\|AdarDeviceInfo" 9_Firmware Both return hits only inside adar1000.c/h themselves. ADAR1000_Manager.h has its own copies of REG_CH1_, REG_INTERFACE_CONFIG_A, etc. and does not include adar1000.h. main.cpp had a lone #include "adar1000.h" but referenced no symbols from it; the REG_ macros it uses resolve through ADAR1000_Manager.h on the next line. No behaviour change: the deleted code was unreachable. Side note on #90: adar1000.c contained a second copy of the REG_CH1_* + (channel & 0x03) channel-rotation pattern tracked in #90 (lines 349, 397-398, 472, 520-521). This commit does not fix #90 -- the live path in ADAR1000_Manager.cpp still needs the channel-index fix -- but it removes the dormant copy so the bug has one less place to hide. Verification: - 9_Firmware/9_1_Microcontroller/tests: make clean && make -> all passing (51/51 UM982 GPS, 24/24 driver, 13/13 ADAR1000_AGC, bugs #1-15, Gap-3 fixes 1-5, safety fixes) - 9_Firmware/tests/cross_layer: 29 passed - grep -rn "adar1000\.h\|adar1000\.c\|Adar_\|AdarDevice" 9_Firmware: 0 hits	2026-04-16 22:12:23 +03:00
Serhii	15ae940be5	test(cross-layer): enforce 2-frame DIG_6 debounce guard on outerAgc.enabled PR #93 added a 2-frame confirmation debounce so a single-sample GPIO glitch cannot flip MCU outer-loop AGC state. The debounce is load-bearing for the "prevents a single-sample glitch" guarantee in the PR body, but no existing test enforces its structure — test_mcu_reads_dig6_before_agc_gate only checks that HAL_GPIO_ReadPin(FPGA_DIG6, ...) and `outerAgc.enabled =` appear somewhere in main.cpp, which a naive direct assignment would still pass. Add test_mcu_dig6_debounce_guards_enable_assignment to TestTier1AgcCrossLayerInvariant, verifying four structural invariants of the debounce: 1. Current DIG_6 sample captured in a local variable 2. Static previous-frame variable defaulting to false (matches FPGA boot: host_agc_enable resets 0) 3. outerAgc.enabled assignment gated by `now == prev` 4. Previous-frame variable advanced each frame Verified test fails on a naive patch that removes the guard and passes on the current PR #93 implementation. Full cross-layer suite stays at 0 failures (36/36 pass locally).	2026-04-16 21:29:37 +03:00
Jason	658752abb7	fix: propagate FPGA AGC enable to MCU outer loop via DIG_6 GPIO Resolve cross-layer AGC control mismatch where opcode 0x28 only controlled the FPGA inner-loop AGC but the STM32 outer-loop AGC (ADAR1000_AGC) ran independently with its own enable state. FPGA: Drive gpio_dig6 from host_agc_enable instead of tied low, making the FPGA register the single source of truth for AGC state. MCU: Change ADAR1000_AGC constructor default from enabled(true) to enabled(false) so boot state matches FPGA reset default (AGC off). Read DIG_6 GPIO every frame with 2-frame confirmation debounce to sync outerAgc.enabled — prevents single-sample glitch from causing spurious AGC state transitions. Tests: Update MCU unit tests for new default, add 6 cross-layer contract tests verifying the FPGA-MCU-GUI AGC invariant chain.	2026-04-17 00:04:37 +05:45