ramses-rf 0.22.2__py3-none-any.whl → 0.51.1__py3-none-any.whl

ramses_rf/system/heat.py

@@ -1,19 +1,16 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 """RAMSES RF - The evohome-compatible system."""
+
 from __future__ import annotations
 
 import asyncio
 import logging
-from asyncio import Future
-from datetime import datetime as dt
-from datetime import timedelta as td
+from datetime import datetime as dt, timedelta as td
 from threading import Lock
 from types import SimpleNamespace
-from typing import Any, Optional, Tuple, TypeVar
+from typing import TYPE_CHECKING, Any, NoReturn, TypeVar
 
-from ..const import (
+from ramses_rf.const import (
     SYS_MODE_MAP,
     SZ_ACTUATORS,
     SZ_CHANGE_COUNTER,
@@ -30,32 +27,18 @@ from ..const import (
     SZ_ZONE_MASK,
     SZ_ZONE_TYPE,
     SZ_ZONES,
-    __dev_mode__,
 )
-from ..device import (
+from ramses_rf.device import (
     BdrSwitch,
     Controller,
     Device,
-    DeviceHeat,
     OtbGateway,
     Temperature,
     UfhController,
 )
-from ..entity_base import Entity, Parent, class_by_attr
-from ..helpers import shrink
-from ..protocol import (
-    DEV_ROLE_MAP,
-    DEV_TYPE_MAP,
-    ZON_ROLE_MAP,
-    Address,
-    Command,
-    ExpiredCallbackError,
-    Message,
-    Priority,
-)
-from ..protocol.command import FaultLog, _mk_cmd
-from ..protocol.const import SZ_PRIORITY, SZ_RETRIES
-from ..schemas import (
+from ramses_rf.entity_base import Entity, Parent, class_by_attr
+from ramses_rf.helpers import shrink
+from ramses_rf.schemas import (
     DEFAULT_MAX_ZONES,
     SCH_TCS,
     SCH_TCS_DHW,
@@ -68,33 +51,54 @@ from ..schemas import (
     SZ_SYSTEM,
     SZ_UFH_SYSTEM,
 )
-from .zones import DhwZone, Zone
+from ramses_tx import (
+    DEV_ROLE_MAP,
+    DEV_TYPE_MAP,
+    ZON_ROLE_MAP,
+    Command,
+    DeviceIdT,
+    Message,
+    Priority,
+)
+from ramses_tx.typed_dicts import PayDictT
+
+from .faultlog import FaultLog
+from .zones import zone_factory
+
+if TYPE_CHECKING:
+    from ramses_tx import Address, Packet
+
+    from .faultlog import FaultIdxT, FaultLogEntry
+    from .zones import DhwZone, Zone
+
 
 # TODO: refactor packet routing (filter *before* routing)
 
 
-# skipcq: PY-W2000
-from ..protocol import (  # noqa: F401, isort: skip, pylint: disable=unused-import
-    I_,
-    RP,
-    RQ,
-    W_,
+from ramses_rf.const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     F9,
     FA,
     FC,
     FF,
-    Code,
 )
 
+from ramses_rf.const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
+    I_,
+    RP,
+    RQ,
+    W_,
+    Code,
+)
 
-DEV_MODE = __dev_mode__
 
 _LOGGER = logging.getLogger(__name__)
-if DEV_MODE:
-    _LOGGER.setLevel(logging.DEBUG)
 
 
-_SystemT = TypeVar("_SystemT", bound="System")
+_SystemT = TypeVar("_SystemT", bound="Evohome")
+
+_StoredHwT = TypeVar("_StoredHwT", bound="StoredHw")
+_LogbookT = TypeVar("_LogbookT", bound="Logbook")
+_MultiZoneT = TypeVar("_MultiZoneT", bound="MultiZone")
 
 
 SYS_KLASS = SimpleNamespace(
@@ -109,7 +113,10 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
 
     _SLUG: str = None  # type: ignore[assignment]
 
-    def __init__(self, ctl) -> None:
+    # TODO: check (code so complex, not sure if this is true)
+    childs: list[Device]  # type: ignore[assignment]
+
+    def __init__(self, ctl: Controller) -> None:
         _LOGGER.debug("Creating a TCS for CTL: %s (%s)", ctl.id, self.__class__)
 
         if ctl.id in ctl._gwy.system_by_id:
@@ -119,45 +126,18 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
 
         super().__init__(ctl._gwy)
 
-        self.id: str = ctl.id
-
-        self.ctl = ctl
-        self.tcs = self
-        self._child_id = FF  # NOTE: domain_id
+        # FIXME: ZZZ entities must know their parent device ID and their own idx
+        self._z_id = ctl.id  # the responsible device is the controller
+        self._z_idx = None  # ? True (sentinel value to pick up arrays?)
 
-        self._app_cntrl: DeviceHeat = None  # schema attr
-        self._heat_demand = None  # state attr
+        self.id: DeviceIdT = ctl.id
 
-    def _update_schema(self, **schema):
-        """Update a CH/DHW system with new schema attrs.
-
-        Raise an exception if the new schema is not a superset of the existing schema.
-        """
-
-        schema = shrink(SCH_TCS(schema))
-
-        if schema.get(SZ_SYSTEM) and (
-            dev_id := schema[SZ_SYSTEM].get(SZ_APPLIANCE_CONTROL)
-        ):
-            self._app_cntrl = self._gwy.get_device(dev_id, parent=self, child_id=FC)
-
-        if _schema := (schema.get(SZ_DHW_SYSTEM)):
-            self.get_dhw_zone(**_schema)  # self._dhw = ...
-
-        if _schema := (schema.get(SZ_ZONES)):
-            [self.get_htg_zone(idx, **s) for idx, s in _schema.items()]
+        self.ctl: Controller = ctl
+        self.tcs: Evohome = self  # type: ignore[assignment]
+        self._child_id = FF  # NOTE: domain_id
 
-    @classmethod
-    def create_from_schema(cls, ctl: Device, **schema):
-        """Create a CH/DHW system for a CTL and set its schema attrs.
-
-        The appropriate System class should have been determined by a factory.
-        Schema attrs include: class (klass) & others.
-        """
-
-        tcs = cls(ctl)
-        tcs._update_schema(**schema)
-        return tcs
+        self._app_cntrl: BdrSwitch | OtbGateway | None = None
+        self._heat_demand = None
 
     def __repr__(self) -> str:
         return f"{self.ctl.id} ({self._SLUG})"
@@ -170,14 +150,16 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
             f"00{DEV_ROLE_MAP.HTG}",  # hotwater_valve
             f"01{DEV_ROLE_MAP.HTG}",  # heating_valve
         ):
-            self._add_discovery_cmd(
-                _mk_cmd(RQ, Code._000C, payload, self.ctl.id), 60 * 60 * 24, delay=0
-            )
+            cmd = Command.from_attrs(RQ, self.ctl.id, Code._000C, payload)
+            self._add_discovery_cmd(cmd, 60 * 60 * 24, delay=0)
 
-        self._add_discovery_cmd(Command.get_tpi_params(self.id), 60 * 60 * 6, delay=5)
+        cmd = Command.get_tpi_params(self.id)
+        self._add_discovery_cmd(cmd, 60 * 60 * 6, delay=5)
 
     def _handle_msg(self, msg: Message) -> None:
-        def eavesdrop_appliance_control(this, *, prev=None) -> None:
+        def eavesdrop_appliance_control(
+            this: Message, *, prev: Message | None = None
+        ) -> None:
             """Discover the heat relay (10: or 13:) for this system.
 
             There's' 3 ways to find a controller's heat relay (in order of reliability):
@@ -186,7 +168,7 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
             2b. The 3EF0 RQ (no RP) *to a 13:* (3x/60min)
             3.  The 3B00 I/I exchange between a CTL & a 13: (TPI cycle rate, usu. 6x/hr)
 
-            Data from the CTL is considered 'authorative'. The 1FC9 RQ/RP exchange
+            Data from the CTL is considered 'authoritative'. The 1FC9 RQ/RP exchange
             to/from a CTL is too rare to be useful.
             """
 
@@ -210,84 +192,67 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
             if (
                 this.code in (Code._22D9, Code._3220) and this.verb == RQ
             ):  # TODO: RPs too?
-                if this.src is self.ctl and isinstance(this.dst, OtbGateway):
-                    app_cntrl = this.dst
+                # dst could be an Address...
+                if this.src is self.ctl and isinstance(this.dst, OtbGateway):  # type: ignore[unreachable]
+                    app_cntrl = this.dst  # type: ignore[unreachable]
 
             elif this.code == Code._3EF0 and this.verb == RQ:
+                # dst could be an Address...
                 if this.src is self.ctl and isinstance(
-                    this.dst, (BdrSwitch, OtbGateway)
+                    this.dst,  # type: ignore[unreachable]
+                    BdrSwitch | OtbGateway,
                 ):
-                    app_cntrl = this.dst
+                    app_cntrl = this.dst  # type: ignore[unreachable]
 
             elif this.code == Code._3B00 and this.verb == I_ and prev is not None:
-                if this.src is self.ctl and isinstance(prev.src, BdrSwitch):
-                    if prev.code == this.code and prev.verb == this.verb:
+                if this.src is self.ctl and isinstance(prev.src, BdrSwitch):  # type: ignore[unreachable]
+                    if prev.code == this.code and prev.verb == this.verb:  # type: ignore[unreachable]
                         app_cntrl = prev.src
 
             if app_cntrl is not None:
-                app_cntrl.set_parent(self, child_id=FC)  # sets self._app_cntrl
+                app_cntrl.set_parent(self, child_id=FC)  # type: ignore[unreachable]
 
-        assert msg.src is self.ctl, f"msg inappropriately routed to {self}"
+        # # assert msg.src is self.ctl, f"msg inappropriately routed to {self}"
 
         super()._handle_msg(msg)
 
-        if (
-            msg.code == Code._000C
-            and msg.payload[SZ_ZONE_TYPE] == DEV_ROLE_MAP.APP
-            and (msg.payload[SZ_DEVICES])
-        ):
-            self._gwy.get_device(
-                msg.payload[SZ_DEVICES][0], parent=self, child_id=FC
-            )  # sets self._app_cntrl
+        if msg.code == Code._000C:
+            if msg.payload[SZ_ZONE_TYPE] == DEV_ROLE_MAP.APP and msg.payload.get(
+                SZ_DEVICES
+            ):
+                self._gwy.get_device(
+                    msg.payload[SZ_DEVICES][0], parent=self, child_id=FC
+                )  # sets self._app_cntrl
             return
 
-        if msg.code == Code._0008:
-            if (domain_id := msg.payload.get(SZ_DOMAIN_ID)) and msg.verb in (I_, RP):
-                self._relay_demands[domain_id] = msg
-                if domain_id == F9:
-                    device = self.dhw.heating_valve if self.dhw else None
-                elif domain_id == "xFA":  # TODO, FIXME
-                    device = self.dhw.hotwater_valve if self.dhw else None
-                elif domain_id == FC:
-                    device = self.appliance_control
-                else:
-                    device = None
-
-                if False and device is not None:  # TODO: FIXME
-                    qos = {SZ_PRIORITY: Priority.LOW, SZ_RETRIES: 2}
-                    for code in (Code._0008, Code._3EF1):
-                        device._make_cmd(code, qos)
-
-        elif msg.code == Code._3150:
+        if msg.code == Code._3150:
             if msg.payload.get(SZ_DOMAIN_ID) == FC and msg.verb in (I_, RP):
                 self._heat_demand = msg.payload
 
         if self._gwy.config.enable_eavesdrop and not self.appliance_control:
             eavesdrop_appliance_control(msg)
 
-    def _make_cmd(self, code, payload="00", **kwargs) -> None:  # skipcq: PYL-W0221
-        super()._make_cmd(code, self.ctl.id, payload=payload, **kwargs)
-
     @property
-    def appliance_control(self) -> Device:
+    def appliance_control(self) -> BdrSwitch | OtbGateway | None:
         """The TCS relay, aka 'appliance control' (BDR or OTB)."""
         if self._app_cntrl:
             return self._app_cntrl
         app_cntrl = [d for d in self.childs if d._child_id == FC]
-        return app_cntrl[0] if len(app_cntrl) == 1 else None  # HACK for 10:
+        return app_cntrl[0] if len(app_cntrl) == 1 else None  # type: ignore[return-value]
 
     @property
-    def tpi_params(self) -> Optional[dict]:  # 1100
-        return self._msg_value(Code._1100)
+    def tpi_params(self) -> PayDictT._1100 | None:  # 1100
+        return self._msg_value(Code._1100)  # type: ignore[return-value]
 
     @property
-    def heat_demand(self) -> None | float:  # 3150/FC
-        return self._msg_value(Code._3150, domain_id=FC, key=SZ_HEAT_DEMAND)
+    def heat_demand(self) -> float | None:  # 3150/FC
+        return self._msg_value(Code._3150, domain_id=FC, key=SZ_HEAT_DEMAND)  # type: ignore[return-value]
 
     @property
-    def is_calling_for_heat(self) -> None | bool:
-        """Return True is the system is currently calling for heat."""
-        return self._app_cntrl and self._app_cntrl.actuator_state
+    def is_calling_for_heat(self) -> NoReturn:
+        raise NotImplementedError(
+            f"{self}: is_calling_for_heat attr is deprecated, use bool(heat_demand)"
+        )
 
     @property
     def schema(self) -> dict[str, Any]:
@@ -338,6 +303,12 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
         if zones:
             result[SZ_ZONES] = zones
 
+        result |= {
+            k: v
+            for k, v in schema.items()
+            if k in ("orphans",) and v  # add UFH?
+        }
+
         return result  # TODO: check against vol schema
 
     @property
@@ -355,30 +326,31 @@ class SystemBase(Parent, Entity):  # 3B00 (multi-relay)
         status: dict[str, Any] = {SZ_SYSTEM: {}}
         status[SZ_SYSTEM]["heat_demand"] = self.heat_demand
 
-        status[SZ_DEVICES] = {d.id: d.status for d in sorted(self.childs)}
+        status[SZ_DEVICES] = {
+            d.id: d.status for d in sorted(self.childs, key=lambda x: x.id)
+        }
 
         return status
 
 
 class MultiZone(SystemBase):  # 0005 (+/- 000C?)
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
-        self.zones = []
-        self.zone_by_idx = {}
-        self._max_zones = getattr(self._gwy.config, SZ_MAX_ZONES, DEFAULT_MAX_ZONES)
+        self.zones: list[Zone] = []
+        self.zone_by_idx: dict[str, Zone] = {}  # should not include HW
+        self._max_zones: int = getattr(
+            self._gwy.config, SZ_MAX_ZONES, DEFAULT_MAX_ZONES
+        )
 
-        self._prev_30c9 = None  # used to eavesdrop zone sensors
+        self._prev_30c9: Message | None = None  # used to eavesdrop zone sensors
 
     def _setup_discovery_cmds(self) -> None:
         super()._setup_discovery_cmds()
 
         for zone_type in list(ZON_ROLE_MAP.HEAT_ZONES) + [ZON_ROLE_MAP.SEN]:
-            self._add_discovery_cmd(
-                _mk_cmd(RQ, Code._0005, f"00{zone_type}", self.id),
-                60 * 60 * 24,
-                delay=0,
-            )
+            cmd = Command.from_attrs(RQ, self.id, Code._0005, f"00{zone_type}")
+            self._add_discovery_cmd(cmd, 60 * 60 * 24, delay=0)
 
     def _handle_msg(self, msg: Message) -> None:
         """Process any relevant message.
@@ -386,7 +358,7 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
         If `zone_idx` in payload, route any messages to the corresponding zone.
         """
 
-        def eavesdrop_zones(this, *, prev=None) -> None:
+        def eavesdrop_zones(this: Message, *, prev: Message | None = None) -> None:
             [
                 self.get_htg_zone(v)
                 for d in msg.payload
@@ -394,29 +366,31 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
                 if k == SZ_ZONE_IDX
             ]
 
-        def eavesdrop_zone_sensors(this, *, prev=None) -> None:
+        def eavesdrop_zone_sensors(
+            this: Message, *, prev: Message | None = None
+        ) -> None:
             """Determine each zone's sensor by matching zone/sensor temperatures."""
 
-            def _testable_zones(changed_zones) -> dict:
+            def _testable_zones(changed_zones: dict[str, float]) -> dict[float, str]:
                 return {
-                    t: z
-                    for z, t in changed_zones.items()
-                    if self.zone_by_idx[z].sensor is None
-                    and t not in [t2 for z2, t2 in changed_zones.items() if z2 != z]
+                    t1: i1
+                    for i1, t1 in changed_zones.items()
+                    if self.zone_by_idx[i1].sensor is None
+                    and t1 not in [t2 for i2, t2 in changed_zones.items() if i2 != i1]
                 }
 
             self._prev_30c9, prev = this, self._prev_30c9
             if prev is None:
-                return
+                return  # type: ignore[unreachable]
 
             # TODO: use msgz/I, not RP
-            secs = self._msg_value(Code._1F09, key="remaining_seconds")
+            secs: int = self._msg_value(Code._1F09, key="remaining_seconds")  # type: ignore[assignment]
             if secs is None or this.dtm > prev.dtm + td(seconds=secs + 5):
                 return  # can only compare against 30C9 pkt from the last cycle
 
             # _LOGGER.warning("System state (before): %s", self.schema)
 
-            changed_zones = {
+            changed_zones: dict[str, float] = {
                 z[SZ_ZONE_IDX]: z[SZ_TEMPERATURE]
                 for z in this.payload
                 if z not in prev.payload and z[SZ_TEMPERATURE] is not None
@@ -469,12 +443,11 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
 
             # _LOGGER.warning("System state (finally): %s", self.schema)
 
-        def handle_msg_by_zone_idx(zone_idx: str, msg):
+        def handle_msg_by_zone_idx(zone_idx: str, msg: Message) -> None:
             if zone := self.zone_by_idx.get(zone_idx):
                 zone._handle_msg(msg)
             # elif self._gwy.config.enable_eavesdrop:
             #     self.get_htg_zone(zone_idx)._handle_msg(msg)
-            pass
 
         super()._handle_msg(msg)
 
@@ -532,7 +505,8 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
         elif isinstance(msg.payload, list) and len(msg.payload):
             # TODO: elif msg.payload.get(SZ_DOMAIN_ID) == FA:  # DHW
             if isinstance(msg.payload[0], dict):  # e.g. 1FC9 is a list of lists:
-                [handle_msg_by_zone_idx(z.get(SZ_ZONE_IDX), msg) for z in msg.payload]
+                for z_dict in msg.payload:
+                    handle_msg_by_zone_idx(z_dict.get(SZ_ZONE_IDX), msg)
 
         # If some zones still don't have a sensor, maybe eavesdrop?
         if (  # TODO: edge case: 1 zone with CTL as SEN
@@ -543,7 +517,10 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
         ):
             eavesdrop_zone_sensors(msg)
 
-    def get_htg_zone(self, zone_idx, *, msg=None, **schema) -> Zone:
+    # TODO: should be a private method
+    def get_htg_zone(
+        self, zone_idx: str, *, msg: Message | None = None, **schema: Any
+    ) -> Zone:
         """Return a heating zone, create it if required.
 
         First, use the schema to create/update it, then pass it any msg to handle.
@@ -552,13 +529,11 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
         If a zone is created, attach it to this TCS.
         """
 
-        from .zones import zone_factory
-
         schema = shrink(SCH_TCS_ZONES_ZON(schema))
 
-        zon = self.zone_by_idx.get(zone_idx)
-        if not zon:
-            zon = zone_factory(self, zone_idx, msg=msg, **schema)
+        zon: Zone = self.zone_by_idx.get(zone_idx)  # type: ignore[assignment]
+        if zon is None:
+            zon = zone_factory(self, zone_idx, msg=msg, **schema)  # type: ignore[unreachable]
             self.zone_by_idx[zon.idx] = zon
             self.zones.append(zon)
 
@@ -592,31 +567,36 @@ class MultiZone(SystemBase):  # 0005 (+/- 000C?)
 
 
 class ScheduleSync(SystemBase):  # 0006 (+/- 0404?)
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
         self._msg_0006: Message = None  # type: ignore[assignment]
 
-        self.zone_lock = Lock()  # used to stop concurrent get_schedules
-        self.zone_lock_idx = None
+        # used to stop concurrent get_schedules
+        self.zone_lock = Lock()  # FIXME: threading lock, or asyncio lock?
+        self.zone_lock_idx: str | None = None
 
     def _setup_discovery_cmds(self) -> None:
         super()._setup_discovery_cmds()
 
-        self._add_discovery_cmd(_mk_cmd(RQ, Code._0006, "00", self.id), 60 * 5, delay=5)
+        cmd = Command.get_schedule_version(self.id)
+        self._add_discovery_cmd(cmd, 60 * 5, delay=5)
 
     def _handle_msg(self, msg: Message) -> None:  # NOTE: active
-        """Periodically retreive the latest global change counter."""
+        """Periodically retrieve the latest global change counter."""
+
         super()._handle_msg(msg)
 
         if msg.code == Code._0006:
             self._msg_0006 = msg
 
-    async def _schedule_version(self, *, force_io: bool = False) -> Tuple[int, bool]:
+    async def _schedule_version(self, *, force_io: bool = False) -> tuple[int, bool]:
         """Return the global schedule version number, and an indication if I/O was done.
 
         If `force_io`, then RQ the latest change counter from the TCS rather than
         rely upon a recent (cached) value.
+
+        Cached values are only used if less than 3 minutes old.
         """
 
         # RQ --- 30:185469 01:037519 --:------ 0006 001 00
@@ -632,31 +612,26 @@ class ScheduleSync(SystemBase):  # 0006 (+/- 0404?)
                 False,
             )  # global_ver, did_io
 
-        self._msg_0006 = await self._gwy.async_send_cmd(
-            Command.get_schedule_version(self.ctl.id)
+        cmd = Command.get_schedule_version(self.ctl.id)
+        pkt = await self._gwy.async_send_cmd(
+            cmd, wait_for_reply=True, priority=Priority.HIGH
         )
-
-        assert isinstance(  # TODO: remove me
-            self._msg_0006, Message
-        ), f"_schedule_version(): {self._msg_0006} (is not a message)"
+        if pkt:
+            self._msg_0006 = Message(pkt)
 
         return self._msg_0006.payload[SZ_CHANGE_COUNTER], True  # global_ver, did_io
 
     def _refresh_schedules(self) -> None:
-        if self._gwy.config.disable_sending:
-            raise RuntimeError("Sending is disabled")
+        zone: Zone
 
-        # schedules based upon 'active' (not most recent) 0006 pkt
         for zone in getattr(self, SZ_ZONES, []):
             self._gwy._loop.create_task(zone.get_schedule(force_io=True))
-        if dhw := getattr(self, "dhw", None):
-            self._gwy._loop.create_task(dhw.get_schedule(force_io=True))
-
-    async def _obtain_lock(self, zone_idx) -> None:
+        if isinstance(self, StoredHw) and self.dhw:
+            self._gwy._loop.create_task(self.dhw.get_schedule(force_io=True))
 
+    async def _obtain_lock(self, zone_idx: str) -> None:
         timeout_dtm = dt.now() + td(minutes=3)
         while dt.now() < timeout_dtm:
-
             self.zone_lock.acquire()
             if self.zone_lock_idx is None:
                 self.zone_lock_idx = zone_idx
@@ -672,14 +647,13 @@ class ScheduleSync(SystemBase):  # 0006 (+/- 0404?)
             )
 
     def _release_lock(self) -> None:
-
         self.zone_lock.acquire()
         self.zone_lock_idx = None
         self.zone_lock.release()
 
     @property
-    def schedule_version(self) -> None | int:
-        return self._msg_value(Code._0006, key=SZ_CHANGE_COUNTER)
+    def schedule_version(self) -> int | None:
+        return self._msg_value(Code._0006, key=SZ_CHANGE_COUNTER)  # type: ignore[return-value]
 
     @property
     def status(self) -> dict[str, Any]:
@@ -693,13 +667,12 @@ class Language(SystemBase):  # 0100
     def _setup_discovery_cmds(self) -> None:
         super()._setup_discovery_cmds()
 
-        self._add_discovery_cmd(
-            Command.get_system_language(self.id), 60 * 60 * 24, delay=60 * 15
-        )
+        cmd = Command.get_system_language(self.id)
+        self._add_discovery_cmd(cmd, 60 * 60 * 24, delay=60 * 15)
 
     @property
-    def language(self) -> None | str:
-        return self._msg_value(Code._0100, key=SZ_LANGUAGE)
+    def language(self) -> str | None:
+        return self._msg_value(Code._0100, key=SZ_LANGUAGE)  # type: ignore[return-value]
 
     @property
     def params(self) -> dict[str, Any]:
@@ -709,7 +682,7 @@ class Language(SystemBase):  # 0100
 
 
 class Logbook(SystemBase):  # 0418
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
         self._prev_event: Message = None  # type: ignore[assignment]
@@ -718,93 +691,63 @@ class Logbook(SystemBase):  # 0418
         self._prev_fault: Message = None  # type: ignore[assignment]
         self._this_fault: Message = None  # type: ignore[assignment]
 
-        # FaultLog(self.ctl)
-        self._faultlog: FaultLog = None  # type: ignore[assignment]
-        self._faultlog_outdated: bool = True
+        self._faultlog: FaultLog = FaultLog(self)
 
     def _setup_discovery_cmds(self) -> None:
         super()._setup_discovery_cmds()
 
-        self._add_discovery_cmd(
-            Command.get_system_log_entry(self.ctl.id, 0), 60 * 5, delay=5
-        )
-        # self._gwy.add_task(self._loop.create_task(self.get_faultlog()))
+        cmd = Command.get_system_log_entry(self.id, 0)
+        self._add_discovery_cmd(cmd, 60 * 5, delay=5)
+        # self._gwy.add_task(
+        #     self._gwy._loop.create_task(self.get_faultlog())
+        # )
 
     def _handle_msg(self, msg: Message) -> None:  # NOTE: active
         super()._handle_msg(msg)
 
-        if msg.code != Code._0418:
-            return
-
-        if msg.payload["log_idx"] == "00":
-            if not self._this_event or (
-                msg.payload["log_entry"] != self._this_event.payload["log_entry"]
-            ):
-                self._this_event, self._prev_event = msg, self._this_event
-            # TODO: self._faultlog_outdated = msg.verb == I_ or self._prev_event and (
-            #     msg.payload["log_entry"] != self._prev_event.payload["log_entry"]
-            # )
-
-        if msg.payload["log_entry"] and msg.payload["log_entry"][1] == "fault":
-            if not self._this_fault or (
-                msg.payload["log_entry"] != self._this_fault.payload["log_entry"]
-            ):
-                self._this_fault, self._prev_fault = msg, self._this_fault
-
-        # if msg.payload["log_entry"][1] == "restore" and not self._this_fault:
-        #     self._send_cmd(Command.get_system_log_entry(self.ctl.id, 1))
-
-        # TODO: if self._faultlog_outdated:
-        #     if not self._gwy.config.disable_sending:
-        #         self._loop.create_task(self.get_faultlog(force_io=True))
+        if msg.code == Code._0418:  # and msg.verb in (I_, RP):
+            self._faultlog.handle_msg(msg)
 
     async def get_faultlog(
-        self, *, start=None, limit=None, force_io=None
-    ) -> None | dict:
-        if self._gwy.config.disable_sending:
-            raise RuntimeError("Sending is disabled")
-
-        try:
-            return await self._faultlog.get_faultlog(
-                start=start, limit=limit, force_io=force_io
-            )
-        except (ExpiredCallbackError, RuntimeError):
-            return None
-
-    # @property
-    # def faultlog_outdated(self) -> bool:
-    #     return self._this_event.verb == I_ or self._prev_event and (
-    #         self._this_event.payload != self._prev_event.payload
-    #     )
-
-    # @property
-    # def faultlog(self) -> dict:
-    #     return self._faultlog.faultlog
+        self,
+        /,
+        *,
+        start: int = 0,
+        limit: int | None = None,
+        force_refresh: bool = False,
+    ) -> dict[FaultIdxT, FaultLogEntry] | None:
+        return await self._faultlog.get_faultlog(
+            start=start, limit=limit, force_refresh=force_refresh
+        )
 
     @property
-    def active_fault(self) -> Optional[tuple]:
-        """Return the most recently logged event, but only if it is a fault."""
-        if self.latest_fault != self.latest_event:
+    def active_faults(self) -> tuple[str, ...] | None:
+        """Return the most recently logged faults that are not restored."""
+        if self._faultlog.active_faults is None:
             return None
-        return self.latest_fault
+        return tuple(str(f) for f in self._faultlog.active_faults)
 
     @property
-    def latest_event(self) -> Optional[tuple]:
+    def latest_event(self) -> str | None:
         """Return the most recently logged event (fault or restore), if any."""
-        return self._this_event and self._this_event.payload["log_entry"]
+        if not self._faultlog.latest_event:
+            return None
+        return str(self._faultlog.latest_event)
 
     @property
-    def latest_fault(self) -> Optional[tuple]:
+    def latest_fault(self) -> str | None:
         """Return the most recently logged fault, if any."""
-        return self._this_fault and self._this_fault.payload["log_entry"]
+        if not self._faultlog.latest_fault:
+            return None
+        return str(self._faultlog.latest_fault)
 
     @property
     def status(self) -> dict[str, Any]:
         return {
             **super().status,
+            "active_faults": self.active_faults,
             "latest_event": self.latest_event,
-            "active_fault": self.active_fault,
-            # "faultlog": self.faultlog,
+            "latest_fault": self.latest_fault,
         }
 
 
@@ -813,7 +756,7 @@ class StoredHw(SystemBase):  # 10A0, 1260, 1F41
     MAX_SETPOINT = 85.0
     DEFAULT_SETPOINT = 50.0
 
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self._dhw: DhwZone = None  # type: ignore[assignment]
 
@@ -825,12 +768,10 @@ class StoredHw(SystemBase):  # 10A0, 1260, 1F41
             # f"00{DEV_ROLE_MAP.HTG}",  # hotwater_valve
             # f"01{DEV_ROLE_MAP.HTG}",  # heating_valve
         ):
-            self._add_discovery_cmd(
-                _mk_cmd(RQ, Code._000C, payload, self.id), 60 * 60 * 24, delay=0
-            )
+            cmd = Command.from_attrs(RQ, self.id, Code._000C, payload)
+            self._add_discovery_cmd(cmd, 60 * 60 * 24, delay=0)
 
     def _handle_msg(self, msg: Message) -> None:
-
         super()._handle_msg(msg)
 
         if (
@@ -858,7 +799,8 @@ class StoredHw(SystemBase):  # 10A0, 1260, 1F41
         # Route all messages to their zones, incl. 000C, 0404, others
         self.get_dhw_zone(msg=msg)
 
-    def get_dhw_zone(self, *, msg=None, **schema) -> DhwZone:
+    # TODO: should be a private method
+    def get_dhw_zone(self, *, msg: Message | None = None, **schema: Any) -> DhwZone:
         """Return a DHW zone, create it if required.
 
         First, use the schema to create/update it, then pass it any msg to handle.
@@ -867,12 +809,10 @@ class StoredHw(SystemBase):  # 10A0, 1260, 1F41
         If a DHW zone is created, attach it to this TCS.
         """
 
-        from .zones import zone_factory
-
         schema = shrink(SCH_TCS_DHW(schema))
 
         if not self._dhw:
-            self._dhw = zone_factory(self, "HW", msg=msg, **schema)
+            self._dhw = zone_factory(self, "HW", msg=msg, **schema)  # type: ignore[assignment]
 
         elif schema:
             self._dhw._update_schema(**schema)
@@ -882,19 +822,19 @@ class StoredHw(SystemBase):  # 10A0, 1260, 1F41
         return self._dhw
 
     @property
-    def dhw(self) -> DhwZone:
+    def dhw(self) -> DhwZone | None:
         return self._dhw
 
     @property
-    def dhw_sensor(self) -> None | Device:
+    def dhw_sensor(self) -> Device | None:
         return self._dhw.sensor if self._dhw else None
 
     @property
-    def hotwater_valve(self) -> None | Device:
+    def hotwater_valve(self) -> Device | None:
         return self._dhw.hotwater_valve if self._dhw else None
 
     @property
-    def heating_valve(self) -> None | Device:
+    def heating_valve(self) -> Device | None:
         return self._dhw.heating_valve if self._dhw else None
 
     @property
@@ -923,23 +863,31 @@ class SysMode(SystemBase):  # 2E04
     def _setup_discovery_cmds(self) -> None:
         super()._setup_discovery_cmds()
 
-        self._add_discovery_cmd(Command.get_system_mode(self.id), 60 * 5, delay=5)
+        cmd = Command.get_system_mode(self.id)
+        self._add_discovery_cmd(cmd, 60 * 5, delay=5)
 
     @property
-    def system_mode(self) -> Optional[dict]:  # 2E04
-        return self._msg_value(Code._2E04)
+    def system_mode(self) -> dict[str, Any] | None:  # 2E04
+        return self._msg_value(Code._2E04)  # type: ignore[return-value]
 
-    def set_mode(self, system_mode, *, until=None) -> Future:
-        """Set a system mode for a specified duration, or indefinitely."""
-        return self._send_cmd(
-            Command.set_system_mode(self.id, system_mode, until=until)
-        )
+    def set_mode(
+        self, system_mode: int | str | None, *, until: dt | str | None = None
+    ) -> asyncio.Task[Packet]:
+        """
+        Set a system mode for a specified duration, or indefinitely.
+
+        :param system_mode: 2-digit item from SYS_MODE_MAP, positional
+        :param until: optional: end of set period
+        :return:
+        """
+        cmd = Command.set_system_mode(self.id, system_mode, until=until)
+        return self._gwy.send_cmd(cmd, priority=Priority.HIGH, wait_for_reply=True)
 
-    def set_auto(self) -> Future:
+    def set_auto(self) -> asyncio.Task[Packet]:
         """Revert system to Auto, set non-PermanentOverride zones to FollowSchedule."""
         return self.set_mode(SYS_MODE_MAP.AUTO)
 
-    def reset_mode(self) -> Future:
+    def reset_mode(self) -> asyncio.Task[Packet]:
         """Revert system to Auto, force *all* zones to FollowSchedule."""
         return self.set_mode(SYS_MODE_MAP.AUTO_WITH_RESET)
 
@@ -954,26 +902,33 @@ class Datetime(SystemBase):  # 313F
     def _setup_discovery_cmds(self) -> None:
         super()._setup_discovery_cmds()
 
-        self._add_discovery_cmd(Command.get_system_time(self.id), 60 * 60, delay=0)
+        cmd = Command.get_system_time(self.id)
+        self._add_discovery_cmd(cmd, 60 * 60, delay=0)
 
     def _handle_msg(self, msg: Message) -> None:
         super()._handle_msg(msg)
 
-        if msg.code == Code._313F and msg.verb in (I_, RP) and self._gwy.pkt_transport:
+        # FIXME: refactoring protocol stack
+        if msg.code == Code._313F and msg.verb in (I_, RP) and self._gwy._transport:
             diff = abs(dt.fromisoformat(msg.payload[SZ_DATETIME]) - self._gwy._dt_now())
             if diff > td(minutes=5):
                 _LOGGER.warning(f"{msg!r} < excessive datetime difference: {diff}")
 
-    async def get_datetime(self) -> Optional[dt]:
-        msg = await self._gwy.async_send_cmd(Command.get_system_time(self.id))
+    async def get_datetime(self) -> dt | None:
+        cmd = Command.get_system_time(self.id)
+        pkt = await self._gwy.async_send_cmd(cmd, wait_for_reply=True)
+        msg = Message._from_pkt(pkt)
         return dt.fromisoformat(msg.payload[SZ_DATETIME])
 
-    async def set_datetime(self, dtm: dt) -> Optional[Message]:
-        return await self._gwy.async_send_cmd(Command.set_system_time(self.id, dtm))
+    async def set_datetime(self, dtm: dt) -> Packet:
+        """Set the date and time of the system."""
+
+        cmd = Command.set_system_time(self.id, dtm)
+        return await self._gwy.async_send_cmd(cmd, priority=Priority.HIGH)
 
 
 class UfHeating(SystemBase):
-    def _ufh_ctls(self):
+    def _ufh_ctls(self) -> list[UfhController]:
         return sorted([d for d in self.childs if isinstance(d, UfhController)])
 
     @property
@@ -999,21 +954,59 @@ class UfHeating(SystemBase):
 
 
 class System(StoredHw, Datetime, Logbook, SystemBase):
-    """The Controller class."""
+    """The Temperature Control System class."""
 
-    _SLUG: str = SYS_KLASS.PRG
+    _SLUG: str = SYS_KLASS.SYS
 
-    def __init__(self, ctl, **kwargs) -> None:
+    def __init__(self, ctl: Controller, **kwargs: Any) -> None:
         super().__init__(ctl, **kwargs)
 
         self._heat_demands: dict[str, Any] = {}
         self._relay_demands: dict[str, Any] = {}
         self._relay_failsafes: dict[str, Any] = {}
 
+    def _update_schema(self, **schema: Any) -> None:
+        """Update a CH/DHW system with new schema attrs.
+
+        Raise an exception if the new schema is not a superset of the existing schema.
+        """
+
+        _schema: dict[str, Any]
+        schema = shrink(SCH_TCS(schema))
+
+        if schema.get(SZ_SYSTEM) and (
+            dev_id := schema[SZ_SYSTEM].get(SZ_APPLIANCE_CONTROL)
+        ):
+            self._app_cntrl = self._gwy.get_device(dev_id, parent=self, child_id=FC)  # type: ignore[assignment]
+
+        if _schema := (schema.get(SZ_DHW_SYSTEM)):  # type: ignore[assignment]
+            self.get_dhw_zone(**_schema)  # self._dhw = ...
+
+        if not isinstance(self, MultiZone):
+            return
+
+        if _schema := (schema.get(SZ_ZONES)):  # type: ignore[assignment]
+            [self.get_htg_zone(idx, **s) for idx, s in _schema.items()]
+
+    @classmethod
+    def create_from_schema(cls, ctl: Controller, **schema: Any) -> System:
+        """Create a CH/DHW system for a CTL and set its schema attrs.
+
+        The appropriate System class should have been determined by a factory.
+        Schema attrs include: class (klass) & others.
+        """
+
+        tcs = cls(ctl)
+        tcs._update_schema(**schema)
+        return tcs
+
     def _handle_msg(self, msg: Message) -> None:
         super()._handle_msg(msg)
 
-        if SZ_DOMAIN_ID in msg.payload:
+        if not isinstance(msg.payload, dict):
+            return
+
+        if (idx := msg.payload.get(SZ_DOMAIN_ID)) and msg.verb in (I_, RP):
             idx = msg.payload[SZ_DOMAIN_ID]
             if msg.code == Code._0008:
                 self._relay_demands[idx] = msg
@@ -1032,24 +1025,24 @@ class System(StoredHw, Datetime, Logbook, SystemBase):
                 assert False, f"Unexpected code with a domain_id: {msg.code}"
 
     @property
-    def heat_demands(self) -> Optional[dict]:  # 3150
+    def heat_demands(self) -> dict[str, Any] | None:  # 3150
         # FC: 00-C8 (no F9, FA), TODO: deprecate as FC only?
         if not self._heat_demands:
             return None
         return {k: v.payload["heat_demand"] for k, v in self._heat_demands.items()}
 
     @property
-    def relay_demands(self) -> Optional[dict]:  # 0008
+    def relay_demands(self) -> dict[str, Any] | None:  # 0008
         # FC: 00-C8, F9: 00-C8, FA: 00 or C8 only (01: all 3, 02: FC/FA only)
         if not self._relay_demands:
             return None
         return {k: v.payload["relay_demand"] for k, v in self._relay_demands.items()}
 
     @property
-    def relay_failsafes(self) -> Optional[dict]:  # 0009
+    def relay_failsafes(self) -> dict[str, Any] | None:  # 0009
         if not self._relay_failsafes:
             return None
-        return {}  # TODO: failsafe_enabled
+        return {}  # FIXME: failsafe_enabled
 
     @property
     def status(self) -> dict[str, Any]:
@@ -1066,28 +1059,25 @@ class System(StoredHw, Datetime, Logbook, SystemBase):
 
 
 class Evohome(ScheduleSync, Language, SysMode, MultiZone, UfHeating, System):
-    """The Evohome system - some controllers are evohome-compatible."""
+    _SLUG: str = SYS_KLASS.TCS  # evohome
 
     # older evohome don't have zone_type=ELE
 
-    _SLUG: str = SYS_KLASS.TCS
-
 
 class Chronotherm(Evohome):
-
     _SLUG: str = SYS_KLASS.SYS
 
 
 class Hometronics(System):
+    _SLUG: str = SYS_KLASS.SYS
+
     # These are only ever been seen from a Hometronics controller
     # .I --- 01:023389 --:------ 01:023389 2D49 003 00C800
     # .I --- 01:023389 --:------ 01:023389 2D49 003 01C800
     # .I --- 01:023389 --:------ 01:023389 2D49 003 880000
     # .I --- 01:023389 --:------ 01:023389 2D49 003 FD0000
 
-    # Hometronic does not react to W/2349 but rather requies W/2309
-
-    _SLUG: str = SYS_KLASS.SYS
+    # Hometronic does not react to W/2349 but rather requires W/2309
 
     #
     # def _setup_discovery_cmds(self) -> None:
@@ -1101,39 +1091,42 @@ class Hometronics(System):
 
 
 class Programmer(Evohome):
-
     _SLUG: str = SYS_KLASS.PRG
 
 
 class Sundial(Evohome):
-
     _SLUG: str = SYS_KLASS.SYS
 
 
-SYS_CLASS_BY_SLUG = class_by_attr(__name__, "_SLUG")  # e.g. "evohome": Evohome
+# e.g. {"evohome": Evohome}
+SYS_CLASS_BY_SLUG: dict[str, type[System]] = class_by_attr(__name__, "_SLUG")
 
 
-def system_factory(ctl, *, msg: Message = None, **schema) -> _SystemT:
+def system_factory(
+    ctl: Controller, *, msg: Message | None = None, **schema: Any
+) -> System:
     """Return the system class for a given controller/schema (defaults to evohome)."""
 
     def best_tcs_class(
         ctl_addr: Address,
         *,
-        msg: Message = None,
+        msg: Message | None = None,
         eavesdrop: bool = False,
-        **schema,
-    ) -> type[_SystemT]:
+        **schema: Any,
+    ) -> type[System]:
         """Return the system class for a given CTL/schema (defaults to evohome)."""
 
-        # a specified system class always takes precidence (even if it is wrong)...
-        if cls := SYS_CLASS_BY_SLUG.get(schema.get(SZ_CLASS)):
+        klass: str = schema.get(SZ_CLASS)  # type: ignore[assignment]
+
+        # a specified system class always takes precedence (even if it is wrong)...
+        if klass and (cls := SYS_CLASS_BY_SLUG.get(klass)):
             _LOGGER.debug(
                 f"Using an explicitly-defined system class for: {ctl_addr} ({cls._SLUG})"
             )
             return cls
 
         # otherwise, use the default system class...
-        _LOGGER.debug(f"Using a generic system class for: {ctl_addr} ({Evohome._SLUG})")
+        _LOGGER.debug(f"Using a generic system class for: {ctl_addr} ({Device._SLUG})")
         return Evohome
 
     return best_tcs_class(