dimplex-controller 0.15.0__tar.gz → 0.16.0__tar.gz

{dimplex_controller-0.15.0 → dimplex_controller-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.15.0
+Version: 0.16.0
 Summary: Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex
 Keywords: dimplex,heating,control,iot,asyncio
 Author: Kieran Roper

{dimplex_controller-0.15.0 → dimplex_controller-0.16.0}/dimplex_controller/auth.py

@@ -101,6 +101,10 @@ class AuthManager:
         self._access_token: str | None = bundle.access_token
         self._refresh_token: str | None = bundle.refresh_token
         self._expires_at: float = bundle.expires_at
+        # Serialises refreshes so concurrent callers share one POST (see
+        # get_access_token). Created eagerly: asyncio locks bind to the running
+        # loop on first use, not on construction.
+        self._refresh_lock = asyncio.Lock()
 
     def _request_kwargs(self) -> dict[str, Any]:
         """Common per-request kwargs (applies the configured timeout)."""
@@ -130,7 +134,17 @@ class AuthManager:
         self._expires_at = bundle.expires_at
 
     async def get_access_token(self) -> str:
-        """Get a valid access token, refreshing if necessary."""
+        """Get a valid access token, refreshing if necessary.
+
+        Refresh is single-flight. Callers that see an expired token queue on
+        :attr:`_refresh_lock` and re-check expiry once they hold it, so only the
+        first performs the ``POST /token`` and the rest reuse its result. The
+        cloud rotates the refresh token on every refresh, so two concurrent
+        refreshes sent the same token meant all but one were answered
+        ``invalid_grant`` — a permanent auth failure produced by ordinary
+        concurrency (dimplex-controller-py#139). A failed refresh raises through
+        ``async with``, leaving the lock free for the next caller.
+        """
         if not self._refresh_token:
             raise DimplexAuthInvalidGrantError(
                 "No refresh token available. User must authenticate first.",
@@ -141,8 +155,11 @@ class AuthManager:
             assert self._access_token is not None
             return self._access_token
 
-        # Token expired or missing, try refresh
-        await self.refresh_tokens()
+        async with self._refresh_lock:
+            # Another caller may have refreshed while we waited for the lock.
+            if not self.is_authenticated:
+                await self.refresh_tokens()
+
         if not self._access_token:
             raise DimplexAuthInvalidGrantError(
                 "Token refresh succeeded but no access token was returned.",

{dimplex_controller-0.15.0 → dimplex_controller-0.16.0}/dimplex_controller/client.py

@@ -26,7 +26,8 @@ from .const import (
     HEADER_DEVICE_OS,
     HEADER_DEVICE_VERSION,
     HEADER_USER_AGENT,
-    HTTP_OK,
+    MODE_TEMP_MAX,
+    MODE_TEMP_MIN,
     NO_SETPOINT_SENTINEL,
     NULL_DATETIME,
 )
@@ -41,6 +42,7 @@ from .models import (
     Hub,
     HygieneFrequency,
     ProductModel,
+    ScheduleProfile,
     SetbackStatus,
     TimerMode,
     TimerModeSettings,
@@ -94,6 +96,28 @@ def _clamp_away_temperature(temperature: float) -> float:
     return clamped
 
 
+def _clamp_mode_temperature(temperature: float) -> float:
+    """Clamp a setpoint into the 7–30 °C the app's mode carousels offer.
+
+    The wire field is a byte, so an out-of-range value used to be sent verbatim
+    and only reduced (or ignored) by the cloud — the write reported success for
+    a setpoint the appliance never reached. Clamping, as Away already does,
+    keeps the requested value and the applied value in agreement and makes the
+    adjustment visible (dimplex-controller-py#141).
+    """
+    value = float(temperature)
+    clamped = min(max(value, MODE_TEMP_MIN), MODE_TEMP_MAX)
+    if clamped != value:
+        _LOGGER.warning(
+            "Setpoint %.1f °C is outside the %s–%s °C the app offers; using %.1f °C",
+            value,
+            MODE_TEMP_MIN,
+            MODE_TEMP_MAX,
+            clamped,
+        )
+    return clamped
+
+
 def _coerce_timeout(timeout: float | aiohttp.ClientTimeout | None) -> aiohttp.ClientTimeout | None:
     """Normalise a timeout value into an :class:`aiohttp.ClientTimeout`.
 
@@ -260,7 +284,11 @@ class DimplexControl:
         for attempt in range(attempts):
             try:
                 async with self._session.request(method, url, headers=headers, **kwargs) as resp:
-                    if resp.status == HTTP_OK:
+                    # Any 2xx is success. Control endpoints may answer 204 No
+                    # Content, and an empty body is already what
+                    # _decode_ok_body handles; gating on exactly 200 raised a
+                    # successful write as an API error (dimplex-controller-py#141).
+                    if 200 <= resp.status < 300:
                         return await self._decode_ok_body(resp)
 
                     text = await resp.text()
@@ -389,19 +417,38 @@ class DimplexControl:
             return []
         return [ProductModel.model_validate(item) for item in data]
 
-    async def get_appliance_features(self, hub_id: str, appliance_id: str) -> TimerModeSettings:
-        """Get timer details (and mode) for an appliance."""
+    async def get_appliance_features(
+        self,
+        hub_id: str,
+        appliance_id: str,
+        *,
+        timer_mode: int | ScheduleProfile = 0,
+    ) -> TimerModeSettings:
+        """Get a profile's timer periods for an appliance.
+
+        ``timer_mode`` selects which profile's periods come back (0 = user
+        timer, 1 = home all day, 2 = out all day); the app fetches each profile
+        separately and caches one entry per value. The response ``TimerMode``
+        echoes the request — it is not the active schedule, which lives in
+        ``ApplianceStatus.StatusTwo`` (dimplex-controller-py#149).
+        """
         payload = {
             "HubId": hub_id,
             "ApplianceId": appliance_id,
-            "TimerMode": 0,  # Required field in request; value ignored on read
+            "TimerMode": int(timer_mode),
         }
         data = await self._request("POST", "/RemoteControl/GetTimerModeDetailsForAppliance", json=payload)
         return TimerModeSettings.model_validate(data)
 
-    async def get_schedule(self, hub_id: str, appliance_id: str) -> TimerModeSettings:
-        """Return the current timer mode + periods (alias of :meth:`get_appliance_features`)."""
-        return await self.get_appliance_features(hub_id, appliance_id)
+    async def get_schedule(
+        self,
+        hub_id: str,
+        appliance_id: str,
+        *,
+        timer_mode: int | ScheduleProfile = 0,
+    ) -> TimerModeSettings:
+        """Return a profile's timer periods (alias of :meth:`get_appliance_features`)."""
+        return await self.get_appliance_features(hub_id, appliance_id, timer_mode=timer_mode)
 
     async def _write_timer_settings(self, settings: TimerModeSettings) -> TimerModeSettings:
         """POST a full :class:`TimerModeSettings` payload and return it."""
@@ -545,6 +592,7 @@ class DimplexControl:
         until: datetime | str | None = None,
         number_of_days: int = 0,
         frequency: int | HygieneFrequency = 0,
+        status_two: int | ScheduleProfile = 0,
         endpoint: str = "/RemoteControl/SetApplianceMode",
     ) -> None:
         """Engage or clear a single :class:`ApplianceModeFlag`.
@@ -561,6 +609,7 @@ class DimplexControl:
             Date=_iso_away_until(until) if enable else NULL_DATETIME,
             NumberOfDays=int(number_of_days) if enable else 0,
             Frequency=int(frequency) if enable else 0,
+            StatusTwo=int(status_two) if enable else 0,
         )
         payload = {
             "Settings": settings.model_dump(mode="json"),
@@ -584,18 +633,27 @@ class DimplexControl:
         with ``Status=1`` (on) / ``Status=0`` (off); ``Time`` carries the boost
         duration in minutes and ``Temperature`` the boost target (7–30 °C).
 
+        A non-positive ``duration_minutes`` raises :class:`ValueError` when
+        engaging: the cloud accepted ``Time=0`` and the appliance simply did not
+        boost, so the caller was told a boost had started that never would
+        (dimplex-controller-py#141). Clearing (``enable=False``) is unaffected —
+        it sends ``Time=0`` by design.
+
         .. versionchanged:: 0.13.0
            Previously sent ``ApplianceModes=16``, which is **Advance** — the
            appliance advanced its schedule instead of boosting, and the
            requested duration was discarded.
         """
+        minutes = int(duration_minutes)
+        if enable and minutes <= 0:
+            raise ValueError(f"boost duration must be a positive number of minutes, got {duration_minutes!r}")
         await self.set_mode_flag(
             hub_id,
             appliance_ids,
             ApplianceModeFlag.BOOST,
             enable=enable,
             temperature=temperature,
-            minutes=int(duration_minutes) if enable else 0,
+            minutes=minutes if enable else 0,
         )
 
     async def clear_boost(
@@ -752,6 +810,26 @@ class DimplexControl:
             temperature=temperature,
         )
 
+    async def set_schedule_profile(
+        self,
+        hub_id: str,
+        appliance_ids: list[str],
+        profile: int | ScheduleProfile,
+    ) -> None:
+        """Apply a schedule profile (User timer / Home all day / Out all day).
+
+        Sends ``ApplianceModes=1`` (:attr:`TIMER_MODE`) with ``Status=1`` and
+        the profile in ``StatusTwo`` — the exact payload the official app's
+        schedule picker sends (dimplex-controller-py#147). Accepts a
+        :class:`ScheduleProfile` or its int value.
+        """
+        await self.set_mode_flag(
+            hub_id,
+            appliance_ids,
+            ApplianceModeFlag.TIMER_MODE,
+            status_two=int(profile),
+        )
+
     async def set_appliance_setpoint_temperature(
         self, hub_id: str, appliance_ids: list[str], temperature: float
     ) -> None:
@@ -763,12 +841,16 @@ class DimplexControl:
         the schedule and is rejected with HTTP 403 on Quantum.
 
         ``Temperature`` is a wire ``byte``, so the value is rounded to whole
-        degrees.
+        degrees, and it is clamped into the 7–30 °C range the app offers
+        (:data:`~dimplex_controller.MODE_TEMP_MIN` /
+        :data:`~dimplex_controller.MODE_TEMP_MAX`) with a warning when it is
+        outside — the cloud silently reduces such a value
+        (dimplex-controller-py#141).
         """
         payload = {
             "HubId": hub_id,
             "ApplianceIds": appliance_ids,
-            "Temperature": int(round(temperature)),
+            "Temperature": int(round(_clamp_mode_temperature(temperature))),
         }
         await self._request("POST", "/RemoteControl/SetApplianceSetpointTemperature", json=payload)
 
@@ -785,7 +867,8 @@ class DimplexControl:
         ``status`` is an :class:`~dimplex_controller.SetbackStatus` byte —
         ``ACTIVE``/``INACTIVE`` for a plain setback, with ``DSM_MODE`` and
         ``LOCAL_FREQUENCY_CONTROL_ACTIVE`` reserved for demand-side-management
-        use.
+        use. ``temperature`` is rounded and clamped into 7–30 °C, as
+        :meth:`set_appliance_setpoint_temperature` does.
 
         Confirmed present in APK 2.26.0 but **not yet validated on live
         hardware**.
@@ -794,7 +877,7 @@ class DimplexControl:
             "HubId": hub_id,
             "ApplianceIds": appliance_ids,
             "Status": int(status),
-            "Temperature": int(round(temperature)),
+            "Temperature": int(round(_clamp_mode_temperature(temperature))),
         }
         await self._request("POST", "/RemoteControl/SetSetbackTemperature", json=payload)
 

{dimplex_controller-0.15.0 → dimplex_controller-0.16.0}/dimplex_controller/models.py

@@ -15,6 +15,13 @@ class TimerMode(IntEnum):
 
     Exact product names vary by appliance firmware; these are the values used
     by the Dimplex Control mobile client and reverse-engineered traffic.
+
+    .. caution::
+       App 2.29.1 uses 0/1/2 here as the *profile* domain (user timer, home all
+       day, out all day) and has no manual/frost/off timer modes — those go
+       through ``SetApplianceMode`` mode bits instead. ``MANUAL``,
+       ``FROST_PROTECTION`` and ``OFF`` are therefore unverified in that client
+       and kept only because consumers map them (dimplex-controller-py#149).
     """
 
     USER_TIMER = 0
@@ -144,6 +151,35 @@ class ProductModel(BaseModel):
             return None
 
 
+_DEFAULT_DATETIME = datetime(1, 1, 1)
+
+
+def _is_null_datetime(value: str) -> bool:
+    """True when ``value`` is the cloud's ``default(DateTime)`` sentinel."""
+    text = value.strip()
+    if not text.startswith(NULL_DATETIME):
+        return False
+    # Tolerate .NET's optional fractional seconds, ``Z`` suffix or offset, e.g.
+    # ``0001-01-01T00:00:00Z`` or ``0001-01-01T00:00:00.0000000+00:00``.
+    return not text[len(NULL_DATETIME) :].strip(".0Z+:")
+
+
+def _map_null_datetime(value: Any) -> Any:
+    """Return ``None`` for the .NET null datetime, leaving real values alone.
+
+    The cloud sends ``0001-01-01T00:00:00`` for an unset date, which Pydantic
+    parsed into ``datetime(1, 1, 1)`` — so an unknown installation date or last
+    telemetry time rendered as year 1 instead of "unknown"
+    (dimplex-controller-py#140). Real timestamps are returned untouched, so
+    Pydantic still parses them (including fractional seconds).
+    """
+    if isinstance(value, datetime):
+        return None if value.replace(tzinfo=None) == _DEFAULT_DATETIME else value
+    if isinstance(value, str) and _is_null_datetime(value):
+        return None
+    return value
+
+
 class Appliance(BaseModel):
     ApplianceId: str
     ApplianceType: str
@@ -161,6 +197,12 @@ class Appliance(BaseModel):
     FirmwareVersion: str | None = None
     ProductModelExtensions: dict[str, str] | None = None
 
+    @field_validator("InstallationDate", "LastTelemDate", mode="before")
+    @classmethod
+    def _map_null_dates(cls, value: Any) -> Any:
+        """Map the cloud's unset-date sentinel to ``None`` rather than year 1."""
+        return _map_null_datetime(value)
+
     @field_validator("ProductModelExtensions", mode="before")
     @classmethod
     def _coerce_provisioning_extensions(cls, value: Any) -> dict[str, str] | None:
@@ -224,6 +266,12 @@ class Hub(BaseModel):
     IsDefault: bool | None = None
     RoleName: str | None = None
 
+    @field_validator("HubRegistrationDate", "InstallationDate", "LastTelemDate", mode="before")
+    @classmethod
+    def _map_null_dates(cls, value: Any) -> Any:
+        """Map the cloud's unset-date sentinel to ``None`` rather than year 1."""
+        return _map_null_datetime(value)
+
 
 class TimerPeriod(BaseModel):
     DayOfWeek: int

{dimplex_controller-0.15.0 → dimplex_controller-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dimplex-controller"
-version = "0.15.0"
+version = "0.16.0"
 description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
 license = "MIT"
 license-files = ["LICENSE"]

{dimplex_controller-0.15.0 → dimplex_controller-0.16.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dimplex-controller"
-version = "0.15.0"
+version = "0.16.0"
 description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
 authors = [{ name = "Kieran Roper" }]
 license = "MIT"