Mirrors/NawfalMotii79-PLFM_RADAR
1
0
Fork 0
mirror of https://github.com/NawfalMotii79/PLFM_RADAR.git synced 2026-06-09 06:57:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(rtl,gui): PR-U / M-8 — sub-frame enable mask routed end-to-end (C-5 hardening)

Browse Source 
The chirp_scheduler had a 3-bit host_subframe_enable input {LONG, MEDIUM, SHORT}
that was tied to the constant RP_DEF_SUBFRAME_ENABLE at the receiver instance,
so the host could neither change it nor know what mask was active. With the
mask not at 3'b111 the scheduler skips a sub-frame at TX but doppler_processor
still writes 48 chirp slots, so the host CRT (`dbin // 16 → {SHORT, MED, LONG}`)
silently mis-attributes the SF axis and unfolds to the wrong velocity.

Plumb the mask through:

- radar_system_top.v: new reg [2:0] host_subframe_enable, cold-reset
  RP_DEF_SUBFRAME_ENABLE, opcode 0x19 setter, wired to rx_inst and usb_inst.
- radar_receiver_final.v: new host_subframe_enable[2:0] input port; the
  chirp_scheduler instance is untied from the constant.
- usb_data_interface_ft2232h.v: new subframe_enable[2:0] input + per-frame
  snapshot reg latched at frame_complete (stable for ft_clk read, same
  pattern as stream_flags_snapshot). Byte 2 emission is now
  {2'b00, subframe_enable[2:0], stream_flags[2:0]} — was {5'b00000, stream}.
- radar_protocol.py: Opcode.SUBFRAME_ENABLE = 0x19; RadarFrame.subframe_enable
  field; parse_bulk_frame surfaces bits[5:3]; reserved-mask 0xF8 → 0xC0.
  Bulk-frame mock encodes the mask in its emit so dashboard replay is correct.
- v7/processing.py: extract_targets_from_frame_crt forces every target to
  AMBIGUOUS when frame.subframe_enable != 0b111. Operator sees the red `?`
  flag in the targets table instead of a silently-wrong velocity.
- v7/software_fpga.py + v7/dashboard.py: subframe_enable mirror + setter, and
  replay dispatch routes 0x19 to set_subframe_enable.

Tests (test_v7.py): TestSubframeEnableRoundTrip (4), TestSoftwareFpgaSubframeEnable
(2), TestCrtSubframeMaskGating (3), 0x19 added to TestOpcodeEnumFillIn and
TestReplayOpcodeDispatch. Existing test_full_frame_round_trip updated to expect
byte 2 = 0x3F (mask 0b111 default + stream 0x07).

Cosim TBs (tb/tb_usb_protocol_v2.v, tb/tb_ft2232h_frame_drop.v) drive the new
input with 3'b111 and assert the new byte-2 layout (T2.3: 0x00 → 0x38).

Regression: test_v7 146/146, test_GUI_V65_Tk 117/117, ruff clean.
iverilog: tb_usb_protocol_v2 27/27 PASS, tb_ft2232h_frame_drop 10/10 PASS.
This commit is contained in:
Jason
2026-05-02 17:49:16 +05:45
parent 8ebb7016de
commit ef32345b26
10 changed files with 283 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
9_Firmware/9_3_GUI/radar_protocol.py
+52 -14
View File
@@ -99,12 +99,22 @@ BULK_FRAME_MAX_SIZE = (BULK_FRAME_HEADER_SIZE + BULK_RANGE_SECTION_BYTES
+ BULK_DOPPLER_MAG_BYTES + BULK_DETECT_DENSE_BYTES
+ BULK_FOOTER_SIZE) # 56330
# Bulk-frame format flag bits (matches stream_ctrl_sync_1 layout in RTL).
# Only the low 3 bits are used on the wire; bits [7:3] are reserved-zero.
# Bulk-frame format flag bits.
# Layout (PR-U / M-8):
# bits[2:0] = stream flags {cfar, doppler, range} (matches stream_ctrl_sync_1)
# bits[5:3] = subframe_enable mask {LONG, MEDIUM, SHORT}
# snapshot of host_subframe_enable at frame_complete (FPGA opcode 0x19).
# Default 3'b111 keeps the production 3-PRI ladder; mask != 3'b111
# means an operator disabled a sub-frame and the host should
# downgrade CRT confidence (dbin // 16 attribution would mis-bin).
# bits[7:6] = reserved-zero — any non-zero in this mask rejects the frame.
BULK_FLAG_STREAM_RANGE = 0x01
BULK_FLAG_STREAM_DOPPLER = 0x02
BULK_FLAG_STREAM_CFAR = 0x04
BULK_FLAGS_RESERVED_MASK = 0xF8 # any bit in this mask set → reject frame
BULK_SUBFRAME_ENABLE_MASK = 0x38 # bits[5:3] = subframe_enable[2:0]
BULK_SUBFRAME_ENABLE_SHIFT = 3
BULK_SUBFRAME_ENABLE_ALL = 0b111 # SHORT | MEDIUM | LONG
BULK_FLAGS_RESERVED_MASK = 0xC0 # any bit in this mask set → reject frame
class Opcode(IntEnum):
@@ -124,6 +134,7 @@ class Opcode(IntEnum):
0x16 host_gain_shift
0x17 host_medium_chirp_cycles (PR-G G2)
0x18 host_medium_listen_cycles (PR-G G2)
0x19 host_subframe_enable (PR-U / M-8 — 3-bit {LONG, MED, SHORT} mask)
"""
# --- Basic control (0x01-0x04) ---
RADAR_MODE = 0x01 # 2-bit mode select
@@ -146,6 +157,13 @@ class Opcode(IntEnum):
MEDIUM_CHIRP = 0x17
MEDIUM_LISTEN = 0x18
# PR-U / M-8: 3-bit sub-frame enable mask {LONG, MEDIUM, SHORT}. Default
# 3'b111 = all on. Setting != 3'b111 disables a sub-frame at the chirp
# scheduler; the FPGA echoes the mask in v2 frame byte 2 bits[5:3] so the
# host CRT downgrades confidence to UNKNOWN (dbin // 16 attribution would
# otherwise be wrong when the scheduler skips a sub-frame).
SUBFRAME_ENABLE = 0x19
# --- Signal processing (0x20-0x27) ---
RANGE_MODE = 0x20
CFAR_GUARD = 0x21
@@ -209,6 +227,14 @@ class RadarFrame:
# mag_only=1 (the only mode FPGA emits today). I/Q arrays will be zero;
# `magnitude` carries the per-cell Manhattan magnitude from the FPGA.
mag_only: bool = False
# PR-U / M-8: 3-bit sub-frame mask {LONG, MEDIUM, SHORT} snapshot from
# the FPGA at frame_complete (v2 frame byte 2 bits[5:3]). Default 0b111
# is the production 3-PRI ladder. Anything else means an operator
# disabled a sub-frame and the host CRT must downgrade confidence —
# `dbin // 16 → {SHORT, MED, LONG}` no longer attributes correctly when
# the chirp scheduler runs only the enabled sub-frames into 48 chirp
# slots in the doppler_processor.
subframe_enable: int = 0b111
@dataclass
@@ -456,10 +482,14 @@ class RadarProtocol:
return None
flags = raw[offset + 2]
# Only the low 3 bits are defined (range/doppler/cfar). Any reserved
# bit set means a future revision or corruption — reject and resync.
# bits[2:0] = stream {cfar,doppler,range}; bits[5:3] = subframe_enable;
# bits[7:6] reserved-zero. Any reserved bit set means a future revision
# or corruption — reject and resync.
if flags & BULK_FLAGS_RESERVED_MASK:
return None
# PR-U / M-8: surface the per-frame sub-frame mask so the host CRT can
# detect mask != 0b111 and degrade rather than mis-attribute the SF axis.
subframe_enable = (flags & BULK_SUBFRAME_ENABLE_MASK) >> BULK_SUBFRAME_ENABLE_SHIFT
frame_number = (raw[offset + 3] << 8) | raw[offset + 4]
n_range = (raw[offset + 5] << 8) | raw[offset + 6]
@@ -497,14 +527,15 @@ class RadarProtocol:
cursor += BULK_DETECT_DENSE_BYTES
return {
"frame_number": frame_number,
"flags": flags,
"n_range": n_range,
"n_doppler": n_doppler,
"range_profile": range_profile,
"doppler_mag": doppler_mag,
"cfar_dense": cfar_dense,
"frame_size": size,
"frame_number": frame_number,
"flags": flags,
"subframe_enable": subframe_enable,
"n_range": n_range,
"n_doppler": n_doppler,
"range_profile": range_profile,
"doppler_mag": doppler_mag,
"cfar_dense": cfar_dense,
"frame_size": size,
}
@staticmethod
@@ -732,7 +763,11 @@ class FT2232HConnection:
buf = bytearray(BULK_FRAME_MAX_SIZE)
buf[0] = HEADER_BYTE
buf[1] = RP_USB_PROTOCOL_VERSION
buf[2] = flags & 0x07 # only 3 stream-enable bits valid; reserved zero
# PR-U / M-8: byte 2 = bits[2:0] stream + bits[5:3] subframe_enable +
# bits[7:6] reserved-zero. Mock emits the production 3-PRI ladder
# (mask = 0b111) so dashboards see CONFIRMED CRT confidence.
buf[2] = ((BULK_SUBFRAME_ENABLE_ALL << BULK_SUBFRAME_ENABLE_SHIFT)
| (flags & 0x07))
buf[3] = (self._mock_frame_num >> 8) & 0xFF
buf[4] = self._mock_frame_num & 0xFF
buf[5] = (NUM_RANGE_BINS >> 8) & 0xFF
@@ -1120,6 +1155,9 @@ class RadarAcquisition(threading.Thread):
# path implemented in the FPGA write FSM), so flag this for downstream
# consumers that expect mag-only when reading from bulk.
frame.mag_only = True
# PR-U / M-8: per-frame snapshot of host_subframe_enable (FPGA opcode
# 0x19, default 0b111). The CRT extractor uses this to gate confidence.
frame.subframe_enable = int(parsed.get("subframe_enable", 0b111)) & 0x07
rprof = parsed["range_profile"]
if rprof is not None:
9_Firmware/9_3_GUI/test_v7.py
+140 -4
View File
@@ -370,16 +370,26 @@ class TestBulkFrameV2RoundTrip(unittest.TestCase):
def _build_v2_frame(self, flags: int, frame_num: int = 0,
doppler: np.ndarray | None = None,
cfar_codes: np.ndarray | None = None,
range_profile: np.ndarray | None = None) -> bytes:
"""Construct a v2 frame the way usb_data_interface_ft2232h.v emits."""
range_profile: np.ndarray | None = None,
subframe_enable: int = 0b111) -> bytes:
"""Construct a v2 frame the way usb_data_interface_ft2232h.v emits.
``subframe_enable`` lands in byte 2 bits[5:3] (PR-U / M-8). Caller
passes raw stream bits in ``flags`` (low 3 bits); helper composes the
full byte 2 = {2'b00, subframe_enable[2:0], stream[2:0]}.
"""
from radar_protocol import (
HEADER_BYTE, FOOTER_BYTE, RP_USB_PROTOCOL_VERSION,
NUM_RANGE_BINS, NUM_DOPPLER_BINS,
BULK_FLAG_STREAM_RANGE, BULK_FLAG_STREAM_DOPPLER, BULK_FLAG_STREAM_CFAR,
BULK_DETECT_BYTES_PER_RANGE,
BULK_SUBFRAME_ENABLE_SHIFT,
)
flags_byte = (((subframe_enable & 0x07) << BULK_SUBFRAME_ENABLE_SHIFT)
| (flags & 0x07)
| (flags & 0xC0)) # preserve reserved bits if caller injects them
parts = [
bytes([HEADER_BYTE, RP_USB_PROTOCOL_VERSION, flags & 0xFF]),
bytes([HEADER_BYTE, RP_USB_PROTOCOL_VERSION, flags_byte & 0xFF]),
struct.pack(">H", frame_num),
struct.pack(">H", NUM_RANGE_BINS),
struct.pack(">H", NUM_DOPPLER_BINS),
@@ -431,7 +441,11 @@ class TestBulkFrameV2RoundTrip(unittest.TestCase):
parsed = RadarProtocol.parse_bulk_frame(frame)
self.assertIsNotNone(parsed)
self.assertEqual(parsed["frame_number"], 42)
self.assertEqual(parsed["flags"], flags)
# PR-U / M-8: byte 2 now packs subframe_enable into bits[5:3]; helper
# defaults to 0b111 (production 3-PRI ladder) so the wire flags byte
# is (0b111 << 3) | 0x07 = 0x3F.
self.assertEqual(parsed["flags"], flags | (0b111 << 3))
self.assertEqual(parsed["subframe_enable"], 0b111)
self.assertEqual(parsed["n_range"], NUM_RANGE_BINS)
self.assertEqual(parsed["n_doppler"], NUM_DOPPLER_BINS)
np.testing.assert_array_equal(parsed["range_profile"], rp)
@@ -484,6 +498,56 @@ class TestBulkFrameV2RoundTrip(unittest.TestCase):
self.assertEqual(boundaries[1], (len(f1), len(f1) + len(f2), "data"))
class TestSubframeEnableRoundTrip(TestBulkFrameV2RoundTrip):
"""PR-U / M-8: byte 2 bits[5:3] carry the per-frame sub-frame mask."""
def test_default_mask_round_trip(self):
"""Production default 0b111 round-trips and is the helper default."""
from radar_protocol import (
RadarProtocol, BULK_FLAG_STREAM_DOPPLER,
)
frame = self._build_v2_frame(BULK_FLAG_STREAM_DOPPLER, frame_num=1)
parsed = RadarProtocol.parse_bulk_frame(frame)
self.assertIsNotNone(parsed)
self.assertEqual(parsed["subframe_enable"], 0b111)
def test_short_disabled_mask(self):
"""subframe_enable = 0b110 (LONG|MEDIUM, no SHORT) survives the wire."""
from radar_protocol import (
RadarProtocol, BULK_FLAG_STREAM_DOPPLER,
)
frame = self._build_v2_frame(BULK_FLAG_STREAM_DOPPLER, frame_num=1,
subframe_enable=0b110)
parsed = RadarProtocol.parse_bulk_frame(frame)
self.assertIsNotNone(parsed)
self.assertEqual(parsed["subframe_enable"], 0b110)
def test_short_only_mask(self):
"""subframe_enable = 0b001 (SHORT only) survives the wire."""
from radar_protocol import (
RadarProtocol, BULK_FLAG_STREAM_DOPPLER,
)
frame = self._build_v2_frame(BULK_FLAG_STREAM_DOPPLER, frame_num=2,
subframe_enable=0b001)
parsed = RadarProtocol.parse_bulk_frame(frame)
self.assertIsNotNone(parsed)
self.assertEqual(parsed["subframe_enable"], 0b001)
def test_subframe_bits_no_longer_in_reserved_mask(self):
"""Bits[5:3] are now valid SF mask, not reserved — must NOT reject."""
from radar_protocol import (
RadarProtocol, BULK_FLAGS_RESERVED_MASK,
BULK_SUBFRAME_ENABLE_MASK,
)
# The new reserved mask must not overlap the SF-enable bit field.
self.assertEqual(BULK_FLAGS_RESERVED_MASK & BULK_SUBFRAME_ENABLE_MASK, 0)
# And bit 6 (top of new reserved mask) STILL rejects.
from radar_protocol import BULK_FLAG_STREAM_RANGE
frame = self._build_v2_frame(BULK_FLAG_STREAM_RANGE | 0x40)
bad = bytes([frame[0], frame[1], frame[2] | 0x40]) + frame[3:]
self.assertIsNone(RadarProtocol.parse_bulk_frame(bad))
class TestStatusPacketV2RoundTrip(unittest.TestCase):
"""PR-G v2 status packet: 7 status_words / 30 bytes."""
@@ -1492,6 +1556,52 @@ class TestExtractTargetsFromFrameCrt(unittest.TestCase):
self.assertGreater(targets[0].longitude, 12.5)
class TestCrtSubframeMaskGating(unittest.TestCase):
"""PR-U / M-8: CRT downgrades confidence to AMBIGUOUS when SF mask != 0b111."""
def _make_3pri_frame(self, subframe_enable: int):
from radar_protocol import RadarFrame
frame = RadarFrame()
# Detection at rbin=10 in all 3 sub-frames at bin 3 — would normally
# CONFIRM, but a non-default mask must force AMBIGUOUS.
for rbin, dbin, mag in [(10, 3, 1000.0), (10, 19, 800.0), (10, 35, 1200.0)]:
frame.detections[rbin, dbin] = 1
frame.magnitude[rbin, dbin] = mag
frame.detection_count = int(frame.detections.sum())
frame.timestamp = 1.0
frame.subframe_enable = subframe_enable
return frame
def test_default_mask_keeps_confirmed_path(self):
from v7.processing import extract_targets_from_frame_crt
from v7.models import WaveformConfig
wc = WaveformConfig()
frame = self._make_3pri_frame(0b111)
targets = extract_targets_from_frame_crt(frame, wc)
self.assertEqual(len(targets), 1)
self.assertEqual(targets[0].velocity_confidence, "CONFIRMED")
def test_short_disabled_forces_ambiguous(self):
"""SHORT off → CRT can't trust dbin // 16 attribution → AMBIGUOUS."""
from v7.processing import extract_targets_from_frame_crt
from v7.models import WaveformConfig
wc = WaveformConfig()
frame = self._make_3pri_frame(0b110)
targets = extract_targets_from_frame_crt(frame, wc)
self.assertEqual(len(targets), 1)
self.assertEqual(targets[0].velocity_confidence, "AMBIGUOUS")
def test_long_only_forces_ambiguous(self):
"""LONG only mask: scheduler skips SHORT+MEDIUM, all targets AMBIGUOUS."""
from v7.processing import extract_targets_from_frame_crt
from v7.models import WaveformConfig
wc = WaveformConfig()
frame = self._make_3pri_frame(0b100)
targets = extract_targets_from_frame_crt(frame, wc)
self.assertEqual(len(targets), 1)
self.assertEqual(targets[0].velocity_confidence, "AMBIGUOUS")
# =============================================================================
# Test: PR-Q.6 — workers route through extract_targets_from_frame_crt
# RadarDataWorker._run_host_dsp + ReplayWorker._extract_targets must use the
@@ -1651,6 +1761,11 @@ class TestOpcodeEnumFillIn(unittest.TestCase):
from radar_protocol import Opcode
self.assertEqual(Opcode.ADC_FORMAT.value, 0x33)
def test_subframe_enable_opcode(self):
"""PR-U / M-8: 0x19 sets host_subframe_enable mask."""
from radar_protocol import Opcode
self.assertEqual(Opcode.SUBFRAME_ENABLE.value, 0x19)
def test_no_duplicate_opcodes(self):
"""All Opcode values are unique (catches accidental collisions)."""
from radar_protocol import Opcode
@@ -1674,6 +1789,21 @@ class TestSoftwareFpgaCfarAlphaSoft(unittest.TestCase):
self.assertEqual(fpga.cfar_alpha_soft, 0x34)
class TestSoftwareFpgaSubframeEnable(unittest.TestCase):
"""PR-U / M-8: SoftwareFPGA mirrors host_subframe_enable, masks to 3 bits."""
def test_default(self):
from v7.software_fpga import SoftwareFPGA
fpga = SoftwareFPGA()
self.assertEqual(fpga.subframe_enable, 0b111) # RP_DEF_SUBFRAME_ENABLE
def test_setter_masks_to_3_bits(self):
from v7.software_fpga import SoftwareFPGA
fpga = SoftwareFPGA()
fpga.set_subframe_enable(0xFE)
self.assertEqual(fpga.subframe_enable, 0b110)
@unittest.skipUnless(_pyqt6_available(), "PyQt6 not installed")
class TestReplayOpcodeDispatch(unittest.TestCase):
"""M-6: replay dispatch routes 0x2D to SoftwareFPGA + acknowledges inert opcodes."""
@@ -1695,6 +1825,12 @@ class TestReplayOpcodeDispatch(unittest.TestCase):
dispatch(fake, 0x2D, 42)
self.assertEqual(fake._software_fpga.cfar_alpha_soft, 42)
def test_0x19_routed_to_set_subframe_enable(self):
"""PR-U / M-8: 0x19 lands on SoftwareFPGA.set_subframe_enable."""
dispatch, fake = self._dashboard_with_replay()
dispatch(fake, 0x19, 0b101)
self.assertEqual(fake._software_fpga.subframe_enable, 0b101)
def test_inert_opcode_does_not_raise(self):
"""Inert opcodes (e.g. 0x32 ADC_PWDN) accepted without exception."""
dispatch, fake = self._dashboard_with_replay()
9_Firmware/9_3_GUI/v7/dashboard.py
+4
View File
@@ -1676,6 +1676,10 @@ class RadarDashboard(QMainWindow):
0x2B: lambda v: fpga.set_agc_params(decay=v),
0x2C: lambda v: fpga.set_agc_params(holdoff=v),
0x2D: lambda v: fpga.set_cfar_alpha_soft(v),
# PR-U / M-8: track the operator's sub-frame mask so subsequent
# frames the host parses use the correct CRT confidence rules
# (replay frames carry the mask the FPGA echoed at capture time).
0x19: lambda v: fpga.set_subframe_enable(v),
}
# Inert in replay: RTL-only chirp timing / range mode / self-test /
# status / ADC strap. The recorded I/Q already reflects whatever
9_Firmware/9_3_GUI/v7/processing.py
+11
View File
@@ -698,6 +698,15 @@ def extract_targets_from_frame_crt(
gps=gps,
)
# PR-U / M-8: when the operator disabled a sub-frame at the FPGA, the
# chirp_scheduler runs only the enabled SFs but doppler_processor still
# emits 48 chirp slots — `dbin // 16 → {SHORT, MED, LONG}` no longer
# attributes correctly. Force AMBIGUOUS for every target so the dashboard
# column flags it red. Default 0b111 keeps the production happy path on
# the CONFIRMED branch via the normal CRT logic.
sf_mask = getattr(frame, "subframe_enable", 0b111) & 0x07
sf_mask_invalid = (sf_mask != 0b111)
chirps_per_sf = waveform.chirps_per_subframe # 16
v_res_per_sf_all = [
waveform.velocity_resolution_short_mps,
@@ -746,6 +755,8 @@ def extract_targets_from_frame_crt(
v_est, confidence, alias_set = unfold_velocity_crt(
v_meas_list, v_unamb_list, v_res_list, max_alias_k=max_alias_k,
)
if sf_mask_invalid:
confidence = "AMBIGUOUS"
range_m = float(rbin) * range_resolution
snr = 10.0 * math.log10(max(peak_mag, 1.0)) if peak_mag > 0 else 0.0
9_Firmware/9_3_GUI/v7/software_fpga.py
+9
View File
@@ -109,6 +109,12 @@ class SoftwareFPGA:
self.agc_decay: int = 1 # 0x2B
self.agc_holdoff: int = 4 # 0x2C
# PR-U / M-8: 3-bit sub-frame mask {LONG, MEDIUM, SHORT}. Default 0b111
# = production 3-PRI ladder. Tracked only — replay frames are already
# rendered, so the mask doesn't affect playback math here. Surfaces in
# the parsed RadarFrame from radar_protocol so the CRT extractor sees it.
self.subframe_enable: int = 0b111 # 0x19
# ------------------------------------------------------------------
# Register setters (same interface as UART commands to real FPGA)
# ------------------------------------------------------------------
@@ -133,6 +139,9 @@ class SoftwareFPGA:
def set_cfar_alpha_soft(self, val: int) -> None:
self.cfar_alpha_soft = int(val) & 0xFF
def set_subframe_enable(self, val: int) -> None:
self.subframe_enable = int(val) & 0x07
def set_cfar_mode(self, val: int) -> None:
self.cfar_mode = int(val) & 0x03