44 lines
2.0 KiB
Markdown
44 lines
2.0 KiB
Markdown
# 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.
|