BMS: surface per-cell balancing state in cell printouts and CSV

Add an "is balancing" indicator to the cell/temperature readouts:
- New accessors in FEB_ADBMS6830B: per-cell discharge getter, active-cell
  count, pack voltage delta (mV), and a balance-complete flag (valid
  readings AND delta < slippage threshold).
- BMS|cells / cell-stats: mark balancing cells with *BAL plus a footer
  summary; BMS|status: show cell delta + balance-done.
- CSV: append <balancing> to voltage rows; append balance_done + delta_mV
  to the status row; schema comments updated.
- Fix FEB_Stop_Balance leaving stale per-cell discharging flags set
  (cleared lock-free; reachable from the 1ms SM task).

Author: ZacharyBer

BMS/Core/User/Inc/FEB_ADBMS6830B.h

@@ -99,6 +99,7 @@ float FEB_ADBMS_GET_ACC_Total_Voltage(void);
 float FEB_ADBMS_GET_Cell_Voltage(uint8_t bank, uint16_t cell);
 float FEB_ADBMS_GET_Cell_Voltage_S(uint8_t bank, uint16_t cell);
 uint8_t FEB_ADBMS_GET_Cell_Violations(uint8_t bank, uint16_t cell);
+uint8_t FEB_ADBMS_GET_Cell_Discharging(uint8_t bank, uint16_t cell);
 
 // ********************************** Temperature ********************************
 
@@ -115,6 +116,9 @@ void FEB_Stop_Balance(void);
 void FEB_Cell_Balance_Start(void);
 void FEB_Cell_Balance_Process(void);
 bool FEB_Cell_Balancing_Status(void);
+uint16_t FEB_ADBMS_GET_Balancing_Cell_Count(void); // # of cells with discharge active
+float FEB_ADBMS_GET_Cell_Voltage_Delta_mV(void);   // pack max-min cell delta in mV, -1 if no valid data
+bool FEB_Cell_Balance_Complete(void);              // true when valid readings AND delta < threshold
 
 // ********************************** Error Type *********************************
 

BMS/Core/User/Src/FEB_ADBMS6830B.c

@@ -823,6 +823,19 @@ uint8_t FEB_ADBMS_GET_Cell_Violations(uint8_t bank, uint16_t cell)
   return violations;
 }
 
+uint8_t FEB_ADBMS_GET_Cell_Discharging(uint8_t bank, uint16_t cell)
+{
+  if (bank >= FEB_NBANKS || cell >= FEB_NUM_CELLS_PER_BANK)
+  {
+    return 0;
+  }
+
+  osMutexAcquire(ADBMSMutexHandle, osWaitForever);
+  uint8_t discharging = FEB_ACC.banks[bank].cells[cell].discharging;
+  osMutexRelease(ADBMSMutexHandle);
+  return discharging;
+}
+
 bool FEB_ADBMS_Precharge_Complete(void)
 {
   // float voltage_V = (float)FEB_IVT_V1_Voltage() * 0.001f;
@@ -1045,6 +1058,63 @@ bool FEB_Cell_Balancing_Status(void)
   return false;
 }
 
+uint16_t FEB_ADBMS_GET_Balancing_Cell_Count(void)
+{
+  uint16_t count = 0;
+  osMutexAcquire(ADBMSMutexHandle, osWaitForever);
+  for (size_t i = 0; i < FEB_NBANKS; ++i)
+  {
+    for (size_t j = 0; j < FEB_NUM_CELLS_PER_BANK; ++j)
+    {
+      if (FEB_ACC.banks[i].cells[j].discharging)
+      {
+        count++;
+      }
+    }
+  }
+  osMutexRelease(ADBMSMutexHandle);
+  return count;
+}
+
+// Pack-wide max-min cell-voltage spread in mV (single source of truth for the
+// balancing delta). Returns -1.0f when no valid cell readings are available.
+float FEB_ADBMS_GET_Cell_Voltage_Delta_mV(void)
+{
+  float min_v = FLT_MAX;
+  float max_v = -FLT_MAX;
+
+  for (size_t i = 0; i < FEB_NBANKS; ++i)
+  {
+    for (size_t j = 0; j < FEB_NUM_CELLS_PER_BANK; ++j)
+    {
+      const float voltage = FEB_ADBMS_GET_Cell_Voltage(i, j) * 1000.0f;
+      if (voltage < 0)
+      {
+        continue; // getter returns -1000mV (-1.0V * 1000) for invalid/out-of-range
+      }
+      if (voltage < min_v)
+        min_v = voltage;
+      if (voltage > max_v)
+        max_v = voltage;
+    }
+  }
+
+  if (max_v < 0 || min_v > 1e8f)
+  {
+    return -1.0f; // no valid readings
+  }
+  return max_v - min_v;
+}
+
+// "Done balancing": valid readings AND pack converged below the slippage
+// threshold. Distinct from !FEB_Cell_Balancing_Status(), which also returns
+// false when balancing is blocked (too hot / no telemetry).
+bool FEB_Cell_Balance_Complete(void)
+{
+  const float delta_mV = FEB_ADBMS_GET_Cell_Voltage_Delta_mV();
+  return (delta_mV >= 0.0f && delta_mV < FEB_MIN_SLIPPAGE_V * 1000.0f);
+}
+
 void FEB_Stop_Balance()
 {
   LOG_D(TAG_BALANCE, "Stopping all cell discharge");
@@ -1053,6 +1123,18 @@ void FEB_Stop_Balance()
   balancing_mask = 0x0000;
   balancing_cycle = 0;
 
+  // Clear the per-cell discharge flags so the console/CSV readout reflects the
+  // hardware (DCC=0 below) once balancing stops. Lock-free: this is reachable
+  // from the 1ms SM task (fault entry / balance transitions), which must never
+  // block on ADBMSMutexHandle; single-byte stores are atomic on Cortex-M4.
+  for (size_t i = 0; i < FEB_NBANKS; ++i)
+  {
+    for (size_t j = 0; j < FEB_NUM_CELLS_PER_BANK; ++j)
+    {
+      FEB_ACC.banks[i].cells[j].discharging = 0;
+    }
+  }
+
   for (uint8_t ic = 0; ic < FEB_NUM_IC; ic++)
   {
     ADBMS6830B_set_cfgr(ic, IC_Config, refon, cth_bits, gpio_bits, 0, dcto_bits, uv, ov);

BMS/Core/User/Src/FEB_Commands.c

@@ -87,6 +87,8 @@ static void subcmd_status(int argc, char *argv[])
   FEB_Console_Printf("Min Temp: %.1fC  Max Temp: %.1fC  Avg: %.1fC\r\n", FEB_ADBMS_GET_ACC_MIN_Temp(),
                      FEB_ADBMS_GET_ACC_MAX_Temp(), FEB_ADBMS_GET_ACC_AVG_Temp());
   FEB_Console_Printf("Balancing: %s\r\n", FEB_Cell_Balancing_Status() ? "ON" : "OFF");
+  FEB_Console_Printf("Cell delta: %.0fmV  Balance done: %s\r\n", FEB_ADBMS_GET_Cell_Voltage_Delta_mV(),
+                     FEB_Cell_Balance_Complete() ? "YES" : "NO");
   FEB_Console_Printf("Error Type: 0x%02X\r\n", FEB_ADBMS_Get_Error_Type());
 }
 
@@ -106,9 +108,13 @@ static void subcmd_cells(int argc, char *argv[])
     {
       float v_c = FEB_ADBMS_GET_Cell_Voltage(bank, cell);
       float v_s = FEB_ADBMS_GET_Cell_Voltage_S(bank, cell);
-      FEB_Console_Printf("  C%02d: %.3f/%.3f\r\n", cell + 1, v_c, v_s);
+      uint8_t bal = FEB_ADBMS_GET_Cell_Discharging(bank, cell);
+      FEB_Console_Printf("  C%02d: %.3f/%.3f%s\r\n", cell + 1, v_c, v_s, bal ? "  *BAL" : "");
     }
   }
+  FEB_Console_Printf("Balancing: %u cells active | delta %.0fmV | done: %s\r\n",
+                     (unsigned int)FEB_ADBMS_GET_Balancing_Cell_Count(), FEB_ADBMS_GET_Cell_Voltage_Delta_mV(),
+                     FEB_Cell_Balance_Complete() ? "YES" : "NO");
 }
 
 /* ============================================================================
@@ -802,9 +808,10 @@ static void cmd_bms(int argc, char *argv[]);
  * CSV-Mode Handlers (one per spec command, registered at top level)
  * ============================================================================ */
 
-/* Mandatory per spec. Emits voltage,<module>,<cell>,<primary>,<secondary>
+/* Mandatory per spec. Emits voltage,<module>,<cell>,<primary>,<secondary>,<balancing>
  * for every cell, then temp,<module>,<sensor>,<temp> for every sensor.
- * "module" is the 1-indexed bank number. */
+ * "module" is the 1-indexed bank number; "balancing" is 1 if the cell's discharge
+ * FET is active this balance cycle, else 0. */
 static void cmd_cell_stats_csv(int argc, char *argv[])
 {
   (void)argc;
@@ -816,7 +823,8 @@ static void cmd_cell_stats_csv(int argc, char *argv[])
     {
       float v_c = FEB_ADBMS_GET_Cell_Voltage(bank, cell);
       float v_s = FEB_ADBMS_GET_Cell_Voltage_S(bank, cell);
-      FEB_Console_CsvEmit("voltage", "%d,%d,%.3f,%.3f", bank + 1, cell + 1, v_c, v_s);
+      uint8_t bal = FEB_ADBMS_GET_Cell_Discharging(bank, cell);
+      FEB_Console_CsvEmit("voltage", "%d,%d,%.3f,%.3f,%d", bank + 1, cell + 1, v_c, v_s, bal);
     }
   }
   for (int bank = 0; bank < FEB_NBANKS; bank++)
@@ -858,13 +866,16 @@ static void cmd_status_csv(int argc, char *argv[])
     }
   }
 
-  /* Body fields: state,pack_v,min_c,max_c,min_s,max_s,min_t,max_t,avg_t,balancing,err_type */
-  FEB_Console_CsvEmit("status", "%s,%.2f,%.3f,%.3f,%.3f,%.3f,%.1f,%.1f,%.1f,%d,0x%02X",
+  /* Body fields: state,pack_v,min_c,max_c,min_s,max_s,min_t,max_t,avg_t,balancing,err_type,balance_done,delta_mV */
+  FEB_Console_CsvEmit("status", "%s,%.2f,%.3f,%.3f,%.3f,%.3f,%.1f,%.1f,%.1f,%d,0x%02X,%d,%.0f",
                       FEB_CAN_State_GetStateName(FEB_SM_Get_Current_State()), FEB_ADBMS_GET_ACC_Total_Voltage(), min_c,
                       max_c, min_s, max_s, FEB_ADBMS_GET_ACC_MIN_Temp(), FEB_ADBMS_GET_ACC_MAX_Temp(),
-                      FEB_ADBMS_GET_ACC_AVG_Temp(), FEB_Cell_Balancing_Status() ? 1 : 0, FEB_ADBMS_Get_Error_Type());
+                      FEB_ADBMS_GET_ACC_AVG_Temp(), FEB_Cell_Balancing_Status() ? 1 : 0, FEB_ADBMS_Get_Error_Type(),
+                      FEB_Cell_Balance_Complete() ? 1 : 0, FEB_ADBMS_GET_Cell_Voltage_Delta_mV());
 }
 
+/* Emits voltage,<module>,<cell>,<primary>,<secondary>,<balancing> per cell.
+ * "balancing" is 1 if the cell's discharge FET is active this cycle, else 0. */
 static void cmd_cells_csv(int argc, char *argv[])
 {
   (void)argc;
@@ -875,7 +886,8 @@ static void cmd_cells_csv(int argc, char *argv[])
     {
       float v_c = FEB_ADBMS_GET_Cell_Voltage(bank, cell);
       float v_s = FEB_ADBMS_GET_Cell_Voltage_S(bank, cell);
-      FEB_Console_CsvEmit("voltage", "%d,%d,%.3f,%.3f", bank + 1, cell + 1, v_c, v_s);
+      uint8_t bal = FEB_ADBMS_GET_Cell_Discharging(bank, cell);
+      FEB_Console_CsvEmit("voltage", "%d,%d,%.3f,%.3f,%d", bank + 1, cell + 1, v_c, v_s, bal);
     }
   }
 }

BMS/VERSION

@@ -1 +1 @@
-1.8.3
+1.8.4

VERSION

@@ -1 +1 @@
-1.9.7
+1.9.8