lucky-cat/docs/battery-management.md

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.