fix(mcu): add FAULT_ACK command to clear system_emergency_state via USB (closes #83)

The volatile fix in the companion PR (#118) makes the safe-mode blink loop
escapable in principle, but no firmware path existed to actually clear
system_emergency_state at runtime — hardware reset was the only exit, which
fires the IWDG and re-energises the PA rails that Emergency_Stop() cut.

This change adds a FAULT_ACK command (opcode 0x40): the host sends an exact
4-byte CDC packet [0x40, 0x00, 0x00, 0x00]; USBHandler detects it regardless
of USB state and sets fault_ack_received; the blink loop checks the flag each
250 ms iteration and clears system_emergency_state, allowing a controlled
operator-acknowledged recovery without triggering a watchdog reset.

Detection is guarded to exact 4-byte packets only. Scanning larger packets
for the subsequence would false-trigger on the IEEE 754 big-endian encoding
of 2.0 (0x4000000000000000), which starts with the same 4 bytes and can
appear in normal settings doubles.

FAULT_ACK is excluded from the FPGA opcode enum to preserve the
Python/Verilog bidirectional contract test; contract_parser.py reads the
new MCU_ONLY_OPCODES frozenset in radar_protocol.py to filter it.

7 new test vectors in test_gap3_fault_ack_clears_emergency.c cover:
detection, loop exit, loop hold without ack, settings false-positive
immunity, truncated packet, wrong opcode, and multi-iteration sequence.

Reported-by: shaun0927 (Junghwan) <https://github.com/shaun0927>
This commit is contained in:
Jason
2026-04-21 03:51:43 +05:45
parent e979363730
commit 5b84af68f6
7 changed files with 172 additions and 3 deletions
+9
View File
@@ -103,6 +103,15 @@ class Opcode(IntEnum):
STATUS_REQUEST = 0xFF
# MCU-only commands — NOT dispatched to the FPGA opcode switch.
# These values have no corresponding case in radar_system_top.v.
# Listed here so the GUI can build and send them via build_command().
# contract_parser.py filters MCU_ONLY_OPCODES out of the Python/Verilog
# bidirectional check.
FAULT_ACK = 0x40 # Exact 4-byte CDC packet; clears system_emergency_state
MCU_ONLY_OPCODES: frozenset[int] = frozenset({0x40})
# ============================================================================
# Data Structures
# ============================================================================