app+board+docs: battery SoC% via fuel-gauge-composite + power source (#8)

Add a battery state-of-charge readout (issue #8) using the upstream Zephyr
voltage-only fuel gauge, so no new driver is written. The M5PM1 PMIC exposes
voltages only, so SoC% is derived from VBAT by OCV lookup.

- board DTS: a `vbatt` voltage-divider (UNITY: output-ohms=<1>, full-ohms
  omitted -> raw microvolt passthrough) over m5pm1_adc ch1, feeding a
  `fuel_gauge` zephyr,fuel-gauge-composite (device-chemistry
  lithium-ion-polymer, ocv-capacity-table-0 =
  BATTERY_OCV_CURVE_LITHIUM_ION_POLYMER_DEFAULT,
  charge-full-design-microamp-hours = 250000 for the 250 mAh cell). Add
  m5pm1_adc channel@2 (VIN) for external-power detection. prj.conf turns on
  CONFIG_FUEL_GAUGE.
- app: status.c reads fuel_gauge_get_prop(RELATIVE_STATE_OF_CHARGE) + VIN;
  battery.c holds the pure soc->bar and VIN->power-source helpers
  (tests/drivers/battery native_sim 4/4). PAGE_POWER shows VBAT, SoC% and the
  power source; the alive serial line adds bat/soc/vin.

HW-017 (2026-06-05): serial `bat=4170 soc=100 vin=5142`, and the PAGE_POWER LCD
shows VBAT 4172 mV / SoC 100% / src USB 5V. 100% at 4.17 V is the expected flat
top (above the 4.032 V OCV curve top); the OCV interpolation is unit-tested and
upstream-tested. Approximate, voltage-only (no coulomb counter, no load
compensation); "currently charging" is out of scope (no reliable M5PM1
charge-status register). Evidence: evidence/20260605-hw017-battery-soc.log,
evidence/PXL_20260605_070039537.MP.jpg.

Docs: SDD 4.5.1, TDD HW-017 + the battery test, validation matrix, and the
upstream plan (vbatt/fuel_gauge are repo-local until the M5PM1 #109961 bindings
merge).

Author: thc1006

app/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.20.0)
 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
 project(m5sticks3_validation)
 
-target_sources(app PRIVATE src/main.c src/ui.c src/status.c src/font.c src/gfx.c)
+target_sources(app PRIVATE src/main.c src/ui.c src/status.c src/font.c src/gfx.c src/battery.c)
 target_sources_ifdef(CONFIG_APP_BLE app PRIVATE src/ble.c)
 target_sources_ifdef(CONFIG_APP_AUDIO app PRIVATE src/audio.c src/audio_dsp.c)
 target_sources_ifdef(CONFIG_APP_IR app PRIVATE src/ir.c src/nec.c)

app/prj.conf

@@ -7,6 +7,10 @@ CONFIG_DISPLAY=y
 CONFIG_REGULATOR=y
 CONFIG_MFD=y
 CONFIG_ADC=y
+# Battery state-of-charge (issue #8): voltage-only OCV fuel gauge over VBAT.
+# The voltage-divider sensor + zephyr,fuel-gauge-composite driver auto-enable
+# from their DT nodes; the FUEL_GAUGE subsystem must be turned on here.
+CONFIG_FUEL_GAUGE=y
 CONFIG_MAIN_STACK_SIZE=4096
 
 # LCD power-rail init ordering (critical, see docs HW-003).

app/src/battery.c

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2026 Hsiu-Chi Tsai
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "battery.h"
+
+uint8_t bat_soc_bars(int soc, uint8_t nbars)
+{
+	if (soc <= 0 || nbars == 0U) {
+		return 0U;
+	}
+	if (soc >= 100) {
+		return nbars;
+	}
+
+	/* Rounded: (soc * nbars + 50) / 100. soc is 1..99 here, so the product
+	 * fits an int and the result is in 0..nbars-1.
+	 */
+	return (uint8_t)(((soc * (int)nbars) + 50) / 100);
+}
+
+bool bat_power_present(int vin_mv)
+{
+	return vin_mv >= BAT_VIN_PRESENT_MV;
+}

app/src/battery.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2026 Hsiu-Chi Tsai
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#ifndef M5STICKS3_BATTERY_H
+#define M5STICKS3_BATTERY_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+/*
+ * Pure battery-display helpers (no Zephyr headers, native_sim-testable). The
+ * state-of-charge percent itself comes from the upstream
+ * zephyr,fuel-gauge-composite OCV lookup (issue #8); these only map it to a UI
+ * bar and classify the power source from the VIN reading. Mirrors the nec.c /
+ * audio_dsp.c pure-logic split.
+ */
+
+/*
+ * VIN (mV) at or above this means external 5V / USB power is present. On battery
+ * the M5PM1 VIN reads far below this; with USB attached it reads ~5000 mV. This
+ * is a coarse "ext power present" signal, NOT a charge-state read (the M5PM1 has
+ * no reliable charging-status register).
+ */
+#define BAT_VIN_PRESENT_MV 4000
+
+/*
+ * Map a state-of-charge percent (0..100) to a 0..nbars bar count, rounded and
+ * clamped. A negative soc (read error) or nbars == 0 returns 0; soc >= 100
+ * returns nbars.
+ */
+uint8_t bat_soc_bars(int soc, uint8_t nbars);
+
+/*
+ * True if external power (USB / 5V) is present, from the VIN reading in mV. A
+ * negative vin_mv (read error / channel unavailable) returns false.
+ */
+bool bat_power_present(int vin_mv);
+
+#endif /* M5STICKS3_BATTERY_H */

app/src/main.c

@@ -222,10 +222,10 @@ int main(void)
 		int k1 = device_is_ready(g0) ? gpio_pin_get_raw(g0, KEY1_PIN) : -1;
 		int k2 = device_is_ready(g0) ? gpio_pin_get_raw(g0, KEY2_PIN) : -1;
 
-		printk("alive uptime_ms=%lld page=%d KEY1=%d KEY2=%d imu=%d "
-		       "accel=[%d.%06d %d.%06d %d.%06d]\n",
-		       st.uptime_ms, page, k1, k2, st.imu_ok,
-		       st.accel[0].val1, abs(st.accel[0].val2),
+		printk("alive uptime_ms=%lld page=%d KEY1=%d KEY2=%d bat=%d soc=%d "
+		       "vin=%d imu=%d accel=[%d.%06d %d.%06d %d.%06d]\n",
+		       st.uptime_ms, page, k1, k2, st.bat_mv, st.soc_pct, st.vin_mv,
+		       st.imu_ok, st.accel[0].val1, abs(st.accel[0].val2),
 		       st.accel[1].val1, abs(st.accel[1].val2),
 		       st.accel[2].val1, abs(st.accel[2].val2));
 

app/src/status.c

@@ -4,6 +4,7 @@
 #include <zephyr/kernel.h>
 #include <zephyr/device.h>
 #include <zephyr/drivers/adc.h>
+#include <zephyr/drivers/fuel_gauge.h>
 
 #if DT_NODE_HAS_STATUS(DT_ALIAS(imu0), okay)
 static const struct device *const imu = DEVICE_DT_GET(DT_ALIAS(imu0));
@@ -18,6 +19,7 @@ static const struct device *const imu;
  * conversion is needed for VBAT.
  */
 #define VBAT_CHANNEL 1U
+#define VIN_CHANNEL  2U
 
 #if DT_NODE_HAS_STATUS(DT_NODELABEL(m5pm1_adc), okay)
 #define HAVE_VBAT 1
@@ -29,10 +31,29 @@ static const struct adc_channel_cfg vbat_ch_cfg = {
 	.acquisition_time = ADC_ACQ_TIME_DEFAULT,
 	.channel_id = VBAT_CHANNEL,
 };
+
+/* VIN (channel 2) detects external 5V/USB power present (issue #8). */
+static const struct adc_channel_cfg vin_ch_cfg = {
+	.gain = ADC_GAIN_1,
+	.reference = ADC_REF_INTERNAL,
+	.acquisition_time = ADC_ACQ_TIME_DEFAULT,
+	.channel_id = VIN_CHANNEL,
+};
 #else
 #define HAVE_VBAT 0
 #endif
 
+/*
+ * Battery state-of-charge via the upstream zephyr,fuel-gauge-composite over VBAT
+ * (issue #8): voltage-only OCV lookup, approximate, no coulomb counter.
+ */
+#if DT_NODE_HAS_STATUS(DT_NODELABEL(fuel_gauge), okay)
+#define HAVE_FUEL_GAUGE 1
+static const struct device *const fuel_gauge = DEVICE_DT_GET(DT_NODELABEL(fuel_gauge));
+#else
+#define HAVE_FUEL_GAUGE 0
+#endif
+
 void status_init(void)
 {
 	if (imu != NULL && device_is_ready(imu)) {
@@ -51,6 +72,7 @@ void status_init(void)
 #if HAVE_VBAT
 	if (device_is_ready(adc)) {
 		(void)adc_channel_setup(adc, &vbat_ch_cfg);
+		(void)adc_channel_setup(adc, &vin_ch_cfg);
 	}
 #endif
 }
@@ -81,10 +103,58 @@ static int read_vbat_mv(void)
 #endif
 }
 
+static int read_vin_mv(void)
+{
+#if HAVE_VBAT
+	uint16_t sample = 0;
+	struct adc_sequence seq = {
+		.channels = BIT(VIN_CHANNEL),
+		.buffer = &sample,
+		.buffer_size = sizeof(sample),
+		.resolution = 12,
+	};
+
+	if (!device_is_ready(adc)) {
+		return -1;
+	}
+
+	if (adc_read(adc, &seq) != 0) {
+		return -1;
+	}
+
+	/* M5PM1 VIN register is already in millivolts. */
+	return (int)sample;
+#else
+	return -1;
+#endif
+}
+
+static int read_soc_pct(void)
+{
+#if HAVE_FUEL_GAUGE
+	union fuel_gauge_prop_val val;
+
+	if (!device_is_ready(fuel_gauge)) {
+		return -1;
+	}
+
+	if (fuel_gauge_get_prop(fuel_gauge, FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE,
+				&val) != 0) {
+		return -1;
+	}
+
+	return (int)val.relative_state_of_charge;
+#else
+	return -1;
+#endif
+}
+
 void status_sample(struct app_status *s)
 {
 	s->uptime_ms = k_uptime_get();
 	s->bat_mv = read_vbat_mv();
+	s->vin_mv = read_vin_mv();
+	s->soc_pct = read_soc_pct();
 	s->imu_ok = false;
 	for (int i = 0; i < 3; i++) {
 		s->accel[i].val1 = 0;

app/src/status.h

@@ -10,7 +10,9 @@
 /* Telemetry gathered once per main-loop iteration. */
 struct app_status {
 	int64_t uptime_ms;
-	int bat_mv;                  /* -1 = not available (until P3) */
+	int bat_mv;                  /* VBAT in mV; -1 = not available */
+	int soc_pct;                 /* battery state-of-charge %; -1 = n/a (issue #8) */
+	int vin_mv;                  /* VIN (5V/USB input) in mV; -1 = n/a */
 	bool imu_ok;
 	struct sensor_value accel[3]; /* x/y/z, m/s^2 */
 };

app/src/ui.c

@@ -1,6 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 #include "ui.h"
 #include "gfx.h"
+#include "battery.h"
 
 #ifdef CONFIG_APP_BLE
 #include "ble.h"
@@ -164,7 +165,22 @@ static void render_power_body(const struct app_status *s)
 		snprintf(line, sizeof(line), "VBAT: n/a    ");
 	}
 	gfx_draw_text(MARGIN_X, body_line_y(0), HOME_FG, HOME_BG, line);
-	gfx_draw_text(MARGIN_X, body_line_y(1), HOME_FG, HOME_BG, "M5PM1 ch1");
+
+	/* State-of-charge from the fuel gauge (issue #8); approximate, voltage-only. */
+	if (s->soc_pct >= 0) {
+		uint8_t bars = bat_soc_bars(s->soc_pct, 4);
+
+		snprintf(line, sizeof(line), "SoC: %d%% [%.*s%.*s]  ", s->soc_pct,
+			 bars, "####", 4 - bars, "----");
+	} else {
+		snprintf(line, sizeof(line), "SoC: n/a     ");
+	}
+	gfx_draw_text(MARGIN_X, body_line_y(1), HOME_FG, HOME_BG, line);
+
+	/* External 5V/USB power vs battery, from the M5PM1 VIN reading. */
+	snprintf(line, sizeof(line), "src: %s   ",
+		 bat_power_present(s->vin_mv) ? "USB 5V" : "battery");
+	gfx_draw_text(MARGIN_X, body_line_y(2), HOME_FG, HOME_BG, line);
 }
 
 #ifdef CONFIG_APP_BLE

boards/m5stack/m5stack_sticks3/m5stack_sticks3_procpu.dts

@@ -12,6 +12,7 @@
 #include <espressif/esp32s3/esp32s3_pico_n8r8.dtsi>
 #include "m5stack_sticks3-pinctrl.dtsi"
 #include <zephyr/dt-bindings/adc/adc.h>
+#include <zephyr/dt-bindings/battery/battery.h>
 #include <zephyr/dt-bindings/input/input-event-codes.h>
 #include <espressif/partitions_0x0_amp.dtsi>
 
@@ -145,6 +146,27 @@
 			rgb-param = [40 02 14];
 		};
 	};
+
+	/*
+	 * Battery state-of-charge (issue #8). The M5PM1 exposes voltages only, so
+	 * SoC% is derived from VBAT with the upstream voltage-only fuel gauge:
+	 * m5pm1_adc ch1 (VBAT, mV) -> vbatt (unity voltage-divider, microvolt
+	 * passthrough) -> fuel_gauge (zephyr,fuel-gauge-composite, LiPo OCV curve).
+	 * See docs/02_SDD.md section 4.5.1.
+	 */
+	vbatt: vbatt {
+		compatible = "voltage-divider";
+		io-channels = <&m5pm1_adc 1>;
+		output-ohms = <1>; /* unity; full-ohms omitted => unscaled passthrough */
+	};
+
+	fuel_gauge: fuel-gauge {
+		compatible = "zephyr,fuel-gauge-composite";
+		source-primary = <&vbatt>;
+		device-chemistry = "lithium-ion-polymer";
+		ocv-capacity-table-0 = <BATTERY_OCV_CURVE_LITHIUM_ION_POLYMER_DEFAULT>;
+		charge-full-design-microamp-hours = <250000>; /* 250 mAh cell */
+	};
 };
 
 &usb_serial {
@@ -221,6 +243,17 @@
 				zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
 				zephyr,resolution = <12>;
 			};
+
+			/* Channel 2 = VIN (5V/USB input, reported in mV). Used to
+			 * detect external power present (issue #8).
+			 */
+			channel@2 {
+				reg = <2>;
+				zephyr,gain = "ADC_GAIN_1";
+				zephyr,reference = "ADC_REF_INTERNAL";
+				zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
+				zephyr,resolution = <12>;
+			};
 		};
 	};
 };

docs/02_SDD.md

@@ -133,6 +133,52 @@ b0), a battery low-voltage cutoff (BATT_LVP 0x08), a power-source readback
 Any "full PMIC" work is therefore charge-enable + power-source/insertion status,
 not a fuel gauge.
 
+#### 4.5.1 Battery state-of-charge (issue #8, voltage-only OCV fuel gauge)
+
+Because the M5PM1 exposes voltages only (no SoC register, above), a battery
+percentage is derived externally with the standard upstream Zephyr
+`zephyr,fuel-gauge-composite` (voltage-only open-circuit-voltage lookup), so no
+new driver is written. The data path is:
+
+```
+m5pm1_adc ch1 (VBAT, mV) -> vbatt (voltage-divider, UNITY) -> fuel_gauge
+   (zephyr,fuel-gauge-composite) -> fuel_gauge_get_prop(RELATIVE_STATE_OF_CHARGE)
+```
+
+- `vbatt` is a `compatible = "voltage-divider"` sensor wrapping
+  `io-channels = <&m5pm1_adc 1>`. The divider is UNITY: `output-ohms = <1>` and
+  `full-ohms` is OMITTED, which is the binding's documented passthrough ("if
+  full-ohms is absent the unscaled voltage is returned"); the sensor reports
+  `SENSOR_CHAN_VOLTAGE` in microvolts. The unit math is exact because the M5PM1
+  ADC reports true millivolts with `ref_internal = 4096 mV` at 12-bit, so
+  `adc_raw_to_microvolts(raw_mv) = raw_mv * 4096/4096 * 1000 = raw_mv * 1000`.
+- `fuel_gauge` is `zephyr,fuel-gauge-composite` with `source-primary = <&vbatt>`,
+  `device-chemistry = "lithium-ion-polymer"`,
+  `ocv-capacity-table-0 = <BATTERY_OCV_CURVE_LITHIUM_ION_POLYMER_DEFAULT>` (the
+  in-tree 11-point microvolt curve from `dt-bindings/battery/battery.h`), and
+  `charge-full-design-microamp-hours = <250000>` (the 250 mAh cell).
+  `fuel-gauge-channels` is left UNSET so the composite queries the generic
+  `SENSOR_CHAN_VOLTAGE` the voltage-divider implements (setting it true would
+  request `SENSOR_CHAN_GAUGE_VOLTAGE`, which the voltage-divider rejects with
+  `-ENOTSUP`). The composite tries the source's gauge SoC channel, gets
+  `-ENOTSUP`, and falls back to `battery_soc_lookup(ocv_table, voltage)/1000`.
+- The app reads the percentage with
+  `fuel_gauge_get_prop(dev, FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE, &val)` ->
+  `val.relative_state_of_charge` (0-100).
+
+Accuracy is bounded and stated honestly: this is voltage-only SoC with no coulomb
+counter, so it is approximate, has no load compensation (a current draw sags VBAT
+and under-reads), and ideally wants a rest period for a true open-circuit
+reading. The default LiPo curve tops at 4.032 V, so a freshly charged cell
+(~4.18 V on this board) reads a flat 100% until it drops below 4.03 V. A
+board-profiled curve is a future refinement.
+
+Power source: "on external power vs battery" is shown from the M5PM1 VIN reading
+(`m5pm1_adc` channel 2): VIN above a threshold means USB/5V is present. The chip
+also has the precise `PWR_SRC 0x04` enum (5VIN/5VINOUT/BAT), used as a follow-up;
+a clean "currently charging" status is not reliably exposed, so charge-state is
+out of scope (not claimed).
+
 ### 4.6 Comprehensive demo application architecture (v0.6)
 
 The v0.6 release evolves `app/` from the single-file validation loop into a