86 lines
4.0 KiB
Markdown
86 lines
4.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.
|
|
|
|
## Controlled Critical-Battery Shutdown
|
|
|
|
When controlled shutdown is enabled, an unplugged battery at or below both the
|
|
configured critical percentage and 3450 mV must produce three valid samples.
|
|
An emergency raw voltage at or below 3350 mV requires two samples and is not
|
|
blocked by the high-load suppression window. Either path latches a single
|
|
shutdown sequence.
|
|
|
|
The sequence stops interaction sources, OTA, multimodal transport, active
|
|
playback, and the stepper before synchronously playing
|
|
`shutdown_power_empty.opus`. The prompt is mandatory: a failed or incomplete
|
|
playback is retried and deep sleep is entered only after playback completion.
|
|
The codec/PA, LCD backlight, Wi-Fi, and stepper outputs are then disabled. PA,
|
|
backlight, and stepper GPIOs are held low through deep sleep. A small NVS record
|
|
stores the shutdown reason, voltage, and percentage on a best-effort basis.
|
|
|
|
GPIO10 is configured as the default active-low wake source. The optional
|
|
active-low button wake GPIO defaults to `-1` (disabled). After deep-sleep wake,
|
|
normal boot continues only while charging or when battery voltage is at least
|
|
3550 mV. Otherwise the device immediately returns to deep sleep before audio,
|
|
LCD, Wi-Fi, or server startup.
|
|
|
|
This is a low-power software shutdown, not physical board power removal,
|
|
because the board power-hold GPIO is disabled. The fixed battery divider and
|
|
any board-level always-on loads continue to draw current.
|
|
|
|
## 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.
|