BMS: FSAE-safe accumulator temperature monitoring

Make the cell-temperature path meet FSAE AMS rules: react to over/under-temp
and to loss of temperature data within the ~1 s window, and latch.

Over/under-temp fault:
- Was unreachable: FEB_TEMP_ERROR_THRESH had drifted to a pack-wide 0.8*N
  aggregate (=336) compared against a per-sensor uint8_t counter. Restore a
  small per-sensor consecutive-violation count so any single cell over/under
  limit latches.
- Was too slow even if reached: the temp scan ran at 2 Hz, so any debounce blew
  the FSAE budget. Drive the scan from FEB_TEMP_SCAN_PERIOD_MS and run it at
  100 ms (work is ~38 ms); phase-offset it from the voltage scan. Worst-case
  latch is now ~400 ms. A _Static_assert ties (THRESH+1)*period to a 900 ms
  budget so the timing can't silently regress.

Temperature-telemetry-loss fail-safe (FSAE: a disconnected temp sense wire must
open the shutdown circuit within 1 s):
- validate_temps() now measures valid reads against the POPULATED sensor count
  (FEB_TEMP_SENSORS_POPULATED_PER_BANK, not the 42-wide array) and latches
  ADBMS_FAULT_FLAG_SENSOR when below FEB_TEMP_MIN_VALID_FRACTION for longer than
  FEB_TEMP_TELEMETRY_TIMEOUT_MS (800 ms). Time-confirmed so a flaky scan won't
  trip it; gated under !FEB_BMS_DISABLE_TEMP_CHECKS so bench boards don't fault.
- evaluate_faults() routes the SENSOR flag to FAULT_BMS/FAULT_CHARGING.

Charging thermal limits: hard 60 -> 45 C, soft 55 -> 40 C (Li-ion charge accept
is stricter than the 60 C discharge ceiling). Verify against the cell datasheet.

Bench-mode safety:
- FEB_BMS_DISABLE_ADBMS_CHECKS default back to 0; bench enabled via the new
  BMS_BENCH_MODE CMake option (-D), not by editing the source default.
- scripts/check-bench-flags.sh fails if any bench override is committed enabled;
  wired into pre-commit and the quality CI workflow.

FEB_NBANKS 1 -> 10.

TUNE/verify against hardware: FEB_TEMP_SENSORS_POPULATED_PER_BANK (41) must match
the real harness; FEB_TEMP_MIN_VALID_FRACTION (0.50); >=30% coverage.

Author: ZacharyBer

.github/workflows/quality.yml

@@ -7,6 +7,17 @@ on:
     branches: [main]
 
 jobs:
+  bench-flags:
+    runs-on: ubuntu-latest
+    name: bench-flag guard
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: BMS ADBMS safety overrides must not be enabled in source
+        run: ./scripts/check-bench-flags.sh
+
   clang-format:
     runs-on: ubuntu-latest
     name: clang-format check

.pre-commit-config.yaml

@@ -49,6 +49,15 @@ repos:
         pass_filenames: false
         always_run: true
 
+      # Bench-flag guard - BMS ADBMS safety overrides must never ship enabled.
+      # Enable bench mode via the build flag (cmake -DBMS_BENCH_MODE=ON) instead.
+      - id: check-bench-flags
+        name: check-bench-flags
+        entry: ./scripts/check-bench-flags.sh
+        language: script
+        pass_filenames: false
+        always_run: true
+
       # Auto-increment patch version on each commit for affected boards + repo.
       # No-ops if a VERSION file is already staged (so /version stays authoritative).
       - id: auto-bump-patch

BMS/CMakeLists.txt

@@ -24,6 +24,18 @@ add_compile_definitions(
     $<$<CONFIG:Debug>:DEBUG>
 )
 
+# ── Bench-mode override (NEVER for a real pack / scrutineering) ───────
+# Sanctioned, *uncommitted* way to disable ADBMS safety checks for bench
+# bring-up with no functional cell monitor attached:
+#     cmake --preset Debug -DBMS_BENCH_MODE=ON   (or pass -DBMS_BENCH_MODE=ON)
+# The in-source default in FEB_Const.h MUST stay 0 — scripts/check-bench-flags.sh
+# enforces that — so this build flag is the only approved way to flip it.
+option(BMS_BENCH_MODE "Disable ADBMS safety checks for bench bring-up (NEVER for a real pack)" OFF)
+if(BMS_BENCH_MODE)
+    add_compile_definitions(FEB_BMS_DISABLE_ADBMS_CHECKS=1)
+    message(WARNING "BMS_BENCH_MODE=ON: ADBMS safety checks DISABLED — bench only, NEVER a real pack")
+endif()
+
 # ══════════════════════════════════════════════════════════════════════
 #  SOURCE COLLECTION
 # ══════════════════════════════════════════════════════════════════════

BMS/Core/User/Inc/FEB_ADBMS6830B.h

@@ -126,7 +126,7 @@ void FEB_ADBMS_Update_Error_Type(uint8_t error);
 // 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
+#define ADBMS_FAULT_FLAG_SENSOR (1u << 2) // temperature telemetry lost (too few valid sensor reads)
 
 /** @brief Latched cell V/T fault flags (ADBMS_FAULT_FLAG_*). */
 uint32_t FEB_ADBMS_Get_Fault_Flags(void);

BMS/Core/User/Inc/FEB_Const.h

@@ -7,7 +7,7 @@
 #define FEB_NUM_ICPBANK 1
 
 // Number of banks in the system
-#define FEB_NBANKS 1
+#define FEB_NBANKS 10
 
 // Total number of ICs in the daisy chain
 #define FEB_NUM_IC (FEB_NUM_ICPBANK * FEB_NBANKS)
@@ -80,20 +80,52 @@
 // Cell temperature limits (in deci-Celsius, 1 dC = 0.1°C)
 #define FEB_CELL_MAX_TEMP_DC 600             // 60.0°C maximum cell temperature
 #define FEB_CELL_MIN_TEMP_DC -200            // -20.0°C minimum cell temperature
-#define FEB_CONFIG_CELL_SOFT_MAX_TEMP_dC 550 // 55.0°C soft limit for charging
+#define FEB_CONFIG_CELL_SOFT_MAX_TEMP_dC 400 // 40.0°C soft limit (stop charging; also gates balancing)
 
 // Error thresholds (consecutive violations before triggering fault)
 #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
+// Per-sensor consecutive out-of-range scans before latching a temp fault. This
+// is checked PER SENSOR against the uint8_t temp_violations[] counter, so it
+// must stay small: ANY single cell over/under limit must fault — we never wait
+// for a fraction of the pack to overheat. (A pack-wide 0.8*N aggregate here was
+// both wrong semantically and unreachable: 0.8*42*10=336 > uint8_t max.)
+#define FEB_TEMP_ERROR_THRESH 3 // Trigger fault after 3 consecutive temp violations
+
+// Temperature scan cadence and FSAE fault-timing budget.
+// The temp scan (FEB_ADBMS_Temperature_Process) is gated to this period in
+// FEB_Task_ADBMS.c. FSAE requires the AMS to open the shutdown circuit within
+// ~1 s of an out-of-range cell temperature (and within 1 s of a temp sense-wire
+// disconnect). The per-sensor debounce above latches in at most
+// (FEB_TEMP_ERROR_THRESH + 1) scans; the static assertion proves that stays
+// under budget, so it cannot silently regress if the period or threshold changes.
+#define FEB_TEMP_SCAN_PERIOD_MS 100  // temperature scan cadence (10 Hz)
+#define FEB_TEMP_FAULT_BUDGET_MS 900 // margin under the 1 s FSAE temperature window
+_Static_assert((FEB_TEMP_ERROR_THRESH + 1) * FEB_TEMP_SCAN_PERIOD_MS <= FEB_TEMP_FAULT_BUDGET_MS,
+               "Over/under-temp fault must latch within the FSAE temperature window");
+
+// Temperature-telemetry-loss fail-safe (FSAE: a disconnected temperature sense
+// wire must open the shutdown circuit within 1 s). If fewer than
+// FEB_TEMP_MIN_VALID_FRACTION of the POPULATED sensors read in-range for longer
+// than FEB_TEMP_TELEMETRY_TIMEOUT_MS, validate_temps() latches a sensor fault.
+// NOTE: *_POPULATED_PER_BANK is a HARDWARE FACT — set it to the number of
+// thermistors actually wired per bank. The array holds FEB_NUM_TEMP_SENSORS=42,
+// but index 39 (MUX6[4]) is unconnected by design, so 41 are expected. A wrong
+// value here either false-trips or under-protects.
+#define FEB_TEMP_SENSORS_POPULATED_PER_BANK 41 // VERIFY against the harness
+#define FEB_TEMP_MIN_VALID_FRACTION 0.50f      // TUNE: fault below this fraction valid
+#define FEB_TEMP_TELEMETRY_TIMEOUT_MS 800      // sustained low reads this long -> fault (< 1 s)
 
 // ********************************** 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)
+#define FEB_CONFIG_CELL_HARD_MAX_TEMP_dC 450     // 45.0C hard charge over-temp -> FAULT_CHARGING
+// Charge thermal limits are stricter than the 60.0C discharge ceiling
+// (FEB_CELL_MAX_TEMP_DC): Li-ion charge accept tops out ~45C. Soft limit
+// (FEB_CONFIG_CELL_SOFT_MAX_TEMP_dC, 40.0C above) stops charge with margin
+// before this hard fault.
 
 // Pack hard-max voltage in VOLTS (compared against pack/IVT voltage in volts).
 #define FEB_CONFIG_PACK_HARD_MAX_VOLTAGE_V                                                                             \
@@ -189,7 +221,7 @@
 // readings and diagnostics remain visible; only enforcement is suppressed.
 // Logs warnings at boot while enabled. NEVER enable with a real pack.
 #ifndef FEB_BMS_DISABLE_ADBMS_CHECKS
-#define FEB_BMS_DISABLE_ADBMS_CHECKS 1
+#define FEB_BMS_DISABLE_ADBMS_CHECKS 0
 #endif
 
 #if FEB_BMS_DISABLE_ADBMS_CHECKS

BMS/Core/User/Src/FEB_ADBMS6830B.c

@@ -49,6 +49,13 @@ uint8_t ERROR_TYPE = 0; // HEXDIGIT 1 voltage faults; HEXDIGIT 2 temp faults; HE
 static volatile uint32_t adbms_fault_flags = 0;
 static volatile uint32_t adbms_last_update_tick = 0;
 
+#if !FEB_BMS_DISABLE_TEMP_CHECKS
+/* Arm tick for the temperature-telemetry-loss fault (0 = disarmed). Set when the
+ * valid-read fraction first drops below FEB_TEMP_MIN_VALID_FRACTION; a sensor
+ * fault latches once it stays low for FEB_TEMP_TELEMETRY_TIMEOUT_MS. */
+static uint32_t temp_telemetry_loss_tick = 0;
+#endif
+
 /* 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
@@ -518,17 +525,45 @@ static void validate_temps()
     DEBUG_TEMP_PRINT("Bank %d: tempRead=%d", bank, FEB_ACC.banks[bank].tempRead);
   }
 
-  float read_ratio = totalReads / (float)(FEB_NUM_TEMP_SENSORS * FEB_NBANKS);
-  DEBUG_TEMP_PRINT("Total reads: %d/%d (%.1f%%)", totalReads, FEB_NUM_TEMP_SENSORS * FEB_NBANKS, read_ratio * 100.0f);
-  if (read_ratio < 0.2)
+  /* Valid-read fraction measured against the POPULATED sensor count (NOT the
+   * 42-wide array: index 39 / MUX6[4] is unconnected by design), so a healthy
+   * pack reads ~100%, not ~98%, and the fault threshold below is meaningful. */
+  const int expected_reads = FEB_TEMP_SENSORS_POPULATED_PER_BANK * FEB_NBANKS;
+  float read_ratio = totalReads / (float)expected_reads;
+  DEBUG_TEMP_PRINT("Total reads: %d/%d (%.1f%%)", totalReads, expected_reads, read_ratio * 100.0f);
+  bool telemetry_low = (read_ratio < FEB_TEMP_MIN_VALID_FRACTION);
+  if (telemetry_low)
   {
     DEBUG_TEMP_PRINT("WARNING: Low temperature read ratio (%.1f%%)", read_ratio * 100.0f);
     FEB_ADBMS_Update_Error_Type(ERROR_TYPE_LOW_TEMP_READS);
-    /* 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(). */
   }
+
+#if !FEB_BMS_DISABLE_TEMP_CHECKS
+  /* FSAE fail-safe: the AMS must open the shutdown circuit within ~1 s if it
+   * loses the temperature data it depends on (e.g. a temperature sense wire
+   * disconnects). Latch a sensor fault when too few populated sensors read valid
+   * for longer than FEB_TEMP_TELEMETRY_TIMEOUT_MS. Time-confirmed so a single
+   * flaky scan does not trip it; evaluate_faults() routes ADBMS_FAULT_FLAG_SENSOR
+   * to FAULT_BMS/FAULT_CHARGING like the over-temp fault. */
+  if (telemetry_low)
+  {
+    uint32_t now = HAL_GetTick();
+    if (temp_telemetry_loss_tick == 0)
+    {
+      temp_telemetry_loss_tick = (now == 0) ? 1u : now; /* 0 is the disarmed sentinel */
+    }
+    else if ((now - temp_telemetry_loss_tick) >= FEB_TEMP_TELEMETRY_TIMEOUT_MS)
+    {
+      printf("[ADBMS] FAULT: temperature telemetry lost - %d/%d sensors valid (%.0f%%)\r\n", totalReads, expected_reads,
+             (double)(read_ratio * 100.0f));
+      adbms_fault_flags |= ADBMS_FAULT_FLAG_SENSOR;
+    }
+  }
+  else
+  {
+    temp_telemetry_loss_tick = 0; /* healthy: disarm the loss timer */
+  }
+#endif
   DEBUG_TEMP_PRINT("Temperature validation complete");
 }
 

BMS/Core/User/Src/FEB_SM.c

@@ -313,11 +313,13 @@ static void evaluate_faults(void)
                         s == BMS_STATE_BALANCE);
   BMS_State_t grp_fault = charger_group ? BMS_STATE_FAULT_CHARGING : BMS_STATE_FAULT_BMS;
 
-  /* (a) Cell voltage / temperature violations latched by the ADBMS task. */
+  /* (a) Cell voltage / temperature violations and temperature-telemetry loss
+   * latched by the ADBMS task (SENSOR = too few valid temp reads, a required
+   * FSAE fail-safe — treated as a hard fault, same as an over-temp cell). */
   uint32_t af = FEB_ADBMS_Get_Fault_Flags();
-  if (af & (ADBMS_FAULT_FLAG_VOLTAGE | ADBMS_FAULT_FLAG_TEMP))
+  if (af & (ADBMS_FAULT_FLAG_VOLTAGE | ADBMS_FAULT_FLAG_TEMP | ADBMS_FAULT_FLAG_SENSOR))
   {
-    LOG_E(TAG_SM, "Cell V/T violation (flags=0x%02lX)", (unsigned long)af);
+    LOG_E(TAG_SM, "Cell V/T/sensor violation (flags=0x%02lX)", (unsigned long)af);
     fault_begin(grp_fault);
     return;
   }

BMS/Core/User/Src/FEB_Task_ADBMS.c

@@ -75,7 +75,11 @@ void StartADBMSTask(void *argument)
 
   /* === Main Task Loop === */
   uint32_t voltage_tick = osKernelGetTickCount();
-  uint32_t temp_tick = osKernelGetTickCount();
+  /* Phase-offset the temperature scan by half a period so it doesn't fire on the
+   * same tick as the (now equal-rate) voltage scan and serialize their isoSPI
+   * work under the shared mutex. Unsigned tick wrap is intentional and matches
+   * the rollover-safe `now - tick` comparison idiom used below. */
+  uint32_t temp_tick = osKernelGetTickCount() - pdMS_TO_TICKS(FEB_TEMP_SCAN_PERIOD_MS / 2);
   uint32_t balance_tick = osKernelGetTickCount();
 
   for (;;)

BMS/VERSION

@@ -1 +1 @@
-1.7.18
+1.7.19

VERSION

@@ -1 +1 @@
-1.7.34
+1.7.35