Author SHA1 Message Date
rickandCursor f0804592c3 Fix backfill-complete notification firing on every HA restart.
Persist a one-shot cold_start_backfill_announced flag in the JSON store so
the initial batch notification is shown only once; backfill still re-runs
silently for batteries without replaced_on. Release v0.1.6.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-25 10:00:34 +02:00
rickandCursor b5c910c425 openspec(quarterly-dashboard-entities): archive and sync lifetime-prediction spec
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:25:36 +02:00
rick 669c9bda5d Merge agent/quarterly-dashboard-entities: quarterly dashboard entities 2026-05-23 11:25:28 +02:00
rickandCursor d048c84eb8 Add quarterly dashboard entities for maintenance cards
Expose due-next-quarter summary and binary companions, days_until_replace
on replace-by sensors, and a simplified example Lovelace card.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:25:23 +02:00
rickandCursor 2d21a34438 openspec(quarterly-dashboard-entities): apply phase complete
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:22:33 +02:00
rickandCursor aeac543356 openspec(quarterly-dashboard-entities): propose phase artifacts
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 11:21:13 +02:00
rick 8154d29d53 Merge agent/license-rename: replace Swarmops name in LICENSE 2026-05-12 19:55:14 +02:00
rickandCursor 89c0a12e51 license: replace Swarmops name with project name
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-12 19:54:10 +02:00
rick 986b4f9fa7 Merge agent/license-readme: public-domain license 2026-05-12 19:46:48 +02:00
24 changed files with 738 additions and 12 deletions
+3 -2
View File
@@ -2,7 +2,7 @@
## 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.4** 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.
@@ -28,7 +28,8 @@ The OpenSpec changes `optimize-coordinator-tick` (v0.1.2), `defer-cold-start-bac
- 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.
- Both `master` and tags `v0.1.0`/`v0.1.1`/`v0.1.2`/`v0.1.3`/`v0.1.4` pushed to gitea (origin) and GitHub (github).
- 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)
+2 -2
View File
@@ -28,8 +28,8 @@ any new restricted code without prior consensus in the project team.
Another way of putting this is the way of the UNLICENSE:
Swarmops is free and unencumbered software released irrevocably
into the public domain.
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,
+8 -3
View File
@@ -72,11 +72,16 @@ For every tracked battery `sensor.foo_battery`, the integration creates:
| `date.foo_battery_replaced_on` | date | Manual override of replaced-on. Future dates rejected. |
| `button.foo_battery_mark_replaced` | button | Sets `replaced_on` to now and resets the model. |
| `number.foo_battery_threshold_override` | number | Optional `%` override. Blank means "use profile default." |
| `binary_sensor.foo_battery_due_next_quarter` | binary | `on` when `replace_by` falls on or before the next quarter end |
And two integration-level summary sensors:
The `replace_by` sensor also exposes a `days_until_replace` attribute (signed
integer days; negative when overdue) when a prediction exists.
And three integration-level summary sensors:
- `sensor.battery_lifetime_due_this_month`
- `sensor.battery_lifetime_due_next_3_months`
- `sensor.battery_lifetime_due_next_quarter` (includes a `next_quarter_end` attribute)
## Replacement detection
@@ -190,10 +195,10 @@ done.
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 eight companion entities flip to `unavailable` in the UI.
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 eight companion entities are removed** from Home Assistant's registry. No orphan `unavailable` rows linger.
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
@@ -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}
+1 -1
View File
@@ -5,7 +5,7 @@ from __future__ import annotations
from typing import Final
DOMAIN: Final = "battery_lifetime"
PLATFORMS: Final = ["sensor", "switch", "button", "date", "number"]
PLATFORMS: Final = ["sensor", "binary_sensor", "switch", "button", "date", "number"]
STORAGE_KEY: Final = "battery_lifetime"
STORAGE_VERSION: Final = 1
@@ -274,6 +274,8 @@ class BatteryLifetimeCoordinator(
self._announce_backfill_complete()
def _announce_backfill_complete(self) -> None:
if self._store.cold_start_backfill_announced:
return
persistent_notification.async_create(
self.hass,
(
@@ -284,13 +286,14 @@ class BatteryLifetimeCoordinator(
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 eight per-source companion entries.
device card is exactly the nine per-source companion entries.
Idempotent: a missing device is a silent no-op.
"""
if not unique_ids:
@@ -1,7 +1,7 @@
{
"domain": "battery_lifetime",
"name": "Battery Lifetime",
"version": "0.1.4",
"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": "Battery 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\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."
"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": "Battery 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\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."
"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,2 @@
schema: spec-driven
created: 2026-05-23
@@ -0,0 +1,57 @@
## Context
The integration already exposes `sensor.<src>_replace_by` timestamps and two rolling summary counters. A quarterly maintenance card (visible during days 1–10 of March, June, September, and December) needs batteries due before the **end of the next calendar quarter** — e.g. on 15 May (Q2), the cutoff is 30 September (Q3 end). Today that logic lives entirely in Lovelace Jinja duplicated across header and filter blocks.
Existing summary sensors use UTC for cutoff boundaries (`due_this_month`, `due_next_3_months`). This change follows the same convention for consistency.
## Goals / Non-Goals
**Goals:**
- One canonical definition of “next quarter end” reused by summary count, binary companion, and card authors.
- Per-battery `binary_sensor.<src>_due_next_quarter` so `auto-entities` can use a trivial `state: "on"` include.
- `days_until_replace` on replace-by for row coloring and sorting without timestamp parsing in templates.
- Keep companion device purge unchanged — removing the device still cascades all entity-registry entries.
**Non-Goals:**
- Changing `battery_lifetime.predict_at` service schema.
- Local-time quarter boundaries (would diverge from existing summary sensors).
- A custom Lovelace card in this repository.
- Retroactive entity creation for installs until the next coordinator refresh / rediscovery (standard HA platform behaviour).
## Decisions
### Decision: Next quarter end is end of the calendar quarter after the current one
Given a reference datetime, map its month to a cutoff at 23:59:59 UTC on the last day of the next calendar quarter:
| Reference month | Next quarter end (UTC) |
| --------------- | ---------------------- |
| Jan–Mar | 30 June |
| Apr–Jun | 30 September |
| Jul–Sep | 31 December |
| Oct–Dec | 31 March (following year) |
Alternative considered: align only during the Mar/Jun/Sep/Dec maintenance window. Rejected because integration entities should be meaningful year-round for automations and other dashboards.
### Decision: `days_until_replace` is a signed whole-day floor
Compute `floor((replace_by - now) / 86400)` in UTC. Negative values mean overdue. Omit the attribute when `replace_by` is `None` or confidence is `no_data`. Alternative considered: fractional days. Rejected — dashboards want integer labels (“12 days”).
### Decision: Binary companion is `off` for `no_data` and untracked batteries
`binary_sensor.<src>_due_next_quarter` is `on` only when `tracking_enabled`, `replace_by` is set, confidence is not `no_data`, and `replace_by <= next_quarter_end`. Stale batteries with a frozen `replace_by` still evaluate normally. Alternative considered: separate `unknown` state. Rejected — binary sensors are simpler as on/off for Lovelace filters.
### Decision: Shared helper module `quarters.py`
Pure functions `next_quarter_end(now)` and `is_due_by_quarter_end(replace_by, now)` keep sensor and binary_sensor platforms thin and unit-testable without HA imports in the core math.
## Risks / Trade-offs
- **Companion count 8 → 9** → README and stale docs referencing “eight companions” need updating; device purge still removes all entities on the device automatically.
- **UTC vs local quarter** → A battery due “today” in local time may differ by one day from UTC boundary; matches existing summary sensor trade-off.
## Migration Plan
Non-breaking additive change. On upgrade, HA loads the new `binary_sensor` platform and creates new entities on the next setup; existing stores and services unchanged. Users replace Lovelace template filters with `*_due_next_quarter` includes when ready.
@@ -0,0 +1,34 @@
## Why
Quarterly battery-maintenance dashboards need calendar-aligned filters that the existing summary sensors (`due_this_month`, `due_next_3_months`) do not provide. Lovelace cards currently duplicate quarter-boundary math in Jinja templates and cannot filter companion entities with a simple include rule. Exposing `due_next_quarter` summary/count semantics, a `days_until_replace` attribute, and a per-battery `due_next_quarter` binary companion makes dashboard cards simpler, faster to author, and consistent with integration-level prediction data.
## What Changes
- Add integration-level sensor `sensor.battery_lifetime_due_next_quarter` counting tracked batteries whose `replace_by` is on or before the end of the calendar quarter immediately following the current one.
- Add `days_until_replace` attribute on each `sensor.<src>_replace_by` companion (signed integer days from now; negative when overdue; omitted when `replace_by` is unknown).
- Add per-battery binary companion `binary_sensor.<src>_due_next_quarter` that is `on` when the battery is tracked, has a computable `replace_by`, is not `no_data`, and that date falls on or before the next quarter end.
- Add shared quarter-boundary helper used by summary and binary companions (same cutoff semantics everywhere).
- Update the example quarterly maintenance Lovelace card to filter on `*_due_next_quarter` instead of inline timestamp math.
- Per-battery companion count increases from eight to nine; companion-device purge cascades automatically via existing device-registry removal.
## Capabilities
### New Capabilities
(none — behavior extends existing lifetime prediction surface)
### Modified Capabilities
- `lifetime-prediction`: adds next-quarter summary sensor, `days_until_replace` attribute on replace-by, and per-battery `due_next_quarter` binary companion.
## Impact
- `custom_components/battery_lifetime/quarters.py` (new): shared next-quarter-end calculation.
- `custom_components/battery_lifetime/sensor.py`: `days_until_replace` attribute; `DueNextQuarterSensor` summary.
- `custom_components/battery_lifetime/binary_sensor.py` (new platform): `DueNextQuarterBinarySensor` per battery.
- `custom_components/battery_lifetime/const.py`: add `binary_sensor` to `PLATFORMS`.
- `custom_components/battery_lifetime/translations/en.json`, `strings.json`: new entity strings.
- `examples/lovelace/quarterly-battery-maintenance-card.yaml`: simplified card using new entities.
- `README.md`: document new entities.
- Tests in `tests/test_entities.py`, `tests/test_init.py`, and new `tests/test_quarters.py`.
- `manifest.json`: version bump.
@@ -0,0 +1,72 @@
## ADDED Requirements
### Requirement: Next-quarter summary sensor
The integration SHALL provide an integration-level sensor `sensor.battery_lifetime_due_next_quarter` that counts tracked batteries whose `replace_by` timestamp is on or before 23:59:59 UTC on the last day of the calendar quarter immediately following the reference quarter of the current UTC date. Disabled batteries (`switch.<src>_tracking_enabled` off) MUST be excluded. Batteries whose `replace_by` is unknown (`no_data`) MUST NOT be counted.
#### Scenario: Count reflects next-quarter cutoff
- **WHEN** the current UTC date is 15 May 2026 and 4 tracked batteries have `replace_by` on or before 30 September 2026 23:59:59 UTC
- **THEN** `sensor.battery_lifetime_due_next_quarter` reports `4`
#### Scenario: Disabled batteries are excluded
- **WHEN** a tracked battery has `replace_by` within the next-quarter window but `switch.<src>_tracking_enabled` is `off`
- **THEN** that battery is NOT included in the count
#### Scenario: December rolls into March next year
- **WHEN** the current UTC date is 10 December 2026 and a battery has `replace_by` on 15 March 2027
- **THEN** that battery IS counted because the next-quarter end is 31 March 2027 23:59:59 UTC
### Requirement: days_until_replace attribute on replace-by sensor
Each `sensor.<src>_replace_by` companion SHALL expose a `days_until_replace` attribute when `replace_by` is known: the signed integer number of whole UTC days from the current instant to `replace_by`, rounded toward zero (negative when overdue). When `replace_by` is unknown (`no_data`), the attribute MUST be omitted.
#### Scenario: Future replacement
- **WHEN** `replace_by` is 10 UTC days in the future
- **THEN** `days_until_replace` is `10`
#### Scenario: Overdue replacement
- **WHEN** `replace_by` was 3 UTC days ago
- **THEN** `days_until_replace` is `-3`
#### Scenario: Unknown replace-by
- **WHEN** prediction quality is `no_data` and `replace_by` is unknown
- **THEN** the `days_until_replace` attribute is not present
### Requirement: Per-battery due-next-quarter binary companion
For every tracked battery, the integration SHALL create `binary_sensor.<src>_due_next_quarter` on the same companion device as the other per-source entities. It SHALL be `on` when the battery is tracked (`tracking_enabled` true), prediction quality is not `no_data`, `replace_by` is set, and `replace_by` is on or before the next-quarter end (same cutoff as the summary sensor). It SHALL be `off` otherwise.
#### Scenario: Battery due within next quarter
- **WHEN** the current UTC date is 1 March 2026, a battery is tracked with `replace_by` on 15 June 2026, and confidence is `medium`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `on`
#### Scenario: Battery due after next quarter
- **WHEN** the current UTC date is 1 March 2026 and a battery has `replace_by` on 15 August 2026
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off`
#### Scenario: Untracked battery is off
- **WHEN** `switch.<src>_tracking_enabled` is `off`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off` regardless of `replace_by`
#### Scenario: No-data battery is off
- **WHEN** prediction quality is `no_data`
- **THEN** `binary_sensor.<src>_due_next_quarter` is `off`
### Requirement: Per-battery companion entity set includes due-next-quarter binary
The per-battery companion entity set SHALL include `binary_sensor.<src>_due_next_quarter` in addition to the existing eight companions. The binary sensor MUST share the same companion device and deterministic unique-id scheme as the other per-source entities.
#### Scenario: New battery discovery creates binary companion
- **WHEN** a new eligible battery source is discovered and companion entities are created
- **THEN** `binary_sensor.<src>_due_next_quarter` exists alongside the other per-source companions within the next coordinator update
@@ -0,0 +1,27 @@
## 1. Quarter boundary helper
- [x] 1.1 Create `custom_components/battery_lifetime/quarters.py` with `next_quarter_end(now)` and `is_due_by_quarter_end(replace_by, now)`
- [x] 1.2 Add unit tests in `tests/test_quarters.py` covering month boundaries and year rollover (December → March)
## 2. Replace-by attribute and summary sensor
- [x] 2.1 Add `days_until_replace` to `ReplaceBySensor.extra_state_attributes` in `sensor.py`
- [x] 2.2 Add `DueNextQuarterSensor` summary entity (`sensor.battery_lifetime_due_next_quarter`) in `sensor.py`
- [x] 2.3 Add translation keys for the new summary sensor
## 3. Binary sensor platform
- [x] 3.1 Create `binary_sensor.py` with `DueNextQuarterBinarySensor` per tracked battery
- [x] 3.2 Register `binary_sensor` in `const.PLATFORMS` and ensure dynamic entity add on discovery matches other platforms
- [x] 3.3 Add translation keys for the binary companion
## 4. Tests and documentation
- [x] 4.1 Extend `tests/test_entities.py` for `days_until_replace`, summary count, and binary sensor on/off cases
- [x] 4.2 Update `tests/test_init.py` for new platform entities
- [x] 4.3 Update `README.md` companion table and summary sensor list (nine companions)
- [x] 4.4 Bump `manifest.json` version
## 5. Lovelace card
- [x] 5.1 Revise `examples/lovelace/quarterly-battery-maintenance-card.yaml` to filter `*_due_next_quarter` and use `days_until_replace` / summary sensor
@@ -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
+39
View File
@@ -542,6 +542,45 @@ async def test_no_pending_backfill_no_notification(hass: Any) -> None:
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
+48
View File
@@ -10,6 +10,7 @@ from homeassistant.components.sensor import SensorDeviceClass
from homeassistant.const import PERCENTAGE
from homeassistant.helpers import entity_registry as er
from custom_components.battery_lifetime.binary_sensor import DueNextQuarterBinarySensor
from custom_components.battery_lifetime.button import MarkReplacedButton
from custom_components.battery_lifetime.coordinator import (
BatteryLifetimeCoordinator,
@@ -20,6 +21,7 @@ from custom_components.battery_lifetime.number import ThresholdOverrideNumber
from custom_components.battery_lifetime.sensor import (
DrainRateSensor,
DueNext3MonthsSensor,
DueNextQuarterSensor,
PredictionQualitySensor,
ReplaceBySensor,
)
@@ -79,6 +81,8 @@ async def test_replace_by_sensor_returns_prediction(
attrs = sensor.extra_state_attributes
assert attrs["source_entity"] == "sensor.foo_battery"
assert attrs["confidence"] in ("low", "medium", "high")
assert "days_until_replace" in attrs
assert isinstance(attrs["days_until_replace"], int)
async def test_prediction_quality_sensor_returns_string(
@@ -138,6 +142,50 @@ async def test_summary_sensors_exclude_disabled_batteries(
assert due_next.native_value == 0
async def test_summary_sensor_counts_due_next_quarter(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
record = coord_with_battery.records["uid-foo"]
record.last_reading_pct = 18.0
record.ewma.last_pct = 18.0
record.ewma.last_at = datetime.now(tz=UTC)
record.last_reading_at = record.ewma.last_at
record.ewma.rate = 1.0
coord_with_battery.data = await coord_with_battery._async_update_data()
sensor = DueNextQuarterSensor(coord_with_battery)
assert sensor.native_value == 1
assert "next_quarter_end" in sensor.extra_state_attributes
async def test_due_next_quarter_binary_sensor(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
record = coord_with_battery.records["uid-foo"]
record.last_reading_pct = 18.0
record.ewma.last_pct = 18.0
record.ewma.last_at = datetime.now(tz=UTC)
record.last_reading_at = record.ewma.last_at
record.ewma.rate = 1.0
coord_with_battery.data = await coord_with_battery._async_update_data()
binary = DueNextQuarterBinarySensor(coord_with_battery, "uid-foo")
assert binary.is_on is True
record.tracking_enabled = False
coord_with_battery.data = await coord_with_battery._async_update_data()
assert binary.is_on is False
async def test_replace_by_omits_days_until_for_no_data(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
record = coord_with_battery.records["uid-foo"]
record.replaced_on = None
record.ewma.rate = None
coord_with_battery.data = await coord_with_battery._async_update_data()
sensor = ReplaceBySensor(coord_with_battery, "uid-foo")
assert "days_until_replace" not in sensor.extra_state_attributes
async def test_profile_switch_toggles_profile(
coord_with_battery: BatteryLifetimeCoordinator,
) -> None:
+2
View File
@@ -53,8 +53,10 @@ async def test_async_setup_entry_creates_companion_entities(hass: Any) -> None:
assert "button.foo_battery_mark_replaced" in states
assert "date.foo_battery_replaced_on" in states
assert "number.foo_battery_threshold_override" in states
assert "binary_sensor.foo_battery_due_next_quarter" in states
assert "sensor.battery_lifetime_due_this_month" in states
assert "sensor.battery_lifetime_due_next_3_months" in states
assert "sensor.battery_lifetime_due_next_quarter" in states
assert hass.services.has_service(DOMAIN, SERVICE_PREDICT_AT)
assert await hass.config_entries.async_unload(entry.entry_id)
+49
View File
@@ -0,0 +1,49 @@
"""Unit tests for calendar-quarter boundary helpers."""
from __future__ import annotations
from datetime import datetime, timezone
from custom_components.battery_lifetime.quarters import (
days_until_replace,
is_due_by_quarter_end,
next_quarter_end,
)
UTC = timezone.utc
def test_next_quarter_end_from_q1() -> None:
now = datetime(2026, 2, 10, 12, 0, 0, tzinfo=UTC)
end = next_quarter_end(now)
assert end == datetime(2026, 6, 30, 23, 59, 59, tzinfo=UTC)
def test_next_quarter_end_from_q2() -> None:
now = datetime(2026, 5, 15, tzinfo=UTC)
end = next_quarter_end(now)
assert end == datetime(2026, 9, 30, 23, 59, 59, tzinfo=UTC)
def test_next_quarter_end_from_q4_rolls_to_march() -> None:
now = datetime(2026, 12, 10, tzinfo=UTC)
end = next_quarter_end(now)
assert end == datetime(2027, 3, 31, 23, 59, 59, tzinfo=UTC)
def test_is_due_by_quarter_end() -> None:
now = datetime(2026, 3, 1, tzinfo=UTC)
due = datetime(2026, 6, 15, tzinfo=UTC)
late = datetime(2026, 8, 1, tzinfo=UTC)
assert is_due_by_quarter_end(due, now=now) is True
assert is_due_by_quarter_end(late, now=now) is False
assert is_due_by_quarter_end(None, now=now) is False
def test_days_until_replace_future_and_overdue() -> None:
now = datetime(2026, 5, 1, 12, 0, 0, tzinfo=UTC)
future = datetime(2026, 5, 11, 12, 0, 0, tzinfo=UTC)
past = datetime(2026, 4, 28, 12, 0, 0, tzinfo=UTC)
assert days_until_replace(future, now=now) == 10
assert days_until_replace(past, now=now) == -3
assert days_until_replace(None, now=now) is None
+2
View File
@@ -27,6 +27,7 @@ async def store(hass: Any) -> BatteryLifetimeStore:
async def test_fresh_store_loads_defaults(store: BatteryLifetimeStore) -> None:
assert store.default_profile == DEFAULT_PROFILE
assert store.cold_start_backfill_announced is False
assert list(store.iter_batteries()) == []
@@ -104,6 +105,7 @@ async def test_migration_fills_missing_fields(
assert entry["profile"] == DEFAULT_PROFILE
assert entry["tracking_enabled"] is True
assert entry["threshold_override"] is None
assert store.cold_start_backfill_announced is True
async def test_remove_then_prune(store: BatteryLifetimeStore) -> None: