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,67 @@
+# Battery Management
+
+## Hardware Profile
+
+- Cell: protected single-cell Li-ion, 600 mAh, 3.7 V nominal, 4.2 V full.
+- Supported measurement range: 3.3 V to 4.2 V for SOC estimation.
+- GPIO9: ADC1 battery sense through R17=100 kOhm (VBAT to ADC) and R18=100
+  kOhm (ADC to ground). `VBAT = VADC * 2`.
+- GPIO10: TP4057 active-low charge output with an input pull-up. A high level
+  means either charge complete or charger absent.
+- Legacy power hold: disabled (`CONFIG_TQ_POWER_HOLD_GPIO=-1`).
+
+## Processing Pipeline
+
+Each hardware sample consists of 16 calibrated ADC readings. The platform
+driver sorts them, discards the lowest four and highest four, averages the
+remaining eight, and applies the divider ratio. Domain processing then applies:
+
+1. A 2.5 V to 4.5 V plausibility check.
+2. Three-sample confirmation for voltage jumps greater than 300 mV.
+3. An exponential filter with 80% previous and 20% new voltage.
+4. Piecewise-linear interpolation over the Li-ion discharge curve.
+5. A two-percent maximum SOC change per accepted sample.
+6. Charge/discharge direction constraints.
+7. Three-sample confirmation and hysteresis for low and critical states.
+
+The initial state thresholds are 20%/25% for low entry/recovery and 5%/10% for
+critical entry/recovery.
+
+Board calibration can be adjusted without source changes using
+`CONFIG_TQ_BATTERY_CALIBRATION_GAIN_PPM` and
+`CONFIG_TQ_BATTERY_CALIBRATION_OFFSET_MV` after comparing the log against a
+multimeter.
+
+## High-Load Handling
+
+Audio playback events and synchronous stepper rotations update one
+platform-owned load tracker. While a load is active and for five seconds after
+its terminal event, samples are marked suppressed. The monitor continues to
+poll once per second for diagnostics and charge state, but suppressed voltage
+does not update filtered voltage, SOC, or low-battery state.
+
+Playback generations prevent a stale terminal event from ending suppression
+for a newer playback. Stepper cleanup executes after every synchronous return,
+including errors and timeouts.
+
+## LCD Status Overlays
+
+The direct LCD renderer composites the transparent `charging.png` asset in the
+top-right corner whenever GPIO10 reports active-low charging. It composites
+`lowbat.png` at the bottom center after the domain level enters low or critical
+state. Both overlays may be visible together, and QR-code presentations omit
+them to preserve scan reliability. Overlay state changes do not trigger any
+shutdown, sleep, prompt, or actuator policy.
+
+## Deferred Policy
+
+Critical status currently produces a state-transition log only. The reserved
+shutdown hook returns `ESP_ERR_NOT_SUPPORTED`; it does not stop audio or the
+stepper, enter deep sleep, or release board power. Implement wake sources and
+the product shutdown sequence before enabling any automatic critical action.
+
+## Bench Calibration
+
+After flashing, compare the `cp_battery` voltage log with a multimeter at no
+load near 4.2 V, 3.9 V, 3.6 V, and 3.3 V. Record audio and stepper voltage sag,
+then run a controlled discharge to tune the SOC curve and threshold timing.