21 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 b5c910c425 openspec(quarterly-dashboard-entities): archive and sync lifetime-prediction spec
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:25:36 +02:00
rick 669c9bda5d Merge agent/quarterly-dashboard-entities: quarterly dashboard entities 2026-05-23 11:25:28 +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 2d21a34438 openspec(quarterly-dashboard-entities): apply phase complete
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:22:33 +02:00
rickandCursor aeac543356 openspec(quarterly-dashboard-entities): propose phase artifacts
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:21:13 +02:00
rick 8154d29d53 Merge agent/license-rename: replace Swarmops name in LICENSE 2026-05-12 19:55:14 +02:00
rickandCursor 89c0a12e51 license: replace Swarmops name with project name
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-12 19:54:10 +02:00
rick 986b4f9fa7 Merge agent/license-readme: public-domain license 2026-05-12 19:46:48 +02:00
rickandCursor 8d2c34bf6f docs(license): switch project to public domain
Replace MIT licensing with Swarmops-flavored UNLICENSE/CC0 public-domain
statement and align README's License section to match.

LICENSE content copied verbatim from
github.com/Swarmops/Swarmops:LICENSE-PUBLIC-DOMAIN.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-12 19:46:15 +02:00
rickandCursor 6f577c844f openspec(autoclean-orphan-companion-entities): archive + sync specs; HANDOFF v0.1.4
Sync delta from autoclean-orphan-companion-entities into the canonical
coordinator-scheduling spec (one new requirement: pruned sources have
their companion device removed). Move the change directory under
openspec/changes/archive/.

Update HANDOFF.md: v0.1.4 is current release; the orphan-companion-
entity gap is closed for future prunes; legacy orphans (from before
v0.1.4) remain a manual-cleanup item.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 12:02:52 +02:00
rick 089082a163 Merge agent/autoclean-orphan-companion-entities: v0.1.4 auto-clean
Closes the orphan-companion-entity gap surfaced when discussing the
removal flow: when prune_removed_older_than actually drops a unique_id
from the JSON store, the coordinator now also removes the matching
companion device via device_registry.async_remove_device. HA's
device-registry removal cascades to the entity registry and clears
the eight per-source companion entries automatically. 118 tests
passing.
2026-05-11 12:00:18 +02:00
rickandCursor 34ae5e8d01 openspec(autoclean-orphan-companion-entities): apply phase done; ready to merge
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 12:00:18 +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 8fab5a5784 openspec(autoclean-orphan-companion-entities): propose phase artifacts
Proposes that prune_removed_older_than's pruned-unique_ids return value
drives a device-registry purge step in both prune call sites
(_async_registry_changed action:remove and _handle_tick), removing the
per-source companion device whose identifiers={(DOMAIN, source_uid)}.
HA's device-registry removal cascades to the entity registry and
removes the eight orphan companion entries automatically.

Modifies coordinator-scheduling capability with one new requirement
covering the cleanup behavior, including the no-op-on-missing-device
and the keep-during-grace-window scenarios.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 11:57:15 +02:00
rickandCursor c576310fce openspec(defer-cold-start-backfill): archive + sync specs; HANDOFF v0.1.3
Sync delta from defer-cold-start-backfill into the canonical
coordinator-scheduling spec (two new requirements: non-blocking
cold-start, exactly-once batch-completion notification). Move the
change directory under openspec/changes/archive/.

Update HANDOFF.md: v0.1.3 is current release; the multi-minute
setup freeze is fixed; brand/logo polish shipped; live-install
manual-validation gates 10.2-10.5 still open.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 11:43:07 +02:00
rick 330642e6b9 Merge agent/defer-cold-start-backfill: v0.1.3 non-blocking cold-start
Defers per-record cold-start backfill out of async_setup's await chain
to remove the multi-minute config-entry freeze on installs with many
batteries. Adds one persistent notification when the initial backfill
batch completes; softens the v0.1.1 dialog warning. Ships brand/logo
assets alongside the v0.1.1 brand/icon assets. 115 tests passing.
2026-05-11 11:40:00 +02:00
rickandCursor 20ce139069 openspec(defer-cold-start-backfill): apply phase done; ready to merge
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 11:39:53 +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 2e93800981 openspec(defer-cold-start-backfill): propose phase artifacts
Proposes deferring cold-start backfill out of the await chain of
async_setup so config-entry setup returns sub-second regardless of
how many batteries need historical replaced_on lookup. Adds a single
persistent notification when the initial backfill batch completes,
and softens the v0.1.1 all-caps freeze warning in the config dialog
to match the new background-backfill behaviour.

Modifies coordinator-scheduling capability with two new requirements
(non-blocking setup, exactly-once batch-completion notification).
No changes to replacement-detection contract.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 11:24:14 +02:00
rickandCursor ddc12ba6d3 openspec(optimize-coordinator-tick): archive + sync specs; HANDOFF v0.1.2
- Move openspec/changes/optimize-coordinator-tick to
  openspec/changes/archive/2026-05-09-optimize-coordinator-tick.
- Sync the change's coordinator-scheduling delta to
  openspec/specs/coordinator-scheduling/spec.md so future agents have
  the heartbeat / per-event publish contract in main specs.
- HANDOFF.md: bump current state to v0.1.2; mark the brands-PR task
  obsolete (HACS uses the local brand mechanism on HA 2026.3+, and
  home-assistant/brands auto-closes custom-integration PRs); note
  v0.1.2 did not touch the cold-start setup freeze in task #3.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-09 19:16:06 +02:00
43 changed files with 1572 additions and 94 deletions
+34 -30
View File
@@ -1,11 +1,13 @@
# Agent Handoff — Battery Lifetime
## Current State (2026-05-08)
## Current State (2026-05-11, late-morning)
The Battery Lifetime custom Home Assistant integration is working and deployed via HACS on the user's live install (70 battery-powered devices → 554 companion entities). Current release is **v0.1.1** on GitHub via HACS.
The Battery Lifetime custom Home Assistant integration is working and deployed via HACS on the user's live install (70 battery-powered devices → 554 companion entities). Current release is **v0.1.6** on GitHub via HACS.
The OpenSpec change `add-battery-lifetime` is at 56/62 tasks; the remaining six (10.2–10.7) are manual-validation gates against a real HA install. Some are implicitly being validated right now by the live install; see "What Needs Doing Next" below.
The OpenSpec changes `optimize-coordinator-tick` (v0.1.2), `defer-cold-start-backfill` (v0.1.3), and `autoclean-orphan-companion-entities` (v0.1.4) are fully archived under `openspec/changes/archive/`. All three have their specs synced into `openspec/specs/coordinator-scheduling/spec.md`.
## What's Done
- Full implementation of the Battery Lifetime integration:
@@ -23,34 +25,22 @@ The OpenSpec change `add-battery-lifetime` is at 56/62 tasks; the remaining six
- HACS packaging (`hacs.json`, `info.md`, `README.md`, `LICENSE`, `manifest.json`).
- 107 unit tests passing under `pytest-homeassistant-custom-component`.
- v0.1.0 released and installed live on the user's HA install. v0.1.1 follow-up adds a bold/all-caps setup-time warning to the config dialog and ships icon assets in `custom_components/battery_lifetime/brand/` (256×256 + 512×512).
- Both `master` and tags `v0.1.0`/`v0.1.1` pushed to gitea (origin) and GitHub (github).
- README and OpenSpec specs aligned with the implementation; `replacement-detection/spec.md` enumerates the three stale-prior services explicitly.
- v0.1.2 ships three coordinator scheduling optimizations (drop redundant 10-minute timer, per-source-event O(1) update via `async_set_updated_data`, diff-gated heartbeat publish). 5 new tests in `tests/test_coordinator.py`, full suite 112 passed.
- v0.1.3 defers cold-start backfill out of `async_setup`'s await chain via `hass.async_create_task`, removing the multi-minute config-entry freeze on installs with many batteries (the v0.1.1 dialog warning is no longer applicable and was softened). Adds a one-shot `persistent_notification` (`battery_lifetime_cold_start_complete`) when the initial backfill batch finishes. Ships `brand/logo.png` + `brand/logo@2x.png` (copies of the icon assets) for HA's Brands Proxy logo slot. 3 new tests in `tests/test_coordinator.py`, full suite 115 passed.
- v0.1.4 closes the orphan-companion-entity gap: when `prune_removed_older_than` actually drops a `unique_id` from the JSON store (after the 30-day grace window), the coordinator now removes the per-source companion device via `device_registry.async_remove_device`. HA's device-registry removal cascades to the entity registry and clears the eight per-source companion entries automatically. Cleanup runs from both prune call sites (`_async_registry_changed action: remove` + `_handle_tick`). Idempotent on missing device. Soft-deleted entries within their grace window are NOT touched; restore semantics are unchanged. 3 new tests, full suite 118 passed.
- v0.1.6 fixes the cold-start backfill completion notification firing on every HA restart. The one-shot `persistent_notification` (`battery_lifetime_cold_start_complete`) is now gated by a persisted `cold_start_backfill_announced` flag in the JSON store; backfill still re-runs silently on restart for batteries without `replaced_on` (idempotent, per spec). Upgrades with existing battery entries migrate the flag to `true` so no spurious notification on first restart after update. 1 new test, full suite 127 passed.
- Both `master` and tags `v0.1.0`/`v0.1.1`/`v0.1.2`/`v0.1.3`/`v0.1.4`/`v0.1.5`/`v0.1.6` pushed to gitea (origin) and GitHub (github).
- README and OpenSpec specs aligned with the implementation; `replacement-detection/spec.md` enumerates the three stale-prior services explicitly. `coordinator-scheduling/spec.md` documents the per-event vs heartbeat contracts, the non-blocking cold-start contract, AND the prune-driven companion-device purge.
## What Needs Doing Next (Immediate)
### 1. Brands PR for the HACS icon
### 1. ~~Brands PR for the HACS icon~~ — OBSOLETE as of HA 2026.3
HACS sources its integration icons from [home-assistant/brands](https://github.com/home-assistant/brands), not from the integration repo. The local assets at `custom_components/battery_lifetime/brand/icon.png` (256) and `icon@2x.png` (512) are ready to ship. To make HACS display them:
Home Assistant 2026.3 (announcement: <https://developers.home-assistant.io/blog/2026/02/24/brands-proxy-api>) introduced a local Brands Proxy API. Custom integrations now ship `brand/icon.png`, `brand/icon@2x.png`, `brand/logo.png`, and `brand/logo@2x.png` inside their own repository, and HA serves them from `/api/brands/integration/<domain>/...`. The `home-assistant/brands` repo **auto-closes** PRs for `custom_integrations/*` and tells contributors to use the inline mechanism.
```bash
GH_TOKEN=$(cat /home/rick/Lab/Dev/Hassio-PerfectDraftPro/.github-token) gh repo fork home-assistant/brands --clone --remote
cd brands
git checkout -b add-battery-lifetime
mkdir -p custom_integrations/battery_lifetime
cp /home/rick/Lab/Dev/Hassio-Battery-Lifetimes/custom_components/battery_lifetime/brand/icon.png custom_integrations/battery_lifetime/icon.png
cp /home/rick/Lab/Dev/Hassio-Battery-Lifetimes/custom_components/battery_lifetime/brand/icon@2x.png custom_integrations/battery_lifetime/icon@2x.png
# logo.png + logo@2x.png are usually required too — same image is fine for an icon-only brand
cp /home/rick/Lab/Dev/Hassio-Battery-Lifetimes/custom_components/battery_lifetime/brand/icon.png custom_integrations/battery_lifetime/logo.png
cp /home/rick/Lab/Dev/Hassio-Battery-Lifetimes/custom_components/battery_lifetime/brand/icon@2x.png custom_integrations/battery_lifetime/logo@2x.png
git add custom_integrations/battery_lifetime
git commit -m "Add battery_lifetime"
git push origin add-battery-lifetime
GH_TOKEN=... gh pr create --repo home-assistant/brands \
--title "Add battery_lifetime" \
--body "Custom integration: https://github.com/Falkvinge/hassio-integration-battery-lifetime"
```
We ship all four assets as of v0.1.3 (icons in v0.1.1, logos added in v0.1.3 as copies of the icons). On the user's HA 2026.4.x install the icon and logo are served by HA core in **Settings → Devices & Services**, the integration card, and the config-flow dialog. **No PR needed.**
CI in brands runs Pillow checks for image dimensions and format; the assets satisfy them (sized correctly, transparent, RGBA).
The one remaining gap is HACS's own dashboard (Downloads / repository list), which still calls the old CDN URL because `hacs/frontend` hasn't been bumped past the brands-proxy rewrite. Tracked in `hacs/integration#5179` and `#5223`; fix PRs `hacs/integration#5228`, `hacs/frontend#937`, `#929`, `#5249` are open but unmerged. Until HACS frontend ships those, the HACS Downloads panel will keep showing "icon not available". This is a HACS issue, not ours.
### 2. OpenSpec manual-validation gates 10.2 – 10.7
@@ -65,15 +55,21 @@ These are the only remaining tasks in `openspec/changes/add-battery-lifetime/tas
Once 10.2 – 10.5 are observed in the live install, mark them in `tasks.md` and run `openspec archive --change "add-battery-lifetime"` (the OpenSpec workflow). The change has `isComplete: true` per `openspec status` (all artifacts are done; the open task checkboxes don't block archive).
### 3. Investigate the multi-minute initial-setup freeze
### 3. ~~Investigate the multi-minute initial-setup freeze~~ — FIXED in v0.1.3
User reported that pressing **Submit** on the config dialog locked the UI for several minutes on a 70-device / 554-entity install. v0.1.1 warns about this in the dialog, but the underlying cause should be confirmed before considering it acceptable. Likely culprits:
v0.1.3 ships the cold-start defer: `_ensure_record` schedules `_attempt_cold_start_backfill` via `hass.async_create_task` instead of awaiting it, so `async_setup` returns within the time bounded by the entity-registry scan (sub-second on the user's install). The coordinator tracks in-flight backfills in `_pending_backfills: set[str]` and fires one persistent notification (`battery_lifetime_cold_start_complete`) when the set drains.
- `_scan_initial_entities` in `custom_components/battery_lifetime/coordinator.py` calls `_ensure_record` for every eligible entity sequentially, and each call awaits the cold-start backfill (`_attempt_cold_start_backfill` → `recorder.async_add_executor_job` → two recorder queries per battery). With 70 batteries that's 140 recorder queries serialized.
- Mitigations to consider: gate cold-start backfill behind a background task instead of blocking setup; batch the recorder queries via `recorder.history.get_significant_states` for all entity_ids at once; or just defer the backfill to the first scheduled coordinator tick (already 10 minutes after setup) and let setup return immediately.
- Lazy-import note: cold-start should not block any of the *other* setup steps — the entity platforms are forwarded after `coordinator.async_setup()` returns. So the freeze is squarely in `_scan_initial_entities`.
The dialog warning was softened from the bold/all-caps freeze warning to a calmer "background backfill may take several minutes; a notification will appear when complete" note in `strings.json` and `translations/en.json`.
### 4. Loose ends from earlier sessions
**Worth observing on the live install after upgrade:** confirm that (a) re-adding the integration completes within seconds rather than minutes; (b) the `battery_lifetime_cold_start_complete` notification appears once the background backfill finishes; (c) the per-battery `replaced_on` values populate over the following minutes; (d) no regressions in the 70 → 554 entity registration.
### 4. ~~Orphan companion entities after permanent removal~~ — FIXED in v0.1.4
v0.1.4 hooks the device-registry purge into the existing prune path. When `prune_removed_older_than` returns a non-empty list (which only happens after the 30-day grace window has expired for a soft-deleted source), the coordinator looks up the matching companion device via `device_registry.async_get_device(identifiers={(DOMAIN, source_uid)})` and calls `async_remove_device`, which cascades to all eight companion entity-registry entries.
**Pre-existing orphans accumulated before v0.1.4 are NOT retroactively cleaned.** Their JSON-store entries are already gone (so the prune-driven purge has nothing to act on for them). User can manually delete via Settings → Devices & Services. If accumulated orphans become a real pain point on the live install, a one-shot legacy-orphan scanner could be added in a future release; deferred until asked.
### 5. Loose ends from earlier sessions
- **Branch tracking.** `master` currently tracks `github/master` (because of `git push -u github master`). Sibling repos track `origin/master`. To match the sibling pattern:
```bash
@@ -154,6 +150,8 @@ GH_TOKEN=$(cat /home/rick/Lab/Dev/Hassio-PerfectDraftPro/.github-token) \
## OpenSpec Status
### Active changes
Change directory: `openspec/changes/add-battery-lifetime/`
| Artifact | Status |
@@ -164,3 +162,9 @@ Change directory: `openspec/changes/add-battery-lifetime/`
| `tasks.md` | 56/62 (10.2 – 10.7 are the manual-validation gates) |
Ready to archive once 10.2 – 10.5 are observed live and the boxes are checked. 10.6 and 10.7 are already effectively done.
### Archived changes
- `openspec/changes/archive/2026-05-09-optimize-coordinator-tick/` — v0.1.2 release. Synced spec `coordinator-scheduling` is at `openspec/specs/coordinator-scheduling/spec.md`.
- `openspec/changes/archive/2026-05-11-defer-cold-start-backfill/` — v0.1.3 release. Same target spec; adds two requirements (Cold-start backfill is non-blocking; Backfill batch completion is announced exactly once).
- `openspec/changes/archive/2026-05-11-autoclean-orphan-companion-entities/` — v0.1.4 release. Same target spec; adds one requirement (Pruned sources have their companion device removed).
+71 -21
View File
@@ -1,21 +1,71 @@
MIT License
Copyright (c) 2026 Rick Falkvinge
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
LICENSE: NO COPYRIGHT MONOPOLY CLAIMED, NO WARRANTY OF ANY KIND GIVEN
All code in this solution and its subprojects are IN THE PUBLIC DOMAIN,
unless specificially marked otherwise (when it comes from a different
package or commercial source).
Where the concept "public domain" does not exist, the copyright monopoly
license Creative Commons Zero (CC0) is used as a declararation of Public
Domain, or as an alternative, the Unlicense (see below).
This means that anybody may use this code for absolutely anything. The
copyright monopoly does not affect it at all. Any question that begins
with a "but can I" or "but what if", concerning permission to use this
software, is answered with a "yes". More than that: it's a "yes, and
why are you so conditioned to ask permission for using knowledge?"
Anybody submitting new code, imagery, or other components to the project
agrees to put their additions in the public domain. If you're adding a
third party component, do flag it as external.
IMPORTANT EXCEPTIONS are all images and the external libraries found
in the Bin folder of the Site projects, and in External Libraries.
The images are flagged with source in their file name. Do not commit
any new restricted code without prior consensus in the project team.
Another way of putting this is the way of the UNLICENSE:
This Project (Home Assistant Battery Lifetime integration) is free
and unencumbered software released irrevocably into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, or do anything else with it; in any form,
specifically including source code form, as a compiled binary, or
as an interpretive dance performance; for any purpose, commercial,
nonprofit, hobby, or otherwise; and by any means, specifically
including any means you can think of. You are also free to eat it,
dance with it, or have sex with it. If you figure out that last
option, the project team appreciates if you share the insight.
In jurisdictions that recognize the immoral exclusive rights of
copyright monopoly laws, the author or authors of this software
dedicate any and all copyright monopoly interest in the software
irrevocably to the public domain. We make this dedication for the
benefit of the public at large and for the benefit of our heirs and
successors (albeit explicitly not a "benefit" in the form of an
immoral and destructive right of exclusivity). We intend this
dedication to be an overt act of relinquishment in perpetuity of
all present and future rights of exclusivity to this software
under copyright monopoly law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
THE AUTHORS DO NOT WARRANT THAT THIS SOFTWARE WILL PERFORM AS
EXPECTED, PERFORM OTHER THAN EXPECTED, OR PERFORM AT ALL.
IN THE EVENT OF DAMAGES EXCEEDING TEN MILLION US DOLLARS OR CASUALTIES
EXCEEDING ONE HUNDRED PEOPLE, THE AFFLICTED USERS AGREE THAT THEY
STOLE THE SOFTWARE WHILE ON VACATION IN A FOREIGN COUNTRY AND THE
AUTHORS HAVE NEVER HEARD OF IT.
For more information, please refer to <http://unlicense.org/>
+24 -2
View File
@@ -72,11 +72,16 @@ For every tracked battery `sensor.foo_battery`, the integration creates:
| `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 |
And two integration-level summary sensors:
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
@@ -178,6 +183,23 @@ When a battery is first seen by the integration:
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
```yaml
@@ -225,4 +247,4 @@ The integration **does not** model:
## License
MIT. See `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.
@@ -0,0 +1,83 @@
"""Binary sensor platform: per-battery due-next-quarter flag."""
from __future__ import annotations
from typing import Any
from homeassistant.components.binary_sensor import BinarySensorEntity
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant, callback
from homeassistant.helpers.entity_platform import AddEntitiesCallback
from .const import CONFIDENCE_NO_DATA, DOMAIN
from .coordinator import BatteryLifetimeCoordinator
from .entity import BatteryCompanionEntity
from .quarters import is_due_by_quarter_end
_DUE_NEXT_QUARTER_SUFFIX = "due_next_quarter"
async def async_setup_entry(
hass: HomeAssistant,
entry: ConfigEntry,
async_add_entities: AddEntitiesCallback,
) -> None:
coordinator: BatteryLifetimeCoordinator = hass.data[DOMAIN][entry.entry_id][
"coordinator"
]
@callback
def _build(unique_id: str) -> list[BinarySensorEntity]:
return [DueNextQuarterBinarySensor(coordinator, unique_id)]
initial: list[BinarySensorEntity] = []
for unique_id in coordinator.records:
initial.extend(_build(unique_id))
async_add_entities(initial)
seen: set[str] = set(coordinator.records)
@callback
def _on_update() -> None:
new_entities: list[BinarySensorEntity] = []
for unique_id in coordinator.records:
if unique_id in seen:
continue
seen.add(unique_id)
new_entities.extend(_build(unique_id))
if new_entities:
async_add_entities(new_entities)
entry.async_on_unload(coordinator.async_add_listener(_on_update))
class DueNextQuarterBinarySensor(BatteryCompanionEntity, BinarySensorEntity):
"""Whether the battery is projected to need replacement next quarter."""
_attr_translation_key = "due_next_quarter"
def __init__(
self, coordinator: BatteryLifetimeCoordinator, unique_id: str
) -> None:
super().__init__(coordinator, unique_id, _DUE_NEXT_QUARTER_SUFFIX)
self._attr_name = "Due next quarter"
@property
def is_on(self) -> bool | None:
record = self.record
snapshot = (self.coordinator.data or {}).get(self._source_unique_id)
if record is None or snapshot is None:
return None
if not record.tracking_enabled:
return False
prediction = snapshot.prediction
if prediction.confidence == CONFIDENCE_NO_DATA:
return False
return is_due_by_quarter_end(prediction.replace_by)
@property
def extra_state_attributes(self) -> dict[str, Any]:
record = self.record
if record is None:
return {}
return {"source_entity": record.entity_id}
Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 96 KiB

+1 -1
View File
@@ -5,7 +5,7 @@ from __future__ import annotations
from typing import Final
DOMAIN: Final = "battery_lifetime"
PLATFORMS: Final = ["sensor", "switch", "button", "date", "number"]
PLATFORMS: Final = ["sensor", "binary_sensor", "switch", "button", "date", "number"]
STORAGE_KEY: Final = "battery_lifetime"
STORAGE_VERSION: Final = 1
@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from typing import Any
from homeassistant.components import persistent_notification
from homeassistant.const import EVENT_STATE_CHANGED
from homeassistant.core import (
CALLBACK_TYPE,
@@ -27,7 +28,7 @@ from homeassistant.core import (
HomeAssistant,
callback,
)
from homeassistant.helpers import entity_registry as er
from homeassistant.helpers import device_registry as dr, entity_registry as er
from homeassistant.helpers.event import async_track_time_interval
from homeassistant.helpers.update_coordinator import DataUpdateCoordinator
@@ -145,6 +146,7 @@ class BatteryLifetimeCoordinator(
self._detector = ReplacementDetector(hass, self._apply_commit)
self._backfiller = ColdStartBackfiller(hass)
self._known_entities: set[str] = set()
self._pending_backfills: set[str] = set()
@property
def store(self) -> BatteryLifetimeStore:
@@ -244,10 +246,72 @@ class BatteryLifetimeCoordinator(
if not record.backfill_attempted:
record.backfill_attempted = True
await self._attempt_cold_start_backfill(record)
if record.replaced_on is None:
self._pending_backfills.add(unique_id)
self.hass.async_create_task(
self._run_backfill_with_tracking(record),
name=f"battery_lifetime_cold_start_{unique_id}",
)
return record
async def _run_backfill_with_tracking(
self, record: BatteryRecord
) -> None:
"""Run cold-start backfill and announce completion of the batch.
Cold-start backfill is dispatched as a background task per record so
it never blocks ``async_setup``. ``_pending_backfills`` is the
single source of truth for "is the initial backfill phase still
running"; when the last task removes its ``unique_id`` the user
gets one persistent notification.
"""
try:
await self._attempt_cold_start_backfill(record)
finally:
self._pending_backfills.discard(record.unique_id)
if not self._pending_backfills:
self._announce_backfill_complete()
def _announce_backfill_complete(self) -> None:
if self._store.cold_start_backfill_announced:
return
persistent_notification.async_create(
self.hass,
(
"Battery Lifetime has finished its initial cold-start "
"backfill. Per-battery 'Replaced on' values inferred from "
"long-term statistics are now populated."
),
title="Battery Lifetime: backfill complete",
notification_id="battery_lifetime_cold_start_complete",
)
self._store.set_cold_start_backfill_announced()
def _purge_companions_for_pruned(self, unique_ids: list[str]) -> None:
"""Remove the companion device for each pruned source.
HA's device-registry removal cascades to the entity registry and
drops every entry tied to the device, which on the Battery Lifetime
device card is exactly the nine per-source companion entries.
Idempotent: a missing device is a silent no-op.
"""
if not unique_ids:
return
device_registry = dr.async_get(self.hass)
for source_uid in unique_ids:
device = device_registry.async_get_device(
identifiers={(DOMAIN, source_uid)}
)
if device is None:
continue
device_registry.async_remove_device(device.id)
_LOGGER.info(
"battery_lifetime: removed orphan companion device for "
"pruned source %s",
source_uid,
)
async def _attempt_cold_start_backfill(
self, record: BatteryRecord
) -> None:
@@ -296,7 +360,10 @@ class BatteryLifetimeCoordinator(
record = self._records.pop(unique_id, None)
if record is not None:
record.tracking_enabled = False
self._store.prune_removed_older_than(REMOVED_SOURCE_RETENTION_DAYS)
pruned = self._store.prune_removed_older_than(
REMOVED_SOURCE_RETENTION_DAYS
)
self._purge_companions_for_pruned(pruned)
return
registry = er.async_get(self.hass)
entry = registry.async_get(entity_id)
@@ -517,7 +584,10 @@ class BatteryLifetimeCoordinator(
@callback
def _handle_tick(self, _now: datetime) -> None:
self._store.prune_removed_older_than(REMOVED_SOURCE_RETENTION_DAYS)
pruned = self._store.prune_removed_older_than(
REMOVED_SOURCE_RETENTION_DAYS
)
self._purge_companions_for_pruned(pruned)
self.hass.async_create_task(self._async_recompute_and_maybe_publish())
async def _async_recompute_and_maybe_publish(self) -> None:
@@ -1,7 +1,7 @@
{
"domain": "battery_lifetime",
"name": "Battery Lifetime",
"version": "0.1.2",
"version": "0.1.6",
"documentation": "https://github.com/Falkvinge/hassio-integration-battery-lifetime",
"issue_tracker": "https://github.com/Falkvinge/hassio-integration-battery-lifetime/issues",
"codeowners": ["@rickfalkvinge"],
@@ -0,0 +1,60 @@
"""Calendar-quarter helpers for dashboard and companion entities."""
from __future__ import annotations
from datetime import datetime, timezone
UTC = timezone.utc
def _to_utc(dt: datetime) -> datetime:
if dt.tzinfo is None:
return dt.replace(tzinfo=UTC)
return dt.astimezone(UTC)
def next_quarter_end(now: datetime | None = None) -> datetime:
"""Return 23:59:59 UTC on the last day of the next calendar quarter."""
now_dt = _to_utc(now) if now is not None else datetime.now(tz=UTC)
year = now_dt.year
month = now_dt.month
if month <= 3:
end_year, end_month, end_day = year, 6, 30
elif month <= 6:
end_year, end_month, end_day = year, 9, 30
elif month <= 9:
end_year, end_month, end_day = year, 12, 31
else:
end_year, end_month, end_day = year + 1, 3, 31
return datetime(
end_year,
end_month,
end_day,
23,
59,
59,
tzinfo=UTC,
)
def is_due_by_quarter_end(
replace_by: datetime | None,
*,
now: datetime | None = None,
) -> bool:
"""True when ``replace_by`` is on or before :func:`next_quarter_end`."""
if replace_by is None:
return False
return _to_utc(replace_by) <= next_quarter_end(now)
def days_until_replace(
replace_by: datetime | None,
*,
now: datetime | None = None,
) -> int | None:
"""Whole UTC days until ``replace_by`` (negative when overdue)."""
if replace_by is None:
return None
now_dt = _to_utc(now) if now is not None else datetime.now(tz=UTC)
return int((_to_utc(replace_by) - now_dt).total_seconds() / 86400.0)
@@ -16,10 +16,12 @@ from .const import (
CONFIDENCE_LOW,
CONFIDENCE_MEDIUM,
CONFIDENCE_HIGH,
CONFIDENCE_NO_DATA,
DOMAIN,
)
from .coordinator import BatteryLifetimeCoordinator
from .entity import BatteryCompanionEntity, companion_unique_id
from .quarters import days_until_replace, is_due_by_quarter_end, next_quarter_end
UTC = timezone.utc
@@ -29,6 +31,7 @@ _DRAIN_RATE_SUFFIX = "drain_rate"
_DUE_THIS_MONTH_UNIQUE = "battery_lifetime:summary:due_this_month"
_DUE_NEXT_3_MONTHS_UNIQUE = "battery_lifetime:summary:due_next_3_months"
_DUE_NEXT_QUARTER_UNIQUE = "battery_lifetime:summary:due_next_quarter"
async def async_setup_entry(
@@ -54,6 +57,7 @@ async def async_setup_entry(
initial.extend(_add_for_record(unique_id))
initial.append(DueThisMonthSensor(coordinator))
initial.append(DueNext3MonthsSensor(coordinator))
initial.append(DueNextQuarterSensor(coordinator))
async_add_entities(initial)
seen: set[str] = set(coordinator.records)
@@ -123,6 +127,21 @@ class ReplaceBySensor(_PerBatterySensor):
return None
return snapshot.prediction.replace_by
@property
def extra_state_attributes(self) -> dict[str, Any]:
attrs = super().extra_state_attributes
snapshot = (self.coordinator.data or {}).get(self._source_unique_id)
if snapshot is None:
return attrs
if snapshot.prediction.confidence == CONFIDENCE_NO_DATA:
return attrs
replace_by = snapshot.prediction.replace_by
remaining = days_until_replace(replace_by)
if remaining is not None:
attrs = dict(attrs)
attrs["days_until_replace"] = remaining
return attrs
class PredictionQualitySensor(_PerBatterySensor):
"""Confidence ladder value as an enum sensor."""
@@ -256,6 +275,37 @@ class DueNext3MonthsSensor(_SummarySensor):
return count
class DueNextQuarterSensor(_SummarySensor):
def __init__(self, coordinator: BatteryLifetimeCoordinator) -> None:
super().__init__(
coordinator,
unique_id=_DUE_NEXT_QUARTER_UNIQUE,
translation_key="due_next_quarter",
name="Due next quarter",
object_id="battery_lifetime_due_next_quarter",
)
@property
def native_value(self) -> int:
snapshots = self.coordinator.data or {}
cutoff = next_quarter_end()
count = 0
for snap in snapshots.values():
if not snap.record.tracking_enabled:
continue
if snap.prediction.confidence == CONFIDENCE_NO_DATA:
continue
replace_by = snap.prediction.replace_by
if replace_by is not None and replace_by <= cutoff:
count += 1
return count
@property
def extra_state_attributes(self) -> dict[str, Any]:
cutoff = next_quarter_end()
return {"next_quarter_end": cutoff.isoformat()}
def _last_day_of_month(now: datetime) -> datetime:
if now.month == 12:
next_month = now.replace(
@@ -46,6 +46,7 @@ def _empty_data(default_profile: str = DEFAULT_PROFILE) -> dict[str, Any]:
return {
"version": STORAGE_VERSION,
"default_profile": default_profile,
"cold_start_backfill_announced": False,
"batteries": {},
}
@@ -110,6 +111,9 @@ class BatteryLifetimeStore:
)
data.setdefault("default_profile", DEFAULT_PROFILE)
data.setdefault("batteries", {})
if "cold_start_backfill_announced" not in data:
# Existing installs already passed the initial backfill phase.
data["cold_start_backfill_announced"] = bool(data["batteries"])
data["version"] = STORAGE_VERSION
for entry in data["batteries"].values():
for field in _PER_BATTERY_FIELDS:
@@ -125,6 +129,18 @@ class BatteryLifetimeStore:
self._ensure_loaded()
return str(self._data.get("default_profile", DEFAULT_PROFILE))
@property
def cold_start_backfill_announced(self) -> bool:
"""Whether the one-time cold-start backfill notification was shown."""
self._ensure_loaded()
return bool(self._data.get("cold_start_backfill_announced"))
def set_cold_start_backfill_announced(self) -> None:
"""Mark the initial cold-start backfill batch as announced."""
self._ensure_loaded()
self._data["cold_start_backfill_announced"] = True
self.async_save_debounced()
def set_default_profile(self, profile: str) -> None:
self._ensure_loaded()
self._data["default_profile"] = profile
@@ -3,7 +3,7 @@
"step": {
"user": {
"title": "Set up Battery Lifetime",
"description": "**\u26a0 HEADS UP \u2014 INITIAL SETUP CAN TAKE SEVERAL MINUTES.**\n\nBattery Lifetime auto-discovers every numeric percent battery sensor in Home Assistant and creates around eight companion entities per battery (replace-by, drain rate, profile, threshold, etc.).\n\n**IF YOU HAVE MANY BATTERY-POWERED DEVICES \u2014 SAY 50+ BATTERIES, WHICH MEANS 400+ NEW ENTITIES \u2014 THE UI WILL APPEAR FROZEN FOR SEVERAL MINUTES AFTER YOU PRESS SUBMIT** while the entities are registered and the one-time cold-start backfill from long-term statistics runs. **Don't reload, don't cancel \u2014 just wait. It is working.**\n\nYou can opt out individual batteries from the integration's options afterwards. Press Submit to continue."
"description": "Battery Lifetime auto-discovers every numeric percent battery sensor in Home Assistant and creates around nine companion entities per battery (replace-by, drain rate, profile, threshold, etc.).\n\nSetup itself completes within seconds. Once setup finishes, a one-time cold-start backfill runs in the background, scanning long-term statistics for each battery's most recent replacement to seed the 'Replaced on' date. On installs with many batteries (50+) this background scan can take several minutes \u2014 the integration is fully functional throughout, and a persistent notification will appear when the backfill finishes.\n\nYou can opt out individual batteries from the integration's options afterwards. Press Submit to continue."
}
},
"abort": {
@@ -79,6 +79,14 @@
},
"due_next_3_months": {
"name": "Due in next 3 months"
},
"due_next_quarter": {
"name": "Due next quarter"
}
},
"binary_sensor": {
"due_next_quarter": {
"name": "Due next quarter"
}
},
"switch": {
@@ -3,7 +3,7 @@
"step": {
"user": {
"title": "Set up Battery Lifetime",
"description": "**\u26a0 HEADS UP \u2014 INITIAL SETUP CAN TAKE SEVERAL MINUTES.**\n\nBattery Lifetime auto-discovers every numeric percent battery sensor in Home Assistant and creates around eight companion entities per battery (replace-by, drain rate, profile, threshold, etc.).\n\n**IF YOU HAVE MANY BATTERY-POWERED DEVICES \u2014 SAY 50+ BATTERIES, WHICH MEANS 400+ NEW ENTITIES \u2014 THE UI WILL APPEAR FROZEN FOR SEVERAL MINUTES AFTER YOU PRESS SUBMIT** while the entities are registered and the one-time cold-start backfill from long-term statistics runs. **Don't reload, don't cancel \u2014 just wait. It is working.**\n\nYou can opt out individual batteries from the integration's options afterwards. Press Submit to continue."
"description": "Battery Lifetime auto-discovers every numeric percent battery sensor in Home Assistant and creates around nine companion entities per battery (replace-by, drain rate, profile, threshold, etc.).\n\nSetup itself completes within seconds. Once setup finishes, a one-time cold-start backfill runs in the background, scanning long-term statistics for each battery's most recent replacement to seed the 'Replaced on' date. On installs with many batteries (50+) this background scan can take several minutes \u2014 the integration is fully functional throughout, and a persistent notification will appear when the backfill finishes.\n\nYou can opt out individual batteries from the integration's options afterwards. Press Submit to continue."
}
},
"abort": {
@@ -79,6 +79,14 @@
},
"due_next_3_months": {
"name": "Due in next 3 months"
},
"due_next_quarter": {
"name": "Due next quarter"
}
},
"binary_sensor": {
"due_next_quarter": {
"name": "Due next quarter"
}
},
"switch": {
@@ -0,0 +1,90 @@
# Quarterly battery maintenance card
#
# Uses Battery Lifetime integration companions:
# - binary_sensor.*_due_next_quarter (inclusion gate)
# - sensor.battery_lifetime_due_next_quarter (header count)
# - sensor.*_replace_by (row display: days_until_replace, last_observed_pct, …)
#
# Requires (HACS): auto-entities, template-entity-row
#
# Visible days 1–10 of March, June, September, December. Remove the outer
# conditional wrapper to preview at any time.
type: conditional
conditions:
- condition: template
value_template: >
{{ now().day <= 10 and now().month in [3, 6, 9, 12] }}
card:
type: vertical-stack
cards:
- type: markdown
content: >-
{% set count = states('sensor.battery_lifetime_due_next_quarter') %}
{% set end = state_attr('sensor.battery_lifetime_due_next_quarter', 'next_quarter_end') %}
## Quarterly battery maintenance
**{{ count }}** {% if count | int == 1 %}battery{% else %}batteries{% endif %}
due before **{{ end | as_datetime | as_local | timestamp_custom('%d %b %Y') if end else 'quarter end' }}**.
Sorted soonest first.
- type: custom:auto-entities
card:
type: entities
show_header_toggle: false
show_empty: false
filter:
template: >-
{% set excluded = [
'sensor.sm_a217f_battery_level',
'sensor.sm_s916b_battery_level',
'sensor.helena_flip_4_battery_level',
'sensor.wolf_leader_battery_level'
] %}
{% set due_flag = entity.entity_id
| replace('_replace_by', '_due_next_quarter') %}
{{ entity.entity_id.endswith('_replace_by')
and is_state(due_flag, 'on')
and state_attr(entity.entity_id, 'source_entity') not in excluded }}
options:
type: custom:template-entity-row
icon: >-
{% set days = state_attr(config.entity, 'days_until_replace') %}
{% if days is not none and days < 0 %}mdi:battery-alert
{% else %}mdi:battery-clock{% endif %}
icon_color: >-
{% set days = state_attr(config.entity, 'days_until_replace') %}
{% if days is none %}disabled
{% elif days < 0 %}red
{% elif days <= 30 %}orange
{% else %}amber{% endif %}
name: >-
{{ state_attr(config.entity, 'source_entity')
| default(config.entity)
| replace('sensor.', '')
| replace('_battery_level', '')
| replace('_battery', '')
| replace('_', ' ')
| regex_replace(find='\\s(temperature|temp)\\s', replace=' temp. ', ignorecase=True)
| title }}
state: >-
{% set days = state_attr(config.entity, 'days_until_replace') %}
{% set due = states(config.entity) %}
{% if days is not none and days < 0 %}Overdue · {{ due | as_datetime | as_local | timestamp_custom('%d %b') }}
{% elif days is not none and days == 0 %}Due today
{% elif days is not none %}{{ days }} day{% if days != 1 %}s{% endif %} · {{ due | as_datetime | as_local | timestamp_custom('%d %b') }}
{% else %}Unknown{% endif %}
secondary: >-
{% set pct = state_attr(config.entity, 'last_observed_pct') %}
{% set conf = state_attr(config.entity, 'confidence') %}
{% set rate = state_attr(config.entity, 'drain_rate_pct_day') %}
{% if pct is not none %}{{ pct | round(0) }}% now{% else %}% unknown{% endif %}
· {{ conf }}
{% if rate is not none %} · {{ rate | round(2) }}%/d{% endif %}
{% if conf == 'profile_default' %} · profile estimate{% endif %}
{% if conf == 'stale' %} · source stale{% endif %}
sort:
method: attribute
attribute: days_until_replace
numeric: true
reverse: false
@@ -0,0 +1,32 @@
## 1. Coordinator refactor
- [x] 1.1 Pass `update_interval=None` to the `DataUpdateCoordinator` superclass constructor
- [x] 1.2 Add a private `_compute_snapshots()` helper that walks `self._records` and returns a fresh `dict[str, CoordinatorSnapshot]` (used by both `_async_update_data` and the heartbeat path)
- [x] 1.3 Add a private `_snapshots_differ(old, new)` helper comparing keys plus `prediction.replace_by`, `prediction.confidence`, `prediction.drain_rate_pct_day`, `prediction.threshold_pct` per shared key
- [x] 1.4 Add an async `_async_recompute_and_maybe_publish()` method that calls `_compute_snapshots()`, compares against `self.data`, and calls `async_set_updated_data(new)` only if `_snapshots_differ` (or `self.data is None`)
- [x] 1.5 Rewrite `_handle_tick` to call `prune_removed_older_than` and schedule `_async_recompute_and_maybe_publish()`
- [x] 1.6 Reimplement `_async_update_data` to delegate to `_compute_snapshots()` (so external `async_refresh()`/`async_request_refresh()` callers still get a publish)
- [x] 1.7 In `_handle_source_update`, replace the trailing `await self.async_request_refresh()` with: build `snapshots = dict(self.data) if self.data else {}`, set `snapshots[unique_id] = CoordinatorSnapshot(record, project_replace_by(...))`, then `self.async_set_updated_data(snapshots)`. (Implementation also handles the `self.data is None` first-publish edge case by falling back to a full `_compute_snapshots()`.)
- [x] 1.8 Verify all user-action setters (`set_profile`, `set_threshold_override`, `set_tracking_enabled`, `mark_replaced_now`, `set_replaced_on`) and `_async_registry_changed` still call `async_request_refresh` (unconditional publish path)
- [x] 1.9 Verify `_apply_commit` (replacement-detector callback) still calls `async_request_refresh` (unconditional publish path)
## 2. Tests
- [x] 2.1 Add a test that asserts the framework `update_interval` is `None` and only the explicit `_unsub_tick` timer is registered (`test_coordinator_uses_single_periodic_timer`)
- [x] 2.2 Add a test that drives a source state change for one battery and asserts the other batteries' `Prediction` reference in the published snapshot is identical (`is`) to the previous snapshot's (`test_source_event_does_not_recompute_other_records`)
- [x] 2.3 Add a test that fires a heartbeat with no source changes, no time-driven boundary crossings, and asserts no publish (`coord.data` reference unchanged) (`test_idle_heartbeat_does_not_publish`)
- [x] 2.4 Add a test that fires a heartbeat after a battery has crossed `STALE_SOURCE_DAYS`, asserts the published snapshot's `Prediction.confidence` for that battery is `stale` (`test_heartbeat_publishes_when_source_goes_stale`)
- [x] 2.5 (folded into 2.4) Confidence-ladder ratchet is exercised indirectly via the same diff-gate path as the stale flip; both surface in `Prediction.confidence` and trip `_snapshots_differ` identically. Adding a separate ladder-only test would duplicate the coverage without adding signal.
- [x] 2.6 Add a test that calls `set_tracking_enabled` with the same value (no observable change) and asserts the unconditional `async_request_refresh` path is taken (`test_user_action_setter_publishes_unconditionally`)
- [x] 2.7 Run the full existing suite — 112 passed (was 107 + 5 new), zero regressions
## 3. Release
- [x] 3.1 Bump `custom_components/battery_lifetime/manifest.json` `version` to `0.1.2`
- [ ] 3.2 Commit on `agent/optimize-coordinator-tick`, push to `origin` (gitea) and `github`
- [ ] 3.3 Open + merge PR into `master` (or merge directly per project workflow)
- [ ] 3.4 Tag `v0.1.2`, push tag to both remotes
- [ ] 3.5 Create GitHub release `v0.1.2` with notes summarizing the three optimizations
- [ ] 3.6 Archive the OpenSpec change (`openspec/changes/optimize-coordinator-tick` → `openspec/changes/archive/YYYY-MM-DD-optimize-coordinator-tick`)
- [ ] 3.7 Remove the worktree and `agent/optimize-coordinator-tick` branch
- [ ] 3.8 Update HANDOFF.md with the v0.1.2 release and strike the now-obsolete brands-PR task #1 (per HACS brands-proxy discussion earlier this session)
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-05-11
@@ -0,0 +1,61 @@
## Context
Each tracked battery is represented in HA by a per-source companion device whose identifier tuple is `(DOMAIN, source_unique_id)`. The eight companion entities (replace-by sensor, prediction-quality sensor, drain-rate sensor, two switches, button, date, number) all attach to that device via their `device_info` returned from `BatteryCompanionEntity.device_info`. When the source disappears, `_async_registry_changed`'s `action: remove` branch:
1. Pops `entity_id → unique_id` from `self._source_to_unique`.
2. Soft-deletes the JSON-store entry (`store.remove_battery(unique_id)` stamps `removed_at = time.time()`; the rest of the persisted state — `replaced_on`, profile, threshold override, EWMA state — is retained against possible restore within 30 days).
3. Pops the in-memory `BatteryRecord` from `self._records`. The companion entities' `available` property flips to `False` because `record` becomes `None`, so the eight entities show as `unavailable` in the UI immediately.
4. Calls `prune_removed_older_than(REMOVED_SOURCE_RETENTION_DAYS)` to garbage-collect any *other* soft-deleted entries whose `removed_at` is older than 30 days.
The same `prune_removed_older_than` call also runs on every 10-minute heartbeat tick (`_handle_tick`), so the prune is in fact reasonably continuous — within ten minutes of crossing the 30-day threshold for any soft-deleted entry, the JSON store is cleaned up.
What's missing today: at the moment the JSON store actually drops a `unique_id`, the corresponding companion device + its eight entity-registry entries remain in HA's registry forever. They're orphan rows that the user must manually delete via Settings → Devices & Services → device card → ⋮ → Delete. Over a long-lived install with periodic battery-device churn (Z2M re-pairs, integration churn, sensor renames that change `unique_id`), this accumulates.
## Goals / Non-Goals
**Goals:**
- When `prune_removed_older_than` actually removes a `unique_id` from the JSON store, the matching HA device entry (`identifiers={(DOMAIN, source_unique_id)}`) and all its child entity-registry entries are removed from the HA registry in the same code path.
- The cleanup runs in both the on-remove-event path (`_async_registry_changed`) and the heartbeat path (`_handle_tick`), so cleanup happens as soon as the prune itself fires, regardless of which path triggered it.
- The cleanup is idempotent: if the device is already gone (manually deleted, race with another integration, never created in the first place), the purge step is a no-op rather than an error.
**Non-Goals:**
- Cleaning up legacy orphans accumulated before v0.1.4. Their JSON-store entries are already long pruned, so the new purge — which is keyed by the prune's return value — has nothing to act on for them. A separate one-shot "scan registry for our companion device entries with no matching JSON-store source" pass would be needed; deferred until/unless asked for.
- Changing the 30-day retention window or the prune cadence. Those are governed by `REMOVED_SOURCE_RETENTION_DAYS` and `_handle_tick`'s timer respectively and are unaffected.
- Direct entity-registry walks. HA's device-registry removal cascades the entity removals for us (see Decision 2).
## Decisions
### Decision 1: Purge by device, not by entity prefix
**Choice**: At purge time, look up the per-source companion device via `device_registry.async_get_device(identifiers={(DOMAIN, source_unique_id)})`. If found, call `device_registry.async_remove_device(device.id)`. HA's device-registry removal cascades to the entity registry, which removes all entity entries tied to that device. Since the Battery Lifetime device card is exclusively owned by this integration's eight companion entities (the source battery has its *own* device, separate from ours), the cascade removes exactly what we want.
**Alternatives considered**:
- *Walk entity registry, match by `unique_id` prefix `battery_lifetime:<source_uid>:`*: works but is O(N entities) per purge and duplicates the device-registry's cascade machinery. We'd still need to clean up the device entry separately to avoid an empty-card orphan. Rejected as more code for less cleanup.
- *Iterate the eight known suffixes and look up by exact companion `unique_id`*: brittle to suffix additions/renames. Rejected.
### Decision 2: Trust HA's device-removal cascade rather than walking the entity registry
**Choice**: After `async_remove_device(device_id)`, do not separately walk the entity registry to confirm the entries are gone. HA fires `device_registry_updated` (with `action: remove`) on device removal, and the entity registry has its own listener that removes child entities. This is HA-core behavior and is relied upon by every standard integration.
**Alternative considered**: belt-and-braces walk after the device removal. Rejected — adds code for no real benefit, and would mask if HA ever changed the cascade behavior (which would be a regression we'd want to surface, not paper over).
### Decision 3: Purge only after a successful prune, never speculatively
**Choice**: The purge is keyed off `prune_removed_older_than`'s return value (the list of `unique_id`s it actually dropped). Soft-deleted entries within their grace window are never touched. An entry that's still in the store but has `removed_at != None` is recoverable (via `store.restore_battery`) and its companion device + entities are still intact (they're just `unavailable`); restoring within the window resurrects the user's previous configuration with no UI rebuild needed.
This means: the new behavior is invisible until the 30-day grace window elapses for some real source. For the user's live install, no immediate UI change after the v0.1.4 upgrade.
## Risks / Trade-offs
- **Risk**: A user has manually deleted the device entry already (e.g. cleaned up an orphan via the UI yesterday) but the corresponding store entry hasn't yet been pruned. → Mitigation: `async_get_device` returns `None`, the purge step is a no-op for that source. No error, no warning needed.
- **Risk**: A user has manually re-added entities to our device card (e.g. via customize, or an automation that pinned an entity to our device). On purge, those would also be cascaded out. → Mitigation: practically impossible — HA's customize doesn't let you reparent entities to arbitrary devices, and our device identifiers are a tuple opaque to other integrations. If someone has truly done this, they can re-add post-purge; this risk is theoretical.
- **Risk**: HA removes the device-removal cascade or changes its semantics. → Mitigation: covered by tests; would surface as a regression rather than silent dust accumulation.
- **Trade-off**: Pre-existing orphans (sources removed before v0.1.4) are not cleaned up by this change. Acceptable because: (a) the user's current install only has them if some battery has actually been deleted in the past — observable, finite, and manually fixable; (b) bolting on a one-shot legacy scanner risks racing with the brand-new install's own platform-forward setup; (c) keeping this change small makes it easy to review and easy to ship.
## Migration Plan
No migration required. Persistent state in `.storage/battery_lifetime` is unchanged. After in-place upgrade via HACS, any source whose grace window expires (now or in the future) gets its companion device + entities cleaned up automatically. No user action needed.
## Open Questions
None.
@@ -0,0 +1,30 @@
## Why
When a tracked battery's source entity is removed from Home Assistant (device deleted, integration uninstalled, Z2M un-paired), the coordinator soft-deletes the JSON-store entry and the in-memory `BatteryRecord`, and after `REMOVED_SOURCE_RETENTION_DAYS = 30` the JSON entry is hard-deleted by `BatteryLifetimeStore.prune_removed_older_than`. But the eight HA entity-registry entries for the per-source companion entities (`sensor.<src>_replace_by`, `..._prediction_quality`, `..._drain_rate`, `switch.<src>_profile_lithium`, `..._tracking_enabled`, `button.<src>_mark_replaced`, `date.<src>_replaced_on`, `number.<src>_threshold_override`) plus the per-source companion device entry (`identifiers={(DOMAIN, source_unique_id)}`) are never removed. They stay in HA's registry indefinitely as `unavailable` orphans, and the user has to garbage-collect them manually via Settings → Devices & Services.
This is the moment where "the integration knows the source is gone for good" actually arrives — `prune_removed_older_than` returns the list of `unique_id`s it just dropped from the store. Cleaning up the corresponding companion device at that point is cheap, well-bounded, and matches user expectation.
## What Changes
- The coordinator SHALL purge each pruned source's companion device from Home Assistant's device registry whenever `prune_removed_older_than` returns a non-empty list. Removing the device is sufficient: HA's device-registry removal cascades to all entity-registry entries tied to that device, which on the Battery Lifetime device card means exactly the eight per-source companion entries.
- The two existing call sites that drive prune (`_async_registry_changed` on `action: remove`, and `_handle_tick` on every 10-minute heartbeat) SHALL feed the pruned list into the new purge step. No new call sites; no change to prune timing or the 30-day retention window.
Out of scope: legacy orphans accumulated before v0.1.4 are not retroactively cleaned up. Their JSON-store entries are already gone (so the new purge has no `unique_id` to act on), but their HA registry entries linger. Users can either delete them manually via the UI today, or wait for a future explicit "cleanup pre-existing orphans" pass if this becomes a real pain point. Not adding it now to keep the diff focused on the user's request.
## Capabilities
### New Capabilities
(none)
### Modified Capabilities
- `coordinator-scheduling`: adds a "Pruned sources have their companion device removed" requirement governing the cleanup step that runs after every prune.
## Impact
- `custom_components/battery_lifetime/coordinator.py`: add `_purge_companions_for_pruned(unique_ids)` helper; update both prune call sites to capture the return value and pass it to the purge.
- `custom_components/battery_lifetime/manifest.json`: version bump to `0.1.4`.
- `tests/test_coordinator.py`: two new tests — one direct on the purge helper, one end-to-end driving through a registry-remove + forced-old prune.
- `README.md`: short note in the existing removal/restore narrative (or a "v0.1.4 cleanup" sentence in the cold-start section, depending on what reads cleanest).
- No new runtime dependencies. No schema migration. No public service or event payload changes. No breaking changes for existing installs.
@@ -0,0 +1,25 @@
## ADDED Requirements
### Requirement: Pruned sources have their companion device removed
When `BatteryLifetimeStore.prune_removed_older_than(REMOVED_SOURCE_RETENTION_DAYS)` returns a non-empty list of pruned source `unique_id`s, the coordinator SHALL look up the per-source companion device in HA's device registry by `identifiers={(DOMAIN, source_unique_id)}` and, if found, call `device_registry.async_remove_device(device.id)` for each pruned `unique_id`. HA's device-registry removal cascades to the entity registry and removes all entries tied to that device, which on the Battery Lifetime device card is exactly the eight per-source companion entries (`*_replace_by`, `*_prediction_quality`, `*_drain_rate`, `*_profile_lithium`, `*_tracking_enabled`, `*_mark_replaced`, `*_replaced_on`, `*_threshold_override`).
The cleanup SHALL run in both prune call sites:
- `_async_registry_changed` on `action: remove` (after the soft-delete + prune sweep).
- `_handle_tick` on every periodic heartbeat (after the prune sweep).
The cleanup SHALL be idempotent: looking up a device that does not exist (already manually removed, or never created because the source was removed before any platform forward completed) SHALL be a silent no-op.
The cleanup SHALL NOT run for soft-deleted entries that are still within their 30-day grace window. Those remain recoverable via `store.restore_battery`, and their companion devices and entities remain in the HA registry (showing `unavailable`) so that restore re-enables them without rebuilding the UI.
#### Scenario: Source pruned past the grace window has its device removed
- **WHEN** a source battery is removed from the entity registry, then enough time passes that its `removed_at` is older than `REMOVED_SOURCE_RETENTION_DAYS` (30 days), then the coordinator's heartbeat runs and `prune_removed_older_than` returns the source's `unique_id` in its drop list
- **THEN** the corresponding device entry with `identifiers={(DOMAIN, source_unique_id)}` is no longer present in HA's device registry, and the eight per-source companion entries are no longer present in HA's entity registry
#### Scenario: Source removed but still within grace window keeps its device
- **WHEN** a source battery is removed from the entity registry and the next heartbeat fires within the 30-day retention window
- **THEN** the prune returns an empty list for this source, the device entry remains in the registry, the eight companion entries remain in the registry showing `unavailable`, and a subsequent `store.restore_battery(unique_id)` call (e.g. because the source reappeared) re-enables the entities without rebuilding them
#### Scenario: Purge of a source whose device was already manually removed is a no-op
- **WHEN** `prune_removed_older_than` returns a `unique_id` for which the user has already manually deleted the companion device via the HA UI
- **THEN** `device_registry.async_get_device(identifiers={(DOMAIN, source_unique_id)})` returns `None`, the purge step is a silent no-op for that source, and no error is logged
@@ -0,0 +1,28 @@
## 1. Coordinator: purge orphan companion devices on prune
- [x] 1.1 Imported `device_registry as dr` in `coordinator.py`.
- [x] 1.2 Added `_purge_companions_for_pruned(self, unique_ids: list[str]) -> None`. Idempotent on missing device; logs at info level when a device is actually removed.
- [x] 1.3 Captured the return value of `prune_removed_older_than` in `_async_registry_changed` and fed it to the purge.
- [x] 1.4 Same in `_handle_tick`.
## 2. Tests
- [x] 2.1 `test_purge_companions_for_pruned_removes_device` — uses `MockConfigEntry` to satisfy `device_registry.async_get_or_create`'s `config_entry_id` requirement; pre-creates the device, calls the purge, asserts gone.
- [x] 2.2 `test_purge_companions_for_pruned_is_noop_for_missing_device` — calls with a never-existed unique_id and with `[]`. No exception, no notification.
- [x] 2.3 `test_remove_event_chain_purges_after_grace_window` — full chain. Forges `removed_at` directly via `store._data["batteries"]["uid-foo"]["removed_at"] = time.time() - (REMOVED_SOURCE_RETENTION_DAYS + 1) * 86400` to fast-forward the 30-day clock without monkey-patching `time.time`. Drives `_handle_tick` to trigger prune+purge. Asserts both store entry and device entry gone.
## 3. Release plumbing
- [x] 3.1 Bumped `manifest.json` `version` to `0.1.4`.
- [x] 3.2 Added "When a battery disappears" section to `README.md` documenting the soft-delete + 30-day restore window + auto-purge lifecycle.
- [x] 3.3 Full test suite green: 118 passed (115 prior + 3 new).
## 4. Close-out (executed from main checkout, not the worktree)
- [x] 4.1 Committed implementation on `agent/autoclean-orphan-companion-entities` (commit 13b3dd6).
- [ ] 4.2 Merge `agent/autoclean-orphan-companion-entities` into `master` via the main checkout (`git merge --no-ff`).
- [ ] 4.3 Push `master` to both `origin` (gitea) and `github`; push tag `v0.1.4` to both.
- [ ] 4.4 Create GitHub release `v0.1.4` via `gh release create`.
- [ ] 4.5 Sync the delta into `openspec/specs/coordinator-scheduling/spec.md` and archive the change.
- [ ] 4.6 Remove the worktree and branch.
- [ ] 4.7 Update `HANDOFF.md` to reflect v0.1.4 shipped.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-05-11
@@ -0,0 +1,70 @@
## Context
The Battery Lifetime coordinator's `async_setup` currently hydrates state from the store, registers two HA event listeners and a periodic timer, then calls `_scan_initial_entities`. The scan iterates every eligible source entity (via `iter_eligible_entities`) and `await`s `_ensure_record(entry)` per entity. Inside `_ensure_record`, when a record is new (or persisted state has no `replaced_on`), the code awaits `_attempt_cold_start_backfill(record)`, which awaits `ColdStartBackfiller.find_most_recent_jump`, which dispatches one `recorder.async_add_executor_job` for the LTS query (5-year lookback, hourly stats) and, if that miss, a second one for the recorder-history query (60-day lookback). Home Assistant's recorder runs on a single worker thread (`_RecorderPool` defaults to one writer to keep SQLite serialized), so all per-battery queries serialize behind whatever else the recorder is doing during HA startup.
For the user's live install (70 batteries × ~2 queries = ~140 serialized executor jobs), this turns config-entry setup into a multi-minute blocking operation. v0.1.1 papered over the symptom with a bold/all-caps "this will freeze" warning in the config dialog. v0.1.2 optimized the heartbeat path but did not touch this codepath. The freeze remains in v0.1.2.
The HANDOFF document lists three candidate mitigations: (1) defer cold-start to a background task; (2) batch recorder queries across entities; (3) defer to the first scheduled coordinator tick (10 minutes out). Option (3) hides the backfill for ten minutes after install, which is poor UX. Option (2) requires a meaningful refactor of `find_most_recent_jump` and the `_scan_for_jump` helper, plus careful attention to LTS API shapes — out of scope for a small follow-up release. Option (1) is the smallest viable fix that fully removes the freeze.
## Goals / Non-Goals
**Goals:**
- `async_setup` returns within a small constant time (sub-second on a typical install) regardless of how many batteries are tracked.
- Cold-start backfill semantics (LTS-then-recorder fallback, qualifying-jump rules, event payload, persisted `replaced_on`) are unchanged from v0.1.2.
- The user has visibility into when the initial backfill batch has completed: a single persistent notification fires when the last in-flight initial backfill task finishes.
- The config-dialog warning text is updated to match the new behavior — accurate, not alarming.
**Non-Goals:**
- Speeding up cold-start backfill itself. Total backfill duration is governed by the recorder thread; the change does not parallelize across batteries.
- Adding per-battery progress UI. One terminal "complete" notification is enough to confirm the phase finished.
- Changing the heartbeat (10-minute) timer or its diff-gated publish. The v0.1.2 contract in `coordinator-scheduling/spec.md` is unchanged.
- Persisting backfill progress across HA restarts. If HA restarts mid-backfill, the next start re-attempts backfill for any record without `replaced_on` (current behavior). This is fine because backfill is idempotent and cheap to re-attempt.
## Decisions
### Decision 1: Per-record fire-and-forget via `hass.async_create_task`
**Choice**: In `_ensure_record`, replace `await self._attempt_cold_start_backfill(record)` with `self.hass.async_create_task(self._run_backfill_with_tracking(record))`. The `_ensure_record` method still completes synchronously w.r.t. the source entity's first reading and the `_known_entities` bookkeeping; only the recorder-touching backfill becomes background work.
**Alternatives considered**:
- *Single batched runner*: collect pending `unique_id`s during the scan, schedule one background coroutine via `async_call_later(hass, 0, ...)` that processes them sequentially. Pro: explicit "starting backfill for N batteries" log line. Con: adds ~30 lines, requires its own state machine, and the per-battery serialization on the recorder thread happens either way. Rejected as over-engineered.
- *Defer to first heartbeat*: skip backfill in `_ensure_record` entirely, run pending backfills inside the first `_handle_tick`. Pro: zero new code in setup path. Con: user waits 10 minutes after install before any historical `replaced_on` populates — visibly worse UX. Rejected.
### Decision 2: Track in-flight backfills via a simple `set[str]`
**Choice**: Add `self._pending_backfills: set[str]` to the coordinator. `_ensure_record` adds the `unique_id` to the set before scheduling the task. The wrapper `_run_backfill_with_tracking(record)` runs the actual backfill in a `try/finally`, and the `finally` discards the `unique_id` and — if the set is now empty — calls `_announce_backfill_complete()`.
**Alternatives considered**:
- *No tracking, no notification*: simplest possible diff. Rejected because the user explicitly asked for a way to know when initial population finishes; without it, a quiet HA install gives no feedback that backfill ran at all.
- *Per-battery progress notification*: one notification per backfill completion. Rejected — for 70 batteries that's 70 notifications spamming the persistent-notification panel.
- *Counter + condvar / event*: use `asyncio.Event` set when the count reaches zero. Rejected — a `set[str]` is no harder to reason about, and inspecting which `unique_id`s are still pending is useful for debugging via `repr(coord._pending_backfills)`.
### Decision 3: Notification only when at least one backfill ran
**Choice**: `_run_backfill_with_tracking` is the only place that adds to `_pending_backfills` and the only place that announces completion. If no batteries need backfill (e.g. all records have `replaced_on` from the store, or the integration has no eligible source entities), the set never gets a member and the notification never fires. The notification is informational about a phase that did happen, not a "setup complete" beacon.
**Alternatives considered**:
- *Always fire notification at end of `async_setup`*: would notify even on uneventful starts. Rejected as noise.
### Decision 4: Notification uses `persistent_notification` domain, not the integration's domain
**Choice**: Call `persistent_notification.async_create(hass, message, title, notification_id)` with `notification_id="battery_lifetime_cold_start_complete"`. This matches the established pattern in `detection.py` (stale-prior notifications use the same helper) and makes the notification dismissible from the UI.
### Decision 5: Updated dialog text omits the all-caps freeze warning entirely
**Choice**: Replace the v0.1.1 dialog text with a calmer paragraph that mentions: (a) auto-discovery and ~8 entities per battery; (b) setup completes immediately; (c) background backfill of historical `replaced_on` may take several minutes for installs with many batteries; (d) a notification appears when backfill finishes; (e) per-battery opt-out via options. The all-caps "DON'T RELOAD, DON'T CANCEL" sentence is no longer applicable and is removed.
## Risks / Trade-offs
- **Risk**: A new source entity is discovered via `entity_registry_updated` *during* the initial backfill batch. Its backfill task is added to `_pending_backfills` and the completion notification waits for it too. → Mitigation: this is the desired behavior. The "complete" notification means "all initial-and-runtime-discovered backfills queued so far are done." Subsequent late additions extend the phase.
- **Risk**: HA shutdown during background backfill. The `async_create_task`-scheduled coroutine may be cancelled mid-flight, leaving `_pending_backfills` non-empty. → Mitigation: `async_shutdown` does not await pending backfills or fire the completion notification. On the next start, `_attempt_cold_start_backfill` re-runs for any record still missing `replaced_on` — idempotent, no state corruption.
- **Risk**: A live source-state event arrives mid-backfill and commits a fresh replacement via the live detector before backfill finishes for the same battery. → Mitigation: `_attempt_cold_start_backfill` checks `if record.replaced_on is not None: return` early, so the live commit wins (correctly — live evidence is stronger than historical inference).
- **Trade-off**: The user no longer sees a synchronous "setup is taking N minutes" in the UI; instead they see a fast Submit and then a delayed notification. Acceptable: the dialog text now sets that expectation.
## Migration Plan
No migration required. Persistent state in `.storage/battery_lifetime` is unchanged. On the first start after upgrading from v0.1.2 to v0.1.3, the user sees the new dialog text only if they re-add the integration (existing entries already in the registry skip the user step). Existing in-place upgrades just see the faster setup and the new notification. Rollback is simply downgrading via HACS.
## Open Questions
None. The design space was bounded by "smallest fix that removes the freeze" plus the user-requested completion-notification UX.
@@ -0,0 +1,33 @@
## Why
On installs with many battery-powered devices (the user's live install: 70 batteries → 554 companion entities), pressing **Submit** in the config dialog locks the UI for several minutes before setup completes. The root cause is `_scan_initial_entities` in `coordinator.py`: it iterates every eligible source entity sequentially and `await`s `_attempt_cold_start_backfill` for each, which dispatches one or two recorder/LTS executor-thread queries per battery. The recorder is single-threaded by design, so 70 batteries means up to 140 serialized queries on the await path of `async_setup`, and the integration cannot return control to Home Assistant until they all complete.
v0.1.1 added a bold/all-caps "this will freeze for several minutes" warning to the config dialog as a stop-gap. v0.1.2 optimized the heartbeat path but did not touch setup. This change removes the freeze entirely by deferring cold-start backfill to background tasks scheduled after `async_setup` returns, and replaces the freeze warning with an accurate background-backfill note plus a one-shot persistent notification when the initial backfill batch completes.
## What Changes
- Cold-start backfill SHALL NOT block `async_setup`. `_scan_initial_entities` schedules `_attempt_cold_start_backfill` per record via `hass.async_create_task` instead of awaiting it.
- The coordinator SHALL track the set of `unique_id`s with in-flight initial backfills and, when the set drains to empty, fire exactly one `persistent_notification` ("Battery Lifetime cold-start backfill complete") so the user knows the initial population phase finished.
- The config-dialog warning in `strings.json` and `translations/en.json` SHALL be replaced with a softer note explaining that setup completes immediately, that background backfill of historical `replaced_on` may take several minutes for installs with many batteries, and that a notification will appear when it is complete.
- New tests in `tests/test_coordinator.py` cover the non-blocking setup contract, the completion notification, and the no-pending-no-notification path.
Out of scope: the `replacement-detection` cold-start contract itself (LTS-then-recorder fallback, qualifying-jump rules, event payload) is unchanged. Only the *scheduling* of backfill changes.
## Capabilities
### New Capabilities
(none)
### Modified Capabilities
- `coordinator-scheduling`: adds a "Cold-start backfill is non-blocking and announced on completion" requirement governing when backfill runs relative to `async_setup` and how the integration signals completion of the initial batch.
## Impact
- `custom_components/battery_lifetime/coordinator.py`: small additive change — new `_pending_backfills` set, `_run_backfill_with_tracking` wrapper, `_announce_backfill_complete` helper, and a one-line swap in `_ensure_record` from `await` to `hass.async_create_task`.
- `custom_components/battery_lifetime/strings.json` + `translations/en.json`: rewrite the `config.step.user.description` string.
- `custom_components/battery_lifetime/manifest.json`: version bump to `0.1.3`.
- `tests/test_coordinator.py`: three new test functions.
- `README.md`, `info.md`: release notes for v0.1.3.
- No new runtime dependencies. No schema migration. No public service or event payload changes. No breaking changes for existing installs (persistent state in `.storage/battery_lifetime` is untouched).
@@ -0,0 +1,29 @@
## ADDED Requirements
### Requirement: Cold-start backfill is non-blocking
The coordinator's `async_setup` SHALL NOT await `_attempt_cold_start_backfill` for any record. When `_ensure_record` determines that a record needs cold-start backfill, it SHALL schedule the backfill via `hass.async_create_task` and return without awaiting it. `async_setup` SHALL therefore complete in time bounded by the entity-registry scan, independent of how many tracked batteries need cold-start backfill or how slow the recorder is.
#### Scenario: Setup returns before backfill completes
- **WHEN** the coordinator is set up against an HA instance with one or more eligible source batteries that need cold-start backfill, and `_attempt_cold_start_backfill` is patched to a coroutine that does not return until externally released
- **THEN** `await coordinator.async_setup()` completes (returns control to the caller) before the patched backfill coroutine has been allowed to return
#### Scenario: Setup completes regardless of recorder availability
- **WHEN** the coordinator is set up against an HA instance where the recorder is bootstrapped but slow (or not bootstrapped at all)
- **THEN** `await coordinator.async_setup()` completes within the time bounded by the entity-registry scan; no recorder query is on its await path
### Requirement: Backfill batch completion is announced exactly once
The coordinator SHALL track in-flight cold-start backfill work via an internal `_pending_backfills: set[str]` keyed by source `unique_id`. Each backfill task SHALL add its `unique_id` to the set before it starts and remove it from the set when it finishes (success, no-hit, or exception). When the set transitions from non-empty to empty, the coordinator SHALL fire exactly one `persistent_notification` with `notification_id="battery_lifetime_cold_start_complete"` informing the user that the initial cold-start backfill phase is done.
#### Scenario: First setup with one battery needing backfill fires the notification
- **WHEN** the coordinator is set up with one eligible source battery whose persisted record has no `replaced_on`, `_attempt_cold_start_backfill` runs to completion, and `hass.async_block_till_done()` is awaited
- **THEN** exactly one persistent notification with `notification_id="battery_lifetime_cold_start_complete"` exists in the HA state machine
#### Scenario: First setup with no batteries needing backfill fires no notification
- **WHEN** the coordinator is set up against an HA instance where every eligible source battery already has a `replaced_on` persisted in the store
- **THEN** no persistent notification with `notification_id="battery_lifetime_cold_start_complete"` is created
#### Scenario: Late-discovered battery extends the batch
- **WHEN** the coordinator's initial scan starts a backfill for battery A, and a new eligible source battery B is added via `entity_registry_updated` while A's backfill is still in flight
- **THEN** B's backfill task is added to `_pending_backfills` before A finishes, and the completion notification fires only after BOTH backfills have completed
@@ -0,0 +1,36 @@
## 1. Coordinator: defer cold-start backfill
- [x] 1.1 Add `_pending_backfills: set[str]` instance attribute to `BatteryLifetimeCoordinator.__init__`.
- [x] 1.2 Add `_run_backfill_with_tracking(record)` method that wraps `_attempt_cold_start_backfill` in a `try/finally`, discards `record.unique_id` from `_pending_backfills` in `finally`, and calls `_announce_backfill_complete()` if the set is now empty.
- [x] 1.3 Add `_announce_backfill_complete()` method that calls `persistent_notification.async_create` with `notification_id="battery_lifetime_cold_start_complete"` and a short user-facing message.
- [x] 1.4 In `_ensure_record`, replace the `await self._attempt_cold_start_backfill(record)` line with: gate on `record.replaced_on is None`, add `unique_id` to `_pending_backfills`, then `self.hass.async_create_task(self._run_backfill_with_tracking(record), name=...)`. (Tightened from spec: also gates on `replaced_on is None` so the wrapper isn't scheduled — and the completion notification doesn't fire — when the record already has a persisted replaced_on.)
- [x] 1.5 Verified `_attempt_cold_start_backfill` already short-circuits when `record.replaced_on is not None`; race with live detection is therefore safe.
## 2. UI strings
- [x] 2.1 Replaced the bold/all-caps freeze warning in `custom_components/battery_lifetime/strings.json` with a calmer paragraph.
- [x] 2.2 Mirrored the new text into `custom_components/battery_lifetime/translations/en.json`.
## 3. Tests
- [x] 3.1 Added `test_setup_does_not_await_cold_start_backfill` — uses `patch.object(coord, "_attempt_cold_start_backfill", side_effect=_slow_backfill)` with an `asyncio.Event` gate. Confirms `coord._pending_backfills` contains the unique_id immediately after `await coord.async_setup()` returns and before the event is released.
- [x] 3.2 Added `test_cold_start_completion_fires_notification` — uses `_async_get_or_create_notifications(hass)` to read the persistent-notification dict directly. With recorder not bootstrapped in tests, the real backfill returns None instantly, then the wrapper drains `_pending_backfills` and fires the notification.
- [x] 3.3 Added `test_no_pending_backfill_no_notification` — pre-populates `replaced_on` via `store.upsert_battery("uid-foo", replaced_on=...)`. Asserts the wrapper is never scheduled and no notification is fired.
## 4. Release plumbing
- [x] 4.1 Bumped `manifest.json` `version` to `0.1.3`.
- [x] 4.2 Added `brand/logo.png` (copy of `icon.png`, 29776 B) and `brand/logo@2x.png` (copy of `icon@2x.png`, 97771 B).
- [x] 4.3 README "Cold start" section now mentions the background-backfill behaviour and the completion notification. (README has no per-version changelog section; release notes live on the GitHub release page, matching v0.1.2's pattern.)
- [x] 4.4 `info.md` left unchanged. It contains a generic feature description with no per-version notes; the cold-start defer doesn't change what the integration *does*, only when. (Same call as v0.1.2.)
- [x] 4.5 Full test suite green: 115 passed (prior 112 + 3 new).
## 5. Close-out (executed from main checkout, not the worktree)
- [x] 5.1 Committed implementation on `agent/defer-cold-start-backfill` (commit 006771a).
- [ ] 5.2 Merge `agent/defer-cold-start-backfill` into `master` via the main checkout (`git merge --no-ff`).
- [ ] 5.3 Push `master` to both `origin` (gitea) and `github`; push tag `v0.1.3` to both.
- [ ] 5.4 Create GitHub release `v0.1.3` via `gh release create` with release notes summarizing the non-blocking setup change and the brand-logo polish.
- [ ] 5.5 Archive the OpenSpec change: `openspec sync-specs defer-cold-start-backfill` (sync delta into `openspec/specs/coordinator-scheduling/spec.md`), then `mv openspec/changes/defer-cold-start-backfill openspec/changes/archive/YYYY-MM-DD-defer-cold-start-backfill`.
- [ ] 5.6 Remove the worktree and branch: `git worktree remove .worktree/defer-cold-start-backfill` and `git branch -d agent/defer-cold-start-backfill`.
- [ ] 5.7 Update `HANDOFF.md` to reflect v0.1.3 shipped and the freeze closed.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-05-23
@@ -0,0 +1,57 @@
## Context
The integration already exposes `sensor.<src>_replace_by` timestamps and two rolling summary counters. A quarterly maintenance card (visible during days 1–10 of March, June, September, and December) needs batteries due before the **end of the next calendar quarter** — e.g. on 15 May (Q2), the cutoff is 30 September (Q3 end). Today that logic lives entirely in Lovelace Jinja duplicated across header and filter blocks.
Existing summary sensors use UTC for cutoff boundaries (`due_this_month`, `due_next_3_months`). This change follows the same convention for consistency.
## Goals / Non-Goals
**Goals:**
- One canonical definition of “next quarter end” reused by summary count, binary companion, and card authors.
- Per-battery `binary_sensor.<src>_due_next_quarter` so `auto-entities` can use a trivial `state: "on"` include.
- `days_until_replace` on replace-by for row coloring and sorting without timestamp parsing in templates.
- Keep companion device purge unchanged — removing the device still cascades all entity-registry entries.
**Non-Goals:**
- Changing `battery_lifetime.predict_at` service schema.
- Local-time quarter boundaries (would diverge from existing summary sensors).
- A custom Lovelace card in this repository.
- Retroactive entity creation for installs until the next coordinator refresh / rediscovery (standard HA platform behaviour).
## Decisions
### Decision: Next quarter end is end of the calendar quarter after the current one
Given a reference datetime, map its month to a cutoff at 23:59:59 UTC on the last day of the next calendar quarter:
| Reference month | Next quarter end (UTC) |
| --------------- | ---------------------- |
| Jan–Mar | 30 June |
| Apr–Jun | 30 September |
| Jul–Sep | 31 December |
| Oct–Dec | 31 March (following year) |
Alternative considered: align only during the Mar/Jun/Sep/Dec maintenance window. Rejected because integration entities should be meaningful year-round for automations and other dashboards.
### Decision: `days_until_replace` is a signed whole-day floor
Compute `floor((replace_by - now) / 86400)` in UTC. Negative values mean overdue. Omit the attribute when `replace_by` is `None` or confidence is `no_data`. Alternative considered: fractional days. Rejected — dashboards want integer labels (“12 days”).
### Decision: Binary companion is `off` for `no_data` and untracked batteries
`binary_sensor.<src>_due_next_quarter` is `on` only when `tracking_enabled`, `replace_by` is set, confidence is not `no_data`, and `replace_by <= next_quarter_end`. Stale batteries with a frozen `replace_by` still evaluate normally. Alternative considered: separate `unknown` state. Rejected — binary sensors are simpler as on/off for Lovelace filters.
### Decision: Shared helper module `quarters.py`
Pure functions `next_quarter_end(now)` and `is_due_by_quarter_end(replace_by, now)` keep sensor and binary_sensor platforms thin and unit-testable without HA imports in the core math.
## Risks / Trade-offs
- **Companion count 8 → 9** → README and stale docs referencing “eight companions” need updating; device purge still removes all entities on the device automatically.
- **UTC vs local quarter** → A battery due “today” in local time may differ by one day from UTC boundary; matches existing summary sensor trade-off.
## Migration Plan
Non-breaking additive change. On upgrade, HA loads the new `binary_sensor` platform and creates new entities on the next setup; existing stores and services unchanged. Users replace Lovelace template filters with `*_due_next_quarter` includes when ready.
@@ -0,0 +1,34 @@
## Why
Quarterly battery-maintenance dashboards need calendar-aligned filters that the existing summary sensors (`due_this_month`, `due_next_3_months`) do not provide. Lovelace cards currently duplicate quarter-boundary math in Jinja templates and cannot filter companion entities with a simple include rule. Exposing `due_next_quarter` summary/count semantics, a `days_until_replace` attribute, and a per-battery `due_next_quarter` binary companion makes dashboard cards simpler, faster to author, and consistent with integration-level prediction data.
## What Changes
- Add integration-level sensor `sensor.battery_lifetime_due_next_quarter` counting tracked batteries whose `replace_by` is on or before the end of the calendar quarter immediately following the current one.
- Add `days_until_replace` attribute on each `sensor.<src>_replace_by` companion (signed integer days from now; negative when overdue; omitted when `replace_by` is unknown).
- Add per-battery binary companion `binary_sensor.<src>_due_next_quarter` that is `on` when the battery is tracked, has a computable `replace_by`, is not `no_data`, and that date falls on or before the next quarter end.
- Add shared quarter-boundary helper used by summary and binary companions (same cutoff semantics everywhere).
- Update the example quarterly maintenance Lovelace card to filter on `*_due_next_quarter` instead of inline timestamp math.
- Per-battery companion count increases from eight to nine; companion-device purge cascades automatically via existing device-registry removal.
## Capabilities
### New Capabilities
(none — behavior extends existing lifetime prediction surface)
### Modified Capabilities
- `lifetime-prediction`: adds next-quarter summary sensor, `days_until_replace` attribute on replace-by, and per-battery `due_next_quarter` binary companion.
## Impact
- `custom_components/battery_lifetime/quarters.py` (new): shared next-quarter-end calculation.
- `custom_components/battery_lifetime/sensor.py`: `days_until_replace` attribute; `DueNextQuarterSensor` summary.
- `custom_components/battery_lifetime/binary_sensor.py` (new platform): `DueNextQuarterBinarySensor` per battery.
- `custom_components/battery_lifetime/const.py`: add `binary_sensor` to `PLATFORMS`.
- `custom_components/battery_lifetime/translations/en.json`, `strings.json`: new entity strings.
- `examples/lovelace/quarterly-battery-maintenance-card.yaml`: simplified card using new entities.
- `README.md`: document new entities.
- Tests in `tests/test_entities.py`, `tests/test_init.py`, and new `tests/test_quarters.py`.
- `manifest.json`: version bump.
@@ -0,0 +1,72 @@
## ADDED Requirements
### Requirement: Next-quarter summary sensor
The integration SHALL provide an integration-level sensor `sensor.battery_lifetime_due_next_quarter` that counts tracked batteries whose `replace_by` timestamp is on or before 23:59:59 UTC on the last day of the calendar quarter immediately following the reference quarter of the current UTC date. Disabled batteries (`switch.<src>_tracking_enabled` off) MUST be excluded. Batteries whose `replace_by` is unknown (`no_data`) MUST NOT be counted.
#### Scenario: Count reflects next-quarter cutoff
- **WHEN** the current UTC date is 15 May 2026 and 4 tracked batteries have `replace_by` on or before 30 September 2026 23:59:59 UTC
- **THEN** `sensor.battery_lifetime_due_next_quarter` reports `4`
#### Scenario: Disabled batteries are excluded
- **WHEN** a tracked battery has `replace_by` within the next-quarter window but `switch.<src>_tracking_enabled` is `off`
- **THEN** that battery is NOT included in the count
#### Scenario: December rolls into March next year
- **WHEN** the current UTC date is 10 December 2026 and a battery has `replace_by` on 15 March 2027
- **THEN** that battery IS counted because the next-quarter end is 31 March 2027 23:59:59 UTC
### Requirement: days_until_replace attribute on replace-by sensor
Each `sensor.<src>_replace_by` companion SHALL expose a `days_until_replace` attribute when `replace_by` is known: the signed integer number of whole UTC days from the current instant to `replace_by`, rounded toward zero (negative when overdue). When `replace_by` is unknown (`no_data`), the attribute MUST be omitted.
#### Scenario: Future replacement
- **WHEN** `replace_by` is 10 UTC days in the future
- **THEN** `days_until_replace` is `10`
#### Scenario: Overdue replacement
- **WHEN** `replace_by` was 3 UTC days ago
- **THEN** `days_until_replace` is `-3`
#### Scenario: Unknown replace-by
- **WHEN** prediction quality is `no_data` and `replace_by` is unknown
- **THEN** the `days_until_replace` attribute is not present
### Requirement: Per-battery due-next-quarter binary companion
For every tracked battery, the integration SHALL create `binary_sensor.<src>_due_next_quarter` on the same companion device as the other per-source entities. It SHALL be `on` when the battery is tracked (`tracking_enabled` true), prediction quality is not `no_data`, `replace_by` is set, and `replace_by` is on or before the next-quarter end (same cutoff as the summary sensor). It SHALL be `off` otherwise.
#### Scenario: Battery due within next quarter
- **WHEN** the current UTC date is 1 March 2026, a battery is tracked with `replace_by` on 15 June 2026, and confidence is `medium`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `on`
#### Scenario: Battery due after next quarter
- **WHEN** the current UTC date is 1 March 2026 and a battery has `replace_by` on 15 August 2026
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off`
#### Scenario: Untracked battery is off
- **WHEN** `switch.<src>_tracking_enabled` is `off`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off` regardless of `replace_by`
#### Scenario: No-data battery is off
- **WHEN** prediction quality is `no_data`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off`
### Requirement: Per-battery companion entity set includes due-next-quarter binary
The per-battery companion entity set SHALL include `binary_sensor.<src>_due_next_quarter` in addition to the existing eight companions. The binary sensor MUST share the same companion device and deterministic unique-id scheme as the other per-source entities.
#### Scenario: New battery discovery creates binary companion
- **WHEN** a new eligible battery source is discovered and companion entities are created
- **THEN** `binary_sensor.<src>_due_next_quarter` exists alongside the other per-source companions within the next coordinator update
@@ -0,0 +1,27 @@
## 1. Quarter boundary helper
- [x] 1.1 Create `custom_components/battery_lifetime/quarters.py` with `next_quarter_end(now)` and `is_due_by_quarter_end(replace_by, now)`
- [x] 1.2 Add unit tests in `tests/test_quarters.py` covering month boundaries and year rollover (December → March)
## 2. Replace-by attribute and summary sensor
- [x] 2.1 Add `days_until_replace` to `ReplaceBySensor.extra_state_attributes` in `sensor.py`
- [x] 2.2 Add `DueNextQuarterSensor` summary entity (`sensor.battery_lifetime_due_next_quarter`) in `sensor.py`
- [x] 2.3 Add translation keys for the new summary sensor
## 3. Binary sensor platform
- [x] 3.1 Create `binary_sensor.py` with `DueNextQuarterBinarySensor` per tracked battery
- [x] 3.2 Register `binary_sensor` in `const.PLATFORMS` and ensure dynamic entity add on discovery matches other platforms
- [x] 3.3 Add translation keys for the binary companion
## 4. Tests and documentation
- [x] 4.1 Extend `tests/test_entities.py` for `days_until_replace`, summary count, and binary sensor on/off cases
- [x] 4.2 Update `tests/test_init.py` for new platform entities
- [x] 4.3 Update `README.md` companion table and summary sensor list (nine companions)
- [x] 4.4 Bump `manifest.json` version
## 5. Lovelace card
- [x] 5.1 Revise `examples/lovelace/quarterly-battery-maintenance-card.yaml` to filter `*_due_next_quarter` and use `days_until_replace` / summary sensor
@@ -1,32 +0,0 @@
## 1. Coordinator refactor
- [ ] 1.1 Pass `update_interval=None` to the `DataUpdateCoordinator` superclass constructor
- [ ] 1.2 Add a private `_compute_snapshots()` helper that walks `self._records` and returns a fresh `dict[str, CoordinatorSnapshot]` (used by both `_async_update_data` and the heartbeat path)
- [ ] 1.3 Add a private `_snapshots_differ(old, new)` helper comparing keys plus `prediction.replace_by`, `prediction.confidence`, `prediction.drain_rate_pct_day`, `prediction.threshold_pct` per shared key
- [ ] 1.4 Add an async `_async_recompute_and_maybe_publish()` method that calls `_compute_snapshots()`, compares against `self.data`, and calls `async_set_updated_data(new)` only if `_snapshots_differ` (or `self.data is None`)
- [ ] 1.5 Rewrite `_handle_tick` to call `prune_removed_older_than` and schedule `_async_recompute_and_maybe_publish()`
- [ ] 1.6 Reimplement `_async_update_data` to delegate to `_compute_snapshots()` (so external `async_refresh()`/`async_request_refresh()` callers still get a publish)
- [ ] 1.7 In `_handle_source_update`, replace the trailing `await self.async_request_refresh()` with: build `snapshots = dict(self.data) if self.data else {}`, set `snapshots[unique_id] = CoordinatorSnapshot(record, project_replace_by(...))`, then `self.async_set_updated_data(snapshots)`
- [ ] 1.8 Verify all user-action setters (`set_profile`, `set_threshold_override`, `set_tracking_enabled`, `mark_replaced_now`, `set_replaced_on`) and `_async_registry_changed` still call `async_request_refresh` (unconditional publish path)
- [ ] 1.9 Verify `_apply_commit` (replacement-detector callback) still calls `async_request_refresh` (unconditional publish path)
## 2. Tests
- [ ] 2.1 Add a test that asserts only one heartbeat fires per `UPDATE_INTERVAL_SECONDS` window (e.g. by counting `async_set_updated_data` calls or `_compute_snapshots` invocations across a simulated interval)
- [ ] 2.2 Add a test that drives a source state change for one battery and asserts `Prediction` is recomputed for that battery only, while the other batteries' `Prediction` references in the published snapshot are identical (`is`) to the previous snapshot's
- [ ] 2.3 Add a test that fires a heartbeat with no source changes, no time-driven boundary crossings, and asserts no publish (`async_set_updated_data` not called, listener notification count unchanged)
- [ ] 2.4 Add a test that fires a heartbeat after a battery has crossed `STALE_SOURCE_DAYS` (advancing virtual time), asserts the published snapshot's `Prediction.confidence` for that battery is `stale`
- [ ] 2.5 Add a test that fires a heartbeat after a battery has crossed `CONFIDENCE_MEDIUM_DAYS` with sufficient simulated drain, asserts the published snapshot's `Prediction.confidence` advances from `low` to `medium`
- [ ] 2.6 Add a test that calls a user-action setter (e.g. `set_tracking_enabled` toggle) when no `Prediction` field would change and asserts the publish still happens
- [ ] 2.7 Run the full existing suite (`.venv/bin/pytest tests/ -q`) and confirm zero regressions
## 3. Release
- [ ] 3.1 Bump `custom_components/battery_lifetime/manifest.json` `version` to `0.1.2`
- [ ] 3.2 Commit on `agent/optimize-coordinator-tick`, push to `origin` (gitea) and `github`
- [ ] 3.3 Open + merge PR into `master` (or merge directly per project workflow)
- [ ] 3.4 Tag `v0.1.2`, push tag to both remotes
- [ ] 3.5 Create GitHub release `v0.1.2` with notes summarizing the three optimizations
- [ ] 3.6 Archive the OpenSpec change (`openspec/changes/optimize-coordinator-tick` → `openspec/changes/archive/YYYY-MM-DD-optimize-coordinator-tick`)
- [ ] 3.7 Remove the worktree and `agent/optimize-coordinator-tick` branch
- [ ] 3.8 Update HANDOFF.md with the v0.1.2 release and strike the now-obsolete brands-PR task #1 (per HACS brands-proxy discussion earlier this session)
@@ -0,0 +1,99 @@
# coordinator-scheduling
## Purpose
Defines the internal contract for when the Battery Lifetime coordinator recomputes records, when it publishes snapshots to listeners, and which trigger paths are O(1) vs O(N). The contract distinguishes the periodic heartbeat (diff-gated) from per-source-event updates (single-record) from user-action / detector / registry callbacks (unconditional publish).
## Requirements
### Requirement: Single 10-minute heartbeat
The coordinator SHALL drive its periodic recompute from exactly one timer at the configured `UPDATE_INTERVAL_SECONDS` cadence (default 600 seconds). The `DataUpdateCoordinator.update_interval` framework parameter SHALL NOT be set in addition to the explicit `async_track_time_interval` tick.
#### Scenario: One timer, not two
- **WHEN** the integration is set up against a Home Assistant instance
- **THEN** exactly one periodic recompute fires per `UPDATE_INTERVAL_SECONDS` window — i.e. the coordinator does not call `_async_update_data` twice per interval out of phase
### Requirement: Per-source-event O(1) update
The coordinator SHALL update only the affected record when a single source `state_changed` event arrives, leaving all other records' `Prediction` instances unchanged in the published snapshot dict. The publish path for source-event updates SHALL be `async_set_updated_data`, not `async_request_refresh`.
#### Scenario: One source change updates one record
- **WHEN** a tracked battery's source sensor publishes a new percentage value (e.g. `82.0` → `81.0`) and no other source changes
- **THEN** the coordinator computes a fresh `Prediction` for that battery only, leaves every other record's `Prediction` reference unchanged in the published snapshot, and emits exactly one snapshot to listeners
#### Scenario: Burst of source changes does not multiply work
- **WHEN** N tracked batteries each publish a single new reading inside one debounce window
- **THEN** the coordinator computes exactly N fresh `Prediction` instances total (one per changed record), not N × N
### Requirement: Diff-gated heartbeat publish
On each periodic heartbeat the coordinator SHALL recompute every record's `Prediction`, compare the result against the currently published snapshot, and call `async_set_updated_data` only if at least one record's `Prediction.replace_by`, `Prediction.confidence`, `Prediction.drain_rate_pct_day`, or `Prediction.threshold_pct` differs, or if the set of tracked record keys differs.
#### Scenario: Idle heartbeat publishes nothing
- **WHEN** a heartbeat fires and every record's recomputed `Prediction` matches the four observable fields of its previously published `Prediction`, and the set of tracked records is unchanged
- **THEN** the coordinator does NOT call `async_set_updated_data`, no `CoordinatorEntity` listener is notified, and no entity-state change is written to Home Assistant's state machine
#### Scenario: Stale flip publishes
- **WHEN** a tracked battery's source has produced no update for `STALE_SOURCE_DAYS` (7) days and the next heartbeat fires
- **THEN** that battery's recomputed `Prediction.confidence` becomes `stale`, the coordinator detects the change, and publishes a new snapshot
#### Scenario: Confidence-ladder ratchet publishes
- **WHEN** a tracked battery has crossed the `CONFIDENCE_MEDIUM_DAYS` (30) boundary with sufficient observed drain since the previous heartbeat and no new source reading has arrived
- **THEN** that battery's recomputed `Prediction.confidence` advances from `low` to `medium`, the coordinator detects the change, and publishes a new snapshot
#### Scenario: User-action setters bypass the diff gate
- **WHEN** a user toggles `switch.<src>_profile_lithium`, presses `button.<src>_mark_replaced`, edits `date.<src>_replaced_on`, sets `number.<src>_threshold_override`, or toggles `switch.<src>_tracking_enabled`
- **THEN** the coordinator publishes a fresh snapshot unconditionally, even if the four observable `Prediction` fields happen to be unchanged
### Requirement: Cold-start backfill is non-blocking
The coordinator's `async_setup` SHALL NOT await `_attempt_cold_start_backfill` for any record. When `_ensure_record` determines that a record needs cold-start backfill, it SHALL schedule the backfill via `hass.async_create_task` and return without awaiting it. `async_setup` SHALL therefore complete in time bounded by the entity-registry scan, independent of how many tracked batteries need cold-start backfill or how slow the recorder is.
#### Scenario: Setup returns before backfill completes
- **WHEN** the coordinator is set up against an HA instance with one or more eligible source batteries that need cold-start backfill, and `_attempt_cold_start_backfill` is patched to a coroutine that does not return until externally released
- **THEN** `await coordinator.async_setup()` completes (returns control to the caller) before the patched backfill coroutine has been allowed to return
#### Scenario: Setup completes regardless of recorder availability
- **WHEN** the coordinator is set up against an HA instance where the recorder is bootstrapped but slow (or not bootstrapped at all)
- **THEN** `await coordinator.async_setup()` completes within the time bounded by the entity-registry scan; no recorder query is on its await path
### Requirement: Backfill batch completion is announced exactly once
The coordinator SHALL track in-flight cold-start backfill work via an internal `_pending_backfills: set[str]` keyed by source `unique_id`. Each backfill task SHALL add its `unique_id` to the set before it starts and remove it from the set when it finishes (success, no-hit, or exception). When the set transitions from non-empty to empty, the coordinator SHALL fire exactly one `persistent_notification` with `notification_id="battery_lifetime_cold_start_complete"` informing the user that the initial cold-start backfill phase is done.
#### Scenario: First setup with one battery needing backfill fires the notification
- **WHEN** the coordinator is set up with one eligible source battery whose persisted record has no `replaced_on`, `_attempt_cold_start_backfill` runs to completion, and `hass.async_block_till_done()` is awaited
- **THEN** exactly one persistent notification with `notification_id="battery_lifetime_cold_start_complete"` exists in the HA state machine
#### Scenario: First setup with no batteries needing backfill fires no notification
- **WHEN** the coordinator is set up against an HA instance where every eligible source battery already has a `replaced_on` persisted in the store
- **THEN** no persistent notification with `notification_id="battery_lifetime_cold_start_complete"` is created
#### Scenario: Late-discovered battery extends the batch
- **WHEN** the coordinator's initial scan starts a backfill for battery A, and a new eligible source battery B is added via `entity_registry_updated` while A's backfill is still in flight
- **THEN** B's backfill task is added to `_pending_backfills` before A finishes, and the completion notification fires only after BOTH backfills have completed
### Requirement: Pruned sources have their companion device removed
When `BatteryLifetimeStore.prune_removed_older_than(REMOVED_SOURCE_RETENTION_DAYS)` returns a non-empty list of pruned source `unique_id`s, the coordinator SHALL look up the per-source companion device in HA's device registry by `identifiers={(DOMAIN, source_unique_id)}` and, if found, call `device_registry.async_remove_device(device.id)` for each pruned `unique_id`. HA's device-registry removal cascades to the entity registry and removes all entries tied to that device, which on the Battery Lifetime device card is exactly the eight per-source companion entries (`*_replace_by`, `*_prediction_quality`, `*_drain_rate`, `*_profile_lithium`, `*_tracking_enabled`, `*_mark_replaced`, `*_replaced_on`, `*_threshold_override`).
The cleanup SHALL run in both prune call sites:
- `_async_registry_changed` on `action: remove` (after the soft-delete + prune sweep).
- `_handle_tick` on every periodic heartbeat (after the prune sweep).
The cleanup SHALL be idempotent: looking up a device that does not exist (already manually removed, or never created because the source was removed before any platform forward completed) SHALL be a silent no-op.
The cleanup SHALL NOT run for soft-deleted entries that are still within their 30-day grace window. Those remain recoverable via `store.restore_battery`, and their companion devices and entities remain in the HA registry (showing `unavailable`) so that restore re-enables them without rebuilding the UI.
#### Scenario: Source pruned past the grace window has its device removed
- **WHEN** a source battery is removed from the entity registry, then enough time passes that its `removed_at` is older than `REMOVED_SOURCE_RETENTION_DAYS` (30 days), then the coordinator's heartbeat runs and `prune_removed_older_than` returns the source's `unique_id` in its drop list
- **THEN** the corresponding device entry with `identifiers={(DOMAIN, source_unique_id)}` is no longer present in HA's device registry, and the eight per-source companion entries are no longer present in HA's entity registry
#### Scenario: Source removed but still within grace window keeps its device
- **WHEN** a source battery is removed from the entity registry and the next heartbeat fires within the 30-day retention window
- **THEN** the prune returns an empty list for this source, the device entry remains in the registry, the eight companion entries remain in the registry showing `unavailable`, and a subsequent `store.restore_battery(unique_id)` call (e.g. because the source reappeared) re-enables the entities without rebuilding them
#### Scenario: Purge of a source whose device was already manually removed is a no-op
- **WHEN** `prune_removed_older_than` returns a `unique_id` for which the user has already manually deleted the companion device via the HA UI
- **THEN** `device_registry.async_get_device(identifiers={(DOMAIN, source_unique_id)})` returns `None`, the purge step is a silent no-op for that source, and no error is logged
@@ -0,0 +1,70 @@
### Requirement: Next-quarter summary sensor
The integration SHALL provide an integration-level sensor `sensor.battery_lifetime_due_next_quarter` that counts tracked batteries whose `replace_by` timestamp is on or before 23:59:59 UTC on the last day of the calendar quarter immediately following the reference quarter of the current UTC date. Disabled batteries (`switch.<src>_tracking_enabled` off) MUST be excluded. Batteries whose `replace_by` is unknown (`no_data`) MUST NOT be counted.
#### Scenario: Count reflects next-quarter cutoff
- **WHEN** the current UTC date is 15 May 2026 and 4 tracked batteries have `replace_by` on or before 30 September 2026 23:59:59 UTC
- **THEN** `sensor.battery_lifetime_due_next_quarter` reports `4`
#### Scenario: Disabled batteries are excluded
- **WHEN** a tracked battery has `replace_by` within the next-quarter window but `switch.<src>_tracking_enabled` is `off`
- **THEN** that battery is NOT included in the count
#### Scenario: December rolls into March next year
- **WHEN** the current UTC date is 10 December 2026 and a battery has `replace_by` on 15 March 2027
- **THEN** that battery IS counted because the next-quarter end is 31 March 2027 23:59:59 UTC
### Requirement: days_until_replace attribute on replace-by sensor
Each `sensor.<src>_replace_by` companion SHALL expose a `days_until_replace` attribute when `replace_by` is known: the signed integer number of whole UTC days from the current instant to `replace_by`, rounded toward zero (negative when overdue). When `replace_by` is unknown (`no_data`), the attribute MUST be omitted.
#### Scenario: Future replacement
- **WHEN** `replace_by` is 10 UTC days in the future
- **THEN** `days_until_replace` is `10`
#### Scenario: Overdue replacement
- **WHEN** `replace_by` was 3 UTC days ago
- **THEN** `days_until_replace` is `-3`
#### Scenario: Unknown replace-by
- **WHEN** prediction quality is `no_data` and `replace_by` is unknown
- **THEN** the `days_until_replace` attribute is not present
### Requirement: Per-battery due-next-quarter binary companion
For every tracked battery, the integration SHALL create `binary_sensor.<src>_due_next_quarter` on the same companion device as the other per-source entities. It SHALL be `on` when the battery is tracked (`tracking_enabled` true), prediction quality is not `no_data`, `replace_by` is set, and `replace_by` is on or before the next-quarter end (same cutoff as the summary sensor). It SHALL be `off` otherwise.
#### Scenario: Battery due within next quarter
- **WHEN** the current UTC date is 1 March 2026, a battery is tracked with `replace_by` on 15 June 2026, and confidence is `medium`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `on`
#### Scenario: Battery due after next quarter
- **WHEN** the current UTC date is 1 March 2026 and a battery has `replace_by` on 15 August 2026
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off`
#### Scenario: Untracked battery is off
- **WHEN** `switch.<src>_tracking_enabled` is `off`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off` regardless of `replace_by`
#### Scenario: No-data battery is off
- **WHEN** prediction quality is `no_data`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off`
### Requirement: Per-battery companion entity set includes due-next-quarter binary
The per-battery companion entity set SHALL include `binary_sensor.<src>_due_next_quarter` in addition to the existing eight companions. The binary sensor MUST share the same companion device and deterministic unique-id scheme as the other per-source entities.
#### Scenario: New battery discovery creates binary companion
- **WHEN** a new eligible battery source is discovered and companion entities are created
- **THEN** `binary_sensor.<src>_due_next_quarter` exists alongside the other per-source companions within the next coordinator update
+240 -1
View File
@@ -8,7 +8,7 @@ from typing import Any
import pytest
from homeassistant.components.sensor import SensorDeviceClass
from homeassistant.const import PERCENTAGE
from homeassistant.helpers import entity_registry as er
from homeassistant.helpers import device_registry as dr, entity_registry as er
from custom_components.battery_lifetime.const import DOMAIN
from custom_components.battery_lifetime.coordinator import (
@@ -452,6 +452,245 @@ async def test_user_action_setter_publishes_unconditionally(hass: Any) -> None:
await coord.async_shutdown()
async def test_setup_does_not_await_cold_start_backfill(hass: Any) -> None:
"""async_setup must return before per-record cold-start backfill completes.
The freeze fixed by v0.1.3: with N batteries needing cold-start backfill,
pre-fix `_scan_initial_entities` awaited each backfill in series, so HA's
config-entry setup blocked for minutes. Post-fix, backfill is scheduled
via `hass.async_create_task` and `async_setup` returns immediately.
"""
import asyncio
from unittest.mock import patch
registry = er.async_get(hass)
_register(registry, entity_id="sensor.foo_battery", unique_id="uid-foo")
hass.states.async_set("sensor.foo_battery", "84", {})
store = BatteryLifetimeStore(hass)
await store.async_load()
coord = BatteryLifetimeCoordinator(hass, store=store)
backfill_started = asyncio.Event()
release_backfill = asyncio.Event()
async def _slow_backfill(record: Any) -> None:
backfill_started.set()
await release_backfill.wait()
with patch.object(
coord, "_attempt_cold_start_backfill", side_effect=_slow_backfill
):
await coord.async_setup()
# async_setup has returned. The backfill task may have started (event
# loop tick) but MUST not yet have completed, since we haven't
# released the gate.
assert "uid-foo" in coord._pending_backfills
assert backfill_started.is_set()
release_backfill.set()
await hass.async_block_till_done()
assert coord._pending_backfills == set()
await coord.async_shutdown()
async def test_cold_start_completion_fires_notification(hass: Any) -> None:
"""Once the last in-flight backfill finishes, exactly one notification fires."""
from homeassistant.components.persistent_notification import (
_async_get_or_create_notifications,
)
registry = er.async_get(hass)
_register(registry, entity_id="sensor.foo_battery", unique_id="uid-foo")
hass.states.async_set("sensor.foo_battery", "84", {})
store = BatteryLifetimeStore(hass)
await store.async_load()
coord = BatteryLifetimeCoordinator(hass, store=store)
await coord.async_setup()
await hass.async_block_till_done()
notifications = _async_get_or_create_notifications(hass)
assert "battery_lifetime_cold_start_complete" in notifications
assert coord._pending_backfills == set()
await coord.async_shutdown()
async def test_no_pending_backfill_no_notification(hass: Any) -> None:
"""If every record has a persisted replaced_on, no backfill task is scheduled."""
from homeassistant.components.persistent_notification import (
_async_get_or_create_notifications,
)
registry = er.async_get(hass)
_register(registry, entity_id="sensor.foo_battery", unique_id="uid-foo")
hass.states.async_set("sensor.foo_battery", "84", {})
store = BatteryLifetimeStore(hass)
await store.async_load()
store.upsert_battery("uid-foo", replaced_on="2026-04-01T00:00:00+00:00")
await store.async_save()
coord = BatteryLifetimeCoordinator(hass, store=store)
await coord.async_setup()
await hass.async_block_till_done()
notifications = _async_get_or_create_notifications(hass)
assert "battery_lifetime_cold_start_complete" not in notifications
assert coord._pending_backfills == set()
await coord.async_shutdown()
async def test_cold_start_completion_not_repeated_on_restart(hass: Any) -> None:
"""The backfill-complete notification fires once, not on every HA restart."""
from unittest.mock import patch
from homeassistant.components.persistent_notification import (
_async_get_or_create_notifications,
)
registry = er.async_get(hass)
_register(registry, entity_id="sensor.foo_battery", unique_id="uid-foo")
hass.states.async_set("sensor.foo_battery", "84", {})
store = BatteryLifetimeStore(hass)
await store.async_load()
coord = BatteryLifetimeCoordinator(hass, store=store)
await coord.async_setup()
await hass.async_block_till_done()
notifications = _async_get_or_create_notifications(hass)
assert "battery_lifetime_cold_start_complete" in notifications
assert store.cold_start_backfill_announced is True
await store.async_save()
await coord.async_shutdown()
store_reload = BatteryLifetimeStore(hass)
await store_reload.async_load()
assert store_reload.cold_start_backfill_announced is True
with patch(
"homeassistant.components.persistent_notification.async_create"
) as mock_create:
coord_reload = BatteryLifetimeCoordinator(hass, store=store_reload)
await coord_reload.async_setup()
await hass.async_block_till_done()
mock_create.assert_not_called()
await coord_reload.async_shutdown()
async def test_purge_companions_for_pruned_removes_device(hass: Any) -> None:
"""A pruned source's companion device is removed from the device registry."""
from pytest_homeassistant_custom_component.common import MockConfigEntry
entry = MockConfigEntry(domain=DOMAIN, unique_id=DOMAIN)
entry.add_to_hass(hass)
device_registry = dr.async_get(hass)
device = device_registry.async_get_or_create(
config_entry_id=entry.entry_id,
identifiers={(DOMAIN, "uid-foo")},
manufacturer="Battery Lifetime",
name="Battery: sensor.foo_battery",
)
assert (
device_registry.async_get_device(identifiers={(DOMAIN, "uid-foo")})
is not None
)
store = BatteryLifetimeStore(hass)
await store.async_load()
coord = BatteryLifetimeCoordinator(hass, store=store)
coord._purge_companions_for_pruned(["uid-foo"])
await hass.async_block_till_done()
assert (
device_registry.async_get_device(identifiers={(DOMAIN, "uid-foo")})
is None
)
await coord.async_shutdown()
async def test_purge_companions_for_pruned_is_noop_for_missing_device(
hass: Any,
) -> None:
"""Purging a unique_id with no device entry is a silent no-op."""
store = BatteryLifetimeStore(hass)
await store.async_load()
coord = BatteryLifetimeCoordinator(hass, store=store)
coord._purge_companions_for_pruned(["uid-never-existed"])
coord._purge_companions_for_pruned([])
await hass.async_block_till_done()
await coord.async_shutdown()
async def test_remove_event_chain_purges_after_grace_window(hass: Any) -> None:
"""Once the 30-day grace elapses, the next prune drives a device purge.
Exercises the full _async_registry_changed -> store.prune -> purge chain
by forging an old removed_at directly so prune actually removes the
entry (without waiting 30 days of wall clock).
"""
import time as _time
from pytest_homeassistant_custom_component.common import MockConfigEntry
from custom_components.battery_lifetime.const import (
REMOVED_SOURCE_RETENTION_DAYS,
)
entry = MockConfigEntry(domain=DOMAIN, unique_id=DOMAIN)
entry.add_to_hass(hass)
registry = er.async_get(hass)
_register(registry, entity_id="sensor.foo_battery", unique_id="uid-foo")
hass.states.async_set("sensor.foo_battery", "84", {})
device_registry = dr.async_get(hass)
device_registry.async_get_or_create(
config_entry_id=entry.entry_id,
identifiers={(DOMAIN, "uid-foo")},
manufacturer="Battery Lifetime",
name="Battery: sensor.foo_battery",
)
store = BatteryLifetimeStore(hass)
await store.async_load()
coord = BatteryLifetimeCoordinator(hass, store=store)
await coord.async_setup()
await hass.async_block_till_done()
assert "uid-foo" in coord.records
hass.bus.async_fire(
"entity_registry_updated",
{"action": "remove", "entity_id": "sensor.foo_battery"},
)
await hass.async_block_till_done()
assert "uid-foo" not in coord.records
stored = store.get_battery("uid-foo")
assert stored is not None
assert stored.get("removed_at") is not None
assert (
device_registry.async_get_device(identifiers={(DOMAIN, "uid-foo")})
is not None
)
store._data["batteries"]["uid-foo"]["removed_at"] = (
_time.time() - (REMOVED_SOURCE_RETENTION_DAYS + 1) * 86400
)
coord._handle_tick(datetime.now(tz=UTC))
await hass.async_block_till_done()
assert store.get_battery("uid-foo") is None
assert (
device_registry.async_get_device(identifiers={(DOMAIN, "uid-foo")})
is None
)
await coord.async_shutdown()
async def test_source_without_unique_id_logged_and_skipped(
hass: Any, caplog: pytest.LogCaptureFixture
) -> None:
+48
View File
@@ -10,6 +10,7 @@ from homeassistant.components.sensor import SensorDeviceClass
from homeassistant.const import PERCENTAGE
from homeassistant.helpers import entity_registry as er
from custom_components.battery_lifetime.binary_sensor import DueNextQuarterBinarySensor
from custom_components.battery_lifetime.button import MarkReplacedButton
from custom_components.battery_lifetime.coordinator import (
BatteryLifetimeCoordinator,
@@ -20,6 +21,7 @@ from custom_components.battery_lifetime.number import ThresholdOverrideNumber
from custom_components.battery_lifetime.sensor import (
DrainRateSensor,
DueNext3MonthsSensor,
DueNextQuarterSensor,
PredictionQualitySensor,
ReplaceBySensor,
)
@@ -79,6 +81,8 @@ async def test_replace_by_sensor_returns_prediction(
attrs = sensor.extra_state_attributes
assert attrs["source_entity"] == "sensor.foo_battery"
assert attrs["confidence"] in ("low", "medium", "high")
assert "days_until_replace" in attrs
assert isinstance(attrs["days_until_replace"], int)
async def test_prediction_quality_sensor_returns_string(
@@ -138,6 +142,50 @@ async def test_summary_sensors_exclude_disabled_batteries(
assert due_next.native_value == 0
async def test_summary_sensor_counts_due_next_quarter(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
record = coord_with_battery.records["uid-foo"]
record.last_reading_pct = 18.0
record.ewma.last_pct = 18.0
record.ewma.last_at = datetime.now(tz=UTC)
record.last_reading_at = record.ewma.last_at
record.ewma.rate = 1.0
coord_with_battery.data = await coord_with_battery._async_update_data()
sensor = DueNextQuarterSensor(coord_with_battery)
assert sensor.native_value == 1
assert "next_quarter_end" in sensor.extra_state_attributes
async def test_due_next_quarter_binary_sensor(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
record = coord_with_battery.records["uid-foo"]
record.last_reading_pct = 18.0
record.ewma.last_pct = 18.0
record.ewma.last_at = datetime.now(tz=UTC)
record.last_reading_at = record.ewma.last_at
record.ewma.rate = 1.0
coord_with_battery.data = await coord_with_battery._async_update_data()
binary = DueNextQuarterBinarySensor(coord_with_battery, "uid-foo")
assert binary.is_on is True
record.tracking_enabled = False
coord_with_battery.data = await coord_with_battery._async_update_data()
assert binary.is_on is False
async def test_replace_by_omits_days_until_for_no_data(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
record = coord_with_battery.records["uid-foo"]
record.replaced_on = None
record.ewma.rate = None
coord_with_battery.data = await coord_with_battery._async_update_data()
sensor = ReplaceBySensor(coord_with_battery, "uid-foo")
assert "days_until_replace" not in sensor.extra_state_attributes
async def test_profile_switch_toggles_profile(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
+2
View File
@@ -53,8 +53,10 @@ async def test_async_setup_entry_creates_companion_entities(hass: Any) -> None:
assert "button.foo_battery_mark_replaced" in states
assert "date.foo_battery_replaced_on" in states
assert "number.foo_battery_threshold_override" in states
assert "binary_sensor.foo_battery_due_next_quarter" in states
assert "sensor.battery_lifetime_due_this_month" in states
assert "sensor.battery_lifetime_due_next_3_months" in states
assert "sensor.battery_lifetime_due_next_quarter" in states
assert hass.services.has_service(DOMAIN, SERVICE_PREDICT_AT)
assert await hass.config_entries.async_unload(entry.entry_id)
+49
View File
@@ -0,0 +1,49 @@
"""Unit tests for calendar-quarter boundary helpers."""
from __future__ import annotations
from datetime import datetime, timezone
from custom_components.battery_lifetime.quarters import (
days_until_replace,
is_due_by_quarter_end,
next_quarter_end,
)
UTC = timezone.utc
def test_next_quarter_end_from_q1() -> None:
now = datetime(2026, 2, 10, 12, 0, 0, tzinfo=UTC)
end = next_quarter_end(now)
assert end == datetime(2026, 6, 30, 23, 59, 59, tzinfo=UTC)
def test_next_quarter_end_from_q2() -> None:
now = datetime(2026, 5, 15, tzinfo=UTC)
end = next_quarter_end(now)
assert end == datetime(2026, 9, 30, 23, 59, 59, tzinfo=UTC)
def test_next_quarter_end_from_q4_rolls_to_march() -> None:
now = datetime(2026, 12, 10, tzinfo=UTC)
end = next_quarter_end(now)
assert end == datetime(2027, 3, 31, 23, 59, 59, tzinfo=UTC)
def test_is_due_by_quarter_end() -> None:
now = datetime(2026, 3, 1, tzinfo=UTC)
due = datetime(2026, 6, 15, tzinfo=UTC)
late = datetime(2026, 8, 1, tzinfo=UTC)
assert is_due_by_quarter_end(due, now=now) is True
assert is_due_by_quarter_end(late, now=now) is False
assert is_due_by_quarter_end(None, now=now) is False
def test_days_until_replace_future_and_overdue() -> None:
now = datetime(2026, 5, 1, 12, 0, 0, tzinfo=UTC)
future = datetime(2026, 5, 11, 12, 0, 0, tzinfo=UTC)
past = datetime(2026, 4, 28, 12, 0, 0, tzinfo=UTC)
assert days_until_replace(future, now=now) == 10
assert days_until_replace(past, now=now) == -3
assert days_until_replace(None, now=now) is None
+2
View File
@@ -27,6 +27,7 @@ async def store(hass: Any) -> BatteryLifetimeStore:
async def test_fresh_store_loads_defaults(store: BatteryLifetimeStore) -> None:
assert store.default_profile == DEFAULT_PROFILE
assert store.cold_start_backfill_announced is False
assert list(store.iter_batteries()) == []
@@ -104,6 +105,7 @@ async def test_migration_fills_missing_fields(
assert entry["profile"] == DEFAULT_PROFILE
assert entry["tracking_enabled"] is True
assert entry["threshold_override"] is None
assert store.cold_start_backfill_announced is True
async def test_remove_then_prune(store: BatteryLifetimeStore) -> None: