ADR 0020: battery profiling complete — refit derived, deliberately not adopted

[brickbots]

Closes out the battery runtime campaign ADR 0020 has been waiting on since July.

Net effect: documentation only. No SOC_LUT knot changes — the middle commit shipped the refit and the third takes it back out, with the reasoning preserved in the history because the reasoning is the point.

The stale bit

ADR 0020's status said the measured knots were still to come and the shipped LUT was "generic Li-ion folklore, annotated as such in the code." Neither is true: #541 landed a measured curve in July, and the pinned-load confirmation runs it was waiting on have since happened.

What the campaign produced

Six discharges on two rev4 units, identical pinned profile (400 ms / gain 20, brightness 255, sleep off):

Sitting	Unit	Runtime	Load
2026-07-17	e63d1a2e	9h18m	degraded — 0% solving
2026-07-17	777f86f4	8h57m	degraded — 0% solving
2026-07-24	e63d1a2e	9h45m	degraded — 0% solving
2026-07-24	777f86f4	9h10m	degraded — 0% solving
2026-07-25	e63d1a2e	9h55m	pinned — 100%
2026-07-26	777f86f4	10h03m	pinned — 100%

Four runs were spoiled by faults that left the workload looking healthy from outside — IMU pseudo-motion blanking the substituted frame, and logind RemoveIPC=yes deleting the cedar shmem segment at SSH logout (#548). Both left solve attempts churning at full rate with zero matches, which is why the tool's load verdict now requires matches > 0.

Headline: about 10 hours on a full charge under a continuously solving load at full brightness with sleep disabled.

The interesting part: the refit was derived and rejected

Fitting the two pinned runs alone gives knots ~20 mV higher through the 5–25% band. Better fit to the scatter — worse setting for the only thing these knots drive. The warner fires on the first noise dip past a threshold, and near the flat knee one ADC LSB (20 mV) spans about three SoC points, so lifting the low knots moves the crossing a long way in wall-clock time. Replaying both pinned runs through LowBatteryWarner:

Curve	5% fires before shutdown	10%
shipped (kept)	31 min / 38 min	79 / 105 min
pinned-only refit	50 min / 69 min	86 / 105 min

Intent is ~30 min at 5%. The shipped curve's lower knee compensates for BATV quantisation noise and hits it; the refit overshoots ~2×. The percentage is advisory UI output, not a measurement — a curve is only better if the warning lands better.

The ADR now records the refit values, the replay table, the decision, and the rule that follows: judge a candidate curve by replaying telemetry through the warner, never by knot distance alone. The code comment says the same thing at the point of temptation.

Verification

• Re-derived with tools/battery_runtime_analysis.py over all six runs and over the two pinned runs alone.
• Replayed both pinned runs through the real LowBatteryWarner under both curves — that table is measured, not estimated.
• Confirmed git diff origin/main...HEAD changes no knot values.
• 1159 unit + smoke tests pass; ruff check + format clean; mypy clean under the project config.

Note

user_guide.rst still quotes a v3/PiSugar figure ("four to five hours") for battery life. There is now a real measured rev4 number to replace it with — tracked in the rev4 docs plan (#572), not fixed here.

🤖 Generated with Claude Code