lucky-cat/docs/adr/0005-battery-management-ownership.md

ADR 0005: Battery Management Ownership

Status

Accepted

Context

The current board uses GPIO9 to measure a protected 600 mAh single-cell Li-ion battery through a 100 kOhm / 100 kOhm divider. GPIO10 receives the active-low TP4057 charge indication. Battery state is affected by ADC calibration, audio and stepper load transients, SOC estimation, threshold hysteresis, and runtime policy, so it cannot have duplicate state in several layers.

Decision

• platform owns ADC1 setup, calibration, trimmed-mean sampling, divider conversion, TP4057 GPIO sampling, and internal audio/stepper load-quality tracking.
• domain owns the single battery status snapshot, voltage filtering, SOC curve interpolation, implausible-jump confirmation, charge/discharge direction constraints, and low/critical hysteresis.
• control_plane owns the periodic monitoring worker and reactions to semantic state transitions.
• domain maps its battery snapshot to semantic LCD visibility, while platform owns transparent PNG composition and panel serialization.
• The first release logs low and critical transitions but intentionally does not stop actuators, enter sleep, or cut power. Typed shutdown preparation remains a reserved, unsupported hook until hardware wake and shutdown policy are decided.
• app_composition keeps using the aggregate control-plane runtime lifecycle; it does not acquire battery samples directly.

Consequences

• GPIO9 must never be configured as the legacy power-hold output on this board.
• High-load samples remain available for diagnostics but cannot update SOC or low-battery state. Normal processing resumes after the configured cooldown.
• GPIO10 cannot distinguish a full battery from an unplugged charger because both produce a high level; the public state therefore reports only charging versus not charging.
• The voltage-to-SOC curve is an initial approximation and requires bench calibration against measured battery voltage and a controlled discharge run.