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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.12.0
+Version: 0.13.0
 Summary: Python client for Dimplex heating controllers (GDHV IoT)
 License: MIT
 License-File: LICENSE
@@ -27,12 +27,12 @@ Description-Content-Type: text/markdown
 
 # Dimplex Controller Python Client
 
-[![PyPI version](https://img.shields.io/pypi/v/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
-[![Python versions](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/dimplex-controller)](https://pypi.org/project/dimplex-controller/)
+[![Python versions](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![CI Tests](https://img.shields.io/github/actions/workflow/status/KRoperUK/dimplex-controller-py/test.yml?branch=main&label=CI)](https://github.com/KRoperUK/dimplex-controller-py/actions/workflows/test.yml)
-[![Downloads](https://img.shields.io/pypi/dm/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
-[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg)](https://buymeacoffee.com/kroperukc)
+[![CI](https://img.shields.io/github/actions/workflow/status/KRoperUK/dimplex-controller-py/test.yml?branch=main&label=CI)](https://github.com/KRoperUK/dimplex-controller-py/actions/workflows/test.yml)
+[![Downloads](https://img.shields.io/pypi/dm/dimplex-controller)](https://pypi.org/project/dimplex-controller/)
+[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow)](https://buymeacoffee.com/kroperukc)
 
 <p align="center">
   <strong>Async Python client for controlling Glen Dimplex Heating &amp; Ventilation (GDHV) appliances via the Dimplex cloud API.</strong>
@@ -177,21 +177,44 @@ for status in status_list:
 ### Sending control commands
 
 ```python
-from dimplex_controller.models import ApplianceModeSettings
-
 # Enable EcoStart
 await client.set_eco_start(hub_id, [appliance_id], True)
 
 # Enable Open Window Detection
 await client.set_open_window_detection(hub_id, [appliance_id], True)
 
-# Activate Boost
+# Timed Boost (ApplianceModes=2, Time = minutes)
 await client.set_boost(hub_id, [appliance_id], temperature=25.0, duration_minutes=60)
 
-# Set target temperature (rewrites timer period setpoints)
-await client.set_target_temperature(hub_id, appliance_id, 21.5)
+# Away until a given moment (ApplianceModes=4). Away is a settable 7–30 °C
+# setback and defaults to the 7 °C anti-freeze floor.
+from datetime import datetime, timedelta, timezone
+
+await client.set_away(
+    hub_id,
+    [appliance_id],
+    temperature=12.0,
+    until=datetime.now(timezone.utc) + timedelta(days=3),
+)
+
+# Set the target temperature — dedicated endpoint, leaves the schedule alone
+await client.set_appliance_setpoint_temperature(hub_id, [appliance_id], 21.5)
+
+# Turn off the way the app does: frost protection at 7 °C
+await client.turn_off(hub_id, [appliance_id])
 ```
 
+> **Mode flag values matter.** `EApplianceModes` is a bitfield where Boost is `2`
+> and Away is `4`; `16` is Advance and `32` is FrostProtect. Releases before
+> 0.13.0 had these wrong, so Boost silently became Advance and Away became a
+> fixed 7 °C frost hold. If you hand-build `ApplianceModeSettings`, use
+> `ApplianceModeFlag`. See
+> [docs/decompiled-api-reference.md](docs/decompiled-api-reference.md).
+>
+> **Avoid `SetTimerMode` for control.** `set_mode()` and the deprecated
+> `set_target_temperature()` rewrite the schedule; Quantum rejects that with
+> HTTP 403. Use `set_appliance_setpoint_temperature()` and `turn_off()`.
+
 ### Energy reports
 
 ```python
@@ -233,16 +256,23 @@ Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_toke
 | `get_user_context()` | Returns `UserContext`. |
 | `get_product_models()` | Returns `list[ProductModel]` (cacheable). |
 | `get_schedule(hub_id, appliance_id)` | Returns `TimerModeSettings` (timer + periods). |
-| `set_mode(hub_id, appliance_id, mode)` | Change timer/operation mode. |
-| `set_target_temperature(hub_id, appliance_id, temp)` | Rewrite all period setpoints or install full-week schedule. |
+| `set_mode(hub_id, appliance_id, mode)` | Rewrite `TimerMode`. **403 on Quantum** — prefer `turn_off`. |
+| `set_target_temperature(hub_id, appliance_id, temp)` | Deprecated: rewrites period setpoints. Prefer `set_appliance_setpoint_temperature`. |
+| `set_appliance_setpoint_temperature(hub_id, appliance_ids, temperature)` | Preferred setpoint path; non-destructive. |
 | `set_period_setpoint(...)` | Update one timer period without clobbering siblings. |
 | `update_period(...)` | Replace a timer period matched by day + start time. |
-| `set_boost(hub_id, appliance_ids, *, temperature, duration_minutes, enable)` | Enable/disable Boost. |
+| `copy_schedule_to_appliances(...)` | Copy one appliance's schedule onto others. |
+| `set_boost(hub_id, appliance_ids, *, temperature, duration_minutes, enable)` | Timed Boost (`ApplianceModes=2`). |
 | `clear_boost(hub_id, appliance_ids)` | Disable Boost. |
-| `set_away(hub_id, appliance_ids, *, temperature, enable, number_of_days)` | Enable/disable Away. |
+| `set_away(hub_id, appliance_ids, *, temperature, enable, until, number_of_days)` | Away setback (`ApplianceModes=4`). |
 | `clear_away(hub_id, appliance_ids)` | Disable Away. |
+| `set_frost_protect(...)` / `turn_off(...)` | Frost protection at 7 °C — the app's "off". |
+| `set_advance(...)` | Advance to the next schedule period. |
+| `set_manual(...)` / `set_eco_mode(...)` | Manual / Eco mode holds. |
+| `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). |
 | `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.12.0 → dimplex_controller-0.13.0}/README.md

@@ -1,11 +1,11 @@
 # Dimplex Controller Python Client
 
-[![PyPI version](https://img.shields.io/pypi/v/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
-[![Python versions](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/dimplex-controller)](https://pypi.org/project/dimplex-controller/)
+[![Python versions](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![CI Tests](https://img.shields.io/github/actions/workflow/status/KRoperUK/dimplex-controller-py/test.yml?branch=main&label=CI)](https://github.com/KRoperUK/dimplex-controller-py/actions/workflows/test.yml)
-[![Downloads](https://img.shields.io/pypi/dm/dimplex-controller.svg)](https://pypi.org/project/dimplex-controller/)
-[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg)](https://buymeacoffee.com/kroperukc)
+[![CI](https://img.shields.io/github/actions/workflow/status/KRoperUK/dimplex-controller-py/test.yml?branch=main&label=CI)](https://github.com/KRoperUK/dimplex-controller-py/actions/workflows/test.yml)
+[![Downloads](https://img.shields.io/pypi/dm/dimplex-controller)](https://pypi.org/project/dimplex-controller/)
+[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow)](https://buymeacoffee.com/kroperukc)
 
 <p align="center">
   <strong>Async Python client for controlling Glen Dimplex Heating &amp; Ventilation (GDHV) appliances via the Dimplex cloud API.</strong>
@@ -150,21 +150,44 @@ for status in status_list:
 ### Sending control commands
 
 ```python
-from dimplex_controller.models import ApplianceModeSettings
-
 # Enable EcoStart
 await client.set_eco_start(hub_id, [appliance_id], True)
 
 # Enable Open Window Detection
 await client.set_open_window_detection(hub_id, [appliance_id], True)
 
-# Activate Boost
+# Timed Boost (ApplianceModes=2, Time = minutes)
 await client.set_boost(hub_id, [appliance_id], temperature=25.0, duration_minutes=60)
 
-# Set target temperature (rewrites timer period setpoints)
-await client.set_target_temperature(hub_id, appliance_id, 21.5)
+# Away until a given moment (ApplianceModes=4). Away is a settable 7–30 °C
+# setback and defaults to the 7 °C anti-freeze floor.
+from datetime import datetime, timedelta, timezone
+
+await client.set_away(
+    hub_id,
+    [appliance_id],
+    temperature=12.0,
+    until=datetime.now(timezone.utc) + timedelta(days=3),
+)
+
+# Set the target temperature — dedicated endpoint, leaves the schedule alone
+await client.set_appliance_setpoint_temperature(hub_id, [appliance_id], 21.5)
+
+# Turn off the way the app does: frost protection at 7 °C
+await client.turn_off(hub_id, [appliance_id])
 ```
 
+> **Mode flag values matter.** `EApplianceModes` is a bitfield where Boost is `2`
+> and Away is `4`; `16` is Advance and `32` is FrostProtect. Releases before
+> 0.13.0 had these wrong, so Boost silently became Advance and Away became a
+> fixed 7 °C frost hold. If you hand-build `ApplianceModeSettings`, use
+> `ApplianceModeFlag`. See
+> [docs/decompiled-api-reference.md](docs/decompiled-api-reference.md).
+>
+> **Avoid `SetTimerMode` for control.** `set_mode()` and the deprecated
+> `set_target_temperature()` rewrite the schedule; Quantum rejects that with
+> HTTP 403. Use `set_appliance_setpoint_temperature()` and `turn_off()`.
+
 ### Energy reports
 
 ```python
@@ -206,16 +229,23 @@ Main client class. Construct with an `aiohttp.ClientSession` and a `refresh_toke
 | `get_user_context()` | Returns `UserContext`. |
 | `get_product_models()` | Returns `list[ProductModel]` (cacheable). |
 | `get_schedule(hub_id, appliance_id)` | Returns `TimerModeSettings` (timer + periods). |
-| `set_mode(hub_id, appliance_id, mode)` | Change timer/operation mode. |
-| `set_target_temperature(hub_id, appliance_id, temp)` | Rewrite all period setpoints or install full-week schedule. |
+| `set_mode(hub_id, appliance_id, mode)` | Rewrite `TimerMode`. **403 on Quantum** — prefer `turn_off`. |
+| `set_target_temperature(hub_id, appliance_id, temp)` | Deprecated: rewrites period setpoints. Prefer `set_appliance_setpoint_temperature`. |
+| `set_appliance_setpoint_temperature(hub_id, appliance_ids, temperature)` | Preferred setpoint path; non-destructive. |
 | `set_period_setpoint(...)` | Update one timer period without clobbering siblings. |
 | `update_period(...)` | Replace a timer period matched by day + start time. |
-| `set_boost(hub_id, appliance_ids, *, temperature, duration_minutes, enable)` | Enable/disable Boost. |
+| `copy_schedule_to_appliances(...)` | Copy one appliance's schedule onto others. |
+| `set_boost(hub_id, appliance_ids, *, temperature, duration_minutes, enable)` | Timed Boost (`ApplianceModes=2`). |
 | `clear_boost(hub_id, appliance_ids)` | Disable Boost. |
-| `set_away(hub_id, appliance_ids, *, temperature, enable, number_of_days)` | Enable/disable Away. |
+| `set_away(hub_id, appliance_ids, *, temperature, enable, until, number_of_days)` | Away setback (`ApplianceModes=4`). |
 | `clear_away(hub_id, appliance_ids)` | Disable Away. |
+| `set_frost_protect(...)` / `turn_off(...)` | Frost protection at 7 °C — the app's "off". |
+| `set_advance(...)` | Advance to the next schedule period. |
+| `set_manual(...)` / `set_eco_mode(...)` | Manual / Eco mode holds. |
+| `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). |
 | `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.12.0 → dimplex_controller-0.13.0}/dimplex_controller/__init__.py

@@ -14,6 +14,15 @@ need a stable id → status mapping.
 from .auth import TokenBundle, TokenListener
 from .capabilities import ApplianceCapabilities, capabilities_for
 from .client import DimplexControl
+from .const import (
+    DEFAULT_AWAY_TEMPERATURE,
+    DEFAULT_BOOST_TEMPERATURE,
+    FROST_TEMPERATURE,
+    MODE_TEMP_MAX,
+    MODE_TEMP_MIN,
+    NO_SETPOINT_SENTINEL,
+    NULL_DATETIME,
+)
 from .exceptions import (
     DimplexApiError,
     DimplexAuthError,
@@ -28,10 +37,14 @@ from .models import (
     Appliance,
     ApplianceModeFlag,
     ApplianceModeSettings,
+    ApplianceModeStatus,
     ApplianceStatus,
     AutomaticProvisioning,
     Hub,
+    HygieneFrequency,
     ProductModel,
+    ScheduleProfile,
+    SetbackStatus,
     TimerMode,
     TimerModeSettings,
     TimerPeriod,
@@ -59,12 +72,23 @@ __all__ = [
     "ApplianceStatus",
     "ApplianceModeSettings",
     "ApplianceModeFlag",
+    "ApplianceModeStatus",
+    "HygieneFrequency",
+    "ScheduleProfile",
+    "SetbackStatus",
     "TimerMode",
     "TimerModeSettings",
     "TimerPeriod",
     "AutomaticProvisioning",
     "ProductModel",
     "TsiEnergyReport",
+    "DEFAULT_AWAY_TEMPERATURE",
+    "DEFAULT_BOOST_TEMPERATURE",
+    "FROST_TEMPERATURE",
+    "MODE_TEMP_MIN",
+    "MODE_TEMP_MAX",
+    "NO_SETPOINT_SENTINEL",
+    "NULL_DATETIME",
     "parse_telemetry_points",
     "filter_telemetry_points",
     "summarise_energy",

{dimplex_controller-0.12.0 → dimplex_controller-0.13.0}/dimplex_controller/auth.py

@@ -309,12 +309,23 @@ class AuthManager:
 
         Uses direct HTTP credential submission so users don't need to
         manually extract auth codes from browser network traffic.
+
+        A separate :class:`aiohttp.ClientSession` is used because the B2C
+        flow requires a dedicated cookie jar for state tracking across
+        redirects (using the shared session would pollute its cookies).
+        The session inherits the caller's **connector** (TLS/proxy config)
+        and the configured timeout so network behaviour is consistent.
         """
         jar = aiohttp.CookieJar(unsafe=True)
         start_url = self.get_login_url()
+        # Inherit the caller's connector (TLS cert, proxy, DNS resolver) so
+        # headless login respects the same network configuration as API calls.
+        connector = self._session.connector
 
         try:
-            async with aiohttp.ClientSession(cookie_jar=jar, timeout=self._timeout) as session:
+            async with aiohttp.ClientSession(
+                cookie_jar=jar, timeout=self._timeout, connector=connector, connector_owner=False
+            ) as session:
                 # Step 1: GET the auth URI, follow redirects to B2C login page
                 _LOGGER.debug("Fetching B2C login page")
                 try:
@@ -374,6 +385,9 @@ class AuthManager:
                 # re-injected with quoted values on the next request.
                 async with aiohttp.ClientSession(
                     cookie_jar=aiohttp.DummyCookieJar(),
+                    timeout=self._timeout,
+                    connector=connector,
+                    connector_owner=False,
                 ) as raw_session:
                     try:
                         async with raw_session.post(

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

@@ -9,6 +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 .models import Appliance, ApplianceStatus, AutomaticProvisioning, ProductModel
 
 # Default boost lengths (minutes) offered by the mobile app for most heaters.
@@ -27,18 +28,26 @@ class ApplianceCapabilities:
 
     boost: bool = True
     away: bool = True
+    advance: 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
+    setback_write: bool = True  # POST /RemoteControl/SetSetbackTemperature
+    frost: bool = True  # ApplianceModeFlag.FROST_PROTECT (the app's "off")
     timer: bool = True
+    # POST /RemoteControl/SetApplianceSetpointTemperature — the non-destructive
+    # setpoint path. Preferred over rewriting the schedule via SetTimerMode,
+    # which Quantum rejects with HTTP 403.
+    setpoint_write: bool = True
     energy_meter: bool = False
     storage: bool = False
     hot_water: bool = False
+    heat_pump: bool = False
+    hygiene: bool = False
     climate: bool = True
-    min_temp: float = 5.0
-    max_temp: float = 30.0
+    min_temp: float = MODE_TEMP_MIN
+    max_temp: float = MODE_TEMP_MAX
+    frost_temp: float = FROST_TEMPERATURE
     default_boost_minutes: int = DEFAULT_BOOST_MINUTES
     boost_durations: tuple[int, ...] = DEFAULT_BOOST_DURATIONS
 
@@ -58,18 +67,23 @@ class ApplianceCapabilities:
         return {
             "boost": self.boost,
             "away": self.away,
+            "advance": self.advance,
             "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,
+            "setpoint_write": self.setpoint_write,
             "energy_meter": self.energy_meter,
             "storage": self.storage,
             "hot_water": self.hot_water,
+            "heat_pump": self.heat_pump,
+            "hygiene": self.hygiene,
             "climate": self.climate,
             "min_temp": self.min_temp,
             "max_temp": self.max_temp,
+            "frost_temp": self.frost_temp,
             "default_boost_minutes": self.default_boost_minutes,
             "boost_durations": list(self.boost_durations),
             "climate_presets": self.climate_presets(),
@@ -125,6 +139,7 @@ def capabilities_for(
     storage = False
     energy_meter = False
     hot_water = False
+    heat_pump = False
     if prov is not None:
         if prov.charge_capacity is not None and prov.charge_capacity > 0:
             storage = True
@@ -134,11 +149,15 @@ def capabilities_for(
     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")):
+    if any(k in tokens for k in ("hot water", "hotwater", "cylinder", "dhw", "waterheater")):
+        hot_water = True
+    if any(k in tokens for k in ("ashw", "heat pump", "heatpump")):
+        heat_pump = True
         hot_water = True
 
     boost = True
     away = True
+    advance = True
     open_window = True
     eco_start = True
     setback_read = True
@@ -162,17 +181,26 @@ def capabilities_for(
         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.
+    if hot_water and not climate:
+        advance = False
+
     return ApplianceCapabilities(
         boost=boost,
         away=away,
+        advance=advance,
         open_window=open_window,
         eco_start=eco_start,
         setback_read=setback_read,
-        setback_write=False,
+        setback_write=True,
         frost=frost,
         timer=timer,
+        setpoint_write=True,
         energy_meter=energy_meter,
         storage=storage,
         hot_water=hot_water,
+        heat_pump=heat_pump,
+        hygiene=hot_water,
         climate=climate,
     )

{dimplex_controller-0.12.0 → dimplex_controller-0.13.0}/dimplex_controller/cli.py

@@ -18,6 +18,7 @@ import contextlib
 import json
 import os
 import sys
+from collections.abc import Awaitable, Callable
 from pathlib import Path
 from typing import Any
 
@@ -25,7 +26,11 @@ import aiohttp
 
 from .auth import TokenBundle
 from .client import DimplexControl
+from .const import DEFAULT_AWAY_TEMPERATURE, DEFAULT_BOOST_TEMPERATURE
 from .exceptions import DimplexError
+from .models import SetbackStatus
+
+_CoroFactory = Callable[[DimplexControl], Awaitable[int]]
 
 
 def _load_tokens(path: Path | None) -> TokenBundle:
@@ -57,7 +62,7 @@ def _redact(value: str | None, *, show: bool) -> str:
 
 async def _with_client(
     args: argparse.Namespace,
-    coro_factory: Any,
+    coro_factory: _CoroFactory,
 ) -> int:
     tokens = _load_tokens(Path(args.tokens_file) if args.tokens_file else None)
     if not tokens.refresh_token and not tokens.access_token:
@@ -139,7 +144,11 @@ async def cmd_status(client: DimplexControl, args: argparse.Namespace) -> int:
         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))
+    payload = status.model_dump(mode="json")
+    # Decoded views the raw payload does not give you.
+    payload["_active_modes"] = status.active_modes
+    payload["_active_setpoint_temperature"] = status.active_setpoint_temperature
+    print(json.dumps(payload, indent=2, default=str))
     return 0
 
 
@@ -177,6 +186,8 @@ async def cmd_away(client: DimplexControl, args: argparse.Namespace) -> int:
         [args.appliance],
         temperature=args.temperature,
         enable=not args.clear,
+        until=args.until,
+        number_of_days=args.days,
     )
     print("ok")
     return 0
@@ -191,6 +202,54 @@ async def cmd_eco(client: DimplexControl, args: argparse.Namespace) -> int:
     return 0
 
 
+async def cmd_setpoint(client: DimplexControl, args: argparse.Namespace) -> int:
+    """Set the active setpoint via the dedicated (non-destructive) endpoint."""
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_appliance_setpoint_temperature(args.hub, [args.appliance], args.temperature)
+    print("ok")
+    return 0
+
+
+async def cmd_off(client: DimplexControl, args: argparse.Namespace) -> int:
+    """Turn the appliance off the way the app does — frost protection at 7 °C."""
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_frost_protect(args.hub, [args.appliance], enable=not args.clear)
+    print("ok")
+    return 0
+
+
+async def cmd_advance(client: DimplexControl, args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_advance(
+        args.hub,
+        [args.appliance],
+        enable=not args.clear,
+        temperature=args.temperature,
+    )
+    print("ok")
+    return 0
+
+
+async def cmd_setback(client: DimplexControl, args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("error: control commands require --yes", file=sys.stderr)
+        return 2
+    await client.set_setback_temperature(
+        args.hub,
+        [args.appliance],
+        temperature=args.temperature,
+        status=SetbackStatus.INACTIVE if args.clear else SetbackStatus.ACTIVE,
+    )
+    print("ok")
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="dimplex",
@@ -233,21 +292,54 @@ def build_parser() -> argparse.ArgumentParser:
     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}),
+    _CONTROL_COMMANDS: dict[str, Callable[..., Awaitable[int]]] = {
+        "boost": cmd_boost,
+        "away": cmd_away,
+        "eco": cmd_eco,
+        "setpoint": cmd_setpoint,
+        "off": cmd_off,
+        "advance": cmd_advance,
+        "setback": cmd_setback,
+    }
+
+    for name, help_text, opts in (
+        (
+            "boost",
+            "Enable or clear timed Boost (--yes required)",
+            {"temperature": DEFAULT_BOOST_TEMPERATURE, "minutes": 60},
+        ),
+        (
+            "away",
+            "Enable or clear Away setback, 7-30 °C (--yes required)",
+            {"temperature": DEFAULT_AWAY_TEMPERATURE, "away_until": True},
+        ),
         ("eco", "Enable or clear EcoStart (--yes required)", {}),
+        (
+            "setpoint",
+            "Set the active setpoint, non-destructive (--yes required)",
+            {"temperature": 21.0},
+        ),
+        ("off", "Turn off via frost protection at 7 °C (--yes required)", {}),
+        ("advance", "Advance to the next schedule period (--yes required)", {"temperature": None}),
+        (
+            "setback",
+            "Write the setback temperature (--yes required; untested)",
+            {"temperature": 16.0},
+        ),
     ):
         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])
+        if "temperature" in opts:
+            p.add_argument("--temperature", type=float, default=opts["temperature"])
+        if "minutes" in opts:
+            p.add_argument("--minutes", type=int, default=opts["minutes"])
+        if opts.get("away_until"):
+            p.add_argument("--days", type=int, default=0, help="Away duration in days (converted to a date)")
+            p.add_argument("--until", help="Away-until datetime, ISO-8601 (overrides --days)")
+        p.set_defaults(func=_CONTROL_COMMANDS[name])
 
     return parser
 
@@ -257,7 +349,8 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     async def run(client: DimplexControl) -> int:
-        return await args.func(client, args)
+        func: Callable[..., Awaitable[int]] = args.func
+        return await func(client, args)
 
     return asyncio.run(_with_client(args, run))