feat(power): add battery monitoring and status overlays

2026-08-18 11:53:14 +08:00
parent 609fe978f1
commit 8f8254b397
31 changed files with 1655 additions and 22 deletions
@@ -0,0 +1,43 @@
+# ADR 0005: Battery Management Ownership
+
+## Status
+
+Accepted
+
+## Context
+
+The current board uses GPIO9 to measure a protected 600 mAh single-cell Li-ion
+battery through a 100 kOhm / 100 kOhm divider. GPIO10 receives the active-low
+TP4057 charge indication. Battery state is affected by ADC calibration, audio
+and stepper load transients, SOC estimation, threshold hysteresis, and runtime
+policy, so it cannot have duplicate state in several layers.
+
+## Decision
+
+- `platform` owns ADC1 setup, calibration, trimmed-mean sampling, divider
+  conversion, TP4057 GPIO sampling, and internal audio/stepper load-quality
+  tracking.
+- `domain` owns the single battery status snapshot, voltage filtering, SOC
+  curve interpolation, implausible-jump confirmation, charge/discharge
+  direction constraints, and low/critical hysteresis.
+- `control_plane` owns the periodic monitoring worker and reactions to semantic
+  state transitions.
+- `domain` maps its battery snapshot to semantic LCD visibility, while
+  `platform` owns transparent PNG composition and panel serialization.
+- The first release logs low and critical transitions but intentionally does
+  not stop actuators, enter sleep, or cut power. Typed shutdown preparation
+  remains a reserved, unsupported hook until hardware wake and shutdown policy
+  are decided.
+- `app_composition` keeps using the aggregate control-plane runtime lifecycle;
+  it does not acquire battery samples directly.
+
+## Consequences
+
+- GPIO9 must never be configured as the legacy power-hold output on this board.
+- High-load samples remain available for diagnostics but cannot update SOC or
+  low-battery state. Normal processing resumes after the configured cooldown.
+- GPIO10 cannot distinguish a full battery from an unplugged charger because
+  both produce a high level; the public state therefore reports only charging
+  versus not charging.
+- The voltage-to-SOC curve is an initial approximation and requires bench
+  calibration against measured battery voltage and a controlled discharge run.