ramses-rf 0.22.40__py3-none-any.whl → 0.51.2__py3-none-any.whl

ramses_rf/entity_base.py

@@ -1,127 +1,276 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-"""RAMSES RF - a RAMSES-II protocol decoder & analyser.
+"""RAMSES RF - Base class for all RAMSES-II objects: devices and constructs."""
 
-Entity is the base of all RAMSES-II objects: devices and also system/zone constructs.
-"""
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import logging
 import random
-from asyncio import Future
-from datetime import datetime as dt
-from datetime import timedelta as td
+from collections.abc import Iterable
+from datetime import datetime as dt, timedelta as td
 from inspect import getmembers, isclass
 from sys import modules
-from typing import TYPE_CHECKING, Any
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Final
+
+from ramses_rf.helpers import schedule_task
+from ramses_tx import Priority, QosParams
+from ramses_tx.address import ALL_DEVICE_ID
+from ramses_tx.const import MsgId
+from ramses_tx.opentherm import OPENTHERM_MESSAGES
+from ramses_tx.ramses import CODES_SCHEMA
 
+from . import exceptions as exc
 from .const import (
     DEV_TYPE_MAP,
     SZ_ACTUATORS,
-    SZ_DEVICE_ID,
     SZ_DOMAIN_ID,
     SZ_NAME,
     SZ_SENSOR,
-    SZ_UFH_IDX,
     SZ_ZONE_IDX,
-    __dev_mode__,
 )
-from .protocol import CorruptStateError
-from .protocol.frame import _CodeT, _DeviceIdT, _HeaderT, _VerbT
-from .protocol.opentherm import OPENTHERM_MESSAGES
-from .protocol.ramses import CODES_SCHEMA
-from .protocol.transport import PacketProtocolPort
 from .schemas import SZ_CIRCUITS
 
-# skipcq: PY-W2000
 from .const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     I_,
     RP,
     RQ,
     W_,
+    Code,
+    VerbT,
+)
+
+from .const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     F9,
     FA,
     FC,
     FF,
-    Code,
 )
 
 if TYPE_CHECKING:
-    from .protocol import Command, Message, Packet
+    from ramses_tx import Command, Message, Packet, VerbT
+    from ramses_tx.frame import HeaderT
+    from ramses_tx.opentherm import OtDataId
+    from ramses_tx.schemas import DeviceIdT, DevIndexT
+
+    from .device import (
+        BdrSwitch,
+        Controller,
+        DhwSensor,
+        OtbGateway,
+        TrvActuator,
+        UfhCircuit,
+    )
+    from .gateway import Gateway
+    from .system import Evohome
 
 
 _QOS_TX_LIMIT = 12  # TODO: needs work
 
-DEV_MODE = __dev_mode__ and False
+_SZ_LAST_PKT: Final = "last_msg"
+_SZ_NEXT_DUE: Final = "next_due"
+_SZ_TIMEOUT: Final = "timeout"
+_SZ_FAILURES: Final = "failures"
+_SZ_INTERVAL: Final = "interval"
+_SZ_COMMAND: Final = "command"
 
-# USE_JMESPATH = False
+#
+# NOTE: All debug flags should be False for deployment to end-users
+_DBG_ENABLE_DISCOVERY_BACKOFF: Final[bool] = False
 
 _LOGGER = logging.getLogger(__name__)
-if DEV_MODE:
-    _LOGGER.setLevel(logging.DEBUG)
 
 
-def class_by_attr(name: str, attr: str) -> dict:  # TODO: change to __module__
-    """Return a mapping of a (unique) attr of classes in a module to that class.
+def class_by_attr(name: str, attr: str) -> dict[str, Any]:  # TODO: change to __module__
+    """Return a mapping of a (unique) attr of classes in a module to that class."""
+
+    def predicate(m: ModuleType) -> bool:
+        return isclass(m) and m.__module__ == name and getattr(m, attr, None)
+
+    return {getattr(c[1], attr): c[1] for c in getmembers(modules[name], predicate)}
+
+
+class _Entity:
+    """The ultimate base class for Devices/Zones/Systems.
 
-    For example:
-      {DEV_TYPE.OTB: OtbGateway, DEV_TYPE.CTL: Controller}
-      {ZON_ROLE.RAD: RadZone,    ZON_ROLE.UFH: UfhZone}
-      {"evohome": Evohome}
+    This class is mainly concerned with:
+     - if the entity can Rx packets (e.g. can the HGI send it an RQ)
     """
 
-    return {
-        getattr(c[1], attr): c[1]
-        for c in getmembers(
-            modules[name],
-            lambda m: isclass(m) and m.__module__ == name and getattr(m, attr, None),  # type: ignore[arg-type, return-value]
+    _SLUG: str = None  # type: ignore[assignment]
+
+    def __init__(self, gwy: Gateway) -> None:
+        self._gwy = gwy
+        self.id: DeviceIdT = None  # type: ignore[assignment]
+
+        self._qos_tx_count = 0  # the number of pkts Tx'd with no matching Rx
+
+    def __repr__(self) -> str:
+        return f"{self.id} ({self._SLUG})"
+
+    # TODO: should be a private method
+    def deprecate_device(self, pkt: Packet, reset: bool = False) -> None:
+        """If an entity is deprecated enough times, stop sending to it."""
+
+        if reset:
+            self._qos_tx_count = 0
+            return
+
+        self._qos_tx_count += 1
+        if self._qos_tx_count == _QOS_TX_LIMIT:
+            _LOGGER.warning(
+                f"{pkt} < Sending now deprecated for {self} "
+                "(consider adjusting device_id filters)"
+            )  # TODO: take whitelist into account
+
+    def _handle_msg(self, msg: Message) -> None:  # TODO: beware, this is a mess
+        """Store a msg in _msgs[code] (only latest I/RP) and _msgz[code][verb][ctx]."""
+
+        raise NotImplementedError
+
+        # super()._handle_msg(msg)  # store the message in the database
+
+        # if self._gwy.hgi and msg.src.id != self._gwy.hgi.id:
+        #     self.deprecate_device(msg._pkt, reset=True)
+
+    # FIXME: this is a mess - to deprecate for async version?
+    def _send_cmd(self, cmd: Command, **kwargs: Any) -> asyncio.Task | None:
+        """Send a Command & return the corresponding Task."""
+
+        # Don't poll this device if it is not responding
+        if self._qos_tx_count > _QOS_TX_LIMIT:
+            _LOGGER.info(f"{cmd} < Sending was deprecated for {self}")
+            return None  # TODO: raise Exception (should be handled before now)
+
+        if [  # TODO: remove this
+            k for k in kwargs if k not in ("priority", "num_repeats")
+        ]:  # FIXME: deprecate QoS in kwargs, should be qos=QosParams(...)
+            raise RuntimeError("Deprecated kwargs: %s", kwargs)
+
+        # cmd._source_entity = self  # TODO: is needed?
+        # _msgs.pop(cmd.code, None)  # NOTE: Cause of DHW bug
+        return self._gwy.send_cmd(cmd, wait_for_reply=False, **kwargs)
+
+    # FIXME: this is a mess
+    async def _async_send_cmd(
+        self,
+        cmd: Command,
+        priority: Priority | None = None,
+        qos: QosParams | None = None,  # FIXME: deprecate QoS in kwargs?
+    ) -> Packet | None:
+        """Send a Command & return the response Packet, or the echo Packet otherwise."""
+
+        # Don't poll this device if it is not responding
+        if self._qos_tx_count > _QOS_TX_LIMIT:
+            _LOGGER.warning(f"{cmd} < Sending was deprecated for {self}")
+            return None  # FIXME: raise Exception (should be handled before now)
+
+        # cmd._source_entity = self  # TODO: is needed?
+        return await self._gwy.async_send_cmd(
+            cmd,
+            max_retries=qos.max_retries if qos else None,
+            priority=priority,
+            timeout=qos.timeout if qos else None,
+            wait_for_reply=qos.wait_for_reply if qos else None,
         )
-    }
 
 
-class MessageDB:
+class _MessageDB(_Entity):
     """Maintain/utilize an entity's state database."""
 
-    _gwy: Any  # HACK
-    ctl: Any  # HACK
-    tcs: Any  # HACK
+    _gwy: Gateway
+    ctl: Controller
+    tcs: Evohome
+
+    # These attr used must be in this class, and the Entity base class
+    _z_id: DeviceIdT
+    _z_idx: DevIndexT | None  # e.g. 03, HW, is None for CTL, TCS
+
+    def __init__(self, gwy: Gateway) -> None:
+        super().__init__(gwy)
 
-    def __init__(self, gwy) -> None:
-        self._msgs: dict[_CodeT, Message] = {}  # code, should be code/ctx? ?deprecate
-        self._msgz: dict[_CodeT, Any] = {}  # code/verb/ctx, should be code/ctx/verb?
+        self._msgs_: dict[Code, Message] = {}  # code, should be code/ctx? ?deprecate
+        self._msgz_: dict[
+            Code, dict[VerbT, dict[bool | str | None, Message]]
+        ] = {}  # code/verb/ctx, should be code/ctx/verb?
 
     def _handle_msg(self, msg: Message) -> None:  # TODO: beware, this is a mess
-        """Store a msg in _msgs[code] (only latest I/RP) and _msgz[code][verb][ctx]."""
+        """Store a msg in the DBs."""
 
-        if msg.verb in (I_, RP):
-            self._msgs[msg.code] = msg
+        if not (
+            msg.src.id == self.id[:9]
+            or (msg.dst.id == self.id[:9] and msg.verb != RQ)
+            or (msg.dst.id == ALL_DEVICE_ID and msg.code == Code._1FC9)
+        ):
+            return  # ZZZ: don't store these
 
-        if msg.code not in self._msgz:
-            self._msgz[msg.code] = {msg.verb: {msg._pkt._ctx: msg}}
-        elif msg.verb not in self._msgz[msg.code]:
-            self._msgz[msg.code][msg.verb] = {msg._pkt._ctx: msg}
-        else:
-            self._msgz[msg.code][msg.verb][msg._pkt._ctx] = msg
+        if msg.verb in (I_, RP):
+            self._msgs_[msg.code] = msg
+
+        if msg.code not in self._msgz_:
+            self._msgz_[msg.code] = {msg.verb: {msg._pkt._ctx: msg}}
+        elif msg.verb not in self._msgz_[msg.code]:
+            self._msgz_[msg.code][msg.verb] = {msg._pkt._ctx: msg}
+        else:  # if not self._gwy._zzz:
+            self._msgz_[msg.code][msg.verb][msg._pkt._ctx] = msg
+        # elif (
+        #     self._msgz[msg.code][msg.verb][msg._pkt._ctx] is not msg
+        # ):  # MsgIdx ensures this
+        #     assert False  # TODO: remove
 
     @property
-    def _msg_db(self) -> list:  # a flattened version of _msgz[code][verb][indx]
+    def _msg_db(self) -> list[Message]:  # flattened version of _msgz[code][verb][indx]
         """Return a flattened version of _msgz[code][verb][index].
 
         The idx is one of:
          - a simple index (e.g. zone_idx, domain_id, aka child_id)
-         - a compund ctx (e.g. 0005/000C/0418)
+         - a compound ctx (e.g. 0005/000C/0418)
          - True (an array of elements, each with its own idx),
          - False (no idx, is usu. 00),
          - None (not deteminable, rare)
         """
         return [m for c in self._msgz.values() for v in c.values() for m in v.values()]
 
-    def _get_msg_by_hdr(self, hdr: _HeaderT) -> None | Message:
+    def _delete_msg(self, msg: Message) -> None:  # FIXME: this is a mess
+        """Remove the msg from all state databases."""
+
+        from .device import Device
+
+        obj: _MessageDB
+
+        if self._gwy._zzz:
+            self._gwy._zzz.rem(msg)
+
+        entities: list[_MessageDB] = []
+        if isinstance(msg.src, Device):
+            entities = [msg.src]
+            if getattr(msg.src, "tcs", None):
+                entities.append(msg.src.tcs)
+                if msg.src.tcs.dhw:
+                    entities.append(msg.src.tcs.dhw)
+                entities.extend(msg.src.tcs.zones)
+
+        # remove the msg from all the state DBs
+        for obj in entities:
+            if msg in obj._msgs_.values():
+                del obj._msgs_[msg.code]
+            with contextlib.suppress(KeyError):
+                del obj._msgz_[msg.code][msg.verb][msg._pkt._ctx]
+
+    def _get_msg_by_hdr(self, hdr: HeaderT) -> Message | None:
         """Return a msg, if any, that matches a header."""
 
-        code, verb, _, *args = hdr.split("|")  # _ is device_id
+        # if self._gwy._zzz:
+        #     msgs = self._gwy._zzz.get(hdr=hdr)
+        #     return msgs[0] if msgs else None
+
+        msg: Message
+        code: Code
+        verb: VerbT
+
+        # _ is device_id
+        code, verb, _, *args = hdr.split("|")  # type: ignore[assignment]
 
         try:
             if args and (ctx := args[0]):  # ctx may == True
@@ -140,26 +289,29 @@ class MessageDB:
 
         return msg
 
-    def _msg_flag(self, code: _CodeT, key, idx) -> None | bool:
-
+    def _msg_flag(self, code: Code, key: str, idx: int) -> bool | None:
         if flags := self._msg_value(code, key=key):
             return bool(flags[idx])
         return None
 
-    def _msg_value(self, code: _CodeT, *args, **kwargs):
-
-        if isinstance(code, (str, tuple)):  # a code or a tuple of codes
+    def _msg_value(
+        self, code: Code | Iterable[Code], *args: Any, **kwargs: Any
+    ) -> dict | list | None:
+        if isinstance(code, str | tuple):  # a code or a tuple of codes
             return self._msg_value_code(code, *args, **kwargs)
         # raise RuntimeError
         return self._msg_value_msg(code, *args, **kwargs)  # assume is a Message
 
     def _msg_value_code(
-        self, code: _CodeT, verb: _VerbT = None, key=None, **kwargs
-    ) -> None | dict | list:
-
-        assert (
-            not isinstance(code, tuple) or verb is None
-        ), f"Unsupported: using a tuple ({code}) with a verb ({verb})"
+        self,
+        code: Code,
+        verb: VerbT | None = None,
+        key: str | None = None,
+        **kwargs: Any,
+    ) -> dict | list | None:
+        assert not isinstance(code, tuple) or verb is None, (
+            f"Unsupported: using a tuple ({code}) with a verb ({verb})"
+        )
 
         if verb:
             try:
@@ -170,26 +322,32 @@ class MessageDB:
                 msg = max(msgs.values()) if msgs else None
         elif isinstance(code, tuple):
             msgs = [m for m in self._msgs.values() if m.code in code]
-            msg = max(msgs) if msgs else None
+            msg = (
+                max(msgs) if msgs else None
+            )  # return highest value found in code:value pairs
         else:
             msg = self._msgs.get(code)
 
         return self._msg_value_msg(msg, key=key, **kwargs)
 
     def _msg_value_msg(
-        self, msg: None | Message, key=None, zone_idx: str = None, domain_id: str = None
-    ) -> None | dict | list:
-
+        self,
+        msg: Message | None,
+        key: str | None = None,
+        zone_idx: str | None = None,
+        domain_id: str | None = None,
+    ) -> dict | list | None:
         if msg is None:
             return None
         elif msg._expired:
-            self._gwy._loop.call_soon(_delete_msg, msg)  # HA bugs without deferred call
+            self._gwy._loop.call_soon(self._delete_msg, msg)  # HA bugs without defer
 
         if msg.code == Code._1FC9:  # NOTE: list of lists/tuples
             return [x[1] for x in msg.payload]
 
-        idx: None | str = None
-        val: None | str = None
+        idx: str | None = None
+        val: str | None = None
+
         if domain_id:
             idx, val = SZ_DOMAIN_ID, domain_id
         elif zone_idx:
@@ -207,9 +365,9 @@ class MessageDB:
             # .I 101 --:------ --:------ 12:126457 2309 006 0107D0-0207D0  # is a CTL
             msg_dict = msg.payload[0]
 
-        assert (
-            not domain_id and not zone_idx or msg_dict.get(idx) == val
-        ), f"{msg_dict} < Coding error: key={idx}, val={val}"
+        assert (not domain_id and not zone_idx) or (msg_dict.get(idx) == val), (
+            f"{msg_dict} < Coding error: key={idx}, val={val}"
+        )
 
         if key:
             return msg_dict.get(key)
@@ -219,30 +377,68 @@ class MessageDB:
             if k not in ("dhw_idx", SZ_DOMAIN_ID, SZ_ZONE_IDX) and k[:1] != "_"
         }
 
+    @property
+    def traits(self) -> dict:
+        """Return the codes seen by the entity."""
+
+        codes = {
+            k: (CODES_SCHEMA[k][SZ_NAME] if k in CODES_SCHEMA else None)
+            for k in sorted(self._msgs)
+            if self._msgs[k].src is (self if hasattr(self, "addr") else self.ctl)
+        }
+
+        return {"_sent": list(codes.keys())}
+
+    @property
+    def _msgs(self) -> dict[Code, Message]:
+        if not self._gwy._zzz:
+            return self._msgs_
+
+        sql = """
+            SELECT dtm from messages WHERE verb in (' I', 'RP') AND (src = ? OR dst = ?)
+        """
+        return {  # ? use context instead?
+            m.code: m for m in self._gwy._zzz.qry(sql, (self.id[:9], self.id[:9]))
+        }  # e.g. 01:123456_HW
+
+    @property
+    def _msgz(self) -> dict[Code, dict[VerbT, dict[bool | str | None, Message]]]:
+        if not self._gwy._zzz:
+            return self._msgz_
+
+        msgs_1: dict[Code, dict[VerbT, dict[bool | str | None, Message]]] = {}
+        msg: Message
+
+        for msg in self._msgs.values():
+            if msg.code not in msgs_1:
+                msgs_1[msg.code] = {msg.verb: {msg._pkt._ctx: msg}}
+            elif msg.verb not in msgs_1[msg.code]:
+                msgs_1[msg.code][msg.verb] = {msg._pkt._ctx: msg}
+            else:
+                msgs_1[msg.code][msg.verb][msg._pkt._ctx] = msg
 
-class Discovery(MessageDB):
+        return msgs_1
+
+
+class _Discovery(_MessageDB):
     MAX_CYCLE_SECS = 30
     MIN_CYCLE_SECS = 3
 
-    def __init__(self, gwy, *args, **kwargs) -> None:
-        super().__init__(gwy, *args, **kwargs)
+    def __init__(self, gwy: Gateway) -> None:
+        super().__init__(gwy)
 
-        self._discovery_cmds: dict[_HeaderT, dict] = None  # type: ignore[assignment]
-        self._discovery_poller = None
+        self._discovery_cmds: dict[HeaderT, dict] = None  # type: ignore[assignment]
+        self._discovery_poller: asyncio.Task | None = None
 
-        self._supported_cmds: dict[str, None | bool] = {}
-        self._supported_cmds_ctx: dict[str, None | bool] = {}
+        self._supported_cmds: dict[str, bool | None] = {}
+        self._supported_cmds_ctx: dict[str, bool | None] = {}
 
-        if not gwy.config.disable_discovery and isinstance(
-            gwy.pkt_protocol, PacketProtocolPort
-        ):  # TODO: here, or in get_xxx()?
-            # gwy._loop.call_soon_threadsafe(
-            #     gwy._loop.call_later, random(0.5, 1.5), self.start_discovery_poller
-            # )
+        if not gwy.config.disable_discovery:
+            # self._start_discovery_poller()  # Can't use derived classes dont exist yet
             gwy._loop.call_soon(self._start_discovery_poller)
 
     @property  # TODO: needs tidy up
-    def discovery_cmds(self) -> dict:
+    def discovery_cmds(self) -> dict[HeaderT, dict]:
         """Return the pollable commands."""
         if self._discovery_cmds is None:
             self._discovery_cmds = {}
@@ -250,29 +446,39 @@ class Discovery(MessageDB):
         return self._discovery_cmds
 
     @property
-    def supported_cmds(self) -> dict:
+    def supported_cmds(self) -> dict[Code, Any]:
         """Return the current list of pollable command codes."""
         return {
             code: (CODES_SCHEMA[code][SZ_NAME] if code in CODES_SCHEMA else None)
             for code in sorted(self._msgz)
-            if self._msgz[code].get(RP) and self.is_pollable_cmd(code)
+            if self._msgz[code].get(RP) and self._is_not_deprecated_cmd(code)
         }
 
     @property
-    def supported_cmds_ot(self) -> dict:
+    def supported_cmds_ot(self) -> dict[MsgId, Any]:
         """Return the current list of pollable OT msg_ids."""
+
+        def _to_data_id(msg_id: MsgId | str) -> OtDataId:
+            return int(msg_id, 16)  # type: ignore[return-value]
+
+        def _to_msg_id(data_id: OtDataId | int) -> MsgId:
+            return f"{data_id:02X}"  # type: ignore[return-value]
+
         return {
-            msg_id: OPENTHERM_MESSAGES[int(msg_id, 16)].get("var")
-            for msg_id in sorted(self._msgz[Code._3220].get(RP, []))
-            if self.is_pollable_cmd(Code._3220, ctx=msg_id)
+            f"0x{msg_id}": OPENTHERM_MESSAGES[_to_data_id(msg_id)].get("en")  # type: ignore[misc]
+            for msg_id in sorted(self._msgz[Code._3220].get(RP, []))  # type: ignore[type-var]
+            if (
+                self._is_not_deprecated_cmd(Code._3220, ctx=msg_id)
+                and _to_data_id(msg_id) in OPENTHERM_MESSAGES
+            )
         }
 
-    def is_pollable_cmd(self, code, ctx=None) -> bool:
+    def _is_not_deprecated_cmd(self, code: Code, ctx: str | None = None) -> bool:
         """Return True if the code|ctx pair is not deprecated."""
 
         if ctx is None:
             supported_cmds = self._supported_cmds
-            idx = code
+            idx = str(code)
         else:
             supported_cmds = self._supported_cmds_ctx
             idx = f"{code}|{ctx}"
@@ -283,15 +489,18 @@ class Discovery(MessageDB):
         raise NotImplementedError
 
     def _add_discovery_cmd(
-        self, cmd: Command, interval, *, timeout: float = None, delay: float = 0
+        self,
+        cmd: Command,
+        interval: float,
+        *,
+        delay: float = 0,
+        timeout: float | None = None,
     ) -> None:
         """Schedule a command to run periodically.
 
         Both `timeout` and `delay` are in seconds.
         """
 
-        cmd._qos.retry_limit = 0  # disable QoS for these: equivalent functionality here
-
         if cmd.rx_header is None:  # TODO: raise TypeError
             _LOGGER.warning(f"cmd({cmd}): invalid (null) header not added to discovery")
             return
@@ -302,32 +511,34 @@ class Discovery(MessageDB):
 
         if delay:
             delay += random.uniform(0.05, 0.45)
-        timeout = (
-            timeout or (cmd._qos.retry_limit + 1) * cmd._qos.rx_timeout.total_seconds()
-        )
 
         self.discovery_cmds[cmd.rx_header] = {
-            "command": cmd,
-            "interval": td(seconds=max(interval, self.MAX_CYCLE_SECS)),
-            "last_msg": None,
-            "next_due": dt.now() + td(seconds=delay),
-            "timeout": timeout,
-            "failures": 0,
+            _SZ_COMMAND: cmd,
+            _SZ_INTERVAL: td(seconds=max(interval, self.MAX_CYCLE_SECS)),
+            _SZ_LAST_PKT: None,
+            _SZ_NEXT_DUE: dt.now() + td(seconds=delay),
+            _SZ_TIMEOUT: timeout,
+            _SZ_FAILURES: 0,
         }
 
     def _start_discovery_poller(self) -> None:
-        if not self._discovery_poller or self._discovery_poller.done():
-            self._discovery_poller = self._gwy.add_task(self._poll_discovery_cmds)
-            self._discovery_poller.set_name(f"{self.id}_discovery_poller")
-            pass
+        """Start the discovery poller (if it is not already running)."""
 
-    async def _stop_discovery_poller(self) -> None:
         if self._discovery_poller and not self._discovery_poller.done():
-            self._discovery_poller.cancel()
-            try:
-                await self._discovery_poller
-            except asyncio.CancelledError:
-                pass
+            return
+
+        self._discovery_poller = schedule_task(self._poll_discovery_cmds)
+        self._discovery_poller.set_name(f"{self.id}_discovery_poller")
+        self._gwy.add_task(self._discovery_poller)
+
+    async def _stop_discovery_poller(self) -> None:
+        """Stop the discovery poller (only if it is running)."""
+        if not self._discovery_poller or self._discovery_poller.done():
+            return
+
+        self._discovery_poller.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await self._discovery_poller
 
     async def _poll_discovery_cmds(self) -> None:
         """Send any outstanding commands that are past due.
@@ -337,14 +548,10 @@ class Discovery(MessageDB):
         """
 
         while True:
-            if self._gwy.config.disable_discovery:  # TODO: remove?
-                await asyncio.sleep(self.MIN_CYCLE_SECS)
-                continue
-
             await self.discover()
 
             if self.discovery_cmds:
-                next_due = min(t["next_due"] for t in self.discovery_cmds.values())
+                next_due = min(t[_SZ_NEXT_DUE] for t in self.discovery_cmds.values())
                 delay = max((next_due - dt.now()).total_seconds(), self.MIN_CYCLE_SECS)
             else:
                 delay = self.MAX_CYCLE_SECS
@@ -352,7 +559,7 @@ class Discovery(MessageDB):
             await asyncio.sleep(min(delay, self.MAX_CYCLE_SECS))
 
     async def discover(self) -> None:
-        def find_latest_msg(hdr: _HeaderT, task: dict) -> None | Message:
+        def find_latest_msg(hdr: HeaderT, task: dict) -> Message | None:
             """Return the latest message for a header from any source (not just RPs)."""
             msgs: list[Message] = [
                 m
@@ -361,48 +568,60 @@ class Discovery(MessageDB):
             ]
 
             try:
-                if task["command"].code in (Code._000A, Code._30C9):
-                    msgs += [self.tcs._msgz[task["command"].code][I_][True]]
+                if task[_SZ_COMMAND].code in (Code._000A, Code._30C9):
+                    msgs += [self.tcs._msgz[task[_SZ_COMMAND].code][I_][True]]
             except KeyError:
                 pass
 
-            return (msgs and max(msgs)) or None
+            return max(msgs) if msgs else None
 
-        def backoff(hdr: _HeaderT, failures: int) -> td:
+        def backoff(hdr: HeaderT, failures: int) -> td:
             """Backoff the interval if there are/were any failures."""
 
+            if not _DBG_ENABLE_DISCOVERY_BACKOFF:  # FIXME: data gaps
+                return self.discovery_cmds[hdr][_SZ_INTERVAL]  # type: ignore[no-any-return]
+
             if failures > 5:
                 secs = 60 * 60 * 6
-                _LOGGER.warning(f"No response for task({hdr}): throttling to 1/6h")
+                _LOGGER.error(
+                    f"No response for {hdr} ({failures}/5): throttling to 1/6h"
+                )
             elif failures > 2:
-                _LOGGER.debug(f"No response for task({hdr}): retrying in 30s")
+                _LOGGER.warning(
+                    f"No response for {hdr} ({failures}/5): retrying in {self.MAX_CYCLE_SECS}s"
+                )
                 secs = self.MAX_CYCLE_SECS
             else:
-                # _LOGGER.info(f"No response for task({hdr}): retrying in 3s")
+                _LOGGER.info(
+                    f"No response for {hdr} ({failures}/5): retrying in {self.MIN_CYCLE_SECS}s"
+                )
                 secs = self.MIN_CYCLE_SECS
 
             return td(seconds=secs)
 
-        async def send_disc_task(hdr: _HeaderT, task: dict) -> None | Message:
-            """Send a scheduled command and wait for/return the reponse."""
+        async def send_disc_cmd(
+            hdr: HeaderT, task: dict, timeout: float = 15
+        ) -> Packet | None:  # TODO: use constant instead of 15
+            """Send a scheduled command and wait for/return the response."""
 
             try:
-                result = await asyncio.wait_for(
-                    self._gwy.async_send_cmd(task["command"]),
-                    timeout=60,  # self.MAX_CYCLE_SECS?
+                pkt: Packet | None = await asyncio.wait_for(
+                    self._gwy.async_send_cmd(task[_SZ_COMMAND]),
+                    timeout=timeout,  # self.MAX_CYCLE_SECS?
                 )
 
-            except asyncio.TimeoutError as exc:  # safety valve timeout
-                _LOGGER.debug(f"{hdr}: {exc} (0x5A)")
+            # TODO: except: handle no QoS
 
-            except TimeoutError as exc:  # TODO: deprecate non-responsive code/device
-                _LOGGER.debug(f"{hdr}: {exc} (0x5B)")
+            except exc.ProtocolError as err:  # InvalidStateError, SendTimeoutError
+                _LOGGER.warning(f"{self}: Failed to send discovery cmd: {hdr}: {err}")
 
-            except Exception as exc:
-                _LOGGER.error(exc)
+            except TimeoutError as err:  # safety valve timeout
+                _LOGGER.warning(
+                    f"{self}: Failed to send discovery cmd: {hdr} within {timeout} secs: {err}"
+                )
 
             else:
-                return result
+                return pkt
 
             return None
 
@@ -410,53 +629,55 @@ class Discovery(MessageDB):
             dt_now = dt.now()
 
             if (msg := find_latest_msg(hdr, task)) and (
-                task["next_due"] < msg.dtm + task["interval"]
+                task[_SZ_NEXT_DUE] < msg.dtm + task[_SZ_INTERVAL]
             ):  # if a newer message is available, take it
-                task["failures"] = 0  # only if task["last_msg"].verb == RP?
-                task["last_msg"] = msg
-                task["next_due"] = msg.dtm + task["interval"]
+                task[_SZ_FAILURES] = 0  # only if task[_SZ_LAST_PKT].verb == RP?
+                task[_SZ_LAST_PKT] = msg._pkt
+                task[_SZ_NEXT_DUE] = msg.dtm + task[_SZ_INTERVAL]
 
-            if task["next_due"] > dt_now:
+            if task[_SZ_NEXT_DUE] > dt_now:
                 continue  # if (most recent) last_msg is is not yet due...
 
             # since we may do I/O, check if the code|msg_id is deprecated
-            task["next_due"] = dt_now + task["interval"]  # might undeprecate later
+            task[_SZ_NEXT_DUE] = dt_now + task[_SZ_INTERVAL]  # might undeprecate later
 
-            if not self.is_pollable_cmd(task["command"].code):
+            if not self._is_not_deprecated_cmd(task[_SZ_COMMAND].code):
                 continue
-            if not self.is_pollable_cmd(
-                task["command"].code, ctx=task["command"].payload[4:6]
+            if not self._is_not_deprecated_cmd(
+                task[_SZ_COMMAND].code, ctx=task[_SZ_COMMAND].payload[4:6]
             ):  # only for Code._3220
                 continue
 
             # we'll have to do I/O...
-            task["next_due"] = dt_now + backoff(hdr, task["failures"])  # JIC
+            task[_SZ_NEXT_DUE] = dt_now + backoff(hdr, task[_SZ_FAILURES])  # JIC
 
-            if msg := await send_disc_task(hdr, task):  # TODO: OK 4 some exceptions
-                task["failures"] = 0  # only if task["last_msg"].verb == RP?
-                task["last_msg"] = msg
-                task["next_due"] = msg.dtm + task["interval"]
+            if pkt := await send_disc_cmd(hdr, task):  # TODO: OK 4 some exceptions
+                task[_SZ_FAILURES] = 0  # only if task[_SZ_LAST_PKT].verb == RP?
+                task[_SZ_LAST_PKT] = pkt
+                task[_SZ_NEXT_DUE] = pkt.dtm + task[_SZ_INTERVAL]
             else:
-                task["failures"] += 1
-                task["last_msg"] = None
-                task["next_due"] = dt_now + backoff(hdr, task["failures"])
+                task[_SZ_FAILURES] += 1
+                task[_SZ_LAST_PKT] = None
+                task[_SZ_NEXT_DUE] = dt_now + backoff(hdr, task[_SZ_FAILURES])
 
-    def deprecate_cmd(self, pkt: Packet, ctx: str = None, reset: bool = False) -> None:
+    def _deprecate_code_ctx(
+        self, pkt: Packet, ctx: str = None, reset: bool = False
+    ) -> None:
         """If a code|ctx is deprecated twice, stop polling for it."""
 
-        def deprecate(supported_dict, idx):
+        def deprecate(supported_dict: dict[str, bool | None], idx: str) -> None:
             if idx not in supported_dict:
                 supported_dict[idx] = None
             elif supported_dict[idx] is None:
-                _LOGGER.warning(
+                _LOGGER.info(
                     f"{pkt} < Polling now deprecated for code|ctx={idx}: "
                     "it appears to be unsupported"
                 )
                 supported_dict[idx] = False
 
-        def reinstate(supported_dict, idx):
-            if self.is_pollable_cmd(idx, None) is False:
-                _LOGGER.warning(
+        def reinstate(supported_dict: dict[str, bool | None], idx: str) -> None:
+            if self._is_not_deprecated_cmd(idx, None) is False:
+                _LOGGER.info(
                     f"{pkt} < Polling now reinstated for code|ctx={idx}: "
                     "it now appears supported"
                 )
@@ -464,107 +685,17 @@ class Discovery(MessageDB):
                 supported_dict.pop(idx)
 
         if ctx is None:
-            supported_dict = self._supported_cmds
-            idx = pkt.code
+            supported_cmds = self._supported_cmds
+            idx: str = pkt.code
         else:
-            supported_dict = self._supported_cmds_ctx
-            idx = f"{pkt.code}|{ctx}"  # msg._pkt._ctx
-
-        (reinstate if reset else deprecate)(supported_dict, idx)
-
-
-class Entity(Discovery):
-    """The ultimate base class for Devices/Zones/Systems.
-
-    This class is mainly concerned with:
-     - if the entity can Rx packets (e.g. can the HGI send it an RQ)
-    """
-
-    _SLUG: str = None  # type: ignore[assignment]
-
-    def __init__(self, gwy) -> None:
-        super().__init__(gwy)
-
-        self._gwy = gwy
-        self.id: _DeviceIdT = None  # type: ignore[assignment]
-
-        self._qos_tx_count = 0  # the number of pkts Tx'd with no matching Rx
-
-    def __repr__(self) -> str:
-        return f"{self.id} ({self._SLUG})"
-
-    def deprecate(self, pkt, reset=False) -> None:
-        """If an entity is deprecated enough times, stop sending to it."""
-
-        if reset:
-            self._qos_tx_count = 0
-            return
-
-        self._qos_tx_count += 1
-        if self._qos_tx_count == _QOS_TX_LIMIT:
-            _LOGGER.warning(
-                f"{pkt} < Sending now deprecated for {self} "
-                "(consider adjusting device_id filters)"
-            )  # TODO: take whitelist into account
-
-    def _handle_msg(self, msg: Message) -> None:  # TODO: beware, this is a mess
-        """Store a msg in _msgs[code] (only latest I/RP) and _msgz[code][verb][ctx]."""
-
-        super()._handle_msg(msg)  # store the message in the database
-
-        if (
-            self._gwy.pkt_protocol is None
-            or msg.src.id != self._gwy.pkt_protocol._hgi80.get(SZ_DEVICE_ID)
-        ):
-            self.deprecate(msg._pkt, reset=True)
-
-    def _make_cmd(self, code, dest_id, payload="00", verb=RQ, **kwargs) -> None:
-        self._send_cmd(self._gwy.create_cmd(verb, dest_id, code, payload, **kwargs))
-
-    def _send_cmd(self, cmd, **kwargs) -> None | Future:
-        if self._gwy.config.disable_sending:
-            _LOGGER.info(f"{cmd} < Sending is disabled")
-            return None
-
-        if self._qos_tx_count > _QOS_TX_LIMIT:
-            _LOGGER.info(f"{cmd} < Sending now deprecated for {self}")
-            return None
-
-        cmd._source_entity = self
-        # self._msgs.pop(cmd.code, None)  # NOTE: Cause of DHW bug
-        return self._gwy.send_cmd(cmd)  # BUG, should be: await async_send_cmd()
-
-    @property
-    def traits(self) -> dict:
-        """Return the codes seen by the entity."""
-
-        codes = {
-            k: (CODES_SCHEMA[k][SZ_NAME] if k in CODES_SCHEMA else None)
-            for k in sorted(self._msgs)
-            if self._msgs[k].src is (self if hasattr(self, "addr") else self.ctl)
-        }
+            supported_cmds = self._supported_cmds_ctx
+            idx = f"{pkt.code}|{ctx}"
 
-        return {"_sent": list(codes.keys())}
+        (reinstate if reset else deprecate)(supported_cmds, idx)
 
 
-def _delete_msg(msg: Message) -> None:
-    """Remove the msg from all state databases."""
-
-    entities = [msg.src]
-    if getattr(msg.src, "tcs", None):
-        entities.append(msg.src.tcs)
-        if msg.src.tcs.dhw:
-            entities.append(msg.src.tcs.dhw)
-        entities.extend(msg.src.tcs.zones)
-
-    # remove the msg from all the state DBs
-    for obj in entities:
-        if msg in obj._msgs.values():
-            del obj._msgs[msg.code]
-        try:
-            del obj._msgz[msg.code][msg.verb][msg._pkt._ctx]
-        except KeyError:
-            pass
+class Entity(_Discovery):
+    """The base class for Devices/Zones/Systems."""
 
 
 class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
@@ -580,16 +711,17 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
     There is a `set_parent` method, but no `set_child` method.
     """
 
-    actuator_by_id: dict[_DeviceIdT, Entity]
-    actuators: list[Entity]
+    actuator_by_id: dict[DeviceIdT, BdrSwitch | UfhCircuit | TrvActuator]
+    actuators: list[BdrSwitch | UfhCircuit | TrvActuator]
 
     circuit_by_id: dict[str, Any]
 
-    _dhw_sensor: Entity
-    _dhw_valve: Entity
-    _htg_valve: Entity
+    _app_cntrl: BdrSwitch | OtbGateway | None
+    _dhw_sensor: DhwSensor | None
+    _dhw_valve: BdrSwitch | None
+    _htg_valve: BdrSwitch | None
 
-    def __init__(self, *args, child_id: str = None, **kwargs) -> None:
+    def __init__(self, *args: Any, child_id: str = None, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
         self._child_id: str = child_id  # type: ignore[assignment]
@@ -598,27 +730,24 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
         self.child_by_id: dict[str, Child] = {}
         self.childs: list[Child] = []
 
-    def _handle_msg(self, msg: Message) -> None:
-        def eavesdrop_ufh_circuits():
-            if msg.code == Code._22C9:
-                # .I --- 02:044446 --:------ 02:044446 22C9 024 00-076C0A28-01 01-06720A28-01 02-06A40A28-01 03-06A40A2-801  # NOTE: fragments
-                # .I --- 02:044446 --:------ 02:044446 22C9 006 04-07D00A28-01                                               # [{'ufh_idx': '04',...
-                circuit_idxs = [c[SZ_UFH_IDX] for c in msg.payload]
-
-                for cct_idx in circuit_idxs:
-                    self.get_circuit(cct_idx, msg=msg)
+    # def _handle_msg(self, msg: Message) -> None:
+    #     def eavesdrop_ufh_circuits():
+    #         if msg.code == Code._22C9:
+    #             # .I --- 02:044446 --:------ 02:044446 22C9 024 00-076C0A28-01 01-06720A28-01 02-06A40A28-01 03-06A40A2-801  # NOTE: fragments
+    #             # .I --- 02:044446 --:------ 02:044446 22C9 006 04-07D00A28-01                                               # [{'ufh_idx': '04',...
+    #             circuit_idxs = [c[SZ_UFH_IDX] for c in msg.payload]
 
-                # BUG: this will fail with > 4 circuits, as uses two pkts for this msg
-                # if [c for c in self.child_by_id if c not in circuit_idxs]:
-                #     raise CorruptStateError
+    #             for cct_idx in circuit_idxs:
+    #                 self.get_circuit(cct_idx, msg=msg)
 
-        super()._handle_msg(msg)
+    #             # BUG: this will fail with > 4 circuits, as uses two pkts for this msg
+    #             # if [c for c in self.child_by_id if c not in circuit_idxs]:
+    #             #     raise CorruptStateError
 
-        if not self._gwy.config.enable_eavesdrop:
-            return
+    #     super()._handle_msg(msg)
 
-        # if True:
-        eavesdrop_ufh_circuits()
+    #     if self._gwy.config.enable_eavesdrop:
+    #         eavesdrop_ufh_circuits()
 
     @property
     def zone_idx(self) -> str:
@@ -629,8 +758,8 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
         """
         return self._child_id
 
-    @zone_idx.setter
-    def zone_idx(self, value) -> None:
+    @zone_idx.setter  # TODO: should be a private setter
+    def zone_idx(self, value: str) -> None:
         """Set the domain id, after validating it."""
         self._child_id = value
 
@@ -658,14 +787,14 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
 
         if hasattr(self, "childs") and child not in self.childs:  # Any parent
             assert isinstance(
-                self, (System, Zone, DhwZone, UfhController)
+                self, System | Zone | DhwZone | UfhController
             )  # TODO: remove me
 
         if is_sensor and child_id == FA:  # DHW zone (sensor)
             assert isinstance(self, DhwZone)  # TODO: remove me
             assert isinstance(child, DhwSensor)
             if self._dhw_sensor and self._dhw_sensor is not child:
-                raise CorruptStateError(
+                raise exc.SystemSchemaInconsistent(
                     f"{self} changed dhw_sensor (from {self._dhw_sensor} to {child})"
                 )
             self._dhw_sensor = child
@@ -673,15 +802,14 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
         elif is_sensor and hasattr(self, SZ_SENSOR):  # HTG zone
             assert isinstance(self, Zone)  # TODO: remove me
             if self.sensor and self.sensor is not child:
-                raise CorruptStateError(
+                raise exc.SystemSchemaInconsistent(
                     f"{self} changed zone sensor (from {self.sensor} to {child})"
                 )
             self._sensor = child
 
         elif is_sensor:
             raise TypeError(
-                f"not a valid combination for {self}: "
-                f"{child}|{child_id}|{is_sensor}"
+                f"not a valid combination for {self}: {child}|{child_id}|{is_sensor}"
             )
 
         elif hasattr(self, SZ_CIRCUITS):  # UFH circuit
@@ -691,18 +819,16 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
 
         elif hasattr(self, SZ_ACTUATORS):  # HTG zone
             assert isinstance(self, Zone)  # TODO: remove me
-            assert isinstance(child, (BdrSwitch, UfhCircuit, TrvActuator)), (
-                "what" if True else "why"
-            )
+            assert isinstance(child, BdrSwitch | UfhCircuit | TrvActuator)
             if child not in self.actuators:
                 self.actuators.append(child)
-                self.actuator_by_id[child.id] = child
+                self.actuator_by_id[child.id] = child  # type: ignore[assignment,index]
 
         elif child_id == F9:  # DHW zone (HTG valve)
             assert isinstance(self, DhwZone)  # TODO: remove me
             assert isinstance(child, BdrSwitch)
             if self._htg_valve and self._htg_valve is not child:
-                raise CorruptStateError(
+                raise exc.SystemSchemaInconsistent(
                     f"{self} changed htg_valve (from {self._htg_valve} to {child})"
                 )
             self._htg_valve = child
@@ -711,43 +837,33 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
             assert isinstance(self, DhwZone)  # TODO: remove me
             assert isinstance(child, BdrSwitch)
             if self._dhw_valve and self._dhw_valve is not child:
-                raise CorruptStateError(
+                raise exc.SystemSchemaInconsistent(
                     f"{self} changed dhw_valve (from {self._dhw_valve} to {child})"
                 )
             self._dhw_valve = child
 
         elif child_id == FC:  # Appliance Controller
             assert isinstance(self, System)  # TODO: remove me
-            assert isinstance(child, (BdrSwitch, OtbGateway))
+            assert isinstance(child, BdrSwitch | OtbGateway)
             if self._app_cntrl and self._app_cntrl is not child:
-                raise CorruptStateError(
+                raise exc.SystemSchemaInconsistent(
                     f"{self} changed app_cntrl (from {self._app_cntrl} to {child})"
                 )
             self._app_cntrl = child
 
         elif child_id == FF:  # System
             assert isinstance(self, System)  # TODO: remove me?
-            assert isinstance(child, (UfhController, OutSensor))
+            assert isinstance(child, UfhController | OutSensor)
             pass
 
         else:
             raise TypeError(
-                f"not a valid combination for {self}: "
-                f"{child}|{child_id}|{is_sensor}"
+                f"not a valid combination for {self}: {child}|{child_id}|{is_sensor}"
             )
 
         self.childs.append(child)
         self.child_by_id[child.id] = child
 
-        if DEV_MODE:
-            _LOGGER.warning(
-                "parent.set_child(), Parent: %s_%s, %s: %s",
-                self.id,
-                child_id,
-                "Sensor" if is_sensor else "Device",
-                child,
-            )
-
 
 class Child(Entity):  # A Zone, Device or a UfhCircuit
     """A Device can be the Child of a Parent (a System, a heating Zone, or a DHW Zone).
@@ -762,39 +878,43 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
     """
 
     def __init__(
-        self, *args, parent: Parent = None, is_sensor: bool = None, **kwargs
+        self,
+        *args: Any,
+        parent: Parent = None,
+        is_sensor: bool | None = None,
+        **kwargs: Any,
     ) -> None:
         super().__init__(*args, **kwargs)
 
-        self._parent = parent  # type: ignore[assignment]
-        self._is_sensor = is_sensor  # type: ignore[assignment]
+        self._parent = parent
+        self._is_sensor = is_sensor
 
-        self._child_id: None | str = None  # TODO: should be: str?
+        self._child_id: str | None = None  # TODO: should be: str?
 
     def _handle_msg(self, msg: Message) -> None:
-        from .device import Controller, UfhController
+        from .device import Controller, Device, UfhController
 
-        def eavesdrop_parent_zone():
+        def eavesdrop_parent_zone() -> None:
             if isinstance(msg.src, UfhController):
                 return
 
             if SZ_ZONE_IDX not in msg.payload:
                 return
 
-            # the follwing is a mess - may just be better off deprecating it
-            if self.type in DEV_TYPE_MAP.HEAT_ZONE_ACTUATORS:
-                self.set_parent(msg.dst, child_id=msg.payload[SZ_ZONE_IDX])
+            if isinstance(self, Device):  # FIXME: a mess...
+                # the following is a mess - may just be better off deprecating it
+                if self.type in DEV_TYPE_MAP.HEAT_ZONE_ACTUATORS:
+                    self.set_parent(msg.dst, child_id=msg.payload[SZ_ZONE_IDX])
 
-            elif self.type in DEV_TYPE_MAP.THM_DEVICES:
-                self.set_parent(
-                    msg.dst, child_id=msg.payload[SZ_ZONE_IDX], is_sensor=True
-                )
+                elif self.type in DEV_TYPE_MAP.THM_DEVICES:
+                    self.set_parent(
+                        msg.dst, child_id=msg.payload[SZ_ZONE_IDX], is_sensor=True
+                    )
 
         super()._handle_msg(msg)
 
         if not self._gwy.config.enable_eavesdrop or (
-            msg.src is msg.dst
-            or not isinstance(msg.dst, (Controller,))  # UfhController))
+            msg.src is msg.dst or not isinstance(msg.dst, Controller)  # UfhController))
         ):
             return
 
@@ -802,8 +922,8 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
             eavesdrop_parent_zone()
 
     def _get_parent(
-        self, parent: Parent, *, child_id: str = None, is_sensor: bool = None
-    ) -> tuple[Parent, None | str]:
+        self, parent: Parent, *, child_id: str = None, is_sensor: bool | None = None
+    ) -> tuple[Parent, str | None]:
         """Get the device's parent, after validating it."""
 
         # NOTE: here to prevent circular references
@@ -818,21 +938,21 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
             UfhCircuit,
             UfhController,
         )
-        from .system import DhwZone, System, Zone
+        from .system import DhwZone, Evohome, System, Zone
 
         if isinstance(self, UfhController):
             child_id = FF
 
-        if isinstance(parent, Controller):  # A controller cant be a Parent
-            parent: System = parent.tcs  # type: ignore[assignment, no-redef]
+        if isinstance(parent, Controller):  # A controller can't be a Parent
+            parent = parent.tcs
 
-        if isinstance(parent, System) and child_id:
+        if isinstance(parent, Evohome) and child_id:
             if child_id in (F9, FA):
-                parent: DhwZone = parent.get_dhw_zone()  # type: ignore[no-redef]
+                parent = parent.get_dhw_zone()
             # elif child_id == FC:
             #     pass
             elif int(child_id, 16) < parent._max_zones:
-                parent: Zone = parent.get_htg_zone(child_id)  # type: ignore[no-redef, attr-defined]
+                parent = parent.get_htg_zone(child_id)
 
         elif isinstance(parent, Zone) and not child_id:
             child_id = child_id or parent.idx
@@ -842,7 +962,7 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
 
         elif isinstance(parent, UfhController) and not child_id:
             raise TypeError(
-                f"{self}: cant set child_id to: {child_id} "
+                f"{self}: can't set child_id to: {child_id} "
                 f"(for Circuits, it must be a circuit_idx)"
             )
 
@@ -850,14 +970,14 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
         #     child_id = parent._child_id  # or, for zones: parent.idx
 
         if self._parent and self._parent != parent:
-            raise CorruptStateError(
-                f"{self} cant change parent "
+            raise exc.SystemSchemaInconsistent(
+                f"{self} can't change parent "
                 f"({self._parent}_{self._child_id} to {parent}_{child_id})"
             )
 
         # if self._child_id is not None and self._child_id != child_id:
         #     raise CorruptStateError(
-        #         f"{self} cant set domain to: {child_id}, "
+        #         f"{self} can't set domain to: {child_id}, "
         #         f"({self._parent}_{self._child_id} to {parent}_{child_id})"
         #     )
 
@@ -902,34 +1022,35 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
         if isinstance(parent, Zone):
             if child_id != parent.idx:
                 raise TypeError(
-                    f"{self}: cant set child_id to: {child_id} "
+                    f"{self}: can't set child_id to: {child_id} "
                     f"(it must match its parent's zone idx, {parent.idx})"
                 )
 
         elif isinstance(parent, DhwZone):  # usu. FA (HW), could be F9
             if child_id not in (F9, FA):  # may not be known if eavesdrop'd
                 raise TypeError(
-                    f"{self}: cant set child_id to: {child_id} "
+                    f"{self}: can't set child_id to: {child_id} "
                     f"(for DHW, it must be F9 or FA)"
                 )
 
         elif isinstance(parent, System):  # usu. FC
             if child_id not in (FC, FF):  # was: not in (F9, FA, FC, "HW"):
                 raise TypeError(
-                    f"{self}: cant set child_id to: {child_id} "
+                    f"{self}: can't set child_id to: {child_id} "
                     f"(for TCS, it must be FC)"
                 )
 
         elif not isinstance(parent, UfhController):  # is like CTL/TCS combined
             raise TypeError(
-                f"{self}: cant set Parent to: {parent} "
+                f"{self}: can't set Parent to: {parent} "
                 f"(it must be System, DHW, Zone, or UfhController)"
             )
 
         return parent, child_id
 
+    # TODO: should be a private method
     def set_parent(
-        self, parent: Parent, *, child_id: str = None, is_sensor: bool = None
+        self, parent: Parent | None, *, child_id: str = None, is_sensor: bool = None
     ) -> Parent:
         """Set the device's parent, after validating it.
 
@@ -943,7 +1064,10 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
         controller, or an UFH controller.
         """
 
-        from .device import UfhController  # NOTE: here to prevent circular references
+        from .device import (  # NOTE: here to prevent circular references
+            Controller,
+            UfhController,
+        )
 
         parent, child_id = self._get_parent(
             parent, child_id=child_id, is_sensor=is_sensor
@@ -952,8 +1076,8 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
 
         if self.ctl and self.ctl is not ctl:
             # NOTE: assume a device is bound to only one CTL (usu. best practice)
-            raise CorruptStateError(
-                f"{self} cant change controller: {self.ctl} to {ctl} "
+            raise exc.SystemSchemaInconsistent(
+                f"{self} can't change controller: {self.ctl} to {ctl} "
                 "(or perhaps the device has multiple controllers?"
             )
 
@@ -964,16 +1088,9 @@ class Child(Entity):  # A Zone, Device or a UfhCircuit
         self._child_id = child_id
         self._parent = parent
 
-        self.ctl = ctl
-        self.tcs = ctl.tcs
+        assert isinstance(ctl, Controller)  # mypy hint
 
-        if DEV_MODE:
-            _LOGGER.warning(
-                "child.set_parent(), Parent: %s_%s, %s: %s",
-                parent.id,
-                child_id,
-                "Sensor" if is_sensor else "Device",
-                self,
-            )
+        self.ctl: Controller = ctl
+        self.tcs: Evohome = ctl.tcs
 
         return parent