dimplex-controller 0.13.0__tar.gz → 0.13.1__tar.gz

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.13.0
-Summary: Python client for Dimplex heating controllers (GDHV IoT)
+Version: 0.13.1
+Summary: Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex
 License: MIT
 License-File: LICENSE
 Keywords: dimplex,heating,control,iot,asyncio
@@ -40,14 +40,24 @@ Description-Content-Type: text/markdown
 
 ---
 
+> [!IMPORTANT]
+> **Unofficial library.** Not affiliated with, endorsed by, or supported by Dimplex, Glen
+> Dimplex Heating & Ventilation (GDHV), or the Glen Dimplex Group. This is an independent
+> project built by **reverse-engineering** the official Dimplex Control Android app and the
+> private cloud API it talks to.
+>
+> There is no public or documented API. Dimplex can change or withdraw that API at any time
+> and without notice, which may break this library. Use it at your own risk.
+>
+> No Dimplex code is included or redistributed. "Dimplex", "Quantum", "QRAD" and related
+> marks belong to their respective owners and are used here only to describe compatibility.
+
 ## What does this do?
 
 `dimplex-controller-py` is an asynchronous Python client that talks to the GDHV IoT cloud platform. It handles Azure B2C authentication (including automatic token refresh), discovers your Hubs, Zones and Appliances, and lets you read telemetry and send control commands — all from a script or a larger application.
 
 It is the engine behind the [Dimplex Hub Home Assistant integration](https://github.com/KRoperUK/dimplex-controller-hass) and is published to PyPI as [`dimplex-controller`](https://pypi.org/project/dimplex-controller/).
 
-> **Note:** This is an unofficial library and is not affiliated with or endorsed by Glen Dimplex Heating & Ventilation (GDHV). Use it at your own risk.
-
 ## Contents
 
 - [Features](#features)
@@ -186,8 +196,9 @@ await client.set_open_window_detection(hub_id, [appliance_id], True)
 # Timed Boost (ApplianceModes=2, Time = minutes)
 await client.set_boost(hub_id, [appliance_id], temperature=25.0, duration_minutes=60)
 
-# Away until a given moment (ApplianceModes=4). Away is a settable 7–30 °C
-# setback and defaults to the 7 °C anti-freeze floor.
+# Away until a given moment (ApplianceModes=4). Away is a settable 7–18 °C
+# setback and defaults to the 7 °C anti-freeze floor. A higher temperature is
+# clamped to 18 °C with a warning, matching what the cloud does to it anyway.
 from datetime import datetime, timedelta, timezone
 
 await client.set_away(

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/README.md

@@ -13,14 +13,24 @@
 
 ---
 
+> [!IMPORTANT]
+> **Unofficial library.** Not affiliated with, endorsed by, or supported by Dimplex, Glen
+> Dimplex Heating & Ventilation (GDHV), or the Glen Dimplex Group. This is an independent
+> project built by **reverse-engineering** the official Dimplex Control Android app and the
+> private cloud API it talks to.
+>
+> There is no public or documented API. Dimplex can change or withdraw that API at any time
+> and without notice, which may break this library. Use it at your own risk.
+>
+> No Dimplex code is included or redistributed. "Dimplex", "Quantum", "QRAD" and related
+> marks belong to their respective owners and are used here only to describe compatibility.
+
 ## What does this do?
 
 `dimplex-controller-py` is an asynchronous Python client that talks to the GDHV IoT cloud platform. It handles Azure B2C authentication (including automatic token refresh), discovers your Hubs, Zones and Appliances, and lets you read telemetry and send control commands — all from a script or a larger application.
 
 It is the engine behind the [Dimplex Hub Home Assistant integration](https://github.com/KRoperUK/dimplex-controller-hass) and is published to PyPI as [`dimplex-controller`](https://pypi.org/project/dimplex-controller/).
 
-> **Note:** This is an unofficial library and is not affiliated with or endorsed by Glen Dimplex Heating & Ventilation (GDHV). Use it at your own risk.
-
 ## Contents
 
 - [Features](#features)
@@ -159,8 +169,9 @@ await client.set_open_window_detection(hub_id, [appliance_id], True)
 # Timed Boost (ApplianceModes=2, Time = minutes)
 await client.set_boost(hub_id, [appliance_id], temperature=25.0, duration_minutes=60)
 
-# Away until a given moment (ApplianceModes=4). Away is a settable 7–30 °C
-# setback and defaults to the 7 °C anti-freeze floor.
+# Away until a given moment (ApplianceModes=4). Away is a settable 7–18 °C
+# setback and defaults to the 7 °C anti-freeze floor. A higher temperature is
+# clamped to 18 °C with a warning, matching what the cloud does to it anyway.
 from datetime import datetime, timedelta, timezone
 
 await client.set_away(

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/dimplex_controller/__init__.py

@@ -1,7 +1,10 @@
 """Dimplex Controller Client.
 
-Async Python client for the Glen Dimplex Heating & Ventilation (GDHV) cloud
-API. See :class:`~dimplex_controller.client.DimplexControl` for the entry
+Unofficial async Python client for the Glen Dimplex Heating & Ventilation
+(GDHV) cloud API. Not affiliated with, endorsed by, or supported by Dimplex
+or the Glen Dimplex Group: the protocol was recovered by reverse-engineering
+the official Dimplex Control Android app, so Dimplex may change or withdraw
+it without notice. See :class:`~dimplex_controller.client.DimplexControl` for the entry
 point and :meth:`DimplexControl.get_appliance_overview` for the read path
 used by the Home Assistant integration.
 
@@ -15,6 +18,8 @@ from .auth import TokenBundle, TokenListener
 from .capabilities import ApplianceCapabilities, capabilities_for
 from .client import DimplexControl
 from .const import (
+    AWAY_TEMP_MAX,
+    AWAY_TEMP_MIN,
     DEFAULT_AWAY_TEMPERATURE,
     DEFAULT_BOOST_TEMPERATURE,
     FROST_TEMPERATURE,
@@ -84,6 +89,8 @@ __all__ = [
     "TsiEnergyReport",
     "DEFAULT_AWAY_TEMPERATURE",
     "DEFAULT_BOOST_TEMPERATURE",
+    "AWAY_TEMP_MIN",
+    "AWAY_TEMP_MAX",
     "FROST_TEMPERATURE",
     "MODE_TEMP_MIN",
     "MODE_TEMP_MAX",

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/dimplex_controller/capabilities.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any
 
-from .const import FROST_TEMPERATURE, MODE_TEMP_MAX, MODE_TEMP_MIN
+from .const import AWAY_TEMP_MAX, AWAY_TEMP_MIN, FROST_TEMPERATURE, MODE_TEMP_MAX, MODE_TEMP_MIN
 from .models import Appliance, ApplianceStatus, AutomaticProvisioning, ProductModel
 
 # Default boost lengths (minutes) offered by the mobile app for most heaters.
@@ -47,6 +47,11 @@ class ApplianceCapabilities:
     climate: bool = True
     min_temp: float = MODE_TEMP_MIN
     max_temp: float = MODE_TEMP_MAX
+    # Away is the one carousel with its own bounds: it shares the 7 °C floor but
+    # stops at 18 °C rather than 30 °C (dimplex-controller-py#98). Consumers
+    # should gate the Away picker on these rather than on min_temp/max_temp.
+    away_min_temp: float = AWAY_TEMP_MIN
+    away_max_temp: float = AWAY_TEMP_MAX
     frost_temp: float = FROST_TEMPERATURE
     default_boost_minutes: int = DEFAULT_BOOST_MINUTES
     boost_durations: tuple[int, ...] = DEFAULT_BOOST_DURATIONS
@@ -83,6 +88,8 @@ class ApplianceCapabilities:
             "climate": self.climate,
             "min_temp": self.min_temp,
             "max_temp": self.max_temp,
+            "away_min_temp": self.away_min_temp,
+            "away_max_temp": self.away_max_temp,
             "frost_temp": self.frost_temp,
             "default_boost_minutes": self.default_boost_minutes,
             "boost_durations": list(self.boost_durations),

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/dimplex_controller/client.py

@@ -12,6 +12,8 @@ import aiohttp
 from .auth import AuthManager, TokenBundle, TokenListener
 from .capabilities import ApplianceCapabilities, capabilities_for
 from .const import (
+    AWAY_TEMP_MAX,
+    AWAY_TEMP_MIN,
     BASE_URL,
     DEFAULT_AWAY_TEMPERATURE,
     DEFAULT_BOOST_TEMPERATURE,
@@ -70,6 +72,26 @@ _RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
 DEFAULT_TIMEOUT = 30.0
 
 
+def _clamp_away_temperature(temperature: float) -> float:
+    """Clamp an Away target into the mode's own 7–18 °C range.
+
+    The cloud reduces a higher value silently, so clamping here keeps the value
+    the caller asked for and the value the appliance ends up at in agreement,
+    and the warning makes the adjustment visible.
+    """
+    value = float(temperature)
+    clamped = min(max(value, AWAY_TEMP_MIN), AWAY_TEMP_MAX)
+    if clamped != value:
+        _LOGGER.warning(
+            "Away temperature %.1f °C is outside the %s–%s °C the app offers for Away; using %.1f °C",
+            value,
+            AWAY_TEMP_MIN,
+            AWAY_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`.
 
@@ -325,7 +347,7 @@ class DimplexControl:
         """Get details for a specific zone."""
         payload = {"HubId": hub_id, "ZoneId": zone_id}
         data = await self._request("POST", "/Zones/GetZone", json=payload)
-        return Zone.model_validate(data)  # type: ignore[no-any-return]
+        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.
@@ -351,7 +373,7 @@ class DimplexControl:
     async def get_user_context(self) -> UserContext:
         """Get user profile/context."""
         data = await self._request("GET", "/Identity/GetUserContext")
-        return UserContext.model_validate(data)  # type: ignore[no-any-return]
+        return UserContext.model_validate(data)
 
     async def get_product_models(self) -> list[ProductModel]:
         """Return the cloud product catalogue (models + provisioning metadata).
@@ -371,7 +393,7 @@ class DimplexControl:
             "TimerMode": 0,  # Required field in request; value ignored on read
         }
         data = await self._request("POST", "/RemoteControl/GetTimerModeDetailsForAppliance", json=payload)
-        return TimerModeSettings.model_validate(data)  # type: ignore[no-any-return]
+        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`)."""
@@ -591,15 +613,26 @@ class DimplexControl:
         """Enable or disable Away mode.
 
         Sends ``ApplianceModes=4`` (:attr:`~dimplex_controller.ApplianceModeFlag.AWAY`).
-        Away is a *settable* setback: the app offers 7–30 °C and defaults to the
-        7 °C anti-freeze floor, so a low ``temperature`` is the normal case
-        rather than a bug.
+        Away is a *settable* setback: the app offers 7–18 °C
+        (:data:`~dimplex_controller.AWAY_TEMP_MIN` / :data:`~dimplex_controller.AWAY_TEMP_MAX`)
+        and defaults to the 7 °C anti-freeze floor, so a low ``temperature`` is
+        the normal case rather than a bug.
 
         ``until`` is the "away until" datetime the app sends in ``Date``. Pass a
         :class:`~datetime.datetime` or an ISO-8601 string. ``number_of_days`` is
         retained for backwards compatibility and, when ``until`` is omitted, is
         converted into an equivalent ``Date``.
 
+        When engaging Away, ``temperature`` is clamped into the Away range and a
+        warning logged if it had to be: the cloud silently reduces a higher
+        value, so clamping locally makes the outcome the caller actually gets
+        visible rather than surprising (dimplex-controller-py#98). The clamp is
+        skipped when clearing, where the temperature is inert.
+
+        .. versionchanged:: 0.13.1
+           ``temperature`` is clamped to ``AWAY_TEMP_MIN``..``AWAY_TEMP_MAX``
+           when ``enable`` is true.
+
         .. versionchanged:: 0.13.0
            Previously sent ``ApplianceModes=32``, which is **FrostProtect** —
            the appliance was pinned to the fixed 7 °C frost setpoint and the
@@ -607,6 +640,8 @@ class DimplexControl:
            Away duration now travels in ``Date`` as the app does, not only in
            ``NumberOfDays``.
         """
+        if enable:
+            temperature = _clamp_away_temperature(temperature)
         days = int(number_of_days)
         if until is None and days > 0:
             until = datetime.now(timezone.utc) + timedelta(days=days)
@@ -876,7 +911,7 @@ class DimplexControl:
             "/RemoteControl/ApiGetTimerModeDetailsForHeatPumpHwcAppliance",
             json=payload,
         )
-        return TimerModeSettings.model_validate(data)  # type: ignore[no-any-return]
+        return TimerModeSettings.model_validate(data)
 
     async def set_heat_pump_hot_water_schedule(self, settings: TimerModeSettings) -> TimerModeSettings:
         """Write an ASHW cylinder's schedule periods.

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/dimplex_controller/const.py

@@ -26,15 +26,24 @@ B2C_POLICY = "B2C_1A_DimplexControlSignupSignin"
 # recovered from Dimplex Control APK 2.26.0.
 # See ``docs/decompiled-api-reference.md``.
 
-# The mode carousels (Away / Boost / Frost / Manual / Eco) all offer 7–30 °C.
+# The mode carousels (Boost / Frost / Manual / Eco) offer 7–30 °C. Away shares
+# the floor but *not* the ceiling — see AWAY_TEMP_MAX below.
 MODE_TEMP_MIN = 7.0
 MODE_TEMP_MAX = 30.0
 
+# Away has its own, narrower ceiling. The app's Away picker will not offer above
+# 18 °C, and a live test against a Quantum requesting 25 °C produced 18 °C in the
+# cloud overview, the app and the appliance's own panel — so the earlier reading
+# of ``UpdateTempRange`` that folded Away into the shared 7–30 carousel was
+# over-generalised (dimplex-controller-py#98).
+AWAY_TEMP_MIN = 7.0
+AWAY_TEMP_MAX = 18.0
+
 # Frost protection is always driven at the anti-freeze floor.
 FROST_TEMPERATURE = 7.0
 
 # Away defaults to the frost floor (it is an anti-freeze setback by default)
-# but is user-settable across MODE_TEMP_MIN..MODE_TEMP_MAX.
+# but is user-settable across AWAY_TEMP_MIN..AWAY_TEMP_MAX.
 DEFAULT_AWAY_TEMPERATURE = FROST_TEMPERATURE
 
 # Boost's default in the app's picker.

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/dimplex_controller/models.py

@@ -139,7 +139,7 @@ class ProductModel(BaseModel):
         if not raw:
             return None
         try:
-            return AutomaticProvisioning.model_validate_json(raw)  # type: ignore[no-any-return]
+            return AutomaticProvisioning.model_validate_json(raw)
         except (json.JSONDecodeError, ValueError):
             return None
 
@@ -178,7 +178,7 @@ class Appliance(BaseModel):
         if not raw:
             return None
         try:
-            return AutomaticProvisioning.model_validate_json(raw)  # type: ignore[no-any-return]
+            return AutomaticProvisioning.model_validate_json(raw)
         except (json.JSONDecodeError, ValueError):
             return None
 
@@ -425,7 +425,7 @@ class TsiEnergyReport(BaseModel):
     """
 
     HubId: str
-    ApplianceTelemetryData: dict[str, list] = Field(default_factory=dict)
+    ApplianceTelemetryData: dict[str, list[Any]] = Field(default_factory=dict)
 
 
 # `TsiReportType` integer values understood by the API. We do not know the

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/dimplex_controller/telemetry.py

@@ -285,7 +285,7 @@ def summarise_energy(
         and isinstance(points[0], tuple)
         and len(points[0]) == 2
     ):
-        parsed = list(points)  # type: ignore[arg-type]
+        parsed = list(points)
     else:
         parsed = parse_telemetry_points(points, value_keys=value_keys)
 

{dimplex_controller-0.13.0 → dimplex_controller-0.13.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "dimplex-controller"
-version = "0.13.0"
-description = "Python client for Dimplex heating controllers (GDHV IoT)"
+version = "0.13.1"
+description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
 authors = ["Kieran Roper"]
 license = "MIT"
 readme = "README.md"
@@ -55,11 +55,16 @@ ignore = ["E501"]
 python_version = "3.10"
 files = ["dimplex_controller"]
 ignore_missing_imports = true
-# Incrementally strict — these catch real bugs without requiring a full rewrite.
-disallow_untyped_defs = true
-warn_return_any = true
-warn_unused_configs = true
-warn_redundant_casts = true
+# `strict` rather than the four flags this used to carry (disallow_untyped_defs,
+# warn_return_any, warn_unused_configs, warn_redundant_casts). The library is the
+# layer the Home Assistant integration trusts for models, capabilities and error
+# types, and that consumer runs strict mypy over its own code — so a library
+# checked more loosely could hand it types that do not hold
+# (dimplex-controller-hass#202).
+#
+# Raising it surfaced seven stale `# type: ignore` comments, all of which mypy
+# reported as unused, plus one missing generic argument. No real type errors.
+strict = true
 
 [tool.pytest.ini_options]
 # All async tests use asyncio; "auto" means new tests don't each need the