68 lines
3.0 KiB
Markdown
68 lines
3.0 KiB
Markdown
# 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.
|