dimplex-controller 0.9.0__tar.gz → 0.10.1__tar.gz

{dimplex_controller-0.9.0 → dimplex_controller-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.9.0
+Version: 0.10.1
 Summary: Python client for Dimplex heating controllers (GDHV IoT)
 License: MIT
 License-File: LICENSE
@@ -167,6 +167,8 @@ for status in status_list:
     print(f"Comfort status: {status.ComfortStatus}")
 ```
 
+> **A note on empty responses:** when every requested appliance is offline (e.g. radiators switched off at the wall) the cloud returns HTTP 200 with an empty list. `get_appliance_overview` surfaces that as `[]` — it is **not** an error. If you need a stable id → status mapping, use `get_appliance_overview_map(...)`, which fills in `None` for missing ids.
+
 ### Sending control commands
 
 ```python
@@ -198,7 +200,11 @@ for appliance_id, telemetry in report.ApplianceTelemetryData.items():
     print(f"{appliance_id}: today={daily.total_kwh} kWh, lifetime={lifetime.total_kwh} kWh")
 ```
 
-`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.
+`parse_telemetry_points` normalises firmware-varying point shapes. `summarise_energy` builds **daily** (local midnight) and **lifetime** totals **per register**. `T1` (off-peak / cheaper) and `T2` (peak / more expensive) must not be summed; parse with `VALUE_KEY_T1` / `VALUE_KEY_T2`. With `include_previous_period=True` the cloud often returns full history — filter client-side rather than trusting `days_back` alone.
+
+## Compatibility
+
+See [docs/compatibility.md](docs/compatibility.md) for the library ↔ Home Assistant version matrix.
 
 ## Configuration
 
@@ -277,8 +283,41 @@ If `parse_telemetry_points` returns an empty list, the API likely returned an un
 
 The GDHV cloud API has rate limits. If you hit them, back off for a few minutes before retrying. The library does not currently implement automatic retries with back-off.
 
+### `get_appliance_overview` returns an empty list
+
+This is the cloud's normal response when every requested appliance is offline (e.g. radiators turned off at the wall, or a hub that has dropped off the network). It is **not** an error — `get_appliance_overview` returns `[]` and `get_appliance_overview_map` returns a dict of `None` values. Treat the call as a successful poll; the appliances will reappear in subsequent calls once they come back online. See the note in [Reading status](#reading-status) for details.
+
+
+## CLI
+
+Install the package (or an editable install) to get the `dimplex` console script:
+
+```bash
+pip install dimplex-controller
+export DIMPLEX_REFRESH_TOKEN=...   # never commit this
+dimplex login
+dimplex hubs
+dimplex zones --hub <hub-id> -v
+dimplex status <hub-id> <appliance-id>
+dimplex energy <hub-id> --days 30
+# control writes require --yes
+dimplex boost <hub-id> <appliance-id> --minutes 60 --yes
+```
+
+Tokens can also come from a JSON file (`--tokens-file` / `DIMPLEX_TOKENS_FILE`) with keys `refresh_token`, `access_token`, `expires_at`. Secrets are redacted in CLI output unless `--show-tokens` is passed.
+
 ## Contributing
 
+### Branch protection (`main`)
+
+Pull requests into `main` must keep the **`ci`** GitHub Actions check green.
+
+- Changes under `dimplex_controller/`, `tests/`, or CI config run **lint**, **pre-commit**, and the **pytest matrix** (Python 3.10–3.13). The `ci` job fails if any of those fail.
+- Docs-only PRs still report a green `ci` without running the full matrix.
+
+Direct pushes to `main` are blocked (PR + squash only; no force-push/delete). Commits must be signed (repo-wide rule).
+
+
 Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) before opening a pull request.
 
 Key points:

{dimplex_controller-0.9.0 → dimplex_controller-0.10.1}/README.md

@@ -139,6 +139,8 @@ for status in status_list:
     print(f"Comfort status: {status.ComfortStatus}")
 ```
 
+> **A note on empty responses:** when every requested appliance is offline (e.g. radiators switched off at the wall) the cloud returns HTTP 200 with an empty list. `get_appliance_overview` surfaces that as `[]` — it is **not** an error. If you need a stable id → status mapping, use `get_appliance_overview_map(...)`, which fills in `None` for missing ids.
+
 ### Sending control commands
 
 ```python
@@ -170,7 +172,11 @@ for appliance_id, telemetry in report.ApplianceTelemetryData.items():
     print(f"{appliance_id}: today={daily.total_kwh} kWh, lifetime={lifetime.total_kwh} kWh")
 ```
 
-`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.
+`parse_telemetry_points` normalises firmware-varying point shapes. `summarise_energy` builds **daily** (local midnight) and **lifetime** totals **per register**. `T1` (off-peak / cheaper) and `T2` (peak / more expensive) must not be summed; parse with `VALUE_KEY_T1` / `VALUE_KEY_T2`. With `include_previous_period=True` the cloud often returns full history — filter client-side rather than trusting `days_back` alone.
+
+## Compatibility
+
+See [docs/compatibility.md](docs/compatibility.md) for the library ↔ Home Assistant version matrix.
 
 ## Configuration
 
@@ -249,8 +255,41 @@ If `parse_telemetry_points` returns an empty list, the API likely returned an un
 
 The GDHV cloud API has rate limits. If you hit them, back off for a few minutes before retrying. The library does not currently implement automatic retries with back-off.
 
+### `get_appliance_overview` returns an empty list
+
+This is the cloud's normal response when every requested appliance is offline (e.g. radiators turned off at the wall, or a hub that has dropped off the network). It is **not** an error — `get_appliance_overview` returns `[]` and `get_appliance_overview_map` returns a dict of `None` values. Treat the call as a successful poll; the appliances will reappear in subsequent calls once they come back online. See the note in [Reading status](#reading-status) for details.
+
+
+## CLI
+
+Install the package (or an editable install) to get the `dimplex` console script:
+
+```bash
+pip install dimplex-controller
+export DIMPLEX_REFRESH_TOKEN=...   # never commit this
+dimplex login
+dimplex hubs
+dimplex zones --hub <hub-id> -v
+dimplex status <hub-id> <appliance-id>
+dimplex energy <hub-id> --days 30
+# control writes require --yes
+dimplex boost <hub-id> <appliance-id> --minutes 60 --yes
+```
+
+Tokens can also come from a JSON file (`--tokens-file` / `DIMPLEX_TOKENS_FILE`) with keys `refresh_token`, `access_token`, `expires_at`. Secrets are redacted in CLI output unless `--show-tokens` is passed.
+
 ## Contributing
 
+### Branch protection (`main`)
+
+Pull requests into `main` must keep the **`ci`** GitHub Actions check green.
+
+- Changes under `dimplex_controller/`, `tests/`, or CI config run **lint**, **pre-commit**, and the **pytest matrix** (Python 3.10–3.13). The `ci` job fails if any of those fail.
+- Docs-only PRs still report a green `ci` without running the full matrix.
+
+Direct pushes to `main` are blocked (PR + squash only; no force-push/delete). Commits must be signed (repo-wide rule).
+
+
 Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) before opening a pull request.
 
 Key points:

{dimplex_controller-0.9.0 → dimplex_controller-0.10.1}/dimplex_controller/__init__.py

@@ -1,6 +1,18 @@
-"""Dimplex Controller Client."""
+"""Dimplex Controller Client.
+
+Async Python client for the Glen Dimplex Heating & Ventilation (GDHV) cloud
+API. 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.
+
+A note on the API: ``get_appliance_overview`` may return an empty list
+with HTTP 200 when the requested appliances are offline. That is a
+successful poll, not an error — use ``get_appliance_overview_map`` if you
+need a stable id → status mapping.
+"""
 
 from .auth import TokenBundle
+from .capabilities import ApplianceCapabilities, capabilities_for
 from .client import DimplexControl
 from .exceptions import (
     DimplexApiError,
@@ -27,6 +39,7 @@ from .models import (
     Zone,
 )
 from .telemetry import (
+    VALUE_KEY_T1,
     VALUE_KEY_T2,
     EnergySummary,
     filter_telemetry_points,
@@ -37,6 +50,8 @@ from .telemetry import (
 __all__ = [
     "DimplexControl",
     "TokenBundle",
+    "ApplianceCapabilities",
+    "capabilities_for",
     "Hub",
     "Zone",
     "Appliance",
@@ -53,6 +68,7 @@ __all__ = [
     "filter_telemetry_points",
     "summarise_energy",
     "EnergySummary",
+    "VALUE_KEY_T1",
     "VALUE_KEY_T2",
     "DimplexError",
     "DimplexApiError",

dimplex_controller-0.10.1/dimplex_controller/capabilities.py

@@ -0,0 +1,178 @@
+"""Appliance capability matrix derived from model, provisioning, and status.
+
+Clients (Home Assistant climate, CLIs, etc.) should gate UI and control paths
+with these flags rather than hard-coding product assumptions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .models import Appliance, ApplianceStatus, AutomaticProvisioning, ProductModel
+
+# Default boost lengths (minutes) offered by the mobile app for most heaters.
+DEFAULT_BOOST_DURATIONS: tuple[int, ...] = (30, 60, 120, 180)
+DEFAULT_BOOST_MINUTES = 60
+
+
+@dataclass(frozen=True)
+class ApplianceCapabilities:
+    """Structured capability flags for one appliance.
+
+    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.
+    """
+
+    boost: bool = True
+    away: bool = True
+    open_window: bool = True
+    eco_start: bool = True
+    setback_read: bool = True
+    setback_write: bool = False  # no confirmed write API yet
+    frost: bool = True  # TimerMode.FROST_PROTECTION
+    timer: bool = True
+    energy_meter: bool = False
+    storage: bool = False
+    hot_water: bool = False
+    climate: bool = True
+    min_temp: float = 5.0
+    max_temp: float = 30.0
+    default_boost_minutes: int = DEFAULT_BOOST_MINUTES
+    boost_durations: tuple[int, ...] = DEFAULT_BOOST_DURATIONS
+
+    def climate_presets(self) -> list[str]:
+        """Return HA-style climate preset keys supported by this appliance."""
+        presets = ["comfort"]
+        if self.boost:
+            presets.append("boost")
+        if self.away:
+            presets.append("away")
+        if self.eco_start:
+            presets.append("eco")
+        return presets
+
+    def as_dict(self) -> dict[str, Any]:
+        """JSON-serialisable snapshot (for diagnostics / logging)."""
+        return {
+            "boost": self.boost,
+            "away": self.away,
+            "open_window": self.open_window,
+            "eco_start": self.eco_start,
+            "setback_read": self.setback_read,
+            "setback_write": self.setback_write,
+            "frost": self.frost,
+            "timer": self.timer,
+            "energy_meter": self.energy_meter,
+            "storage": self.storage,
+            "hot_water": self.hot_water,
+            "climate": self.climate,
+            "min_temp": self.min_temp,
+            "max_temp": self.max_temp,
+            "default_boost_minutes": self.default_boost_minutes,
+            "boost_durations": list(self.boost_durations),
+            "climate_presets": self.climate_presets(),
+        }
+
+
+def _type_tokens(appliance: Appliance | None, product: ProductModel | None) -> str:
+    parts: list[str] = []
+    if appliance is not None:
+        for attr in ("ApplianceType", "ApplianceModel", "FriendlyName"):
+            value = getattr(appliance, attr, None)
+            if value:
+                parts.append(str(value))
+    if product is not None:
+        for attr in ("ProductTypeName", "ProductModelName"):
+            value = getattr(product, attr, None)
+            if value:
+                parts.append(str(value))
+    return " ".join(parts).lower()
+
+
+def _provisioning(appliance: Appliance | None, product: ProductModel | None) -> AutomaticProvisioning | None:
+    if appliance is not None:
+        prov = appliance.automatic_provisioning
+        if prov is not None:
+            return prov
+    if product is not None:
+        return product.automatic_provisioning
+    return None
+
+
+def capabilities_for(
+    appliance: Appliance | None = None,
+    *,
+    status: ApplianceStatus | None = None,
+    product: ProductModel | None = None,
+) -> ApplianceCapabilities:
+    """Derive capability flags for an appliance.
+
+    Sources (in roughly increasing specificity):
+
+    * product catalogue / type name heuristics
+    * ``AUTOMATIC_PROVISIONING`` (rated power, storage)
+    * live overview fields (boost/away/OWD/setback/hot water)
+
+    When a status field is present (including ``False`` / ``0``) the related
+    feature is treated as supported. Missing fields leave defaults (generally
+    enabled for control paths the cloud exposes generically).
+    """
+    tokens = _type_tokens(appliance, product)
+    prov = _provisioning(appliance, product)
+
+    storage = False
+    energy_meter = False
+    hot_water = False
+    if prov is not None:
+        if prov.charge_capacity is not None and prov.charge_capacity > 0:
+            storage = True
+        if prov.rated_power is not None and prov.rated_power > 0:
+            energy_meter = True  # metered family often has TSI history too
+
+    if any(k in tokens for k in ("quantum", "storage", "qrad", "charge")):
+        storage = True
+        energy_meter = True
+    if any(k in tokens for k in ("hot water", "hotwater", "cylinder", "dhw")):
+        hot_water = True
+
+    boost = True
+    away = True
+    open_window = True
+    eco_start = True
+    setback_read = True
+    frost = True
+    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:
+            boost = True
+        if status.AwayDateTime is not None or status.AwayTemperature is not None:
+            away = True
+        if status.OpenWindowEnabled is not None:
+            open_window = True
+        if status.EcoStartEnabled is not None:
+            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
+
+    return ApplianceCapabilities(
+        boost=boost,
+        away=away,
+        open_window=open_window,
+        eco_start=eco_start,
+        setback_read=setback_read,
+        setback_write=False,
+        frost=frost,
+        timer=timer,
+        energy_meter=energy_meter,
+        storage=storage,
+        hot_water=hot_water,
+        climate=climate,
+    )

dimplex_controller-0.10.1/dimplex_controller/cli.py

@@ -0,0 +1,266 @@
+"""Command-line interface for smoke-testing Dimplex cloud access.
+
+Tokens are read from environment variables by default:
+
+* ``DIMPLEX_REFRESH_TOKEN``
+* ``DIMPLEX_ACCESS_TOKEN`` (optional)
+* ``DIMPLEX_EXPIRES_AT`` (optional unix timestamp)
+
+Or from a JSON file via ``--tokens-file`` (keys: refresh_token, access_token,
+expires_at). Secrets are never printed unless ``--show-tokens`` is passed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import aiohttp
+
+from .auth import TokenBundle
+from .client import DimplexControl
+from .exceptions import DimplexError
+
+
+def _load_tokens(path: Path | None) -> TokenBundle:
+    if path is not None:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return TokenBundle.from_mapping(data)
+    return TokenBundle(
+        refresh_token=os.environ.get("DIMPLEX_REFRESH_TOKEN"),
+        access_token=os.environ.get("DIMPLEX_ACCESS_TOKEN"),
+        expires_at=float(os.environ.get("DIMPLEX_EXPIRES_AT") or 0),
+    )
+
+
+def _save_tokens(path: Path, bundle: TokenBundle) -> None:
+    path.write_text(json.dumps(bundle.as_dict(), indent=2) + "\n", encoding="utf-8")
+    with contextlib.suppress(OSError):
+        path.chmod(0o600)
+
+
+def _redact(value: str | None, *, show: bool) -> str:
+    if not value:
+        return "(none)"
+    if show:
+        return value
+    if len(value) <= 8:
+        return "***"
+    return f"{value[:4]}…{value[-4:]} ({len(value)} chars)"
+
+
+async def _with_client(
+    args: argparse.Namespace,
+    coro_factory: Any,
+) -> int:
+    tokens = _load_tokens(Path(args.tokens_file) if args.tokens_file else None)
+    if not tokens.refresh_token and not tokens.access_token:
+        print(
+            "error: no tokens — set DIMPLEX_REFRESH_TOKEN or pass --tokens-file",
+            file=sys.stderr,
+        )
+        return 2
+
+    async with aiohttp.ClientSession() as session:
+        client = DimplexControl(session, token_bundle=tokens)
+        try:
+            await client.auth.get_access_token()
+            if args.tokens_file:
+                _save_tokens(Path(args.tokens_file), client.export_tokens())
+            return await coro_factory(client)
+        except DimplexError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+
+
+async def cmd_login(client: DimplexControl, args: argparse.Namespace) -> int:
+    """Validate tokens and optionally write them back."""
+    bundle = client.export_tokens()
+    print("authenticated")
+    print(f"  refresh_token: {_redact(bundle.refresh_token, show=args.show_tokens)}")
+    print(f"  access_token:  {_redact(bundle.access_token, show=args.show_tokens)}")
+    print(f"  expires_at:    {bundle.expires_at}")
+    if args.tokens_file:
+        _save_tokens(Path(args.tokens_file), bundle)
+        print(f"  wrote:         {args.tokens_file}")
+    return 0
+
+
+async def cmd_hubs(client: DimplexControl, args: argparse.Namespace) -> int:
+    hubs = await client.get_hubs()
+    for hub in hubs:
+        name = hub.FriendlyName or hub.Name or "(unnamed)"
+        print(f"{hub.HubId}\t{name}\tconnection={hub.ConnectionState}")
+    if not hubs:
+        print("(no hubs)")
+    return 0
+
+
+async def cmd_zones(client: DimplexControl, args: argparse.Namespace) -> int:
+    hubs = await client.get_hubs()
+    hub_id = args.hub or (hubs[0].HubId if hubs else None)
+    if not hub_id:
+        print("error: no hub id", file=sys.stderr)
+        return 2
+    zones = await client.get_hub_zones(hub_id)
+    for zone in zones:
+        print(f"{zone.ZoneId}\t{zone.ZoneName}\thub={zone.HubId}\tappliances={len(zone.Appliances)}")
+        if args.verbose:
+            for app in zone.Appliances:
+                print(f"  {app.ApplianceId}\t{app.FriendlyName}\t{app.ApplianceModel or app.ApplianceType}")
+    return 0
+
+
+async def cmd_appliances(client: DimplexControl, args: argparse.Namespace) -> int:
+    hubs = await client.get_hubs()
+    for hub in hubs:
+        if args.hub and hub.HubId != args.hub:
+            continue
+        zones = await client.get_hub_zones(hub.HubId)
+        for zone in zones:
+            for app in zone.Appliances:
+                print(
+                    f"{app.ApplianceId}\t{app.FriendlyName}\t"
+                    f"{app.ApplianceModel or app.ApplianceType}\t"
+                    f"zone={zone.ZoneName}\thub={hub.HubId}"
+                )
+    return 0
+
+
+async def cmd_status(client: DimplexControl, args: argparse.Namespace) -> int:
+    overview = await client.get_appliance_overview(args.hub, [args.appliance])
+    if not overview:
+        print("(no status — appliance offline or empty overview)")
+        return 0
+    status = overview[0]
+    print(json.dumps(status.model_dump(mode="json"), indent=2, default=str))
+    return 0
+
+
+async def cmd_energy(client: DimplexControl, args: argparse.Namespace) -> int:
+    report = await client.get_tsi_energy_report(hub_id=args.hub, days_back=args.days)
+    summary: dict[str, Any] = {
+        "hub_id": report.HubId,
+        "appliances": {app_id: len(points or []) for app_id, points in (report.ApplianceTelemetryData or {}).items()},
+    }
+    print(json.dumps(summary, indent=2))
+    return 0
+
+
+async def cmd_boost(client: DimplexControl, args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_boost(
+        args.hub,
+        [args.appliance],
+        temperature=args.temperature,
+        duration_minutes=args.minutes,
+        enable=not args.clear,
+    )
+    print("ok")
+    return 0
+
+
+async def cmd_away(client: DimplexControl, args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_away(
+        args.hub,
+        [args.appliance],
+        temperature=args.temperature,
+        enable=not args.clear,
+    )
+    print("ok")
+    return 0
+
+
+async def cmd_eco(client: DimplexControl, args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_eco_start(args.hub, [args.appliance], not args.clear)
+    print("ok")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dimplex",
+        description="Dimplex Control cloud CLI (debug / smoke tests)",
+    )
+    parser.add_argument(
+        "--tokens-file",
+        default=os.environ.get("DIMPLEX_TOKENS_FILE"),
+        help="JSON token file (default: env DIMPLEX_TOKENS_FILE or DIMPLEX_* vars)",
+    )
+    parser.add_argument(
+        "--show-tokens",
+        action="store_true",
+        help="Print full tokens (default: redacted)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_login = sub.add_parser("login", help="Validate tokens and print redacted status")
+    p_login.set_defaults(func=cmd_login)
+
+    p_hubs = sub.add_parser("hubs", help="List hubs")
+    p_hubs.set_defaults(func=cmd_hubs)
+
+    p_zones = sub.add_parser("zones", help="List zones for a hub")
+    p_zones.add_argument("--hub", help="Hub id (default: first hub)")
+    p_zones.add_argument("-v", "--verbose", action="store_true")
+    p_zones.set_defaults(func=cmd_zones)
+
+    p_apps = sub.add_parser("appliances", help="List appliances")
+    p_apps.add_argument("--hub", help="Filter by hub id")
+    p_apps.set_defaults(func=cmd_appliances)
+
+    p_status = sub.add_parser("status", help="Appliance overview status")
+    p_status.add_argument("hub")
+    p_status.add_argument("appliance")
+    p_status.set_defaults(func=cmd_status)
+
+    p_energy = sub.add_parser("energy", help="Energy report summary (point counts only)")
+    p_energy.add_argument("hub")
+    p_energy.add_argument("--days", type=int, default=30)
+    p_energy.set_defaults(func=cmd_energy)
+
+    for name, help_text, defaults in (
+        ("boost", "Enable or clear boost (--yes required)", {"minutes": 60, "temperature": 25.0}),
+        ("away", "Enable or clear away (--yes required)", {"temperature": 16.0}),
+        ("eco", "Enable or clear EcoStart (--yes required)", {}),
+    ):
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("hub")
+        p.add_argument("appliance")
+        p.add_argument("--yes", action="store_true", help="Confirm control write")
+        p.add_argument("--clear", action="store_true", help="Disable the mode")
+        if "temperature" in defaults:
+            p.add_argument("--temperature", type=float, default=defaults["temperature"])
+        if "minutes" in defaults:
+            p.add_argument("--minutes", type=int, default=defaults["minutes"])
+        p.set_defaults(func={"boost": cmd_boost, "away": cmd_away, "eco": cmd_eco}[name])
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    async def run(client: DimplexControl) -> int:
+        return await args.func(client, args)
+
+    return asyncio.run(_with_client(args, run))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{dimplex_controller-0.9.0 → dimplex_controller-0.10.1}/dimplex_controller/client.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import asyncio
 import logging
+import random
 from datetime import datetime, timedelta, timezone
 from typing import Any
 
 import aiohttp
 
 from .auth import AuthManager, TokenBundle
+from .capabilities import ApplianceCapabilities, capabilities_for
 from .const import (
     BASE_URL,
     HEADER_APP_NAME,
@@ -20,6 +23,7 @@ from .const import (
 )
 from .exceptions import DimplexApiError, DimplexConnectionError
 from .models import (
+    Appliance,
     ApplianceModeFlag,
     ApplianceModeSettings,
     ApplianceStatus,
@@ -45,6 +49,12 @@ DEFAULT_TSI_INTERVAL = "01:00:00"
 # Default boost length when the caller does not specify one (minutes).
 DEFAULT_BOOST_MINUTES = 60
 
+# HTTP retry policy (see ``DimplexControl`` constructor).
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_BASE_DELAY = 0.5
+DEFAULT_RETRY_MAX_DELAY = 8.0
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
 
 def _iso_utc_days_ago(days: int) -> str:
     """Return an ISO-8601 UTC timestamp ``days`` before now (no microseconds)."""
@@ -63,11 +73,26 @@ class DimplexControl:
         expires_at: float = 0,
         *,
         token_bundle: TokenBundle | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        retry_max_delay: float = DEFAULT_RETRY_MAX_DELAY,
+        retry_non_idempotent: bool = False,
     ):
         """Initialize the client.
 
         Prefer ``token_bundle`` for new code. The individual token kwargs remain
         supported for backwards compatibility.
+
+        Retry policy (centralised on ``_request``):
+
+        * **GET** (and other safe methods): retry on connection errors and
+          HTTP 429/5xx with exponential backoff + jitter; honour ``Retry-After``
+          when present.
+        * **POST/PUT/PATCH/DELETE**: no retries by default (non-idempotent
+          control calls). Set ``retry_non_idempotent=True`` to apply the same
+          policy (use with care).
+        * ``max_retries`` is the number of *retries* after the first attempt
+          (0 disables retries).
         """
         if token_bundle is not None:
             token_data: dict[str, Any] | TokenBundle = token_bundle
@@ -82,6 +107,10 @@ class DimplexControl:
 
         self._session = session
         self.auth = AuthManager(session, token_data)
+        self._max_retries = max(0, int(max_retries))
+        self._retry_base_delay = float(retry_base_delay)
+        self._retry_max_delay = float(retry_max_delay)
+        self._retry_non_idempotent = bool(retry_non_idempotent)
 
     @property
     def is_authenticated(self) -> bool:
@@ -96,8 +125,31 @@ class DimplexControl:
         """Replace in-memory auth tokens."""
         self.auth.apply_tokens(bundle)
 
+    def _should_retry(self, method: str) -> bool:
+        upper = method.upper()
+        if upper in {"GET", "HEAD", "OPTIONS"}:
+            return True
+        return self._retry_non_idempotent
+
+    def _backoff_seconds(self, attempt: int, retry_after: float | None = None) -> float:
+        """Compute delay before the next attempt (``attempt`` is 0-based)."""
+        if retry_after is not None and retry_after >= 0:
+            return min(retry_after, self._retry_max_delay)
+        # Exponential backoff with full jitter: U(0, min(max, base * 2^attempt))
+        ceiling = min(self._retry_max_delay, self._retry_base_delay * (2**attempt))
+        return random.uniform(0, ceiling)
+
+    @staticmethod
+    def _parse_retry_after(header_value: str | None) -> float | None:
+        if not header_value:
+            return None
+        try:
+            return max(0.0, float(header_value.strip()))
+        except ValueError:
+            return None
+
     async def _request(self, method: str, endpoint: str, **kwargs: Any) -> Any:
-        """Make an authenticated request."""
+        """Make an authenticated request with optional retry/backoff."""
         token = await self.auth.get_access_token()
         headers = kwargs.pop("headers", {})
         headers.update(
@@ -118,20 +170,70 @@ class DimplexControl:
         )
 
         url = f"{BASE_URL}{endpoint}"
-        try:
-            async with self._session.request(method, url, headers=headers, **kwargs) as resp:
-                if resp.status != HTTP_OK:
+        allow_retry = self._should_retry(method)
+        attempts = self._max_retries + 1 if allow_retry else 1
+        last_error: Exception | None = None
+
+        for attempt in range(attempts):
+            try:
+                async with self._session.request(method, url, headers=headers, **kwargs) as resp:
+                    if resp.status == HTTP_OK:
+                        if resp.content_length == 0:
+                            return {}
+                        return await resp.json()
+
                     text = await resp.text()
+                    retry_after = self._parse_retry_after(resp.headers.get("Retry-After"))
+                    if allow_retry and resp.status in _RETRYABLE_STATUS and attempt + 1 < attempts:
+                        delay = self._backoff_seconds(attempt, retry_after)
+                        _LOGGER.warning(
+                            "API %s %s failed with %s; retry %s/%s in %.2fs",
+                            method,
+                            endpoint,
+                            resp.status,
+                            attempt + 1,
+                            self._max_retries,
+                            delay,
+                        )
+                        last_error = DimplexApiError(resp.status, text)
+                        await asyncio.sleep(delay)
+                        continue
+
                     _LOGGER.error("API request failed: %s - %s", resp.status, text)
                     raise DimplexApiError(resp.status, text)
-
-                # API might return empty body for some calls
-                if resp.content_length == 0:
-                    return {}
-                return await resp.json()
-        except aiohttp.ClientError as e:
-            _LOGGER.error("Connection error during API request: %s", e)
-            raise DimplexConnectionError(f"Connection error: {e}") from e
+            except aiohttp.ClientError as e:
+                if allow_retry and attempt + 1 < attempts:
+                    delay = self._backoff_seconds(attempt)
+                    _LOGGER.warning(
+                        "Connection error on %s %s; retry %s/%s in %.2fs: %s",
+                        method,
+                        endpoint,
+                        attempt + 1,
+                        self._max_retries,
+                        delay,
+                        e,
+                    )
+                    last_error = DimplexConnectionError(f"Connection error: {e}")
+                    await asyncio.sleep(delay)
+                    continue
+                _LOGGER.error("Connection error during API request: %s", e)
+                raise DimplexConnectionError(f"Connection error: {e}") from e
+
+        if isinstance(last_error, DimplexApiError):
+            raise last_error
+        if isinstance(last_error, DimplexConnectionError):
+            raise last_error
+        raise DimplexConnectionError("Request failed after retries")
+
+    @staticmethod
+    def capabilities_for(
+        appliance: Appliance | None = None,
+        *,
+        status: ApplianceStatus | None = None,
+        product: ProductModel | None = None,
+    ) -> ApplianceCapabilities:
+        """Return a capability matrix for an appliance (see :mod:`.capabilities`)."""
+        return capabilities_for(appliance, status=status, product=product)
 
     async def get_hubs(self) -> list[Hub]:
         """Get all hubs for the user."""
@@ -195,6 +297,16 @@ class DimplexControl:
         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 _write_timer_settings(self, settings: TimerModeSettings) -> TimerModeSettings:
+        """POST a full :class:`TimerModeSettings` payload and return it."""
+        payload = {"TimerModeSettings": settings.model_dump(mode="json")}
+        await self._request("POST", "/RemoteControl/SetTimerMode", json=payload)
+        return settings
+
     async def set_mode(self, hub_id: str, appliance_id: str, mode: int | TimerMode) -> None:
         """Set the timer / operation mode.
 
@@ -202,9 +314,56 @@ class DimplexControl:
         """
         current = await self.get_appliance_features(hub_id, appliance_id)
         current.TimerMode = int(mode)
+        await self._write_timer_settings(current)
 
-        payload = {"TimerModeSettings": current.model_dump(mode="json")}
-        await self._request("POST", "/RemoteControl/SetTimerMode", json=payload)
+    async def set_period_setpoint(
+        self,
+        hub_id: str,
+        appliance_id: str,
+        *,
+        day_of_week: int,
+        start_time: str,
+        temperature: float,
+        end_time: str | None = None,
+    ) -> TimerModeSettings:
+        """Update one timer period's setpoint (and optional end) without clobbering others.
+
+        Matches periods by ``DayOfWeek`` + ``StartTime``. Raises ``ValueError`` if
+        no period matches. Prefer this over rewriting the whole schedule.
+        """
+        current = await self.get_appliance_features(hub_id, appliance_id)
+        matched = False
+        for period in current.TimerPeriods:
+            if period.DayOfWeek == day_of_week and period.StartTime == start_time:
+                period.Temperature = float(temperature)
+                if end_time is not None:
+                    period.EndTime = end_time
+                matched = True
+                break
+        if not matched:
+            raise ValueError(f"No timer period for day={day_of_week} start={start_time!r} on appliance {appliance_id}")
+        return await self._write_timer_settings(current)
+
+    async def update_period(
+        self,
+        hub_id: str,
+        appliance_id: str,
+        period: TimerPeriod,
+        *,
+        match_start_time: str | None = None,
+    ) -> TimerModeSettings:
+        """Replace a single period matched by day + start time (read-modify-write).
+
+        ``match_start_time`` defaults to ``period.StartTime`` so callers can also
+        change the period's start by passing the previous start string.
+        """
+        key_start = match_start_time if match_start_time is not None else period.StartTime
+        current = await self.get_appliance_features(hub_id, appliance_id)
+        for index, existing in enumerate(current.TimerPeriods):
+            if existing.DayOfWeek == period.DayOfWeek and existing.StartTime == key_start:
+                current.TimerPeriods[index] = period
+                return await self._write_timer_settings(current)
+        raise ValueError(f"No timer period for day={period.DayOfWeek} start={key_start!r} on appliance {appliance_id}")
 
     async def set_target_temperature(self, hub_id: str, appliance_id: str, temp: float) -> None:
         """Set the target / comfort temperature for an appliance.
@@ -219,6 +378,10 @@ class DimplexControl:
 
         This matches the reverse-engineered mobile-app approach of rewriting
         the active schedule rather than a dedicated "set temperature" RPC.
+
+        **Note:** unlike :meth:`set_period_setpoint`, this updates *all* period
+        temperatures (or installs a full-week schedule). Use the period helpers
+        when only one window should change.
         """
         current = await self.get_appliance_features(hub_id, appliance_id)
 
@@ -237,8 +400,7 @@ class DimplexControl:
                 for day in range(7)
             ]
 
-        payload = {"TimerModeSettings": current.model_dump(mode="json")}
-        await self._request("POST", "/RemoteControl/SetTimerMode", json=payload)
+        await self._write_timer_settings(current)
 
     async def set_appliance_mode(
         self, hub_id: str, appliance_ids: list[str], mode_settings: ApplianceModeSettings
@@ -339,6 +501,13 @@ class DimplexControl:
         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.
+
+        Points may include both ``T1`` (off-peak / cheaper) and ``T2``
+        (peak / more expensive). Parse them with
+        :data:`~dimplex_controller.telemetry.VALUE_KEY_T1` and
+        :data:`~dimplex_controller.telemetry.VALUE_KEY_T2` separately —
+        never sum T1+T2 into a single total.
+
         """
         if start_date is None:
             start_date = _iso_utc_days_ago(days_back)

{dimplex_controller-0.9.0 → dimplex_controller-0.10.1}/dimplex_controller/telemetry.py

@@ -7,7 +7,17 @@ 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.
+with either ``T1`` or ``ST`` as the energy value key. Some appliances also
+report a secondary register ``T2`` on the same point.
+
+**T1 and T2 must stay separate.** They are dual-rate tariff registers, not
+dual samples of the same meter:
+
+* **T1** — off-peak (cheaper rate)
+* **T2** — peak (more expensive rate)
+
+Never sum T1+T2 into a single "total energy" figure, and never fall back from
+T1 parsing to T2 values (or vice versa).
 
 Important cloud semantics (live-verified):
 
@@ -18,10 +28,10 @@ Important cloud semantics (live-verified):
 * Points are typically **one kWh sample per calendar day**, not a continuous
   cumulative counter.
 
-Use :func:`summarise_energy` for the two product totals:
+Use :func:`summarise_energy` for the two product totals **per register**:
 
 * ``daily`` — kWh for the local calendar day (from local midnight)
-* ``lifetime`` — sum of all parsed points (earliest → latest)
+* ``lifetime`` — sum of all parsed points for that register only
 """
 
 from __future__ import annotations
@@ -44,7 +54,10 @@ _DEFAULT_TIMESTAMP_KEYS = (
     "from",
     "start",
 )
-_DEFAULT_VALUE_KEYS = (
+
+# Primary / off-peak energy register (T1 / single-register appliances).
+# Intentionally excludes ``t2`` so off-peak and peak series are never mixed.
+VALUE_KEY_T1 = (
     "t1",
     "st",  # Observed on QRAD050F / QRAD075F energy reports (see dimplex-controller-hass #27).
     "value",
@@ -54,12 +67,11 @@ _DEFAULT_VALUE_KEYS = (
     "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.
+# Secondary / peak energy register (T2) observed for some Quantum appliances.
+# Points may contain both ``T1`` and ``T2`` in the same payload — parse each
+# with its own key list; do not combine.
 VALUE_KEY_T2 = (
     "t2",
     "value2",
@@ -67,6 +79,9 @@ VALUE_KEY_T2 = (
     "energy2",
 )
 
+# Backwards-compatible alias for the primary register key list.
+_DEFAULT_VALUE_KEYS = VALUE_KEY_T1
+
 EnergyMode = Literal["daily", "lifetime", "window"]
 TelemetryPoint = tuple[datetime | None, float]
 
@@ -135,7 +150,7 @@ def _coerce_value(raw: Any) -> float | None:
     return None
 
 
-def _iter_items(point: Any) -> Iterable[tuple[str, Any]] | None:
+def _iter_items(point: Any, value_keys: tuple[str, ...]) -> 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
@@ -144,7 +159,7 @@ def _iter_items(point: Any) -> Iterable[tuple[str, Any]] | None:
     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))
+    return ((k, lower.get(k)) for k in (*_DEFAULT_TIMESTAMP_KEYS, *value_keys))
 
 
 def parse_telemetry_points(
@@ -160,9 +175,10 @@ def parse_telemetry_points(
     * 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.
+    ``value_keys`` overrides the value-key priority list. Defaults to
+    :data:`VALUE_KEY_T1` (primary register only). Use :data:`VALUE_KEY_T2` to
+    extract the secondary register. T1 and T2 must be parsed separately —
+    never pass a key list that mixes both if you need tariff-accurate totals.
 
     Unparseable entries are silently skipped. The order of the input list is
     preserved.
@@ -170,7 +186,7 @@ def parse_telemetry_points(
     if not isinstance(points, list):
         return []
 
-    value_key_order = value_keys if value_keys is not None else _DEFAULT_VALUE_KEYS
+    value_key_order = value_keys if value_keys is not None else VALUE_KEY_T1
     timestamp_keys = _DEFAULT_TIMESTAMP_KEYS
 
     out: list[TelemetryPoint] = []
@@ -178,7 +194,7 @@ def parse_telemetry_points(
         ts: datetime | None = None
         value: float | None = None
 
-        items = _iter_items(point)
+        items = _iter_items(point, value_key_order)
         if items is not None:
             for key, raw in items:
                 if key in timestamp_keys and ts is None:

{dimplex_controller-0.9.0 → dimplex_controller-0.10.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dimplex-controller"
-version = "0.9.0"
+version = "0.10.1"
 description = "Python client for Dimplex heating controllers (GDHV IoT)"
 authors = ["Kieran Roper"]
 license = "MIT"
@@ -23,6 +23,9 @@ classifiers = [
 ]
 packages = [{ include = "dimplex_controller" }]
 
+[tool.poetry.scripts]
+dimplex = "dimplex_controller.cli:main"
+
 [tool.poetry.dependencies]
 python = "^3.10"
 aiohttp = "^3.9.0"