feat(stm32wl): support reading Vbat from internal ADC channel

Add support for reading battery voltage using the STM32WL internal VBAT ADC channel.

**src/Power.cpp**

**Global additions**

- ADC configuration macros and STM32 LL ADC helper includes
- Global variable `Vref` to store the measured ADC reference voltage (in mV), used to scale all subsequent VBAT readings
- `stm32wlLevel` singleton instance

**New class: `Stm32wlBatteryLevel` (extends `HasBatteryLevel`)**

- `getBatteryPercent()`
  Identical implementation to `AnalogBatteryLevel::getBatteryPercent()`, mapping voltage to SoC using the OCV curve.
- `runOnce()`
  Performs a one-time ADC read of the internal reference voltage (VREFINT) to determine the effective ADC reference.
- `getBattVoltage()`
  Reads the STM32WL internal VBAT ADC channel and applies the required ×3 scaling to compensate for the internal 1/3 divider.
- `isBatteryConnect()`
  Always returns true, as VBAT is internally tied to VDD when the battery supplies the MCU.

**Power integration**

- Adds `Power::stm32wlInit()` as a one-time probe and inserts it ahead of `analogInit()` so STM32WL internal VBAT is preferred when available.

**Possible regressions**

- None expected. `stm32wlInit()` is compiled as a stub unless both `ARCH_STM32WL` and `BATTERY_PIN == AVBAT` are defined.

---

**src/power.h**

Selects an appropriate battery chemistry curve for STM32WL internal VBAT usage.

- Adds an LFP OCV curve when `ARCH_STM32WL` and `BATTERY_PIN == AVBAT` are defined
  - STM32WL VBAT/VDD absolute maximum is 4 V, so Li-ion/LiPo (NMC) cells are not suitable for direct VBAT operation.

**Possible regressions**

- None expected. OCV selection only changes when `ARCH_STM32WL` and `BATTERY_PIN == AVBAT` are defined.

---

**variants/stm32/rak3172/variant.h**

Enables STM32WL internal VBAT sensing for the RAK3172 target.

**Possible regressions**

- None expected. The RAK3172 variant previously had no battery voltage reporting.

**Hardware tested**

- Verified on the Russell board (RAK3172-based).

---

**variants/stm32/russell/variant.h**

Enables STM32WL internal VBAT sensing for the Russell target.

**Possible regressions**

- None expected. Battery voltage reporting was not previously implemented.

**Hardware tested**

- Verified on the Russell board.

---

**variants/stm32/stm32.ini**

Reduces flash usage for STM32WL targets close to the size limit.

- Comments out `PIO_FRAMEWORK_ARDUINO_NANOLIB_FLOAT_PRINTF`
- Documents that it is only required when debug logging is enabled

**Possible regressions**

- None expected. All existing STM32WL variants are built with `DEBUG_MUTE`.

Signed-off-by: Andrew Yong <me@ndoo.sg>

Author: ndoo

src/Power.cpp

@@ -35,6 +35,21 @@
 #include "nrfx_power.h"
 #endif
 
+#if defined(ARCH_STM32WL) && BATTERY_PIN == AVBAT
+#include "stm32yyxx_ll_adc.h"
+
+/* Analog read resolution */
+#if defined(LL_ADC_RESOLUTION_12B)
+#define LL_ADC_RESOLUTION LL_ADC_RESOLUTION_12B
+#define BATTERY_SENSE_RESOLUTION_BITS 12
+#elif defined(LL_ADC_DS_DATA_WIDTH_12_BIT)
+#define LL_ADC_RESOLUTION LL_ADC_DS_DATA_WIDTH_12_BIT
+#else
+#error "ADC resolution could not be defined!"
+#endif
+#define ADC_RANGE 4096
+#endif
+
 #if defined(DEBUG_HEAP_MQTT) && !MESHTASTIC_EXCLUDE_MQTT
 #include "mqtt/MQTT.h"
 #include "target_specific.h"
@@ -698,6 +713,8 @@ bool Power::setup()
         found = true;
     } else if (meshSolarInit()) {
         found = true;
+    } else if (stm32wlInit()) {
+        found = true;
     } else if (analogInit()) {
         found = true;
     }
@@ -1602,6 +1619,110 @@ bool Power::meshSolarInit()
 }
 #endif
 
+#if defined(ARCH_STM32WL) && BATTERY_PIN == AVBAT
+
+/**
+ * STM32WL internal VBAT ADC channel
+ */
+
+// 3300mV is a placeholder value in case of future errata e.g. STM32U0
+uint32_t Vref = 3300;
+
+class Stm32wlBatteryLevel : public HasBatteryLevel
+{
+
+  public:
+    /**
+     * Battery state of charge, from 0 to 100 or -1 for unknown
+     * Copied wholesale from AnalogBatteryLevel
+     */
+    virtual int getBatteryPercent() override
+    {
+        float v = getBattVoltage();
+
+        if (v < noBatVolt)
+            return -1; // If voltage is super low assume no battery installed
+
+        float battery_SOC = 0.0;
+        uint16_t voltage = v / NUM_CELLS; // single cell voltage (average)
+        for (int i = 0; i < NUM_OCV_POINTS; i++) {
+            if (OCV[i] <= voltage) {
+                if (i == 0) {
+                    battery_SOC = 100.0; // 100% full
+                } else {
+                    // interpolate between OCV[i] and OCV[i-1]
+                    battery_SOC = (float)100.0 / (NUM_OCV_POINTS - 1.0) *
+                                  (NUM_OCV_POINTS - 1.0 - i + ((float)voltage - OCV[i]) / (OCV[i - 1] - OCV[i]));
+                }
+                break;
+            }
+        }
+#if defined(BATTERY_CHARGING_INV)
+        // bit of trickery to show 99% up until the charge finishes
+        if (!digitalRead(BATTERY_CHARGING_INV) && battery_SOC > 99)
+            battery_SOC = 99;
+#endif
+        return clamp((int)(battery_SOC), 0, 100);
+    }
+
+    /**
+     * Read VREF in mV once, used to scale all subsequent VBAT readings
+     */
+    bool runOnce()
+    {
+#ifdef __LL_ADC_CALC_VREFANALOG_VOLTAGE
+        Vref = __LL_ADC_CALC_VREFANALOG_VOLTAGE(analogRead(AVREF), LL_ADC_RESOLUTION);
+#else
+        Vref = VREFINT * ADC_RANGE / analogRead(AVREF); // ADC sample to mV
+#endif
+        return true;
+    }
+
+    /**
+     * Read VBAT in mV
+     */
+    virtual uint16_t getBattVoltage() override
+    {
+        // VBAT pin is internally connected to a bridge divider by three (DS13105§3.18.3)
+        return 3 * __LL_ADC_CALC_DATA_TO_VOLTAGE(Vref, analogRead(BATTERY_PIN), LL_ADC_RESOLUTION);
+    }
+
+    /**
+     * If BATTERY_PIN = AVBAT, assume a battery is present (otherwise don't define it!)
+     */
+    virtual bool isBatteryConnect() override { return true; }
+
+  private:
+    const uint16_t OCV[NUM_OCV_POINTS] = {OCV_ARRAY};
+    const float chargingVolt = (OCV[0] + 10) * NUM_CELLS;
+    const float noBatVolt = (OCV[NUM_OCV_POINTS - 1] - 500) * NUM_CELLS;
+};
+
+Stm32wlBatteryLevel stm32wlLevel;
+
+/**
+ * Init the STM32WL internal VBAT ADC channel
+ */
+bool Power::stm32wlInit()
+{
+    bool result = stm32wlLevel.runOnce();
+    LOG_DEBUG("Power::stm32wlInit is %s", result ? "ready" : "not ready yet");
+    if (!result)
+        return false;
+    batteryLevel = &stm32wlLevel;
+    return true;
+}
+
+#else
+/**
+ * The STM32WL battery level sensor is unavailable - default to AnalogBatteryLevel
+ */
+bool Power::stm32wlInit()
+{
+    return false;
+}
+#endif
+
 #ifdef HAS_SERIAL_BATTERY_LEVEL
 #include <SoftwareSerial.h>
 

src/power.h

@@ -15,8 +15,13 @@
 
 // Device specific curves go in variant.h
 #ifndef OCV_ARRAY
+#if defined(ARCH_STM32WL) && BATTERY_PIN == AVBAT
+// STM32 VDD/VBAT absolute maximum is 4V so use an LFP curve
+#define OCV_ARRAY 3650, 3400, 3340, 3320, 3300, 3280, 3270, 3260, 3240, 3200, 2500
+#else
 #define OCV_ARRAY 4190, 4050, 3990, 3890, 3800, 3720, 3630, 3530, 3420, 3300, 3100
 #endif
+#endif
 
 /*Note: 12V lead acid is 6 cells, most board accept only 1 cell LiIon/LiPo*/
 #ifndef NUM_CELLS
@@ -109,6 +114,8 @@ class Power : private concurrency::OSThread
     bool lipoChargerInit();
     /// Setup a meshSolar battery sensor
     bool meshSolarInit();
+    /// Setup an STM32WL battery sensor
+    bool stm32wlInit();
     /// Setup a serial battery sensor
     bool serialBatteryInit();
 

variants/stm32/rak3172/variant.h

@@ -16,6 +16,8 @@ Do not expect a working Meshtastic device with this target.
 #define LED_PIN PA0 // Green LED
 #define LED_STATE_ON 1
 
+#define BATTERY_PIN AVBAT
+
 #define RAK3172
 
 #endif

variants/stm32/russell/variant.h

@@ -13,6 +13,8 @@
 // #define EXT_CHRG_DETECT PA5
 // #define EXT_PWR_DETECT PA4
 
+#define BATTERY_PIN AVBAT
+
 // Bosch Sensortec BME280
 #define HAS_SENSOR 1
 

variants/stm32/stm32.ini

@@ -27,7 +27,7 @@ build_flags =
   -DMESHTASTIC_EXCLUDE_TZ=1 ; Exclude TZ to save some flash space.
   -DSERIAL_RX_BUFFER_SIZE=256 ; For GPS - the default of 64 is too small.
   -DHAS_SCREEN=0 ; Always disable screen for STM32, it is not supported.
-  -DPIO_FRAMEWORK_ARDUINO_NANOLIB_FLOAT_PRINTF ; This is REQUIRED for at least traceroute debug prints - without it the length ends up uninitialized.
+  #-DPIO_FRAMEWORK_ARDUINO_NANOLIB_FLOAT_PRINTF ; This is REQUIRED if DEBUG_MUTE is undef - without it the length ends up uninitialized.
   -DDEBUG_MUTE ; You can #undef DEBUG_MUTE in certain source files if you need the logs.
   -fmerge-all-constants
   -ffunction-sections