Helper: Add battery percentage from millivolts function using OCV battery chemistry mapping

Signed-off-by: Luis Garcia <git@luigi311.com>

Author: luigi311

src/helpers/Battery.cpp

@@ -0,0 +1,65 @@
+#include <stddef.h>
+#include "Battery.h"
+
+// Build the OCV table from the configured macro.
+// 11 entries: 100%, 90%, ..., 0%.
+static const uint16_t kOcvTable[] = { OCV_ARRAY };
+static const size_t kOcvTableSize = sizeof(kOcvTable) / sizeof(kOcvTable[0]);
+
+#if defined(__cplusplus) && __cplusplus >= 201103L
+static_assert(kOcvTableSize == 11,
+              "OCV_ARRAY must contain exactly 11 entries: 100%, 90%, ..., 0%.");
+#endif
+
+int batteryPercentFromMilliVolts(uint16_t batteryMilliVolts) {
+  const uint8_t stepPct = 10;         // distance between table entries (100 → 90 → ... → 0)
+  const size_t n = kOcvTableSize;     // should be 11
+
+  if (n != 11 || batteryMilliVolts <= 0) {
+    // Error: invalid OCV_ARRAY table size or voltage
+    return -1;
+  }
+
+  // Above or equal to "full" voltage → clamp to 100%
+  if (batteryMilliVolts >= kOcvTable[0]) {
+    return 100;
+  }
+
+  // Below or equal to "empty" voltage → clamp to 0%
+  if (batteryMilliVolts <= kOcvTable[n - 1]) {
+    return 0;
+  }
+
+  // Find the segment [i, i+1] where:
+  //   vHigh >= batteryMilliVolts >= vLow
+  // and map that to [pctHigh, pctLow] = [100 - 10*i, 100 - 10*(i+1)]
+  for (size_t i = 0; i < n - 1; ++i) {
+    uint16_t vHigh = kOcvTable[i];       // higher voltage, higher %
+    uint16_t vLow  = kOcvTable[i + 1];   // lower voltage, lower %
+
+    if (batteryMilliVolts <= vHigh && batteryMilliVolts >= vLow) {
+      uint8_t pctHigh = 100 - i * stepPct;
+      uint8_t pctLow  = 100 - (i + 1) * stepPct;
+
+      uint16_t dv = vHigh - vLow;
+      if (dv == 0) {
+        return pctLow;
+      }
+
+      // How far are we from the low voltage towards the high, as a fraction of the segment?
+      uint16_t pv = batteryMilliVolts - vLow;  // in [0, dv]
+
+      // Interpolate percentage within this 10% band.
+      uint8_t deltaPct = (uint32_t)pv * stepPct / dv;
+      int pct = pctLow + deltaPct;
+
+      // Clamp to [0, 100]
+      if (pct < 0)   pct = 0;
+      if (pct > 100) pct = 100;
+      return pct;
+    }
+  }
+
+  // Should be unreachable if the table is monotonic and cases above are handled.
+  return -1;
+}

src/helpers/Battery.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include <stdint.h>
+#include <stddef.h>
+
+// -----------------------------------------------------------------------------
+// Open Circuit Voltage (OCV) map configuration
+//
+// OCV_ARRAY must expand to 11 integer millivolt values, corresponding to:
+//
+//   100%, 90%, 80%, 70%, 60%, 50%, 40%, 30%, 20%, 10%, 0%
+//
+// in *descending* voltage order.
+//
+// -----------------------------------------------------------------------------
+
+#ifndef OCV_ARRAY
+  #ifdef CELL_TYPE_LIFEPO4
+    #define OCV_ARRAY 3400, 3350, 3320, 3290, 3270, 3260, 3250, 3230, 3200, 3120, 3000
+  #elif defined(CELL_TYPE_LEADACID)
+    #define OCV_ARRAY 2120, 2090, 2070, 2050, 2030, 2010, 1990, 1980, 1970, 1960, 1950
+  #elif defined(CELL_TYPE_ALKALINE)
+    #define OCV_ARRAY 1580, 1400, 1350, 1300, 1280, 1250, 1230, 1190, 1150, 1100, 1000
+  #elif defined(CELL_TYPE_NIMH)
+    #define OCV_ARRAY 1400, 1300, 1280, 1270, 1260, 1250, 1240, 1230, 1210, 1150, 1000
+  #elif defined(CELL_TYPE_LTO)
+    #define OCV_ARRAY 2700, 2560, 2540, 2520, 2500, 2460, 2420, 2400, 2380, 2320, 1500
+  #else 
+    // Default Li-Ion / Li-Po
+    #define OCV_ARRAY 4190, 4050, 3990, 3890, 3800, 3720, 3630, 3530, 3420, 3300, 3100
+  #endif
+#endif
+
+
+/**
+ * Convert a battery voltage (in millivolts) to approximate state-of-charge (%),
+ * using the OCV curve defined by OCV_ARRAY.
+ *
+ * Assumes:
+ *  - OCV_ARRAY has 11 entries, in descending order.
+ *  - These correspond to 100, 90, 80, ..., 0 percent.
+ *  - The input batteryMilliVolts is in the same scale as the OCV values.
+ *
+ * Returns an integer percentage in [0, 100] or -1 on error.
+ */
+int batteryPercentFromMilliVolts(uint16_t batteryMilliVolts);