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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.14.0
+Version: 0.15.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
@@ -17,8 +17,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
-Requires-Dist: aiohttp>=3.14.3,<4
-Requires-Dist: pydantic>=2.13.5,<3
+Requires-Dist: aiohttp>=3.9.0,<4
+Requires-Dist: pydantic>=2.0.0,<3
 Requires-Python: >=3.10, <4.0
 Project-URL: Homepage, https://github.com/KRoperUK/dimplex-controller-py
 Project-URL: Repository, https://github.com/KRoperUK/dimplex-controller-py
@@ -285,7 +285,9 @@ Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_toke
 | `set_setback_temperature(...)` | Write the setback temperature (untested). |
 | `set_eco_start(hub_id, appliance_ids, enable)` | Toggle EcoStart. |
 | `set_open_window_detection(hub_id, appliance_ids, enable)` | Toggle Open Window Detection. |
-| `set_hot_water_*(...)` / `*_heat_pump_hot_water_schedule(...)` | Hot-water cylinder surface (untested — no hardware). |
+| `set_hot_water_holiday(hub_id, appliance_ids, until, *, enable, heat_pump)` | Cylinder Holiday on/off (validated on an ASHW cylinder). |
+| `get_heat_pump_hot_water_schedule(...)` | ASHW cylinder schedule as `HeatPumpHwcSchedule` (validated). Writing it answers 403. |
+| `set_hot_water_*(...)` | Remaining cylinder controls (untested — no hardware). |
 | `get_tsi_energy_report(hub_id, ...)` | Returns `TsiEnergyReport`. |
 | `capabilities_for(appliance, *, status, product)` | Derive an `ApplianceCapabilities` matrix. |
 | `export_tokens()` / `apply_tokens(bundle)` | Token persistence helpers. |

{dimplex_controller-0.14.0 → dimplex_controller-0.15.0}/README.md

@@ -259,7 +259,9 @@ Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_toke
 | `set_setback_temperature(...)` | Write the setback temperature (untested). |
 | `set_eco_start(hub_id, appliance_ids, enable)` | Toggle EcoStart. |
 | `set_open_window_detection(hub_id, appliance_ids, enable)` | Toggle Open Window Detection. |
-| `set_hot_water_*(...)` / `*_heat_pump_hot_water_schedule(...)` | Hot-water cylinder surface (untested — no hardware). |
+| `set_hot_water_holiday(hub_id, appliance_ids, until, *, enable, heat_pump)` | Cylinder Holiday on/off (validated on an ASHW cylinder). |
+| `get_heat_pump_hot_water_schedule(...)` | ASHW cylinder schedule as `HeatPumpHwcSchedule` (validated). Writing it answers 403. |
+| `set_hot_water_*(...)` | Remaining cylinder controls (untested — no hardware). |
 | `get_tsi_energy_report(hub_id, ...)` | Returns `TsiEnergyReport`. |
 | `capabilities_for(appliance, *, status, product)` | Derive an `ApplianceCapabilities` matrix. |
 | `export_tokens()` / `apply_tokens(bundle)` | Token persistence helpers. |

{dimplex_controller-0.14.0 → dimplex_controller-0.15.0}/dimplex_controller/__init__.py

@@ -45,6 +45,8 @@ from .models import (
     ApplianceModeStatus,
     ApplianceStatus,
     AutomaticProvisioning,
+    HeatPumpHwcPeriod,
+    HeatPumpHwcSchedule,
     Hub,
     HygieneFrequency,
     ProductModel,
@@ -62,6 +64,7 @@ from .telemetry import (
     EnergySummary,
     filter_telemetry_points,
     parse_telemetry_points,
+    reported_energy,
     summarise_energy,
 )
 
@@ -83,6 +86,8 @@ __all__ = [
     "SetbackStatus",
     "TimerMode",
     "TimerModeSettings",
+    "HeatPumpHwcPeriod",
+    "HeatPumpHwcSchedule",
     "TimerPeriod",
     "AutomaticProvisioning",
     "ProductModel",
@@ -98,6 +103,7 @@ __all__ = [
     "NULL_DATETIME",
     "parse_telemetry_points",
     "filter_telemetry_points",
+    "reported_energy",
     "summarise_energy",
     "EnergySummary",
     "VALUE_KEY_T1",

{dimplex_controller-0.14.0 → dimplex_controller-0.15.0}/dimplex_controller/capabilities.py

@@ -24,6 +24,14 @@ class ApplianceCapabilities:
     Flags are best-effort: when status/product metadata is incomplete the
     library prefers enabling known cloud control paths (boost/away/OWD) so
     users are not locked out of working RPCs.
+
+    One flag is weaker than the rest and must not be used as a gate:
+    :attr:`energy_meter` is a *family hint* derived from the nameplate, so it is
+    true for essentially every appliance with a rated power. When the question is
+    "has this appliance ever reported energy?", ask the telemetry —
+    :func:`dimplex_controller.reported_energy`, or
+    :func:`dimplex_controller.summarise_energy` when the totals are wanted too
+    (dimplex-controller-py#113).
     """
 
     boost: bool = True
@@ -39,6 +47,7 @@ class ApplianceCapabilities:
     # setpoint path. Preferred over rewriting the schedule via SetTimerMode,
     # which Quantum rejects with HTTP 403.
     setpoint_write: bool = True
+    # Family hint, not proof of metering — see the class docstring before gating on it.
     energy_meter: bool = False
     storage: bool = False
     hot_water: bool = False
@@ -162,15 +171,23 @@ def capabilities_for(
         heat_pump = True
         hot_water = True
 
-    boost = True
-    away = True
+    if status is not None and status.AvailableHotWater is not None:
+        hot_water = True
+
+    # A cylinder reports its *water* target in ActiveSetPointTemperature (45 °C
+    # on a live ASHW cylinder), so only a room temperature makes it room climate.
+    # Without one, the room-heater features default to off — a live cylinder
+    # sends null for every one of them — unless its status reports them.
+    climate = not hot_water or (status is not None and status.RoomTemperature is not None)
+
+    boost = climate
+    away = climate
     advance = True
-    open_window = True
-    eco_start = True
-    setback_read = True
-    frost = True
+    open_window = climate
+    eco_start = climate
+    setback_read = climate
+    frost = climate
     timer = True
-    climate = not hot_water  # cylinder-only appliances are not room climate
 
     if status is not None:
         if status.BoostDuration is not None or status.BoostTemperature is not None:
@@ -183,10 +200,6 @@ def capabilities_for(
             eco_start = True
         if status.SetbackEnabled is not None or status.SetbackTemperature is not None:
             setback_read = True
-        if status.AvailableHotWater is not None:
-            hot_water = True
-        if status.RoomTemperature is not None or status.ActiveSetPointTemperature is not None:
-            climate = True
 
     # Advance only means something for a scheduled room heater; a cylinder has
     # no "next comfort period" to jump to.
@@ -200,10 +213,11 @@ def capabilities_for(
         open_window=open_window,
         eco_start=eco_start,
         setback_read=setback_read,
-        setback_write=True,
+        setback_write=climate,
         frost=frost,
         timer=timer,
-        setpoint_write=True,
+        # The room setpoint endpoint; cylinders have their own (Set*TemperatureHwc).
+        setpoint_write=climate,
         energy_meter=energy_meter,
         storage=storage,
         hot_water=hot_water,

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

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import math
 import random
 from datetime import datetime, timedelta, timezone
 from typing import Any
@@ -36,6 +37,7 @@ from .models import (
     ApplianceModeSettings,
     ApplianceModeStatus,
     ApplianceStatus,
+    HeatPumpHwcSchedule,
     Hub,
     HygieneFrequency,
     ProductModel,
@@ -840,6 +842,42 @@ class DimplexControl:
             endpoint=endpoint,
         )
 
+    async def set_hot_water_holiday(
+        self,
+        hub_id: str,
+        appliance_ids: list[str],
+        until: datetime | None = None,
+        *,
+        enable: bool = True,
+        heat_pump: bool = False,
+    ) -> None:
+        """Put a cylinder on Holiday (standby) until ``until``, or clear it.
+
+        Verified on a live ASHW cylinder (EDL200UK-630RF) with ``heat_pump=True``:
+        engaging moved ``ApplianceModes`` 8192 → 8200 and set
+        ``HolidayNumOfDays``, heating stopped, and clearing restored 8192. The
+        cylinder counts holidays in whole days, so ``until`` is also sent as a
+        rounded-up day count; a caller that wants a time of day has to clear
+        Holiday itself at that time.
+        """
+        days = 0
+        if enable:
+            if until is None:
+                raise ValueError("a holiday needs an end time")
+            end = until if until.tzinfo is not None else until.replace(tzinfo=timezone.utc)
+            seconds = (end - datetime.now(timezone.utc)).total_seconds()
+            days = max(1, math.ceil(seconds / 86400))
+        endpoint = "/RemoteControl/SetApplianceModeHeatPumpHwc" if heat_pump else "/RemoteControl/SetApplianceModeHwc"
+        await self.set_mode_flag(
+            hub_id,
+            appliance_ids,
+            ApplianceModeFlag.HOLIDAY,
+            enable=enable,
+            until=until,
+            number_of_days=days,
+            endpoint=endpoint,
+        )
+
     async def set_hot_water_boost_temperature(
         self, hub_id: str, appliance_ids: list[str], temperature: float, *, enable: bool = True
     ) -> None:
@@ -902,10 +940,12 @@ class DimplexControl:
             endpoint=endpoint,
         )
 
-    async def get_heat_pump_hot_water_schedule(self, hub_id: str, appliance_id: str) -> TimerModeSettings:
-        """Read an ASHW cylinder's schedule.
+    async def get_heat_pump_hot_water_schedule(self, hub_id: str, appliance_id: str) -> HeatPumpHwcSchedule:
+        """Read an ASHW cylinder's weekly schedule.
 
-        .. warning:: Untested — APK-confirmed only.
+        Verified on a live ASHW cylinder (EDL200UK-630RF). The reply does not fit
+        :class:`TimerModeSettings` — there is no ``TimerMode`` and each period is
+        ``{DayOfWeek, StartTime, Mode}`` — hence :class:`HeatPumpHwcSchedule`.
         """
         payload = {"HubId": hub_id, "ApplianceId": appliance_id}
         data = await self._request(
@@ -913,12 +953,16 @@ class DimplexControl:
             "/RemoteControl/ApiGetTimerModeDetailsForHeatPumpHwcAppliance",
             json=payload,
         )
-        return TimerModeSettings.model_validate(data)
+        return HeatPumpHwcSchedule.model_validate(data)
 
     async def set_heat_pump_hot_water_schedule(self, settings: TimerModeSettings) -> TimerModeSettings:
         """Write an ASHW cylinder's schedule periods.
 
-        .. warning:: Untested — APK-confirmed only.
+        .. warning:: Does not work yet. On a live ASHW cylinder this endpoint
+           answered HTTP 403 to every body tried — wrapped in ``TimerModeSettings``
+           or ``Settings``, with or without ``TimerMode``, integer or ``HH:MM:SS``
+           times, and app versions up to 3.0.0 — while unwrapped bodies got 400.
+           The request the official app sends has not been captured.
         """
         payload = {"TimerModeSettings": settings.model_dump(mode="json")}
         await self._request("POST", "/RemoteControl/UpdateHeatPumpHwcSchedulePeriods", json=payload)

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

@@ -255,6 +255,31 @@ class TimerModeSettings(BaseModel):
     TimerPeriods: list[TimerPeriod] = Field(default_factory=list)
 
 
+class HeatPumpHwcPeriod(BaseModel):
+    """One period of an ASHW cylinder's weekly schedule.
+
+    A live cylinder returns one ``{DayOfWeek, StartTime: 0, Mode: 2}`` per day.
+    ``DayOfWeek`` is .NET's (0 = Sunday). ``StartTime`` is an integer, presumed
+    minutes after midnight, and what each ``Mode`` value means is not yet known.
+    """
+
+    DayOfWeek: int
+    StartTime: int
+    Mode: int
+
+
+class HeatPumpHwcSchedule(BaseModel):
+    """``ApiGetTimerModeDetailsForHeatPumpHwcAppliance`` reply.
+
+    Unlike the room-heater :class:`TimerModeSettings` it has no ``TimerMode``
+    and its periods carry a mode instead of an end time and temperature.
+    """
+
+    HubId: str
+    ApplianceId: str
+    TimerPeriods: list[HeatPumpHwcPeriod] = Field(default_factory=list)
+
+
 class UserContext(BaseModel):
     Id: str
     EmailAddress: str | None = None
@@ -286,6 +311,21 @@ class ApplianceStatus(BaseModel):
     LockStatus: int | None = None
     ErrorCode: str | None = None
     WarningCode: str | None = None
+    # Hot-water cylinder fields, as a live ASHW cylinder (EDL200UK-630RF) sends
+    # them. AvailableHotWater above is litres of usable hot water (the app shows
+    # it as "336 L Hot water").
+    Capacity: int | None = None  # tank size, litres
+    HeatingUp: bool | None = None
+    IsGreenEnergyActive: bool | None = None
+    HygieneFrequency: int | None = None  # EFrequency, see HygieneFrequency
+    HygieneTemperature: float | None = None
+    HolidayNumOfDays: int | None = None
+    # Present in the same reply, always null on the cylinder seen so far.
+    DelayedStartTime: str | None = None
+    DsmStatus: int | None = None
+    ModifiedPower: float | None = None
+    ConnectedChargeProfiles: Any = None
+    StandaloneChargeProfiles: Any = None
 
     @field_validator("ErrorCode", "WarningCode", mode="before")
     @classmethod

{dimplex_controller-0.14.0 → dimplex_controller-0.15.0}/dimplex_controller/telemetry.py

@@ -222,6 +222,34 @@ def parse_telemetry_points(
     return out
 
 
+def reported_energy(
+    points: Any,
+    *,
+    value_keys: tuple[str, ...] | None = None,
+) -> bool:
+    """Return True when telemetry carries usable points for an appliance.
+
+    The evidence-based counterpart to
+    :attr:`ApplianceCapabilities.energy_meter <.capabilities.ApplianceCapabilities>`,
+    which is a family hint derived from the nameplate and is therefore true for
+    essentially every appliance — it cannot separate a genuinely metered one from an
+    appliance the hub never reports energy for (dimplex-controller-py#113).
+
+    Pass the appliance's entry from
+    :attr:`TsiEnergyReport.ApplianceTelemetryData
+    <.models.TsiEnergyReport>` (raw entries are normalised by
+    :func:`parse_telemetry_points`, so both raw and already-parsed points are
+    accepted). Nothing recognised, an empty list, or a value the parser skips all
+    answer ``False`` — which is the question a consumer gating entity creation
+    actually has.
+
+    Only presence is decided here. A caller that also wants the figures should call
+    :func:`parse_telemetry_points` or :func:`summarise_energy` once and test the
+    result, rather than parse a series twice.
+    """
+    return bool(parse_telemetry_points(points, value_keys=value_keys))
+
+
 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:

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

@@ -1,6 +1,6 @@
 [project]
 name = "dimplex-controller"
-version = "0.14.0"
+version = "0.15.0"
 description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -27,8 +27,8 @@ classifiers = [
     "Topic :: Home Automation",
 ]
 dependencies = [
-    "aiohttp>=3.14.3,<4",
-    "pydantic>=2.13.5,<3",
+    "aiohttp>=3.9.0,<4",
+    "pydantic>=2.0.0,<3",
 ]
 
 [[project.authors]]

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

@@ -1,6 +1,6 @@
 [project]
 name = "dimplex-controller"
-version = "0.14.0"
+version = "0.15.0"
 description = "Unofficial async Python client for Dimplex (GDHV IoT) heating appliances — not affiliated with Glen Dimplex"
 authors = [{ name = "Kieran Roper" }]
 license = "MIT"
@@ -21,12 +21,21 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
     "Topic :: Home Automation",
 ]
-# Lower bounds are the versions this release was developed and tested against;
-# the upper bounds keep the previous caret semantics (a caret range is
-# `>=X,<next-major`), so consumers gain no surprise from the migration.
+# The upper bounds keep the previous caret semantics (a caret range is
+# `>=X,<next-major`), so consumers gain no surprise from the uv migration.
 dependencies = [
-    "aiohttp>=3.14.3,<4",
-    "pydantic>=2.13.5,<3",
+    # Lower bounds are what the code needs, not what uv.lock happens to resolve.
+    # They were raised to the locked versions when the project migrated to uv and
+    # bumped everything in one pass (#110), which made this library uninstallable
+    # alongside Home Assistant: the integration's test stack pins pydantic 2.13.4
+    # while this demanded >=2.13.5, so `dimplex-controller>=0.14.0` resolved to
+    # nothing and the HA integration could not adopt the 0.14.0 ErrorCode/WarningCode
+    # fix (dimplex-controller-hass#256).
+    #
+    # Nothing here needs either new API: plain ``BaseModel``, ``field_validator``,
+    # ``ConfigDict`` and an aiohttp ``ClientSession`` are all 2.0/3.9-era.
+    "aiohttp>=3.9.0,<4",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.urls]