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:

A 2.5 V to 4.5 V plausibility check.
Three-sample confirmation for voltage jumps greater than 300 mV.
An exponential filter with 80% previous and 20% new voltage.
Piecewise-linear interpolation over the Li-ion discharge curve.
A two-percent maximum SOC change per accepted sample.
Charge/discharge direction constraints.
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.

4.0 KiB Raw Blame History