Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
f0804592c3 | ||
|
|
b5c910c425 | ||
|
|
669c9bda5d | ||
|
|
d048c84eb8 | ||
|
|
2d21a34438 | ||
|
|
aeac543356 | ||
|
|
8154d29d53 | ||
|
|
89c0a12e51 | ||
|
|
986b4f9fa7 | ||
|
|
8d2c34bf6f | ||
|
|
6f577c844f | ||
|
|
089082a163 | ||
|
|
34ae5e8d01 | ||
|
|
13b3dd63ce | ||
|
|
8fab5a5784 | ||
|
|
c576310fce | ||
|
|
330642e6b9 | ||
|
|
20ce139069 | ||
|
|
006771a5f2 | ||
|
|
2e93800981 | ||
|
|
ddc12ba6d3 |
+34
-30
@@ -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).
|
||||
|
||||
@@ -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/>
|
||||
|
||||
@@ -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 |
@@ -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.
|
||||
+25
@@ -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).
|
||||
+29
@@ -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.
|
||||
+72
@@ -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
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user