PR-AB.b expanded commit 5: Beam-ready handshake (RTL + MCU + GUI)

Wire a per-frame MCU→FPGA "beam pattern ready" handshake so the chirp
scheduler can stall between 48-chirp frames until the MCU finishes
writing the next ADAR1000 pattern. The legacy unused stm32_new_chirp
input on PD8 is repurposed as stm32_beam_ready; chirp_scheduler.v gets
a new S_BEAM_WAIT state entered after each frame_pulse and an 80 ms
watchdog so a missed MCU toggle degrades to wall-clock cadence with a
sticky telemetry bit rather than stalling the radar.

Cold-reset defaults the handshake off (host_handshake_enable=0, new
opcode 0x1A); the GUI opts in once the MCU PD8 wiring is verified on
the bench. Both the FT601 and FT2232H status word 4 paths get the new
beam_handshake_watchdog_fired sticky at bit [1] (reclaimed from the
range_mode retirement in commit 1).

RTL:
- chirp_scheduler.v: 2-FF ASYNC_REG sync on beam_ready_async; 1-cycle
  edge detect (any transition, MCU side uses HAL_GPIO_TogglePin); new
  S_BEAM_WAIT state entered at frame_pulse when host_handshake_enable=1;
  23-bit beam_watchdog counter with BEAM_WATCHDOG_MAX = 8_000_000 (~80 ms
  at 100 MHz, ~10 nominal frames); beam_handshake_watchdog_fired output
  sticky across mixers_enable cycles, cleared only by reset_n; mid-wait
  disable releases the FSM so dropping the opcode never strands the
  radar between frames.
- radar_receiver_final.v: thread stm32_beam_ready_async +
  host_handshake_enable + beam_handshake_watchdog_fired through the
  scheduler instance.
- radar_system_top.v: rename input port stm32_new_chirp → stm32_beam_ready;
  add host_handshake_enable register (cold-reset = 1'b0); opcode 0x1A
  dispatch (value[0]); add rx_beam_handshake_watchdog wire; pack into
  status_words[4][1] in both USB paths.
- radar_system_top_50t.v: rename wrapper port + sub-instance wiring.
- usb_data_interface.v + usb_data_interface_ft2232h.v: add
  status_beam_handshake_watchdog input + 2-FF level CDC (same convention
  as F-6.4 / F-1.2 stickies); refresh word-4 layout doc comment; pack
  beam_handshake_wd_sync_1 into status_words[4][1].

XDC:
- xc7a50t_ftg256.xdc + xc7a200t_fbg484.xdc: rename stm32_new_chirp port
  references to stm32_beam_ready (same PD8 pin, F13 on 50T / L18 on
  200T).

MCU:
- main.h: add FPGA_BEAM_READY_Pin = GPIO_PIN_8 + FPGA_BEAM_READY_GPIO_Port
  = GPIOD alongside the existing FPGA_FRAME_PULSE alias.
- main.cpp:runRadarPulseSequence: insert HAL_GPIO_TogglePin(GPIOD,
  GPIO_PIN_8) after each setCustomBeamPattern16(RX) — once after the
  per-azimuth broadside (vector_0), once after matrix1, once after
  matrix2 — between the SPI burst completion and waitForFramePulse.

GUI:
- radar_protocol.py: Opcode.HANDSHAKE_ENABLE = 0x1A;
  StatusResponse.beam_handshake_watchdog = 0 default; parse word 4 bit
  [1] in parse_status_packet; update word-4 layout comment.
- test_GUI_V65_Tk.py: add beam_handshake_watchdog kwarg to
  _make_status_packet (sets bit [1] of word 4); refresh
  test_parse_status_word4_layout_co_spec to cover the new bit (used+9=32);
  add test_parse_status_beam_handshake_watchdog round-trip;
  test_handshake_enable_opcode pins 0x1A; defaults / chirps_mismatch /
  agc-coexist tests gain a watchdog==0 assertion; bump
  test_all_rtl_opcodes_present expected set to include 0x17/0x18/0x19/0x1A.

TB:
- new tb_chirp_scheduler_handshake.v (16 checks): legacy open-loop, edge
  exit (rising + falling), 200-cycle idle hold, watchdog auto-advance
  via force on dut.beam_watchdog, sticky-survives-mixers_disable,
  mid-wait disable release, reset_n clears sticky.
- run_regression.sh: register the new TB in PHASE 1.
- tb_radar_receiver_final.v: tie the 3 new receiver ports off
  (beam_ready_async=0, handshake_enable=0, watchdog unconnected).
- tb_system_mechanics.v / tb_system_opcodes.v: explicit
  .stm32_beam_ready(1'b0) connection (the cold-reset
  host_handshake_enable=0 keeps the FSM out of S_BEAM_WAIT).
- tb_usb_data_interface.v / tb_usb_protocol_v2.v / tb_e2e_dsp_to_host.v /
  tb_ft2232h_frame_drop.v: tie .status_beam_handshake_watchdog(1'b0).

Ride-along ruff sweep (14 → 0 across the repo):
- tb/cosim/compare_independent.py: RUF003 — '5×' → 'at least 5x'.
- tb/cosim/gen_e2e_expected.py: noqa: E402 on the post-sys.path import;
  drop unused EXPECTED_RANGE_BIN + EXPECTED_DOPPLER_BIN_PER_SF imports;
  fold the detect-class slot if/else into a ternary (SIM108).
- tb/cosim/gen_e2e_stimulus.py: drop int() wrapping round() at four
  call sites (RUF046 — round() already returns int in Python 3);
  rewrite the range-bin derivation comment block from code-like
  `# range_bin = ...` to prose (ERA001); strip stray f from
  placeholder-free error string (F541).
- tb/cosim/tb_e2e_dsp_to_host_parse.py: open(path, 'r') → open(path)
  (UP015).
- v7/dashboard.py: '3×' → '3x' (RUF003); drop quotes from
  'StatusResponse | None' annotation (UP037, file already has
  `from __future__ import annotations`).

CI summary (all suites green pre-commit):
- ruff: All checks passed!
- FPGA regression (iverilog): 43 / 0 / 0 (incl. new handshake TB 16/16).
- MCU tests: 51 / 0 + 34 / 0 + 13 / 13 ADAR1000_AGC.
- GUI Tk (test_GUI_V65_Tk): 120 / 0.
- GUI v7 (test_v7): 152 / 0.

Production rollout note: bitstream cold-resets with host_handshake_enable=0
so existing flashes keep their open-loop cadence until the GUI sends
opcode 0x1A=1. Once enabled, the per-pattern dwell tracks both the chirp
ladder (PD14 frame_pulse from commit-3 work) and the MCU pattern-write
completion (PD8 toggle from this commit), eliminating drift from the SPI
burst timing.

9_Firmware/9_2_FPGA/tb/cosim/compare_independent.py

@@ -358,7 +358,7 @@ def check_mf_invariants(result: CheckResult):
         f"twin={twin_peak}, ref={ref_peak}"
     )
 
-    # Sidelobe behaviour: peak should be ≥ 5× the median magnitude. Under
+    # Sidelobe behaviour: peak should be at least 5x the median magnitude. Under
     # scaled-mode at amp=4000 the peak rises to ~977 while sidelobes stay
     # near the LSB floor, easily clearing the threshold.
     twin_peak_val = float(twin_mag[delay])

9_Firmware/9_2_FPGA/tb/cosim/gen_e2e_expected.py

@@ -62,7 +62,7 @@ import numpy as np
 THIS_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, THIS_DIR)
 
-from fpga_model import DopplerProcessor, run_cfar_ca
+from fpga_model import DopplerProcessor, run_cfar_ca  # noqa: E402
 
 # Pull stimulus configuration verbatim so dimensions stay aligned.
 from gen_e2e_stimulus import (   # noqa: E402
@@ -72,8 +72,6 @@ from gen_e2e_stimulus import (   # noqa: E402
     CHIRPS_PER_FRAME,
     RANGE_BINS,
     HOST_DC_NOTCH_WIDTH,
-    EXPECTED_RANGE_BIN,
-    EXPECTED_DOPPLER_BIN_PER_SF,
     EXPECTED_DETECT_CELLS,
 )
 
@@ -263,10 +261,8 @@ def pack_bulk_frame(frame_number: int, flags: int,
                 packed = 0
                 for slot in range(4):
                     db = byte_idx * 4 + slot
-                    if db < DOPPLER_TOTAL_BINS:
-                        code = int(cfar_class[rb, db]) & 0x3
-                    else:
-                        code = 0   # padding
+                    # padding for db >= DOPPLER_TOTAL_BINS lands on slot 3
+                    code = int(cfar_class[rb, db]) & 0x3 if db < DOPPLER_TOTAL_BINS else 0
                     packed |= code << ((3 - slot) * 2)
                 out.append(packed)
 

9_Firmware/9_2_FPGA/tb/cosim/gen_e2e_stimulus.py

@@ -98,16 +98,15 @@ HOST_DC_NOTCH_WIDTH = 1
 # ============================================================================
 # Target placement -> expected bin coordinates
 # ============================================================================
-# range_bin = round(2 * R / c * fs / decim)
-#   = round(2 * 100 / 3e8 * 400e6 / 4)
-#   = round(66.667) = 67
-EXPECTED_RANGE_BIN = int(round(2.0 * TARGET_RANGE_M / C_LIGHT * RANGE_BIN_HZ))
+# Range bin formula: round(2 * R / c * fs / decim). For R=100m, fs=400 MHz,
+# decim=4 -> round(2 * 100 / 3e8 * 100e6) = round(66.667) = 67.
+EXPECTED_RANGE_BIN = round(2.0 * TARGET_RANGE_M / C_LIGHT * RANGE_BIN_HZ)
 
 # Per-sub-frame doppler bin (folding into 16-pt FFT). For our 5 m/s target
 # this is intentionally non-folding -> 1 in all three sub-frames.
 F_DOPPLER_HZ = 2.0 * TARGET_VEL_MPS * F_CARRIER / C_LIGHT
 EXPECTED_DOPPLER_BIN_PER_SF = tuple(
-    int(round(F_DOPPLER_HZ * DOPPLER_FFT_SIZE * pri)) % DOPPLER_FFT_SIZE
+    round(F_DOPPLER_HZ * DOPPLER_FFT_SIZE * pri) % DOPPLER_FFT_SIZE
     for pri in PRI_BY_SF
 )
 # Flat 48-bin doppler-axis expected cells (sub_frame << 4 | bin).
@@ -160,8 +159,8 @@ def generate_range_decim_frame(seed: int = SCENE_SEED) -> tuple[np.ndarray, np.n
 
         # Target injection at the expected range bin.
         phi = _target_phase_rad(c)
-        sig_i = int(round(TARGET_AMPLITUDE * np.cos(phi)))
-        sig_q = int(round(TARGET_AMPLITUDE * np.sin(phi)))
+        sig_i = round(TARGET_AMPLITUDE * np.cos(phi))
+        sig_q = round(TARGET_AMPLITUDE * np.sin(phi))
         frame_i[c, EXPECTED_RANGE_BIN] += sig_i
         frame_q[c, EXPECTED_RANGE_BIN] += sig_q
 
@@ -231,7 +230,7 @@ def main() -> int:
           f"shape={frame_i.shape}")
 
     if n_lines != expected_lines:
-        print(f"  ERROR: line count mismatch", file=sys.stderr)
+        print("  ERROR: line count mismatch", file=sys.stderr)
         return 1
 
     # Sanity: target peak should dominate at the expected range bin.

9_Firmware/9_2_FPGA/tb/cosim/tb_e2e_dsp_to_host_parse.py

@@ -95,7 +95,7 @@ class TestState:
 def load_captured_frame_hex(path: str) -> bytes:
     """Read iverilog $writememh output (one byte per line, 2-hex-digit)."""
     out = bytearray()
-    with open(path, 'r') as f:
+    with open(path) as f:
         for line in f:
             tok = line.strip()
             if not tok or tok.startswith('//'):