6 Commits
Author SHA1 Message Date
rickandCursor f0804592c3 Fix backfill-complete notification firing on every HA restart.
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>
2026-05-25 10:00:34 +02:00
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
rickandCursor 13b3dd63ce v0.1.4: auto-clean companion device when source is pruned
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>
2026-05-11 11:59:56 +02:00
rickandCursor 006771a5f2 v0.1.3: defer cold-start backfill so setup returns sub-second
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>
2026-05-11 11:38:59 +02:00
rickandCursor 24e4450bec v0.1.2: coordinator scheduling optimizations
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>
2026-05-09 19:13:22 +02:00
rickandCursor 1c2f8b6c07 Initial commit: Battery Lifetime integration v0.1.0
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>
2026-05-08 18:53:51 +02:00