feat: tunable per-window (1m/5m/15m) update intervals

The single publish interval drove one coordinator that refreshed every
sensor together. Split into three coordinators (one per averaging
window) sharing the existing sampler; each sensor binds to its window's
coordinator, while non-window sensors (max_mhz, epp, epb) and the
summary follow the 1m/primary window. Slower windows can now publish
(and record) far less often than the responsive 1m window.

The config/options flow exposes a per-window interval; each is validated
to be >= the sample interval. Backward compatible: resolve_publish_
interval() seeds every window from the legacy single
publish_interval_seconds, so existing entries are unchanged until tuned
(no config-entry migration needed).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bakerkj

custom_components/cpu_capacity/__init__.py

@@ -10,12 +10,14 @@
 from homeassistant.core import HomeAssistant
 
 from .const import (
-    CONF_PUBLISH_INTERVAL_SECONDS,
     CONF_SAMPLE_INTERVAL_SECONDS,
-    DEFAULT_PUBLISH_INTERVAL_SECONDS,
     DEFAULT_SAMPLE_INTERVAL_SECONDS,
     DOMAIN,
+    MAX_PUBLISH_INTERVAL,
+    MIN_PUBLISH_INTERVAL,
     PLATFORMS,
+    PUBLISH_INTERVAL_CONF_BY_WINDOW,
+    resolve_publish_interval,
 )
 from .coordinator import CpuCapacityCoordinator, CpuCapacitySampler
 
@@ -25,7 +27,7 @@
 @dataclass
 class CpuCapacityEntryData:
     sampler: CpuCapacitySampler
-    coordinator: CpuCapacityCoordinator
+    coordinators: dict[str, CpuCapacityCoordinator]
 
 
 def _entry_float(entry: ConfigEntry, key: str, default: float) -> float:
@@ -47,33 +49,43 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             entry, CONF_SAMPLE_INTERVAL_SECONDS, DEFAULT_SAMPLE_INTERVAL_SECONDS
         ),
     )
-    publish_interval = max(
-        1.0,
-        _entry_float(
-            entry, CONF_PUBLISH_INTERVAL_SECONDS, DEFAULT_PUBLISH_INTERVAL_SECONDS
-        ),
-    )
-    if publish_interval < sample_interval:
-        publish_interval = sample_interval
+    source = {**entry.data, **entry.options}
+    publish_intervals = {
+        window: min(
+            MAX_PUBLISH_INTERVAL,
+            max(
+                MIN_PUBLISH_INTERVAL,
+                sample_interval,
+                resolve_publish_interval(window, source),
+            ),
+        )
+        for window in PUBLISH_INTERVAL_CONF_BY_WINDOW
+    }
 
     logger = _LOGGER.getChild(entry.entry_id)
 
     sampler = CpuCapacitySampler(
         hass,
         logger,
         sample_interval_seconds=sample_interval,
-        publish_interval_seconds=publish_interval,
+        publish_intervals_by_window=publish_intervals,
     )
-    coordinator = CpuCapacityCoordinator(hass, logger, sampler)
+    coordinators = {
+        window: CpuCapacityCoordinator(
+            hass, logger, sampler, window, publish_intervals[window]
+        )
+        for window in PUBLISH_INTERVAL_CONF_BY_WINDOW
+    }
     entry_added = False
 
     try:
         await sampler.async_start()
-        await coordinator.async_config_entry_first_refresh()
+        for coordinator in coordinators.values():
+            await coordinator.async_config_entry_first_refresh()
 
         hass.data.setdefault(DOMAIN, {})[entry.entry_id] = CpuCapacityEntryData(
             sampler=sampler,
-            coordinator=coordinator,
+            coordinators=coordinators,
         )
         entry_added = True
 

custom_components/cpu_capacity/config_flow.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import Any
 
 import voluptuous as vol
@@ -11,7 +12,6 @@
 from homeassistant.core import callback
 
 from .const import (
-    CONF_PUBLISH_INTERVAL_SECONDS,
     CONF_SAMPLE_INTERVAL_SECONDS,
     DEFAULT_NAME,
     DEFAULT_PUBLISH_INTERVAL_SECONDS,
@@ -21,29 +21,39 @@
     MAX_SAMPLE_INTERVAL,
     MIN_PUBLISH_INTERVAL,
     MIN_SAMPLE_INTERVAL,
+    PUBLISH_INTERVAL_CONF_BY_WINDOW,
     UNIQUE_ID,
+    resolve_publish_interval,
 )
 
 
-def _build_schema(sample_default: float, publish_default: float) -> vol.Schema:
-    return vol.Schema(
-        {
-            vol.Required(
-                CONF_SAMPLE_INTERVAL_SECONDS,
-                default=float(sample_default),
-            ): vol.All(
-                vol.Coerce(float),
-                vol.Range(min=MIN_SAMPLE_INTERVAL, max=MAX_SAMPLE_INTERVAL),
-            ),
-            vol.Required(
-                CONF_PUBLISH_INTERVAL_SECONDS,
-                default=float(publish_default),
-            ): vol.All(
-                vol.Coerce(float),
-                vol.Range(min=MIN_PUBLISH_INTERVAL, max=MAX_PUBLISH_INTERVAL),
-            ),
-        }
-    )
+def _build_schema(
+    sample_default: float, publish_defaults: Mapping[str, float]
+) -> vol.Schema:
+    schema: dict[Any, Any] = {
+        vol.Required(
+            CONF_SAMPLE_INTERVAL_SECONDS,
+            default=float(sample_default),
+        ): vol.All(
+            vol.Coerce(float),
+            vol.Range(min=MIN_SAMPLE_INTERVAL, max=MAX_SAMPLE_INTERVAL),
+        ),
+    }
+    for window, conf in PUBLISH_INTERVAL_CONF_BY_WINDOW.items():
+        schema[vol.Required(conf, default=float(publish_defaults[window]))] = vol.All(
+            vol.Coerce(float),
+            vol.Range(min=MIN_PUBLISH_INTERVAL, max=MAX_PUBLISH_INTERVAL),
+        )
+    return vol.Schema(schema)
+
+
+def _publish_error(user_input: dict[str, Any]) -> str | None:
+    """Each window must publish no faster than the sampler produces data."""
+    sample_interval = float(user_input[CONF_SAMPLE_INTERVAL_SECONDS])
+    for conf in PUBLISH_INTERVAL_CONF_BY_WINDOW.values():
+        if float(user_input[conf]) < sample_interval:
+            return "publish_too_small"
+    return None
 
 
 @config_entries.HANDLERS.register(DOMAIN)
@@ -66,10 +76,9 @@ async def async_step_user(
         errors: dict[str, str] = {}
 
         if user_input is not None:
-            sample_interval = float(user_input[CONF_SAMPLE_INTERVAL_SECONDS])
-            publish_interval = float(user_input[CONF_PUBLISH_INTERVAL_SECONDS])
-            if publish_interval < sample_interval:
-                errors["base"] = "publish_too_small"
+            error = _publish_error(user_input)
+            if error:
+                errors["base"] = error
             else:
                 await self.async_set_unique_id(UNIQUE_ID)
                 self._abort_if_unique_id_configured()
@@ -79,7 +88,10 @@ async def async_step_user(
             step_id="user",
             data_schema=_build_schema(
                 DEFAULT_SAMPLE_INTERVAL_SECONDS,
-                DEFAULT_PUBLISH_INTERVAL_SECONDS,
+                {
+                    window: DEFAULT_PUBLISH_INTERVAL_SECONDS
+                    for window in PUBLISH_INTERVAL_CONF_BY_WINDOW
+                },
             ),
             errors=errors,
         )
@@ -95,34 +107,26 @@ async def async_step_init(
         errors: dict[str, str] = {}
 
         if user_input is not None:
-            sample_interval = float(user_input[CONF_SAMPLE_INTERVAL_SECONDS])
-            publish_interval = float(user_input[CONF_PUBLISH_INTERVAL_SECONDS])
-            if publish_interval < sample_interval:
-                errors["base"] = "publish_too_small"
+            error = _publish_error(user_input)
+            if error:
+                errors["base"] = error
             else:
                 return self.async_create_entry(title="", data=user_input)
 
+        source = {**self._config_entry.data, **self._config_entry.options}
         sample_default = float(
-            self._config_entry.options.get(
-                CONF_SAMPLE_INTERVAL_SECONDS,
-                self._config_entry.data.get(
-                    CONF_SAMPLE_INTERVAL_SECONDS,
-                    DEFAULT_SAMPLE_INTERVAL_SECONDS,
-                ),
-            )
-        )
-        publish_default = float(
-            self._config_entry.options.get(
-                CONF_PUBLISH_INTERVAL_SECONDS,
-                self._config_entry.data.get(
-                    CONF_PUBLISH_INTERVAL_SECONDS,
-                    DEFAULT_PUBLISH_INTERVAL_SECONDS,
-                ),
-            )
+            source.get(CONF_SAMPLE_INTERVAL_SECONDS, DEFAULT_SAMPLE_INTERVAL_SECONDS)
         )
+        # Pre-existing entries only have the legacy single value;
+        # resolve_publish_interval seeds every window from it so the form
+        # opens reflecting the current behaviour.
+        publish_defaults = {
+            window: resolve_publish_interval(window, source)
+            for window in PUBLISH_INTERVAL_CONF_BY_WINDOW
+        }
 
         return self.async_show_form(
             step_id="init",
-            data_schema=_build_schema(sample_default, publish_default),
+            data_schema=_build_schema(sample_default, publish_defaults),
             errors=errors,
         )

custom_components/cpu_capacity/const.py

@@ -1,13 +1,31 @@
 # Copyright (c) 2026 Kenneth Baker <bakerkj@umich.edu>
 # All rights reserved.
 
+from collections.abc import Mapping
+from typing import Any
+
 from homeassistant.const import Platform
 
 DOMAIN = "cpu_capacity"
 PLATFORMS: list[Platform] = [Platform.SENSOR]
 
 CONF_SAMPLE_INTERVAL_SECONDS = "sample_interval_seconds"
+# Legacy single publish interval. Still read as the fallback for any window
+# whose per-window key is absent, so pre-existing config entries keep their
+# previous behaviour until the windows are tuned individually.
 CONF_PUBLISH_INTERVAL_SECONDS = "publish_interval_seconds"
+CONF_PUBLISH_INTERVAL_1M_SECONDS = "publish_interval_1m_seconds"
+CONF_PUBLISH_INTERVAL_5M_SECONDS = "publish_interval_5m_seconds"
+CONF_PUBLISH_INTERVAL_15M_SECONDS = "publish_interval_15m_seconds"
+
+# Ordered so callers iterate windows deterministically (forms, refreshes).
+PUBLISH_INTERVAL_CONF_BY_WINDOW: dict[str, str] = {
+    "1m": CONF_PUBLISH_INTERVAL_1M_SECONDS,
+    "5m": CONF_PUBLISH_INTERVAL_5M_SECONDS,
+    "15m": CONF_PUBLISH_INTERVAL_15M_SECONDS,
+}
+# Non-window sensors (max_mhz, epp, epb, summary) follow this window's cadence.
+PRIMARY_WINDOW = "1m"
 
 DEFAULT_SAMPLE_INTERVAL_SECONDS = 0.5
 DEFAULT_PUBLISH_INTERVAL_SECONDS = 15.0
@@ -22,6 +40,26 @@
 STALE_DATA_TIMEOUT_MULTIPLIER = 3.0
 SUMMARY_SENSOR_NAME = "Summary"
 
+
+def resolve_publish_interval(window: str, source: Mapping[str, Any]) -> float:
+    """Resolve the publish interval for a window from a config entry mapping.
+
+    ``source`` is the merged ``{**entry.data, **entry.options}`` mapping. A
+    per-window value wins; otherwise the legacy single
+    ``publish_interval_seconds`` is used; otherwise the default. Invalid
+    values fall back to the default rather than raising.
+    """
+    raw = source.get(PUBLISH_INTERVAL_CONF_BY_WINDOW[window])
+    if raw is None:
+        raw = source.get(
+            CONF_PUBLISH_INTERVAL_SECONDS, DEFAULT_PUBLISH_INTERVAL_SECONDS
+        )
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return float(DEFAULT_PUBLISH_INTERVAL_SECONDS)
+
+
 EPP_PATH_TEMPLATE = (
     "/sys/devices/system/cpu/cpu{cpu}/cpufreq/energy_performance_preference"
 )

custom_components/cpu_capacity/coordinator.py

@@ -52,7 +52,7 @@ class CoordinatorSnapshot(TypedDict):
     sample_count: int
     last_sample_epoch: float
     sample_interval_seconds: float
-    publish_interval_seconds: float
+    publish_intervals_by_window: dict[str, float]
     cpus: dict[int, CpuSnapshot]
 
 
@@ -277,15 +277,20 @@ def __init__(
         hass: HomeAssistant,
         logger: logging.Logger,
         sample_interval_seconds: float,
-        publish_interval_seconds: float,
+        publish_intervals_by_window: dict[str, float],
     ) -> None:
         self.hass = hass
         self.logger = logger
         self._sample_interval_seconds = max(0.1, float(sample_interval_seconds))
-        self._publish_interval_seconds = max(
-            self._sample_interval_seconds,
-            float(publish_interval_seconds),
-        )
+        # Each window publishes no faster than the sampler produces data.
+        self._publish_intervals_by_window: dict[str, float] = {
+            window: max(
+                self._sample_interval_seconds,
+                float(publish_intervals_by_window[window]),
+            )
+            for window in WINDOW_SECONDS
+            if window in publish_intervals_by_window
+        }
 
         self._window_sizes: dict[str, int] = {
             label: max(1, int(math.ceil(seconds / self._sample_interval_seconds)))
@@ -329,8 +334,8 @@ def sample_interval_seconds(self) -> float:
         return self._sample_interval_seconds
 
     @property
-    def publish_interval_seconds(self) -> float:
-        return self._publish_interval_seconds
+    def publish_intervals_by_window(self) -> dict[str, float]:
+        return dict(self._publish_intervals_by_window)
 
     async def async_start(self) -> None:
         if self._running:
@@ -486,24 +491,35 @@ def _build_snapshot_sync(self) -> CoordinatorSnapshot:
             sample_count=self._sample_count,
             last_sample_epoch=self._last_sample_epoch,
             sample_interval_seconds=self._sample_interval_seconds,
-            publish_interval_seconds=self._publish_interval_seconds,
+            publish_intervals_by_window=dict(self._publish_intervals_by_window),
             cpus=cpu_data,
         )
 
 
 class CpuCapacityCoordinator(DataUpdateCoordinator[CoordinatorSnapshot]):
+    """Publishes the shared sampler's data at one window's cadence.
+
+    One instance per averaging window (1m/5m/15m); all instances share a
+    single :class:`CpuCapacitySampler`, so each refresh only snapshots the
+    already-collected rolling averages.
+    """
+
     def __init__(
         self,
         hass: HomeAssistant,
         logger: logging.Logger,
         sampler: CpuCapacitySampler,
+        window: str,
+        publish_interval_seconds: float,
     ) -> None:
         self.sampler = sampler
+        self.window = window
+        self._publish_interval_seconds = publish_interval_seconds
         super().__init__(
             hass,
             logger,
-            name=DOMAIN,
-            update_interval=timedelta(seconds=sampler.publish_interval_seconds),
+            name=f"{DOMAIN}_{window}",
+            update_interval=timedelta(seconds=publish_interval_seconds),
         )
 
     async def _async_update_data(self) -> CoordinatorSnapshot:
@@ -516,7 +532,7 @@ async def _async_update_data(self) -> CoordinatorSnapshot:
             raise UpdateFailed("No sample timestamp available")
 
         stale_timeout = max(
-            5.0, self.sampler.publish_interval_seconds * STALE_DATA_TIMEOUT_MULTIPLIER
+            5.0, self._publish_interval_seconds * STALE_DATA_TIMEOUT_MULTIPLIER
         )
         age = time.time() - snapshot["last_sample_epoch"]
         if age > stale_timeout: