Persist a one-shot cold_start_backfill_announced flag in the JSON store so
the initial batch notification is shown only once; backfill still re-runs
silently for batteries without replaced_on. Release v0.1.6.
Co-authored-by: Cursor <cursoragent@cursor.com>
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>
When a tracked battery's source disappears, the coordinator's
_async_registry_changed handler soft-deletes the JSON-store entry
(replaced_on/profile/threshold preserved against restore within
30 days) and pops the in-memory BatteryRecord (companion entities
flip to unavailable). After REMOVED_SOURCE_RETENTION_DAYS the soft
deletes are pruned by store.prune_removed_older_than.
Pre-v0.1.4, the eight per-source companion entities and their
device-card entry remained in HA's registry forever as orphan
unavailable rows. Users had to garbage-collect manually.
This release adds a purge step keyed off prune_removed_older_than's
return value (the list of unique_ids actually dropped). For each,
the coordinator looks up the per-source companion device via
device_registry.async_get_device(identifiers={(DOMAIN, source_uid)})
and, if found, calls async_remove_device. HA's device-registry
removal cascades to the entity registry and removes the eight
companion entries automatically.
The purge runs from both prune call sites:
- _async_registry_changed action:remove (immediate prune sweep)
- _handle_tick (every 10-minute heartbeat)
Idempotent: a missing device is a silent no-op (covers manual
prior cleanup races and never-created cases). Soft-deleted entries
within their grace window are NOT touched -- restore via
store.restore_battery still works without UI rebuild.
Out of scope: legacy orphans accumulated before v0.1.4 (their
JSON-store entries are already gone, so there's nothing to drive
the new purge for them). Manual cleanup via UI remains.
Tests: 3 new in tests/test_coordinator.py covering the helper
directly, the no-op-on-missing-device path, and the full
remove-event -> grace-elapsed -> prune -> purge chain.
Full suite 118 passed.
README "When a battery disappears" section added documenting the
soft-delete + restore-window + auto-purge lifecycle.
Modifies the coordinator-scheduling capability with one ADDED
requirement; spec sync at archive time.
Co-authored-by: Cursor <cursoragent@cursor.com>
The v0.1.1 dialog warned that setup could freeze for several minutes
on installs with many batteries. Root cause was _scan_initial_entities
in coordinator.py awaiting _attempt_cold_start_backfill for every
record in series, dispatching 1-2 recorder/LTS executor jobs each.
With the user's 70-battery install, ~140 serialized executor jobs
on the await chain of async_setup blocked config-entry setup for
several minutes.
This release defers cold-start backfill out of the await chain:
1. Per-record fire-and-forget. _ensure_record schedules
_attempt_cold_start_backfill via hass.async_create_task instead of
awaiting it. async_setup returns within the time bounded by the
entity-registry scan, regardless of how many batteries need
backfill or how slow the recorder is.
2. One persistent notification when the initial backfill batch
finishes. The coordinator tracks in-flight backfills via
_pending_backfills: set[str]; when the set transitions from
non-empty to empty, exactly one persistent_notification fires
with notification_id="battery_lifetime_cold_start_complete". No
notification fires if no batteries needed backfill.
3. Softened config-dialog text. The bold/all-caps "WILL APPEAR
FROZEN FOR SEVERAL MINUTES" warning is replaced with an accurate
"background backfill may take several minutes; a notification
will appear when complete" note.
Cold-start semantics (LTS-then-recorder fallback, qualifying-jump
rules, replacement event payload, persisted replaced_on) unchanged.
Live-vs-historical race handled by _attempt_cold_start_backfill's
existing replaced_on guard: live commits during background backfill
win.
Also ships brand/logo.png and brand/logo@2x.png (copies of the icon
assets) so HA's brands-proxy logo slot is populated alongside the
icon shipped in v0.1.1.
Tests: 3 new in tests/test_coordinator.py covering non-blocking
setup, exactly-once completion notification, and
no-pending-no-notification. Full suite 115 passed.
Modifies the coordinator-scheduling capability with two ADDED
requirements; spec sync happens at archive time.
Co-authored-by: Cursor <cursoragent@cursor.com>
Three focused changes to the coordinator's recompute and publish paths:
1. Drop the redundant 10-minute timer. The DataUpdateCoordinator's
built-in update_interval and the explicit async_track_time_interval
tick were both firing every 600 s out of phase, doubling the
recompute rate on idle. Set update_interval=None and let the
explicit tick own the cadence (it already owns prune side effects).
2. Per-source-event single-record update. _handle_source_update now
calls async_set_updated_data with a shallow-copied snapshot dict
that replaces only the changed record's CoordinatorSnapshot,
carrying the other records' Prediction instances forward by
reference. Replaces the previous async_request_refresh which
triggered a full O(N) walk per source event. First-publish edge
case (self.data is None) falls back to a complete _compute_snapshots
so the snapshot dict is never partially populated.
3. Diff-gated heartbeat publish. The 10-minute tick now recomputes
every record but only calls async_set_updated_data if at least one
record's externally observable Prediction fields (replace_by,
confidence, drain_rate_pct_day, threshold_pct) changed, or the set
of tracked record keys changed. Idle systems where nothing
time-driven crossed a boundary skip the publish entirely.
The diff gate applies only to the heartbeat. Per-source events
(#2) and user-action setters / detector commits / registry events
keep the unconditional publish path so user-visible toggles always
reflect immediately, even when they leave the four observable
Prediction fields unchanged.
The heartbeat is intentionally NOT conditioned on "source value
changed" because three time-driven flips happen with no source
change: stale flip at 7-day source idleness, confidence-ladder
ratchet at 7/30/60-day boundaries, and summary-sensor cutoffs.
All three surface in Prediction, so the Prediction diff gate
preserves them while suppressing genuinely no-op publishes.
Tests: 5 new in tests/test_coordinator.py covering single-timer
contract, per-source O(1) update, idle-heartbeat skip, stale-flip
publish, and unconditional setter refresh. Full suite 112 passed
(was 107 + 5 new), zero regressions.
OpenSpec change: optimize-coordinator-tick.
Co-authored-by: Cursor <cursoragent@cursor.com>
A Home Assistant custom integration that turns every numeric percent
battery sensor into an actionable predicted-replacement-by datetime,
with auto-detection of replacements, lithium/alkaline chemistry
profiles, a confidence ladder, cold-start backfill from long-term
statistics, and a forward-prediction service. HACS-installable.
Implements the add-battery-lifetime OpenSpec change:
- 56/62 tasks done (10.2-10.7 are manual-validation gates)
- 18 spec requirements across 5 capabilities
- 107 unit tests passing under pytest-homeassistant-custom-component
Co-authored-by: Cursor <cursoragent@cursor.com>