# 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.