dimplex-controller 0.6.1__tar.gz → 0.7.0__tar.gz

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.6.1
+Version: 0.7.0
 Summary: Python client for Dimplex heating controllers (GDHV IoT)
 License: MIT
 License-File: LICENSE
@@ -179,24 +179,27 @@ await client.set_eco_start(hub_id, [appliance_id], True)
 # Enable Open Window Detection
 await client.set_open_window_detection(hub_id, [appliance_id], True)
 
-# Activate Boost (Mode 16, Status 1 = On)
-boost_settings = ApplianceModeSettings(ApplianceModes=16, Status=1, Temperature=25.0)
-await client.set_appliance_mode(hub_id, [appliance_id], boost_settings)
+# Activate Boost
+await client.set_boost(hub_id, [appliance_id], temperature=25.0, duration_minutes=60)
+
+# Set target temperature (rewrites timer period setpoints)
+await client.set_target_temperature(hub_id, appliance_id, 21.5)
 ```
 
 ### Energy reports
 
 ```python
-from dimplex_controller import parse_telemetry_points
+from dimplex_controller import parse_telemetry_points, summarise_energy
 
 report = await client.get_tsi_energy_report(hub_id)
-for appliance_id, telemetry in report.telemetry.items():
+for appliance_id, telemetry in report.ApplianceTelemetryData.items():
     points = parse_telemetry_points(telemetry)
-    for timestamp, value in points:
-        print(f"{appliance_id}: {value} kWh at {timestamp}")
+    daily = summarise_energy(points, mode="daily")
+    lifetime = summarise_energy(points, mode="lifetime")
+    print(f"{appliance_id}: today={daily.total_kwh} kWh, lifetime={lifetime.total_kwh} kWh")
 ```
 
-The `parse_telemetry_points` helper normalises arbitrary API response shapes (varying firmware formats) into `(timestamp, value)` tuples.
+`parse_telemetry_points` normalises firmware-varying point shapes. `summarise_energy` builds **daily** (local midnight) and **lifetime** totals. With `include_previous_period=True` the cloud often returns full history — filter client-side rather than trusting `days_back` alone.
 
 ## Configuration
 

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/README.md

@@ -150,24 +150,27 @@ await client.set_eco_start(hub_id, [appliance_id], True)
 # Enable Open Window Detection
 await client.set_open_window_detection(hub_id, [appliance_id], True)
 
-# Activate Boost (Mode 16, Status 1 = On)
-boost_settings = ApplianceModeSettings(ApplianceModes=16, Status=1, Temperature=25.0)
-await client.set_appliance_mode(hub_id, [appliance_id], boost_settings)
+# Activate Boost
+await client.set_boost(hub_id, [appliance_id], temperature=25.0, duration_minutes=60)
+
+# Set target temperature (rewrites timer period setpoints)
+await client.set_target_temperature(hub_id, appliance_id, 21.5)
 ```
 
 ### Energy reports
 
 ```python
-from dimplex_controller import parse_telemetry_points
+from dimplex_controller import parse_telemetry_points, summarise_energy
 
 report = await client.get_tsi_energy_report(hub_id)
-for appliance_id, telemetry in report.telemetry.items():
+for appliance_id, telemetry in report.ApplianceTelemetryData.items():
     points = parse_telemetry_points(telemetry)
-    for timestamp, value in points:
-        print(f"{appliance_id}: {value} kWh at {timestamp}")
+    daily = summarise_energy(points, mode="daily")
+    lifetime = summarise_energy(points, mode="lifetime")
+    print(f"{appliance_id}: today={daily.total_kwh} kWh, lifetime={lifetime.total_kwh} kWh")
 ```
 
-The `parse_telemetry_points` helper normalises arbitrary API response shapes (varying firmware formats) into `(timestamp, value)` tuples.
+`parse_telemetry_points` normalises firmware-varying point shapes. `summarise_energy` builds **daily** (local midnight) and **lifetime** totals. With `include_previous_period=True` the cloud often returns full history — filter client-side rather than trusting `days_back` alone.
 
 ## Configuration
 

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/dimplex_controller/__init__.py

@@ -1,28 +1,47 @@
 """Dimplex Controller Client."""
 
+from .auth import TokenBundle
 from .client import DimplexControl
 from .exceptions import DimplexApiError, DimplexAuthError, DimplexConnectionError, DimplexError
 from .models import (
     Appliance,
+    ApplianceModeFlag,
     ApplianceModeSettings,
     ApplianceStatus,
     AutomaticProvisioning,
     Hub,
+    TimerMode,
+    TimerModeSettings,
+    TimerPeriod,
     TsiEnergyReport,
     Zone,
 )
-from .telemetry import VALUE_KEY_T2, parse_telemetry_points
+from .telemetry import (
+    VALUE_KEY_T2,
+    EnergySummary,
+    filter_telemetry_points,
+    parse_telemetry_points,
+    summarise_energy,
+)
 
 __all__ = [
     "DimplexControl",
+    "TokenBundle",
     "Hub",
     "Zone",
     "Appliance",
     "ApplianceStatus",
     "ApplianceModeSettings",
+    "ApplianceModeFlag",
+    "TimerMode",
+    "TimerModeSettings",
+    "TimerPeriod",
     "AutomaticProvisioning",
     "TsiEnergyReport",
     "parse_telemetry_points",
+    "filter_telemetry_points",
+    "summarise_energy",
+    "EnergySummary",
     "VALUE_KEY_T2",
     "DimplexError",
     "DimplexApiError",

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/dimplex_controller/auth.py

@@ -1,8 +1,13 @@
+from __future__ import annotations
+
 import json
 import logging
 import os
 import re
 import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
 from urllib.parse import parse_qs, urlparse
 
 import aiohttp
@@ -19,33 +24,90 @@ from .exceptions import DimplexAuthError
 
 _LOGGER = logging.getLogger(__name__)
 
+TokenListener = Callable[["TokenBundle"], Awaitable[None] | None]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenBundle:
+    """Public, serialisable snapshot of auth tokens."""
+
+    access_token: str | None = None
+    refresh_token: str | None = None
+    expires_at: float = 0.0
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a plain dict suitable for JSON / config-entry storage."""
+        return {
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at,
+        }
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, Any] | None) -> TokenBundle:
+        """Build a bundle from a dict-like token store."""
+        if not data:
+            return cls()
+        return cls(
+            access_token=data.get("access_token"),
+            refresh_token=data.get("refresh_token"),
+            expires_at=float(data.get("expires_at") or 0),
+        )
+
 
 class AuthManager:
     """Manages authentication for Dimplex Control."""
 
-    def __init__(self, session: aiohttp.ClientSession, token_data: dict | None = None):
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        token_data: dict[str, Any] | TokenBundle | None = None,
+        *,
+        on_token_update: TokenListener | None = None,
+    ):
         """Initialize the auth manager."""
         self._session = session
-        self._access_token: str | None = token_data.get("access_token") if token_data else None
-        self._refresh_token: str | None = token_data.get("refresh_token") if token_data else None
-        self._expires_at: float = token_data.get("expires_at", 0) if token_data else 0
+        self._on_token_update = on_token_update
+        bundle = token_data if isinstance(token_data, TokenBundle) else TokenBundle.from_mapping(token_data)
+        self._access_token: str | None = bundle.access_token
+        self._refresh_token: str | None = bundle.refresh_token
+        self._expires_at: float = bundle.expires_at
 
     @property
     def is_authenticated(self) -> bool:
         """Check if we have a valid access token."""
         return self._access_token is not None and time.time() < self._expires_at
 
+    def export_tokens(self) -> TokenBundle:
+        """Return the current token snapshot (safe for persistence)."""
+        return TokenBundle(
+            access_token=self._access_token,
+            refresh_token=self._refresh_token,
+            expires_at=self._expires_at,
+        )
+
+    def apply_tokens(self, bundle: TokenBundle | dict[str, Any]) -> None:
+        """Replace in-memory tokens from a :class:`TokenBundle` or dict."""
+        if not isinstance(bundle, TokenBundle):
+            bundle = TokenBundle.from_mapping(bundle)
+        self._access_token = bundle.access_token
+        self._refresh_token = bundle.refresh_token
+        self._expires_at = bundle.expires_at
+
     async def get_access_token(self) -> str:
         """Get a valid access token, refreshing if necessary."""
         if not self._refresh_token:
             raise DimplexAuthError("No refresh token available. User must authenticate first.")
 
         if self.is_authenticated:
-            return self._access_token  # type: ignore[return-value]
+            assert self._access_token is not None
+            return self._access_token
 
         # Token expired or missing, try refresh
         await self.refresh_tokens()
-        return self._access_token  # type: ignore[return-value]
+        if not self._access_token:
+            raise DimplexAuthError("Token refresh succeeded but no access token was returned.")
+        return self._access_token
 
     async def refresh_tokens(self) -> None:
         """Refresh the access token using the refresh token."""
@@ -67,12 +129,42 @@ class AuthManager:
             data = await resp.json()
             self._update_tokens(data)
 
-    def _update_tokens(self, data: dict) -> None:
+    def _update_tokens(self, data: dict[str, Any]) -> None:
         """Update internal token state from API response."""
         self._access_token = data.get("access_token")
-        self._refresh_token = data.get("refresh_token")
+        # Some refresh responses omit a new refresh token — keep the old one.
+        if data.get("refresh_token"):
+            self._refresh_token = data.get("refresh_token")
         expires_in = data.get("expires_in", 3600)
-        self._expires_at = time.time() + expires_in - 60  # Buffer 60s
+        self._expires_at = time.time() + float(expires_in) - 60  # Buffer 60s
+        if self._on_token_update is not None:
+            result = self._on_token_update(self.export_tokens())
+            if hasattr(result, "__await__"):
+                # Listener may be async; fire-and-forget is unsafe here — callers
+                # should prefer sync listeners or schedule from the callback.
+                pass
+
+    def save_tokens(self, file_path: str) -> None:
+        """Save current tokens to a JSON file."""
+        data = self.export_tokens().as_dict()
+        with open(file_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        _LOGGER.info("Tokens saved to %s", file_path)
+
+    @classmethod
+    def load_tokens(cls, file_path: str) -> dict[str, Any] | None:
+        """Load tokens from a JSON file."""
+        if not os.path.exists(file_path):
+            return None
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                data = json.load(f)
+            if isinstance(data, dict):
+                return data
+            return None
+        except Exception as e:
+            _LOGGER.error("Failed to load tokens from %s: %s", file_path, e)
+            return None
 
     def get_login_url(self) -> str:
         """Generate the login URL for the user to visit."""
@@ -304,26 +396,3 @@ class AuthManager:
                         raise DimplexAuthError(f"Unexpected HTTP {resp.status} during redirect chain")
 
             raise DimplexAuthError("Exceeded maximum redirect hops without capturing auth code")
-
-    def save_tokens(self, file_path: str) -> None:
-        """Save current tokens to a JSON file."""
-        data = {
-            "access_token": self._access_token,
-            "refresh_token": self._refresh_token,
-            "expires_at": self._expires_at,
-        }
-        with open(file_path, "w") as f:
-            json.dump(data, f, indent=2)
-        _LOGGER.info("Tokens saved to %s", file_path)
-
-    @classmethod
-    def load_tokens(cls, file_path: str) -> dict | None:
-        """Load tokens from a JSON file."""
-        if not os.path.exists(file_path):
-            return None
-        try:
-            with open(file_path) as f:
-                return json.load(f)
-        except Exception as e:
-            _LOGGER.error("Failed to load tokens from %s: %s", file_path, e)
-            return None

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/dimplex_controller/client.py

@@ -1,10 +1,12 @@
+from __future__ import annotations
+
 import logging
 from datetime import datetime, timedelta, timezone
 from typing import Any
 
 import aiohttp
 
-from .auth import AuthManager
+from .auth import AuthManager, TokenBundle
 from .const import (
     BASE_URL,
     HEADER_APP_NAME,
@@ -18,10 +20,13 @@ from .const import (
 )
 from .exceptions import DimplexApiError, DimplexConnectionError
 from .models import (
+    ApplianceModeFlag,
     ApplianceModeSettings,
     ApplianceStatus,
     Hub,
+    TimerMode,
     TimerModeSettings,
+    TimerPeriod,
     TsiEnergyReport,
     UserContext,
     Zone,
@@ -30,11 +35,15 @@ from .models import (
 _LOGGER = logging.getLogger(__name__)
 
 # Default lookback when the caller does not pin a start date. The energy
-# endpoint is paginated server-side; 30 days is a reasonable default that
-# keeps the response small while still giving the caller a meaningful window.
+# endpoint is paginated server-side; with IncludePreviousPeriod the cloud
+# often returns the full history regardless, so this mainly bounds the
+# "current window" half of the request.
 DEFAULT_TSI_REPORT_DAYS = 30
 DEFAULT_TSI_INTERVAL = "01:00:00"
 
+# Default boost length when the caller does not specify one (minutes).
+DEFAULT_BOOST_MINUTES = 60
+
 
 def _iso_utc_days_ago(days: int) -> str:
     """Return an ISO-8601 UTC timestamp ``days`` before now (no microseconds)."""
@@ -51,15 +60,24 @@ class DimplexControl:
         refresh_token: str | None = None,
         access_token: str | None = None,
         expires_at: float = 0,
+        *,
+        token_bundle: TokenBundle | None = None,
     ):
-        """Initialize the client."""
-        token_data = {}
-        if refresh_token:
-            token_data["refresh_token"] = refresh_token
-        if access_token:
-            token_data["access_token"] = access_token
-        if expires_at:
-            token_data["expires_at"] = expires_at  # type: ignore[assignment]
+        """Initialize the client.
+
+        Prefer ``token_bundle`` for new code. The individual token kwargs remain
+        supported for backwards compatibility.
+        """
+        if token_bundle is not None:
+            token_data: dict[str, Any] | TokenBundle = token_bundle
+        else:
+            token_data = {}
+            if refresh_token:
+                token_data["refresh_token"] = refresh_token
+            if access_token:
+                token_data["access_token"] = access_token
+            if expires_at:
+                token_data["expires_at"] = expires_at
 
         self._session = session
         self.auth = AuthManager(session, token_data)
@@ -69,7 +87,15 @@ class DimplexControl:
         """Check if authenticated."""
         return self.auth.is_authenticated
 
-    async def _request(self, method: str, endpoint: str, **kwargs) -> dict:
+    def export_tokens(self) -> TokenBundle:
+        """Return the current auth token snapshot."""
+        return self.auth.export_tokens()
+
+    def apply_tokens(self, bundle: TokenBundle | dict[str, Any]) -> None:
+        """Replace in-memory auth tokens."""
+        self.auth.apply_tokens(bundle)
+
+    async def _request(self, method: str, endpoint: str, **kwargs: Any) -> Any:
         """Make an authenticated request."""
         token = await self.auth.get_access_token()
         headers = kwargs.pop("headers", {})
@@ -109,76 +135,164 @@ class DimplexControl:
     async def get_hubs(self) -> list[Hub]:
         """Get all hubs for the user."""
         data = await self._request("GET", "/Hubs/GetUserHubs")
-        # Log analysis shows list of objects
-        return [Hub(**h) for h in data]
+        return [Hub.model_validate(h) for h in data]
 
     async def get_hub_zones(self, hub_id: str) -> list[Zone]:
         """Get zones and appliances for a hub."""
         data = await self._request("GET", "/Zones/GetZonesAndAppliancesForHubId", params={"HubId": hub_id})
-        return [Zone(**z) for z in data]
+        return [Zone.model_validate(z) for z in data]
 
     async def get_zone(self, hub_id: str, zone_id: str) -> Zone:
         """Get details for a specific zone."""
         payload = {"HubId": hub_id, "ZoneId": zone_id}
         data = await self._request("POST", "/Zones/GetZone", json=payload)
-        return Zone(**data)
+        return Zone.model_validate(data)
 
     async def get_appliance_overview(self, hub_id: str, appliance_ids: list[str]) -> list[ApplianceStatus]:
-        """Get status overview for specific appliances."""
+        """Get status overview for specific appliances.
+
+        When appliances are offline the cloud may return an empty list with
+        HTTP 200. That is success — use :meth:`get_appliance_overview_map` if
+        you need a stable id → status mapping.
+        """
         payload = {"HubId": hub_id, "ApplianceIds": appliance_ids}
         data = await self._request("POST", "/RemoteControl/GetApplianceOverview", json=payload)
-        return [ApplianceStatus(**item) for item in data]
+        if not data:
+            return []
+        return [ApplianceStatus.model_validate(item) for item in data]
+
+    async def get_appliance_overview_map(
+        self, hub_id: str, appliance_ids: list[str]
+    ) -> dict[str, ApplianceStatus | None]:
+        """Return a map of appliance id → status (``None`` when missing)."""
+        overview = await self.get_appliance_overview(hub_id, appliance_ids)
+        by_id = {status.ApplianceId: status for status in overview}
+        return {appliance_id: by_id.get(appliance_id) for appliance_id in appliance_ids}
 
     async def get_user_context(self) -> UserContext:
         """Get user profile/context."""
         data = await self._request("GET", "/Identity/GetUserContext")
-        return UserContext(**data)
+        return UserContext.model_validate(data)
 
     async def get_appliance_features(self, hub_id: str, appliance_id: str) -> TimerModeSettings:
         """Get timer details (and mode) for an appliance."""
-        # In the logs, this endpoint returns current mode and timer profiles
         payload = {
             "HubId": hub_id,
             "ApplianceId": appliance_id,
-            "TimerMode": 0,  # Required field in request, value doesn't seem to matter for fetching?
+            "TimerMode": 0,  # Required field in request; value ignored on read
         }
         data = await self._request("POST", "/RemoteControl/GetTimerModeDetailsForAppliance", json=payload)
-        return TimerModeSettings(**data)
+        return TimerModeSettings.model_validate(data)
 
-    async def set_mode(self, hub_id: str, appliance_id: str, mode: int) -> None:
-        """Set the operation mode.
+    async def set_mode(self, hub_id: str, appliance_id: str, mode: int | TimerMode) -> None:
+        """Set the timer / operation mode.
 
-        Modes (inferred):
-        0: Manual? (User Timer?)
-        1: Manual
-        2: Frost Protection
-        3: Off?
+        See :class:`~dimplex_controller.models.TimerMode` for known values.
         """
-        # We need to fetch current settings first to preserve other fields if API requires full object
         current = await self.get_appliance_features(hub_id, appliance_id)
-        current.TimerMode = mode
-
-        payload = {"TimerModeSettings": current.dict()}
+        current.TimerMode = int(mode)
 
+        payload = {"TimerModeSettings": current.model_dump(mode="json")}
         await self._request("POST", "/RemoteControl/SetTimerMode", json=payload)
 
     async def set_target_temperature(self, hub_id: str, appliance_id: str, temp: float) -> None:
-        """Set target temperature.
+        """Set the target / comfort temperature for an appliance.
+
+        The Dimplex cloud stores setpoints on timer periods. This method:
 
-        WARNING: The logs show setting temperature involves updating the 'TimerPeriods' for the current mode.
-        This client might need to be smarter about which period to update (current active one).
-        For now, this is a placeholder/advanced TODO.
+        1. Loads the current timer configuration.
+        2. Updates every period's temperature (preserving day/time windows).
+        3. If no periods exist (common for some Quantum configs), installs a
+           full-week 00:00–23:59 schedule at the requested temperature in
+           manual mode so the cloud has a concrete setpoint to apply.
+
+        This matches the reverse-engineered mobile-app approach of rewriting
+        the active schedule rather than a dedicated "set temperature" RPC.
         """
-        _LOGGER.warning("set_target_temperature not fully implemented - requires complex schedule manipulation")
-        pass
+        current = await self.get_appliance_features(hub_id, appliance_id)
+
+        if current.TimerPeriods:
+            for period in current.TimerPeriods:
+                period.Temperature = float(temp)
+        else:
+            current.TimerMode = int(TimerMode.MANUAL)
+            current.TimerPeriods = [
+                TimerPeriod(
+                    DayOfWeek=day,
+                    StartTime="00:00:00",
+                    EndTime="23:59:59",
+                    Temperature=float(temp),
+                )
+                for day in range(7)
+            ]
+
+        payload = {"TimerModeSettings": current.model_dump(mode="json")}
+        await self._request("POST", "/RemoteControl/SetTimerMode", json=payload)
 
     async def set_appliance_mode(
         self, hub_id: str, appliance_ids: list[str], mode_settings: ApplianceModeSettings
     ) -> None:
         """Set appliance mode (Boost, Away, etc.)."""
-        payload = {"Settings": mode_settings.dict(), "HubId": hub_id, "ApplianceIds": appliance_ids}
+        payload = {
+            "Settings": mode_settings.model_dump(mode="json"),
+            "HubId": hub_id,
+            "ApplianceIds": appliance_ids,
+        }
         await self._request("POST", "/RemoteControl/SetApplianceMode", json=payload)
 
+    async def set_boost(
+        self,
+        hub_id: str,
+        appliance_ids: list[str],
+        *,
+        temperature: float,
+        duration_minutes: int = DEFAULT_BOOST_MINUTES,
+        enable: bool = True,
+    ) -> None:
+        """Enable or disable Boost for one or more appliances.
+
+        The mobile app uses ``ApplianceModes=16`` with ``Status=1`` (on) /
+        ``Status=0`` (off). ``Time`` carries the boost duration in minutes.
+        """
+        settings = ApplianceModeSettings(
+            ApplianceModes=int(ApplianceModeFlag.BOOST),
+            Status=1 if enable else 0,
+            Temperature=float(temperature),
+            Time=int(duration_minutes) if enable else 0,
+        )
+        await self.set_appliance_mode(hub_id, appliance_ids, settings)
+
+    async def clear_boost(self, hub_id: str, appliance_ids: list[str], *, temperature: float = 21.0) -> None:
+        """Disable Boost for the given appliances."""
+        await self.set_boost(hub_id, appliance_ids, temperature=temperature, duration_minutes=0, enable=False)
+
+    async def set_away(
+        self,
+        hub_id: str,
+        appliance_ids: list[str],
+        *,
+        temperature: float,
+        enable: bool = True,
+        number_of_days: int = 0,
+    ) -> None:
+        """Enable or disable Away mode.
+
+        Uses ``ApplianceModes=32`` (best-effort; confirmed via status-frame
+        pairing with Away* fields). Prefer verifying on a live appliance
+        after firmware updates.
+        """
+        settings = ApplianceModeSettings(
+            ApplianceModes=int(ApplianceModeFlag.AWAY),
+            Status=1 if enable else 0,
+            Temperature=float(temperature),
+            NumberOfDays=int(number_of_days) if enable else 0,
+        )
+        await self.set_appliance_mode(hub_id, appliance_ids, settings)
+
+    async def clear_away(self, hub_id: str, appliance_ids: list[str], *, temperature: float = 16.0) -> None:
+        """Disable Away mode for the given appliances."""
+        await self.set_away(hub_id, appliance_ids, temperature=temperature, enable=False)
+
     async def set_eco_start(self, hub_id: str, appliance_ids: list[str], enable: bool) -> None:
         """Enable/Disable EcoStart."""
         payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
@@ -196,19 +310,24 @@ class DimplexControl:
         interval: str = DEFAULT_TSI_INTERVAL,
         start_date: str | None = None,
         end_date: str | None = None,
-        include_previous_period: bool = False,
+        include_previous_period: bool = True,
         days_back: int = DEFAULT_TSI_REPORT_DAYS,
     ) -> TsiEnergyReport:
         """Fetch the Time Series Insights energy report for a hub.
 
         Returns a :class:`~dimplex_controller.models.TsiEnergyReport`. Each
         per-appliance list is left as the raw payload — use
-        :func:`dimplex_controller.telemetry.parse_telemetry_points` to
-        normalise the points into ``(timestamp, value)`` tuples.
+        :func:`dimplex_controller.telemetry.parse_telemetry_points` and
+        :func:`dimplex_controller.telemetry.summarise_energy` to normalise
+        and aggregate.
 
         When the hub has no metered appliances (e.g. non-QRAD heaters, or a
         quiet summer hub) the per-appliance lists come back empty; that is
         treated as success, not an error.
+
+        Note: with ``include_previous_period=True`` (the default) the cloud
+        frequently returns the **full available daily history**, not only the
+        ``days_back`` window. Filter client-side for daily/lifetime totals.
         """
         if start_date is None:
             start_date = _iso_utc_days_ago(days_back)

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/dimplex_controller/models.py

@@ -1,9 +1,39 @@
+from __future__ import annotations
+
 import json
 from datetime import datetime, time
+from enum import IntEnum, IntFlag
 
 from pydantic import BaseModel, Field, field_validator
 
 
+class TimerMode(IntEnum):
+    """Observed timer / operation mode values for ``TimerModeSettings.TimerMode``.
+
+    Exact product names vary by appliance firmware; these are the values used
+    by the Dimplex Control mobile client and reverse-engineered traffic.
+    """
+
+    USER_TIMER = 0
+    MANUAL = 1
+    FROST_PROTECTION = 2
+    OFF = 3
+
+
+class ApplianceModeFlag(IntFlag):
+    """Bit flags for ``ApplianceStatus.ApplianceModes`` / mode write payloads.
+
+    Only bits confirmed in traffic or the official app docs are named.
+    ``BOOST`` (16) is used by the mobile app for boost mode.
+    ``AWAY`` (32) is inferred from status frame pairing with Away* fields —
+    treat as best-effort until more captures confirm it for every model.
+    """
+
+    NONE = 0
+    BOOST = 16
+    AWAY = 32
+
+
 class AutomaticProvisioning(BaseModel):
     """Parsed contents of ``ProductModelExtensions.AUTOMATIC_PROVISIONING``.
 
@@ -137,7 +167,7 @@ class ApplianceStatus(BaseModel):
     StatusTwo: int | None = None
     ApplianceModes: int | None = None
     RoomTemperature: float | None = None
-    ActiveSetPointTemperature: int | None = None
+    ActiveSetPointTemperature: float | None = None
     NormalTemperature: float | None = None
     AwayDateTime: str | None = None
     AwayTemperature: float | None = None
@@ -154,6 +184,27 @@ class ApplianceStatus(BaseModel):
     ErrorCode: str | None = None
     WarningCode: str | None = None
 
+    @property
+    def mode_flags(self) -> ApplianceModeFlag:
+        """Return ``ApplianceModes`` as a typed flag set."""
+        if self.ApplianceModes is None:
+            return ApplianceModeFlag.NONE
+        return ApplianceModeFlag(self.ApplianceModes)
+
+    @property
+    def is_boost_active(self) -> bool:
+        """True when boost duration is set or the boost mode bit is present."""
+        if self.BoostDuration is not None and self.BoostDuration > 0:
+            return True
+        return bool(self.mode_flags & ApplianceModeFlag.BOOST)
+
+    @property
+    def is_away_active(self) -> bool:
+        """True when away fields indicate an active away session."""
+        if self.AwayDateTime and self.AwayDateTime not in ("", "0001-01-01T00:00:00"):
+            return True
+        return bool(self.mode_flags & ApplianceModeFlag.AWAY)
+
 
 class ApplianceModeSettings(BaseModel):
     """Settings used to control appliance modes like Boost or Away."""

dimplex_controller-0.7.0/dimplex_controller/telemetry.py

@@ -0,0 +1,304 @@
+"""Telemetry parsing for the Dimplex Reports API.
+
+The response from ``POST /Reports/GetTsiEnergyReportDataForHub`` contains
+``ApplianceTelemetryData``: a dict keyed by appliance id, with one list of
+``telemetry points`` per appliance. The shape of each point is not documented
+and varies between firmware versions, so we normalise whatever the cloud
+sends into ``(timestamp, value)`` tuples.
+
+Real-world payloads have been observed using ``TS`` (Unix-epoch timestamp)
+with either ``T1`` or ``ST`` as the energy value key.
+
+Important cloud semantics (live-verified):
+
+* With ``IncludePreviousPeriod=true`` the cloud often returns **the full
+  available daily history** (from first telem / install), not just the
+  ``StartDate``→``EndDate`` window.
+* With ``IncludePreviousPeriod=false`` and idle heaters, lists may be empty.
+* Points are typically **one kWh sample per calendar day**, not a continuous
+  cumulative counter.
+
+Use :func:`summarise_energy` for the two product totals:
+
+* ``daily`` — kWh for the local calendar day (from local midnight)
+* ``lifetime`` — sum of all parsed points (earliest → latest)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import date, datetime, time, timezone, tzinfo
+from typing import Any, Literal
+
+# Keys the cloud has been observed using, in priority order. The first match
+# wins. Case-insensitive lookup is done by lowercasing the dict before
+# scanning, so callers do not have to worry about casing.
+_DEFAULT_TIMESTAMP_KEYS = (
+    "timestamp",
+    "time",
+    "ts",
+    "t",
+    "datetime",
+    "date",
+    "from",
+    "start",
+)
+_DEFAULT_VALUE_KEYS = (
+    "t1",
+    "st",  # Observed on QRAD050F / QRAD075F energy reports (see dimplex-controller-hass #27).
+    "value",
+    "kwh",
+    "energy",
+    "consumption",
+    "energykwh",
+    "amount",
+    "v",
+    # Fallback for appliances that only report the secondary register.
+    "t2",
+)
+
+# Secondary energy register observed for some Quantum appliances. Points may
+# contain both ``T1`` and ``T2`` in the same payload.
+VALUE_KEY_T2 = (
+    "t2",
+    "value2",
+    "kwh2",
+    "energy2",
+)
+
+EnergyMode = Literal["daily", "lifetime", "window"]
+TelemetryPoint = tuple[datetime | None, float]
+
+
+@dataclass(frozen=True, slots=True)
+class EnergySummary:
+    """Aggregated energy for a set of telemetry points.
+
+    Attributes:
+        total_kwh: Sum of point values in kWh.
+        point_count: Number of points included in the total.
+        start: Earliest timestamp among included points (or day start for daily).
+        end: Latest timestamp among included points (or None).
+        mode: Aggregation mode used to produce this summary.
+    """
+
+    total_kwh: float
+    point_count: int
+    start: datetime | None
+    end: datetime | None
+    mode: EnergyMode
+
+
+def _coerce_timestamp(raw: Any) -> datetime | None:
+    """Best-effort conversion of ``raw`` into a ``datetime``.
+
+    Accepts ``datetime`` instances, ISO-8601 strings, and Unix epoch numbers
+    (seconds or milliseconds). Returns ``None`` if the value cannot be parsed.
+    """
+    if raw is None:
+        return None
+    if isinstance(raw, datetime):
+        return raw
+    if isinstance(raw, int | float):
+        ts = float(raw)
+        if ts > 1e12:
+            ts = ts / 1000.0
+        try:
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+        except (OverflowError, OSError, ValueError):
+            return None
+    if isinstance(raw, str):
+        text = raw.strip()
+        if not text:
+            return None
+        try:
+            return datetime.fromisoformat(text.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return None
+
+
+def _coerce_value(raw: Any) -> float | None:
+    """Best-effort conversion of ``raw`` into a ``float``."""
+    if raw is None:
+        return None
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int | float):
+        return float(raw)
+    if isinstance(raw, str):
+        try:
+            return float(raw.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _iter_items(point: Any) -> Iterable[tuple[str, Any]] | None:
+    """Yield ``(key, value)`` pairs from a dict-like ``point``.
+
+    Returns ``None`` for non-dict points so the caller can fall through to the
+    list / scalar branches.
+    """
+    if not isinstance(point, dict):
+        return None
+    lower = {str(k).lower(): v for k, v in point.items()}
+    return ((k, lower.get(k)) for k in (*_DEFAULT_TIMESTAMP_KEYS, *_DEFAULT_VALUE_KEYS, *VALUE_KEY_T2))
+
+
+def parse_telemetry_points(
+    points: Any,
+    *,
+    value_keys: tuple[str, ...] | None = None,
+) -> list[TelemetryPoint]:
+    """Normalise a list of telemetry points into ``(timestamp, value)`` pairs.
+
+    Each entry in ``points`` may be:
+
+    * a ``dict`` with one of the recognised timestamp/value keys
+    * a 2-element ``[timestamp, value]`` list or tuple
+    * a bare scalar (treated as a cumulative value at an unknown timestamp)
+
+    ``value_keys`` overrides the value-key priority list. Use
+    :data:`VALUE_KEY_T2` to extract the secondary energy register when the
+    cloud returns both ``T1`` and ``T2`` in the same payload.
+
+    Unparseable entries are silently skipped. The order of the input list is
+    preserved.
+    """
+    if not isinstance(points, list):
+        return []
+
+    value_key_order = value_keys if value_keys is not None else _DEFAULT_VALUE_KEYS
+    timestamp_keys = _DEFAULT_TIMESTAMP_KEYS
+
+    out: list[TelemetryPoint] = []
+    for point in points:
+        ts: datetime | None = None
+        value: float | None = None
+
+        items = _iter_items(point)
+        if items is not None:
+            for key, raw in items:
+                if key in timestamp_keys and ts is None:
+                    ts = _coerce_timestamp(raw)
+                elif key in value_key_order and value is None:
+                    value = _coerce_value(raw)
+        elif isinstance(point, list | tuple) and len(point) == 2:
+            ts = _coerce_timestamp(point[0])
+            value = _coerce_value(point[1])
+        else:
+            value = _coerce_value(point)
+
+        if value is None:
+            continue
+        out.append((ts, value))
+    return out
+
+
+def _ensure_aware(ts: datetime, default_tz: tzinfo) -> datetime:
+    """Return ``ts`` with a timezone; naive datetimes are assumed ``default_tz``."""
+    if ts.tzinfo is None:
+        return ts.replace(tzinfo=default_tz)
+    return ts
+
+
+def local_midnight(now: datetime, tz: tzinfo) -> datetime:
+    """Return the start of the local calendar day containing ``now``."""
+    local = _ensure_aware(now, tz).astimezone(tz)
+    return datetime.combine(local.date(), time.min, tzinfo=tz)
+
+
+def filter_telemetry_points(
+    points: Sequence[TelemetryPoint],
+    *,
+    start: datetime | None = None,
+    end: datetime | None = None,
+    on_date: date | None = None,
+    tz: tzinfo = timezone.utc,
+) -> list[TelemetryPoint]:
+    """Filter parsed points by absolute window and/or local calendar date.
+
+    * ``start`` / ``end`` are inclusive bounds (compared in UTC).
+    * ``on_date`` keeps points whose local date (in ``tz``) equals that day.
+    Points with a missing timestamp are dropped when any filter is active.
+    """
+    if start is None and end is None and on_date is None:
+        return list(points)
+
+    start_utc = _ensure_aware(start, tz).astimezone(timezone.utc) if start is not None else None
+    end_utc = _ensure_aware(end, tz).astimezone(timezone.utc) if end is not None else None
+
+    out: list[TelemetryPoint] = []
+    for ts, value in points:
+        if ts is None:
+            continue
+        aware = _ensure_aware(ts, timezone.utc)
+        if start_utc is not None and aware < start_utc:
+            continue
+        if end_utc is not None and aware > end_utc:
+            continue
+        if on_date is not None and aware.astimezone(tz).date() != on_date:
+            continue
+        out.append((aware, value))
+    return out
+
+
+def summarise_energy(
+    points: Sequence[TelemetryPoint] | Any,
+    *,
+    mode: EnergyMode = "lifetime",
+    now: datetime | None = None,
+    tz: tzinfo = timezone.utc,
+    start: datetime | None = None,
+    end: datetime | None = None,
+    value_keys: tuple[str, ...] | None = None,
+) -> EnergySummary:
+    """Aggregate telemetry into a daily, lifetime, or custom-window total.
+
+    ``points`` may be raw cloud payloads or already-parsed
+    :data:`TelemetryPoint` tuples. When raw, they are passed through
+    :func:`parse_telemetry_points` first.
+    """
+    parsed: list[TelemetryPoint]
+    if (
+        isinstance(points, Sequence)
+        and not isinstance(points, str | bytes)
+        and points
+        and isinstance(points[0], tuple)
+        and len(points[0]) == 2
+    ):
+        parsed = list(points)  # type: ignore[arg-type]
+    else:
+        parsed = parse_telemetry_points(points, value_keys=value_keys)
+
+    ref_now = now if now is not None else datetime.now(timezone.utc)
+    ref_now = _ensure_aware(ref_now, tz)
+
+    if mode == "daily":
+        day = ref_now.astimezone(tz).date()
+        selected = filter_telemetry_points(parsed, on_date=day, tz=tz)
+        day_start = local_midnight(ref_now, tz)
+        timestamps = [ts for ts, _ in selected if ts is not None]
+        total = sum(v for _, v in selected)
+        return EnergySummary(
+            total_kwh=round(total, 3),
+            point_count=len(selected),
+            start=day_start,
+            end=max(timestamps) if timestamps else None,
+            mode="daily",
+        )
+
+    # lifetime — include every parseable point; window — optional start/end filter
+    selected = filter_telemetry_points(parsed, start=start, end=end, tz=tz) if mode == "window" else list(parsed)
+
+    timestamps = [ts for ts, _ in selected if ts is not None]
+    total = sum(v for _, v in selected)
+    return EnergySummary(
+        total_kwh=round(total, 3),
+        point_count=len(selected),
+        start=min(timestamps) if timestamps else None,
+        end=max(timestamps) if timestamps else None,
+        mode=mode,
+    )

{dimplex_controller-0.6.1 → dimplex_controller-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dimplex-controller"
-version = "0.6.1"
+version = "0.7.0"
 description = "Python client for Dimplex heating controllers (GDHV IoT)"
 authors = ["Kieran Roper"]
 license = "MIT"

dimplex_controller-0.6.1/dimplex_controller/telemetry.py

@@ -1,160 +0,0 @@
-"""Telemetry parsing for the Dimplex Reports API.
-
-The response from ``POST /Reports/GetTsiEnergyReportDataForHub`` contains
-``ApplianceTelemetryData``: a dict keyed by appliance id, with one list of
-``telemetry points`` per appliance. The shape of each point is not documented
-and varies between firmware versions, so we normalise whatever the cloud
-sends into ``(timestamp, value)`` tuples.
-
-Real-world payloads have been observed using ``TS`` (Unix-epoch timestamp)
-with either ``T1`` or ``ST`` as the energy value key.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Iterable
-from datetime import datetime, timezone
-from typing import Any
-
-# Keys the cloud has been observed using, in priority order. The first match
-# wins. Case-insensitive lookup is done by lowercasing the dict before
-# scanning, so callers do not have to worry about casing.
-_DEFAULT_TIMESTAMP_KEYS = (
-    "timestamp",
-    "time",
-    "ts",
-    "t",
-    "datetime",
-    "date",
-    "from",
-    "start",
-)
-_DEFAULT_VALUE_KEYS = (
-    "t1",
-    "st",  # Observed on QRAD050F / QRAD075F energy reports (see dimplex-controller-hass #27).
-    "value",
-    "kwh",
-    "energy",
-    "consumption",
-    "energykwh",
-    "amount",
-    "v",
-    # Fallback for appliances that only report the secondary register.
-    "t2",
-)
-
-# Secondary energy register observed for some Quantum appliances. Points may
-# contain both ``T1`` and ``T2`` in the same payload.
-VALUE_KEY_T2 = (
-    "t2",
-    "value2",
-    "kwh2",
-    "energy2",
-)
-
-
-def _coerce_timestamp(raw: Any) -> datetime | None:
-    """Best-effort conversion of ``raw`` into a ``datetime``.
-
-    Accepts ``datetime`` instances, ISO-8601 strings, and Unix epoch numbers
-    (seconds or milliseconds). Returns ``None`` if the value cannot be parsed.
-    """
-    if raw is None:
-        return None
-    if isinstance(raw, datetime):
-        return raw
-    if isinstance(raw, int | float):
-        ts = float(raw)
-        if ts > 1e12:
-            ts = ts / 1000.0
-        try:
-            return datetime.fromtimestamp(ts, tz=timezone.utc)
-        except (OverflowError, OSError, ValueError):
-            return None
-    if isinstance(raw, str):
-        text = raw.strip()
-        if not text:
-            return None
-        try:
-            return datetime.fromisoformat(text.replace("Z", "+00:00"))
-        except ValueError:
-            return None
-    return None
-
-
-def _coerce_value(raw: Any) -> float | None:
-    """Best-effort conversion of ``raw`` into a ``float``."""
-    if raw is None:
-        return None
-    if isinstance(raw, bool):
-        return None
-    if isinstance(raw, int | float):
-        return float(raw)
-    if isinstance(raw, str):
-        try:
-            return float(raw.strip())
-        except ValueError:
-            return None
-    return None
-
-
-def _iter_items(point: Any) -> Iterable[tuple[str, Any]] | None:
-    """Yield ``(key, value)`` pairs from a dict-like ``point``.
-
-    Returns ``None`` for non-dict points so the caller can fall through to the
-    list / scalar branches.
-    """
-    if not isinstance(point, dict):
-        return None
-    lower = {str(k).lower(): v for k, v in point.items()}
-    return ((k, lower.get(k)) for k in (*_DEFAULT_TIMESTAMP_KEYS, *_DEFAULT_VALUE_KEYS, *VALUE_KEY_T2))
-
-
-def parse_telemetry_points(
-    points: Any,
-    *,
-    value_keys: tuple[str, ...] | None = None,
-) -> list[tuple[datetime | None, float]]:
-    """Normalise a list of telemetry points into ``(timestamp, value)`` pairs.
-
-    Each entry in ``points`` may be:
-
-    * a ``dict`` with one of the recognised timestamp/value keys
-    * a 2-element ``[timestamp, value]`` list or tuple
-    * a bare scalar (treated as a cumulative value at an unknown timestamp)
-
-    ``value_keys`` overrides the value-key priority list. Use
-    :data:`VALUE_KEY_T2` to extract the secondary energy register when the
-    cloud returns both ``T1`` and ``T2`` in the same payload.
-
-    Unparseable entries are silently skipped. The order of the input list is
-    preserved.
-    """
-    if not isinstance(points, list):
-        return []
-
-    value_key_order = value_keys if value_keys is not None else _DEFAULT_VALUE_KEYS
-    timestamp_keys = _DEFAULT_TIMESTAMP_KEYS
-
-    out: list[tuple[datetime | None, float]] = []
-    for point in points:
-        ts: datetime | None = None
-        value: float | None = None
-
-        items = _iter_items(point)
-        if items is not None:
-            for key, raw in items:
-                if key in timestamp_keys and ts is None:
-                    ts = _coerce_timestamp(raw)
-                elif key in value_key_order and value is None:
-                    value = _coerce_value(raw)
-        elif isinstance(point, list | tuple) and len(point) == 2:
-            ts = _coerce_timestamp(point[0])
-            value = _coerce_value(point[1])
-        else:
-            value = _coerce_value(point)
-
-        if value is None:
-            continue
-        out.append((ts, value))
-    return out