BMS: implement spec state machine with SN4-aligned charging + safety audit fixes

Reconcile the BMS state machine with the SN5 spec diagram, porting charging
behavior from SN4, then fix issues found in a full SN4-vs-SN5 safety audit.

State machine:
- Re-enable precharge voltage gate (3->4, IVT >= 90% pack), R2D gate (4->5),
  and R2D-loss return (5->4); BSPD/APPS remain safe-default TODO stubs
- Central evaluate_faults() on the 1ms tick: cell V/T violations, sensor
  timeouts (IVT + cell monitor), overcurrent, continuous IMD, contactor
  feedback plausibility; drive group -> FAULT_BMS/IMD, charger group ->
  FAULT_CHARGING (explicit handler faults coerced to match, per SN4/diagram)
- All fault states latch until power cycle (updateStateProtected generalized)
- Balance: console 6<->8 transitions + auto-return when cells balanced

Charging (ported from SN4, FreeRTOS-safe):
- New FEB_CAN_Charger module: extended-ID CCS protocol (0x1806E5F4 /
  0x18FF50E5), Charging_Status soft/hard limits, trickle charge; charger
  actively commanded OFF whenever connected and not in CHARGING;
  done_charging re-arms on charger unplug
- New FEB_CAN_Heartbeat module: DASH/PCU presence drives LV_POWER <->
  BATTERY_FREE (only-charger-on-CAN / reconnection)

Audit fixes:
- Lock-free ADBMS pack snapshots so the 1ms SM task never blocks on the
  ADBMS mutex (temp scans hold it for tens of ms)
- CAN filter consolidation: heartbeats and IVT each use one mask filter;
  boot usage drops from 14/14 banks (dynamic registrations silently dropped)
  to 4/14; feb_can_filter now reports overflow instead of dropping silently
- Saturating violation counters; charging blocked until first cell scan

Thresholds marked TUNE must be set from real pack/fuse/charger ratings
before track use.

Author: ZacharyBer

BMS/Core/User/Inc/FEB_ADBMS6830B.h

@@ -121,4 +121,33 @@ bool FEB_Cell_Balancing_Status(void);
 uint8_t FEB_ADBMS_Get_Error_Type(void);
 void FEB_ADBMS_Update_Error_Type(uint8_t error);
 
+// ********************************** Fault Flags (SM handoff) *******************
+// Sticky flags set by the ADBMS task (under mutex) and read lock-free by the
+// state machine task. 32-bit aligned reads are atomic on Cortex-M4.
+#define ADBMS_FAULT_FLAG_VOLTAGE (1u << 0)
+#define ADBMS_FAULT_FLAG_TEMP (1u << 1)
+#define ADBMS_FAULT_FLAG_SENSOR (1u << 2) // reserved: PEC / comm failure
+
+/** @brief Latched cell V/T fault flags (ADBMS_FAULT_FLAG_*). */
+uint32_t FEB_ADBMS_Get_Fault_Flags(void);
+
+/** @brief HAL tick of last completed V/T process (0 = never). Used for the
+ *  cell-monitor sensor-timeout check in the state machine. */
+uint32_t FEB_ADBMS_Get_Last_Update_Tick(void);
+
+// ********************************** Lock-free Snapshots ************************
+// Pack-level values published by the ADBMS task at the end of each scan and
+// readable WITHOUT the ADBMS mutex (atomic 32-bit reads). Use these — not the
+// FEB_ADBMS_GET_ACC_* getters — from the 1ms state-machine task: the mutex is
+// held for tens of ms during a temperature scan and would stall the SM.
+
+/** @brief Pack total voltage [V] from the last scan (0 until first scan). */
+float FEB_ADBMS_Snapshot_Total_Voltage(void);
+
+/** @brief Highest cell voltage [V] from the last scan. */
+float FEB_ADBMS_Snapshot_Max_Cell_Voltage(void);
+
+/** @brief Highest pack temperature [C] from the last scan (NaN until first scan). */
+float FEB_ADBMS_Snapshot_Max_Temp(void);
+
 #endif /* INC_FEB_ADBMS6830B_H_ */

BMS/Core/User/Inc/FEB_CAN_Charger.h

@@ -0,0 +1,52 @@
+/**
+ * @file FEB_CAN_Charger.h
+ * @brief Charger CAN interface (ported from SN4 BMS)
+ * @author Formula Electric @ Berkeley
+ *
+ * Talks to the CCS charger over extended-ID CAN:
+ *   - BMS  -> charger : 0x1806E5F4 (max voltage / max current / control)
+ *   - charger -> BMS  : 0x18FF50E5 (operating voltage / current / status)
+ *
+ * Behaviour mirrors SN4 (FEB_CAN_Charger.c) but uses the SN5 feb_can_lib
+ * RX/TX API (extended-ID aware, FreeRTOS-safe queues) instead of raw HAL.
+ */
+
+#ifndef INC_FEB_CAN_CHARGER_H_
+#define INC_FEB_CAN_CHARGER_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+
+/**
+ * @brief Register charger CAN reception. Call from the CAN RX task before
+ *        FEB_CAN_Filter_UpdateFromRegistry().
+ */
+void FEB_CAN_Charger_Init(void);
+
+/**
+ * @brief True if a charger frame was received within FEB_CHARGER_RX_TIMEOUT_MS.
+ *        Used to gate BATTERY_FREE -> CHARGER_PRECHARGE (6->7).
+ */
+bool FEB_CAN_Charger_Received(void);
+
+/**
+ * @brief SN4 charge-decision function (uses existing cell V/T telemetry).
+ * @return  1  charge complete / soft V or T limit hit -> stop, return to FREE
+ *         -1  hard pack/cell over-voltage or over-temp -> FAULT_CHARGING
+ *          0  keep charging
+ */
+int8_t FEB_CAN_Charging_Status(void);
+
+/** @brief Command the charger to start (control byte = 0). */
+void FEB_CAN_Charger_Start_Charge(void);
+
+/** @brief Command the charger to stop (control byte = 1, marks done). */
+void FEB_CAN_Charger_Stop_Charge(void);
+
+/**
+ * @brief Periodic charger command TX + trickle-charge logic.
+ *        No-op unless the state machine is in CHARGING. Call ~every 100 ms.
+ */
+void FEB_CAN_Charger_Process(void);
+
+#endif /* INC_FEB_CAN_CHARGER_H_ */

BMS/Core/User/Inc/FEB_CAN_Heartbeat.h

@@ -0,0 +1,46 @@
+/**
+ * @file FEB_CAN_Heartbeat.h
+ * @brief CAN-presence (heartbeat) tracking for the BMS
+ * @author Formula Electric @ Berkeley
+ *
+ * Tracks which subsystems are alive on the bus by timestamping their heartbeat
+ * frames (0xD0-0xD5, defined in the shared CAN library). Drives the
+ * BATTERY_FREE <-> LV_POWER transitions (spec "Only Charger on CAN" /
+ * "Other subsystems on CAN"). This is the SN5-idiom equivalent of SN4's
+ * FEB_COMBINED_STATUS()/FAck scheme: simple last-seen freshness rather than
+ * failed-ack counters.
+ */
+
+#ifndef INC_FEB_CAN_HEARTBEAT_H_
+#define INC_FEB_CAN_HEARTBEAT_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef enum
+{
+  FEB_HB_PCU = 0,
+  FEB_HB_DASH,
+  FEB_HB_LVPDB,
+  FEB_HB_DCU,
+  FEB_HB_FSN,
+  FEB_HB_RSN,
+  FEB_HB_COUNT
+} FEB_HB_Device_t;
+
+/**
+ * @brief Register heartbeat RX. Call from the CAN RX task before
+ *        FEB_CAN_Filter_UpdateFromRegistry().
+ */
+void FEB_CAN_Heartbeat_Init(void);
+
+/** @brief True if @p dev sent a heartbeat within @p timeout_ms. */
+bool FEB_CAN_Heartbeat_DevFresh(FEB_HB_Device_t dev, uint32_t timeout_ms);
+
+/**
+ * @brief True if "other subsystems" (DASH or PCU) are present on CAN.
+ *        Mirrors SN4 FEB_COMBINED_STATUS(), which keys on DASH/PCU.
+ */
+bool FEB_CAN_Heartbeat_OthersPresent(uint32_t timeout_ms);
+
+#endif /* INC_FEB_CAN_HEARTBEAT_H_ */

BMS/Core/User/Inc/FEB_CAN_State.h

@@ -12,6 +12,10 @@
  * @brief BMS state machine states (aligned with SN4)
  * @note Values match CAN bms_state signal (5-bit, 0-31 valid range)
  * @note Values must match FEB_SM_ST_t in PCU/Core/User/Inc/FEB_CAN_BMS.h
+ * @note SN5 keeps an extra CHARGER_PRECHARGE (7) state that the spec diagram
+ *       does not show, so diagram state numbers >= 7 (Charging, Balance, the
+ *       fault states) are offset by +1 here. Do NOT renumber to "match" the
+ *       diagram: PCU mirrors these exact values and compares state == DRIVE (5).
  */
 typedef enum
 {
@@ -71,11 +75,11 @@ const char *FEB_CAN_State_GetStateName(BMS_State_t state);
 
 /**
  * @brief Process automatic state transitions based on R2D signal
- * @note Call from 1ms timer callback
  *
- * Handles:
- * - ENERGIZED -> DRIVE when R2D active
- * - DRIVE -> ENERGIZED when R2D inactive/timeout
+ * @warning DO NOT CALL. The ENERGIZED<->DRIVE R2D logic now lives in
+ *          FEB_SM.c (EnergizedTransition / DriveTransition). Calling this would
+ *          double-drive those transitions. Retained only to avoid touching the
+ *          generated wiring; remove once confirmed unused everywhere.
  */
 void FEB_CAN_State_ProcessTransitions(void);
 

BMS/Core/User/Inc/FEB_Const.h

@@ -86,6 +86,37 @@
 #define FEB_VOLTAGE_ERROR_THRESH 3 // Trigger fault after 3 consecutive voltage violations
 #define FEB_TEMP_ERROR_THRESH 5    // Trigger fault after 5 consecutive temp violations
 
+// ********************************** Charging Limits (SN4-derived) **************
+// Used by FEB_CAN_Charging_Status(). Soft limit -> stop charging and return to
+// BATTERY_FREE; hard limit -> FAULT_CHARGING. SN5 values (do not copy SN4's
+// pack-specific thermal numbers verbatim).
+#define FEB_CONFIG_CELL_HARD_MAX_VOLTAGE_mV 4200 // Hard cell over-voltage -> FAULT_CHARGING
+#define FEB_CONFIG_CELL_SOFT_MAX_VOLTAGE_mV 4180 // TUNE: soft target -> stop charge
+#define FEB_CONFIG_CELL_HARD_MAX_TEMP_dC 600     // 60.0C hard over-temp -> FAULT_CHARGING
+// (soft charge temp limit FEB_CONFIG_CELL_SOFT_MAX_TEMP_dC defined above = 550)
+
+// Pack hard-max voltage in VOLTS (compared against pack/IVT voltage in volts).
+#define FEB_CONFIG_PACK_HARD_MAX_VOLTAGE_V                                                                             \
+  ((FEB_NBANKS * FEB_NUM_CELLS_PER_BANK * FEB_CONFIG_CELL_HARD_MAX_VOLTAGE_mV) / 1000.0f)
+
+// ********************************** Charger CAN (SN4-derived) ******************
+// Charger command (BMS -> charger) targets, in charger units (deci-amps / deci-volts).
+#define FEB_CHARGE_CURRENT_dA 40 // TUNE: 4.0 A nominal charge current
+#define FEB_TRICKLE_CHARGE_CURRENT_dA (FEB_CHARGE_CURRENT_dA / 2)
+#define FEB_TRICKLE_CHARGE_INTERVAL_MS 5000 // toggle interval near full charge
+#define FEB_CHARGE_TARGET_VOLTAGE_dV ((uint16_t)(FEB_CONFIG_PACK_HARD_MAX_VOLTAGE_V * 10.0f * 0.99f))        // TUNE
+#define FEB_TRICKLE_CHARGE_START_VOLTAGE_dV ((uint16_t)(FEB_CONFIG_PACK_HARD_MAX_VOLTAGE_V * 10.0f * 0.98f)) // TUNE
+#define FEB_CHARGER_RX_TIMEOUT_MS 1000 // charger considered absent after this
+
+// ********************************** Fault Evaluation Thresholds ****************
+#define FEB_DISCHARGE_OVERCURRENT_A 350.0f    // TUNE: drive-side limit (fuse/AIR rating)
+#define FEB_CHARGE_OVERCURRENT_A 60.0f        // TUNE: charge-side limit (charger rating)
+#define FEB_OVERCURRENT_CONFIRM_MS 50         // |I| must exceed limit this long before fault
+#define FEB_IVT_FAULT_TIMEOUT_MS 1000         // IVT CAN staleness -> sensor timeout fault
+#define FEB_ADBMS_DATA_TIMEOUT_MS 1000        // cell-monitor staleness -> sensor timeout fault
+#define FEB_IMD_FAULT_CONFIRM_MS 100          // debounce IMD-open before faulting
+#define FEB_CONTACTOR_FEEDBACK_TIMEOUT_MS 200 // cmd vs sense mismatch -> weld/stuck fault
+
 // ********************************** isoSPI Communication Mode ******************
 
 // isoSPI Mode Selection - Choose ONE of the following:

BMS/Core/User/Src/FEB_ADBMS6830B.c

@@ -42,6 +42,22 @@ uint16_t balancing_mask = 0xAAAA;
 
 uint8_t ERROR_TYPE = 0; // HEXDIGIT 1 voltage faults; HEXDIGIT 2 temp faults; HEXDIGIT 3 relay faults
 
+/* Sticky fault flags + freshness tick for the state machine.
+ * Written here under ADBMSMutexHandle (validators run while the task holds it);
+ * read lock-free by the SM task via FEB_ADBMS_Get_Fault_Flags() /
+ * FEB_ADBMS_Get_Last_Update_Tick(). 32-bit aligned access is atomic on M4. */
+static volatile uint32_t adbms_fault_flags = 0;
+static volatile uint32_t adbms_last_update_tick = 0;
+
+/* Lock-free pack-level snapshots for the 1ms SM task. Written at the end of
+ * each process pass (writer holds ADBMSMutexHandle); read without the mutex
+ * (aligned 32-bit float reads are atomic on Cortex-M4). The mutex-taking
+ * FEB_ADBMS_GET_ACC_* getters MUST NOT be called from the SM task hot path:
+ * a temperature scan holds the mutex for tens of ms and would stall it. */
+static volatile float adbms_snap_total_V = 0.0f;
+static volatile float adbms_snap_max_cell_V = 0.0f;
+static volatile float adbms_snap_max_temp_C = NAN;
+
 // ********************************** Config Bits ********************************
 
 static bool refon = 1;
@@ -224,15 +240,22 @@ static void validate_voltages()
         // Check redundant S-code measurement to confirm violation
         if (voltageS > vMax || voltageS < vMin)
         {
-          FEB_ACC.banks[bank].cells[cell].violations += 1;
-          DEBUG_VOLTAGE_PRINT("Both C and S codes confirm violation: violations=%d",
-                              FEB_ACC.banks[bank].cells[cell].violations);
-          if (FEB_ACC.banks[bank].cells[cell].violations == FEB_VOLTAGE_ERROR_THRESH)
+          /* Saturating increment (counter is uint8_t — a free-running += would
+           * wrap at 255); actions fire exactly once, on the crossing scan. */
+          if (FEB_ACC.banks[bank].cells[cell].violations < FEB_VOLTAGE_ERROR_THRESH)
           {
-            printf("[ADBMS] FAULT: Cell voltage out of range - Bank %d Cell %d: %.3fV (limits: %.3f-%.3fV)\r\n", bank,
-                   cell, voltageC / 1000.0f, vMin / 1000.0f, vMax / 1000.0f);
-            FEB_ADBMS_Update_Error_Type(ERROR_TYPE_VOLTAGE_VIOLATION);
-            // FEB_SM_Transition(FEB_SM_ST_FAULT_BMS);
+            FEB_ACC.banks[bank].cells[cell].violations += 1;
+            DEBUG_VOLTAGE_PRINT("Both C and S codes confirm violation: violations=%d",
+                                FEB_ACC.banks[bank].cells[cell].violations);
+            if (FEB_ACC.banks[bank].cells[cell].violations >= FEB_VOLTAGE_ERROR_THRESH)
+            {
+              printf("[ADBMS] FAULT: Cell voltage out of range - Bank %d Cell %d: %.3fV (limits: %.3f-%.3fV)\r\n", bank,
+                     cell, voltageC / 1000.0f, vMin / 1000.0f, vMax / 1000.0f);
+              FEB_ADBMS_Update_Error_Type(ERROR_TYPE_VOLTAGE_VIOLATION);
+              /* Latch for the SM task; evaluate_faults() in FEB_SM.c routes this
+               * to FAULT_BMS (drive group) or FAULT_CHARGING (charger group). */
+              adbms_fault_flags |= ADBMS_FAULT_FLAG_VOLTAGE;
+            }
           }
         }
         else
@@ -449,13 +472,18 @@ static void validate_temps()
       {
         DEBUG_TEMP_PRINT("Temperature violation: Bank %d Sensor %d Temp=%.1fC violations=%d", bank, sensor,
                          temp / 10.0f, FEB_ACC.banks[bank].temp_violations[sensor] + 1);
-        FEB_ACC.banks[bank].temp_violations[sensor]++;
-        if (FEB_ACC.banks[bank].temp_violations[sensor] == FEB_TEMP_ERROR_THRESH)
+        /* Saturating increment (uint8_t would wrap); actions fire once. */
+        if (FEB_ACC.banks[bank].temp_violations[sensor] < FEB_TEMP_ERROR_THRESH)
         {
-          printf("[ADBMS] FAULT: Cell temperature out of range - Bank %d Sensor %d: %.1fC (limits: %.1f-%.1fC)\r\n",
-                 bank, sensor, temp / 10.0f, tMin / 10.0f, tMax / 10.0f);
-          FEB_ADBMS_Update_Error_Type(ERROR_TYPE_TEMP_VIOLATION);
-          // FEB_SM_Transition(FEB_SM_ST_FAULT_BMS);
+          FEB_ACC.banks[bank].temp_violations[sensor]++;
+          if (FEB_ACC.banks[bank].temp_violations[sensor] >= FEB_TEMP_ERROR_THRESH)
+          {
+            printf("[ADBMS] FAULT: Cell temperature out of range - Bank %d Sensor %d: %.1fC (limits: %.1f-%.1fC)\r\n",
+                   bank, sensor, temp / 10.0f, tMin / 10.0f, tMax / 10.0f);
+            FEB_ADBMS_Update_Error_Type(ERROR_TYPE_TEMP_VIOLATION);
+            /* Latch for the SM task; evaluate_faults() routes per state group. */
+            adbms_fault_flags |= ADBMS_FAULT_FLAG_TEMP;
+          }
         }
       }
       else
@@ -473,7 +501,10 @@ static void validate_temps()
   {
     DEBUG_TEMP_PRINT("WARNING: Low temperature read ratio (%.1f%%)", read_ratio * 100.0f);
     FEB_ADBMS_Update_Error_Type(ERROR_TYPE_LOW_TEMP_READS);
-    // FEB_SM_Transition(FEB_SM_ST_FAULT_BMS);
+    /* NOTE: chronic low temp-read ratio is a sensor-health warning, not a cell
+     * over-temp event; intentionally NOT latched as a hard fault (would
+     * false-trip on a flaky harness). A truly dead cell-monitor is caught by
+     * the staleness timeout (adbms_last_update_tick) in evaluate_faults(). */
   }
   DEBUG_TEMP_PRINT("Temperature validation complete");
 }
@@ -582,6 +613,10 @@ void FEB_ADBMS_Voltage_Process()
   read_cell_voltages();
   store_cell_voltages();
   validate_voltages();
+  /* Publish lock-free snapshots for the SM task (we hold the mutex here) */
+  adbms_snap_total_V = FEB_ACC.total_voltage_V;
+  adbms_snap_max_cell_V = FEB_ACC.pack_max_voltage_V;
+  adbms_last_update_tick = HAL_GetTick(); /* freshness for SM sensor-timeout check */
   DEBUG_VOLTAGE_PRINT("=== Voltage Process Completed ===");
 }
 
@@ -604,6 +639,9 @@ void FEB_ADBMS_Temperature_Process()
   }
   compute_pack_temp_stats();
   validate_temps();
+  /* Publish lock-free snapshot for the SM task (we hold the mutex here) */
+  adbms_snap_max_temp_C = FEB_ACC.pack_max_temp;
+  adbms_last_update_tick = HAL_GetTick(); /* freshness for SM sensor-timeout check */
 
   DEBUG_TEMP_PRINT("=== Temperature Process Completed ===");
 }
@@ -918,3 +956,33 @@ void FEB_ADBMS_Update_Error_Type(uint8_t error)
 {
   ERROR_TYPE = error;
 }
+
+// ********************************** Fault Flags (SM handoff) *******************
+
+uint32_t FEB_ADBMS_Get_Fault_Flags(void)
+{
+  return adbms_fault_flags;
+}
+
+uint32_t FEB_ADBMS_Get_Last_Update_Tick(void)
+{
+  return adbms_last_update_tick;
+}
+
+// ********************************** Lock-free Snapshots ************************
+// For the 1ms SM task / charger logic. Never blocks on ADBMSMutexHandle.
+
+float FEB_ADBMS_Snapshot_Total_Voltage(void)
+{
+  return adbms_snap_total_V;
+}
+
+float FEB_ADBMS_Snapshot_Max_Cell_Voltage(void)
+{
+  return adbms_snap_max_cell_V;
+}
+
+float FEB_ADBMS_Snapshot_Max_Temp(void)
+{
+  return adbms_snap_max_temp_C;
+}