POINTTAPI cleanup: thermostat-valve entities, fast/slow polling, translations (#20)

* Refine POINTTAPI number description composition

* Clean up POINTTAPI follow-up helpers

* Polish thermostat valve labels and protocol display

* Polish thermostat valve labels and protocol display

* Polish thermostat valve labels and fix integer-like counters

* Clarify boost switch labels across locales

* Add thermostat valve child lock and valve offset support

Commit the thermostat valve POINTTAPI support and localized labels.

* Add thermostat valve temperature actual sensor

Commit the final thermostat valve actual-temperature sensor support and translations.

* Enrich unit tests

* Fix Ruff E712 boolean comparison in POINTTAPI entity

* Refresh README entities inventory and update credits

* Polish README: badges, complete entity matrix, and credits update

* Increase unit test coverage

* Increase coverage for config and POINTTAPI flows

* Optimize POINTTAPI polling performance

* Persist POINTTAPI startup data

* Add zone average temperature sensors

* Keep live valve telemetry on fast polling

Keep battery, RSSI, and device metadata on the slower polling cadence while preserving fast updates for live thermostat valve telemetry.

* Harden POINTTAPI cache and startup flow

Debounce and restrict persistent cache data, refresh before forwarding platforms, simplify coordinator discovery, and add regression coverage.

* Remove unused POINTTAPI persistent cache

Author: jfhautenauven

README.md

@@ -371,7 +371,6 @@ async def async_init(self) -> bool:
                 self.hass, self.config_entry, self.gateway
             )
             self._data.coordinator = coordinator
-            await coordinator.async_config_entry_first_refresh()
             device_registry = dr.async_get(self.hass)
             device_registry.async_get_or_create(
                 config_entry_id=self.config_entry.entry_id,
@@ -381,6 +380,7 @@ async def async_init(self) -> bool:
                 name=f"EasyControl (POINTTAPI) {self._host}",
                 sw_version="",
             )
+            await coordinator.async_config_entry_first_refresh()
             await self.hass.config_entries.async_forward_entry_setups(
                 self.config_entry,
                 [p for p in self.supported_platforms if p],

custom_components/bosch/__init__.py

@@ -117,13 +117,17 @@ async def bulk(self, paths: list[str]) -> dict:
         to sequential GETs. Raises ConfigEntryAuthFailed on 401/403 like get().
         """
         result: dict = {}
+        token = await self._token_callback()
         for i in range(0, len(paths), MAX_BULK_PATHS):
-            result.update(await self._bulk_single(paths[i : i + MAX_BULK_PATHS]))
+            result.update(
+                await self._bulk_single(paths[i : i + MAX_BULK_PATHS], token)
+            )
         return result
 
-    async def _bulk_single(self, paths: list[str]) -> dict:
+    async def _bulk_single(self, paths: list[str], token: str | None = None) -> dict:
         """Issue one bulk POST for up to MAX_BULK_PATHS paths."""
-        token = await self._token_callback()
+        if token is None:
+            token = await self._token_callback()
         headers = {"Authorization": f"Bearer {token}", "Content-Type": APP_JSON}
         body = json.dumps([{"gatewayId": self._device_id, "resourcePaths": list(paths)}])
         async with self._session.post(

custom_components/bosch/pointtapi_client.py

@@ -50,13 +50,40 @@
 ID_KEY = "id"
 
 HISTORY_HOURLY_PATH = "/energy/historyHourly"
+# Hourly history does not need to be fetched with every 60-second state poll.
+HISTORY_HOURLY_REFRESH_INTERVAL = 30 * 60
+# Configuration, diagnostics, energy and device inventories change less often
+# than temperatures and operating modes.
+SLOW_RESOURCE_REFRESH_INTERVAL = 5 * 60
+SLOW_RESOURCE_PREFIXES = (
+    "/gateway",
+    "/energy",
+    "/solarCircuits",
+    "/devices",
+    "/programs",
+    "/system/appliance",
+)
+FAST_DEVICE_RESOURCE_MARKERS = (
+    "/devices/list",
+    "/etrv/",
+    "/thermostat/",
+)
 # Re-run the discovery reference walk at most this often so resources that
 # appear later (e.g. solar enabled by an installer) get picked up.
 REDISCOVERY_INTERVAL = 24 * 3600
 # Throttle the bulk-failure WARNING to once per hour; repeats log at DEBUG.
 BULK_WARN_INTERVAL = 3600
 
 
+def _is_slow_resource(path: str) -> bool:
+    """Return whether a resource can use the slower polling cadence."""
+    if path.startswith("/devices/") and any(
+        marker in path for marker in FAST_DEVICE_RESOURCE_MARKERS
+    ):
+        return False
+    return path == "/notifications" or path.startswith(SLOW_RESOURCE_PREFIXES)
+
+
 async def _fetch_history_hourly_all(client: PoinTTAPIClient) -> dict[str, Any] | None:
     """Walk /energy/historyHourly pagination forward to collect every entry.
 
@@ -97,16 +124,12 @@ async def _fetch_history_hourly_all(client: PoinTTAPIClient) -> dict[str, Any] |
     return first
 
 
-async def _zone_roots(client: PoinTTAPIClient) -> list[str]:
-    """GET /zones and return one walk root per zone ("/zones/zn1", ...).
-
-    Multi-zone gateways (ETRVs paired to rooms) list every zone here; walking
-    each one as a root gives it the same fetch depth zn1 always had. Falls
-    back to ["/zones/zn1"] when the listing is missing or fails, preserving
-    single-zone behavior.
-    """
+async def _discover_roots(
+    client: PoinTTAPIClient, root: str, fallback: str
+) -> list[str]:
+    """Return reference roots from a listing, or its static fallback."""
     try:
-        resp = await client.get("/zones")
+        resp = await client.get(root)
         if isinstance(resp, dict):
             roots = [
                 r[ID_KEY]
@@ -116,63 +139,27 @@ async def _zone_roots(client: PoinTTAPIClient) -> list[str]:
             if roots:
                 return roots
     except ConfigEntryAuthFailed:
-        _LOGGER.debug("POINTTAPI 401/403 on /zones, assuming single zone")
+        _LOGGER.debug("POINTTAPI 401/403 on %s, using %s", root, fallback)
     except Exception as err:
         _LOGGER.debug(
-            "POINTTAPI /zones listing unavailable (%s), assuming single zone", err
+            "POINTTAPI %s listing unavailable (%s), using %s", root, err, fallback
         )
-    return ["/zones/zn1"]
+    return [fallback]
 
 
-async def _program_roots(client: PoinTTAPIClient) -> list[str]:
-    """GET /programs and return one walk root per listed program.
+async def _zone_roots(client: PoinTTAPIClient) -> list[str]:
+    """Return one walk root per zone, with a zn1 fallback."""
+    return await _discover_roots(client, "/zones", "/zones/zn1")
 
-    Mirrors zone-root expansion: use the listing references as source-of-truth
-    and fall back to the top-level /programs root when discovery is missing or
-    unavailable.
-    """
-    try:
-        resp = await client.get("/programs")
-        if isinstance(resp, dict):
-            roots = [
-                r[ID_KEY]
-                for r in (resp.get(REFERENCES_KEY) or [])
-                if isinstance(r, dict) and r.get(ID_KEY)
-            ]
-            if roots:
-                return roots
-    except ConfigEntryAuthFailed:
-        _LOGGER.debug("POINTTAPI 401/403 on /programs, using /programs root")
-    except Exception as err:
-        _LOGGER.debug(
-            "POINTTAPI /programs listing unavailable (%s), using /programs root", err
-        )
-    return ["/programs"]
 
+async def _program_roots(client: PoinTTAPIClient) -> list[str]:
+    """Return one walk root per listed program."""
+    return await _discover_roots(client, "/programs", "/programs")
 
-async def _device_roots(client: PoinTTAPIClient) -> list[str]:
-    """GET /devices and return one walk root per listed device.
 
-    Mirrors zone/program root expansion and falls back to the top-level
-    /devices root when discovery is missing or unavailable.
-    """
-    try:
-        resp = await client.get("/devices")
-        if isinstance(resp, dict):
-            roots = [
-                r[ID_KEY]
-                for r in (resp.get(REFERENCES_KEY) or [])
-                if isinstance(r, dict) and r.get(ID_KEY)
-            ]
-            if roots:
-                return roots
-    except ConfigEntryAuthFailed:
-        _LOGGER.debug("POINTTAPI 401/403 on /devices, using /devices root")
-    except Exception as err:
-        _LOGGER.debug(
-            "POINTTAPI /devices listing unavailable (%s), using /devices root", err
-        )
-    return ["/devices"]
+async def _device_roots(client: PoinTTAPIClient) -> list[str]:
+    """Return one walk root per listed device."""
+    return await _discover_roots(client, "/devices", "/devices")
 
 
 async def _fetch_paths(client: PoinTTAPIClient) -> dict[str, Any]:
@@ -195,6 +182,8 @@ async def _fetch_paths(client: PoinTTAPIClient) -> dict[str, Any]:
             roots.extend(await _device_roots(client))
             continue
         roots.append(r)
+    roots = list(dict.fromkeys(roots))
+    seen_references: set[str] = set()
     for root in roots:
         if root == "/energy/historyHourly":
             try:
@@ -214,8 +203,9 @@ async def _fetch_paths(client: PoinTTAPIClient) -> dict[str, Any]:
             refs = resp.get(REFERENCES_KEY) or []
             for ref in refs:
                 ref_id = ref.get(ID_KEY) if isinstance(ref, dict) else None
-                if not ref_id:
+                if not ref_id or ref_id in seen_references:
                     continue
+                seen_references.add(ref_id)
                 try:
                     sub = await client.get(ref_id)
                     if isinstance(sub, dict):
@@ -281,6 +271,12 @@ def __init__(
         self._bulk_paths: list[str] = []
         self._last_discovery: float = 0.0
         self._bulk_warned_at: float | None = None
+        self._history_hourly_data: dict[str, Any] | None = None
+        self._last_history_hourly_fetch: float = 0.0
+        self._slow_bulk_paths: list[str] = []
+        self._fast_bulk_paths: list[str] = []
+        self._slow_data: dict[str, Any] = {}
+        self._last_slow_fetch: float = 0.0
 
     @property
     def client(self) -> PoinTTAPIClient:
@@ -315,38 +311,71 @@ async def _fetch(self) -> dict[str, Any]:
             # The paginated historyHourly resource stays on sequential GETs
             # (bulk resourcePaths carry no query strings).
             self._bulk_paths = [p for p in data if p != HISTORY_HOURLY_PATH]
+            self._slow_bulk_paths = [p for p in self._bulk_paths if _is_slow_resource(p)]
+            self._fast_bulk_paths = [p for p in self._bulk_paths if not _is_slow_resource(p)]
+            self._slow_data = {
+                p: data[p] for p in self._slow_bulk_paths if p in data
+            }
+            self._last_slow_fetch = now
             self._last_discovery = now
+            history = data.get(HISTORY_HOURLY_PATH)
+            if isinstance(history, dict):
+                self._history_hourly_data = history
+                self._last_history_hourly_fetch = now
             return data
 
-        try:
-            data = await self._client.bulk(self._bulk_paths)
-        except ConfigEntryAuthFailed:
-            raise
-        except Exception as err:
-            self._log_bulk_failure(err)
-            return await _fetch_paths(self._client)
-        if not data:
+        slow_due = (
+            not self._slow_data
+            or now - self._last_slow_fetch >= SLOW_RESOURCE_REFRESH_INTERVAL
+        )
+        bulk_paths = self._fast_bulk_paths + (
+            self._slow_bulk_paths if slow_due else []
+        )
+        if not bulk_paths:
+            data = {}
+        else:
+            try:
+                data = await self._client.bulk(bulk_paths)
+            except ConfigEntryAuthFailed:
+                raise
+            except Exception as err:
+                self._log_bulk_failure(err)
+                return await _fetch_paths(self._client)
+        if not data and bulk_paths:
             # An all-paths-failed envelope would wipe entity state; treat as
             # a wholesale failure instead.
             self._log_bulk_failure("empty bulk result")
             return await _fetch_paths(self._client)
+        if slow_due:
+            self._slow_data.update(
+                {p: data[p] for p in self._slow_bulk_paths if p in data}
+            )
+            self._last_slow_fetch = now
+        data = {**self._slow_data, **data}
         _LOGGER.debug(
             "POINTTAPI bulk steady state: %d/%d paths returned",
             len(data), len(self._bulk_paths),
         )
 
-        if HISTORY_HOURLY_PATH in POINTTAPI_COORDINATOR_ROOTS:
+        if (
+            self._history_hourly_data is None
+            or now - self._last_history_hourly_fetch
+            >= HISTORY_HOURLY_REFRESH_INTERVAL
+        ):
             try:
                 merged = await _fetch_history_hourly_all(self._client)
                 if isinstance(merged, dict):
-                    data[HISTORY_HOURLY_PATH] = merged
+                    self._history_hourly_data = merged
+                    self._last_history_hourly_fetch = now
             except ConfigEntryAuthFailed:
-                _LOGGER.debug("POINTTAPI 401/403 on %s, skipping", HISTORY_HOURLY_PATH)
+                _LOGGER.debug("POINTTAPI 401/403 on %s, keeping cached data", HISTORY_HOURLY_PATH)
             except Exception as err:
                 _LOGGER.debug(
                     "POINTTAPI optional path %s not available: %s",
                     HISTORY_HOURLY_PATH, err,
                 )
+        if self._history_hourly_data is not None:
+            data[HISTORY_HOURLY_PATH] = self._history_hourly_data
         return data
 
     def _log_bulk_failure(self, err: Any) -> None: