Files
rickandCursor d048c84eb8 Add quarterly dashboard entities for maintenance cards
Expose due-next-quarter summary and binary companions, days_until_replace
on replace-by sensors, and a simplified example Lovelace card.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:25:23 +02:00

12 KiB
Raw Permalink Blame History

Battery Lifetime

A Home Assistant integration that turns raw battery % sensors into actionable replacement-date predictions, with auto-detected replacement events, two chemistry profiles (alkaline / lithium primary), and a forward- prediction service for "before I leave the cottage" planning.

Home Assistant gives you sensor.foo_battery = 47%. This integration adds sensor.foo_battery_replace_by = 2026-09-14, plus the small set of companion entities you need to tell it about chemistry, mark replacements manually, and opt individual batteries out.

Why this exists

The built-in HA battery percentage sensors are not actionable. You can't sort batteries by "needs replacement soon", you can't ask HA "which of these will fail before I'm back from the cottage?", and you can't tell HA which batteries are which chemistry. This integration fills that gap, with deliberately transparent extrapolation (no ML, no Bayesian magic — just a rolling drain rate plus chemistry-aware projection).

Installation

This integration is distributed as a HACS custom integration. The canonical repository is hosted on git.falkvinge.net. To install via HACS:

  1. In Home Assistant, open HACS → Integrations → ⋮ → Custom repositories.
  2. Add https://github.com/<mirror>/hassio-battery-lifetime-integration (or whichever GitHub mirror you maintain) with category Integration. (HACS requires GitHub-hosted repositories. The git.falkvinge.net repo is the source of truth; mirror it to GitHub for HACS distribution.)
  3. Search for Battery Lifetime in HACS, install, restart Home Assistant.
  4. Settings → Devices & Services → Add Integration → Battery Lifetime.

Manual

  1. Copy custom_components/battery_lifetime/ into your HA config/custom_components/.
  2. Restart Home Assistant.
  3. Settings → Devices & Services → Add Integration → Battery Lifetime.

What gets discovered

The integration enumerates all entities in the entity registry with:

  • device_class: battery
  • unit_of_measurement: %
  • a numeric current state in the range [0, 100]
  • a stable unique_id

The following are deliberately skipped (logged at info level on first sight):

  • categorical battery sensors (low / normal / full)
  • boolean low-battery sensors (binary_sensor.*_battery_low, on/off)
  • voltage-only battery sensors (V or mV)

If you want a sensor like that tracked, expose it as a % sensor via a template integration.

Per-battery companion entities

For every tracked battery sensor.foo_battery, the integration creates:

Entity Type Meaning
sensor.foo_battery_replace_by timestamp Predicted replacement datetime, or unknown
sensor.foo_battery_prediction_quality enum no_data / profile_default / low / medium / high / stale
sensor.foo_battery_drain_rate %/d Observed EWMA drain rate
switch.foo_battery_profile_lithium switch on = lithium, off = alkaline (icons differ per state)
switch.foo_battery_tracking_enabled switch on = tracked. Toggle off to opt out without deleting.
date.foo_battery_replaced_on date Manual override of replaced-on. Future dates rejected.
button.foo_battery_mark_replaced button Sets replaced_on to now and resets the model.
number.foo_battery_threshold_override number Optional % override. Blank means "use profile default."
binary_sensor.foo_battery_due_next_quarter binary on when replace_by falls on or before the next quarter end

The replace_by sensor also exposes a days_until_replace attribute (signed integer days; negative when overdue) when a prediction exists.

And three integration-level summary sensors:

  • sensor.battery_lifetime_due_this_month
  • sensor.battery_lifetime_due_next_3_months
  • sensor.battery_lifetime_due_next_quarter (includes a next_quarter_end attribute)

Replacement detection

Replacements are detected automatically from the source sensor's value pattern. A replacement is committed when all of the following hold:

  1. The most recent prior reading was strictly less than 80%.
  2. The new reading is at least 100%.
  3. The prior reading is at most 30 days old.
  4. The 100% reading persists across at least one more update from the source, or for one continuous hour, whichever comes first.
  5. The battery is currently tracked (its tracking_enabled switch is on).

A 100% reading that drops below 95% within an hour is discarded as a glitch.

If the prior reading is older than 30 days, the integration does not auto-commit. Instead, it raises a persistent HA notification asking you to Confirm, Dismiss, or Exclude the battery. The notification names the source entity; respond by calling one of these services from Developer Tools → Services (or from a script/automation):

  • battery_lifetime.confirm_stale_replacement — record the replacement at the candidate's first 100% reading.
  • battery_lifetime.dismiss_stale_replacement — ignore this candidate; tracking stays on.
  • battery_lifetime.exclude_stale_replacement — ignore this candidate and turn tracking off for the battery (sets switch.<src>_tracking_enabled to off).

All three take a single entity_id field — the source battery sensor, the one named in the notification. This protects you from sensor gaps that look like replacements.

Manual paths:

  • button.foo_battery_mark_replaced — press it after swapping cells.
  • date.foo_battery_replaced_on — directly set the date if you remember exactly when you swapped them. Future dates are rejected.

Every committed replacement (auto or manual) emits the battery_lifetime_replacement_detected HA event with the source entity_id, unique_id, before/after percentages, prior reading age, the committed replaced_on, a confirmed flag, and a source field that names which path committed it (auto, manual_button, manual_date_edit, cold_start_backfill, stale_confirmed).

Chemistry profiles

Two profiles ship in v1:

Profile Default threshold Default lifetime Curve shape
alkaline 15% 365 d Smooth taper, EWMA from day 1
lithium 5% 1825 d Plateau (≥85%) then cliff

The integration-level default profile (settable in the options flow) applies to newly discovered batteries. The default ships as lithium. Override per battery with the profile_lithium switch on the device card (it's a toggle: on = lithium, off = alkaline).

If you've got a battery whose firmware "linearizes" the lithium discharge (rare), set its profile to alkaline — what the model cares about is curve shape, not the chemistry label.

Lithium plateau caveat. While a lithium-profile battery's source reads ≥85%, the prediction is the chemistry-default lifetime anchored on replaced_on, not extrapolation of the (misleadingly slow) observed drain. Confidence stays at profile_default during the plateau regardless of how much time has passed. Once the source drops below 85%, the model switches to EWMA extrapolation.

Confidence ladder

The *_prediction_quality sensor reflects how trustworthy the prediction is:

  • no_data — no replaced_on known, no qualifying drain seen yet.
  • profile_default — replaced_on known, but not enough drain observed yet, or the lithium battery is on its plateau.
  • low — at least 7 days since replaced_on and at least 1% drain observed.
  • medium — at least 30 days and at least 5% drain.
  • high — at least 60 days and at least 10% drain.
  • stale (orthogonal) — the source has produced no update in the last 7 days. Takes precedence over the others when active.

Expect the first 30–60 days of any fresh install to sit at low or below. This is honest behaviour, not a bug. Lithium batteries on plateau will sit at profile_default for many months until the chemistry actually starts to drop.

Cold start

When a battery is first seen by the integration:

  1. Long-term statistics are scanned for the most recent qualifying jump (<80% → ≥100% within the last few years). If found, that's replaced_on.
  2. Recorder is scanned next as a fallback. Recorder default retention is ~10 days, so this rarely fires unless you've increased retention.
  3. If neither yields a hit, the integration sits in no_data and continues listening. Once at least 7 days of post-attach data with at least 1% drain accumulate, it extrapolates backwards along the active profile to estimate replaced_on and updates accordingly.

The cold-start scan runs in the background after the integration finishes setting up, so the Settings → Devices & Services dialog returns within seconds even on installs with many batteries. On a 70-battery install the background scan can take several minutes; the integration is fully functional throughout, and a one-time persistent notification ("Battery Lifetime: backfill complete") appears when the initial backfill batch is done.

When a battery disappears

When a source battery is removed from Home Assistant (device deleted, Zigbee2MQTT un-paired, integration uninstalled), the integration:

  1. Drops the in-memory state immediately. The nine companion entities flip to unavailable in the UI.
  2. Soft-deletes the persistent state in .storage/battery_lifetime — replaced_on, profile, threshold override, and EWMA state are kept against the chance of restore. The entry is stamped with a removed_at timestamp.
  3. If the same unique_id reappears within 30 days (e.g. you re-pair the device), the prior state is restored and the companion entities resume automatically — no UI rebuild, your replaced_on is preserved.
  4. After 30 days, the soft-deleted store entry is pruned, and the companion device card plus all nine companion entities are removed from Home Assistant's registry. No orphan unavailable rows linger.

The forward-prediction service

service: battery_lifetime.predict_at
data:
  date: "2026-10-15"
  margin_days: 14         # optional, default 0
  actionable_only: false  # optional, default false
  include_excluded: false # optional, default false

The response contains a results list. Each entry is one battery:

results:
  - entity_id: sensor.kitchen_motion_battery
    replace_by_entity: sensor.kitchen_motion_battery_replace_by
    unique_id: 0x00158d000123abcd-battery
    profile: lithium
    threshold_pct: 5
    drain_rate_pct_day: 0.18
    predicted_pct_at_date: 8
    predicted_state: below_threshold
    confidence: medium
    tracking_enabled: true

Use it from a script, automation, or template to power your own "replace-this-month" or "before-the-cottage" dashboards.

Non-goals (v1)

The integration does not model:

  • Categorical (low/normal/full) or boolean low-battery sensors.
  • Voltage-only (V / mV) battery sensors.
  • Rechargeable batteries (NiMH eneloops, Li-ion packs, USB-backup devices, EcoFlow whole-house batteries). The auto-replacement rule will fire spuriously on every recharge cycle. Exclude rechargeables by toggling tracking_enabled off.
  • "3×AA dies as a set" multi-cell awareness. Each entity is modeled independently.
  • Custom Lovelace cards (left to a sibling project).
  • Cross-device learning, Bayesian priors, or ML.

License

This project was AI-generated. Human involvement did not meet the bar for substantial originality required for copyright protection. This work is in the public domain where applicable, or otherwise not subject to copyright protection.