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

ramses_rf/device/base.py

@@ -1,28 +1,31 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
 Base for all devices.
 """
+
 from __future__ import annotations
 
 import logging
-from datetime import timedelta as td
-from typing import Any, Callable, Optional
-
-from ..const import DEV_TYPE, DEV_TYPE_MAP, SZ_DEVICE_ID, __dev_mode__
-from ..entity_base import Child, Entity, class_by_attr
-from ..helpers import shrink
-from ..protocol.address import Address
-from ..protocol.backports import StrEnum
-from ..protocol.command import Command, _mk_cmd
-from ..protocol.message import Message
-from ..protocol.ramses import CODES_BY_DEV_SLUG, CODES_ONLY_FROM_CTL
-from ..schemas import SCH_TRAITS, SZ_ALIAS, SZ_CLASS, SZ_FAKED, SZ_KNOWN_LIST
-
-# skipcq: PY-W2000
-from ..const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from ramses_rf.binding_fsm import BindContext, Vendor
+from ramses_rf.const import DEV_TYPE_MAP, SZ_OEM_CODE, DevType
+from ramses_rf.entity_base import Child, Entity, class_by_attr
+from ramses_rf.helpers import shrink
+from ramses_rf.schemas import (
+    SCH_TRAITS,
+    SZ_ALIAS,
+    SZ_CLASS,
+    SZ_FAKED,
+    SZ_KNOWN_LIST,
+    SZ_SCHEME,
+)
+from ramses_tx import Command, Packet, Priority, QosParams
+from ramses_tx.ramses import CODES_BY_DEV_SLUG, CODES_ONLY_FROM_CTL
+
+from ramses_rf.const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     I_,
     RP,
     RQ,
@@ -30,30 +33,12 @@ from ..const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     Code,
 )
 
-DEFAULT_BDR_ID = "13:888888"
-DEFAULT_EXT_ID = "17:888888"
-DEFAULT_THM_ID = "03:888888"
-
-
-class BindState(StrEnum):
-    #
-    #       DHW/THM, TRV -> CTL     (temp, valve_position), or:
-    #                CTL -> BDR/OTB (heat_demand)
-    #          [ REQUEST -> WAITING ]
-    #            unbound -- unbound
-    #            unbound -- listening
-    #           offering -> listening
-    #           offering <- accepting
-    # (confirming) bound -> accepting
-    #              bound -- bound
-    #
-    UNKNOWN = ("None",)
-    UNBOUND = ("unb",)  # unbound
-    LISTENING = ("l",)  # waiting for offer
-    OFFERING = ("of",)  # waiting for accept:              -> sent offer
-    ACCEPTING = ("a",)  # waiting for confirm: rcvd offer  -> sent accept
-    # NFIRMED = "c",  # bound:               rcvd accept -> sent confirm
-    BOUND = ("bound",)  # bound:               rcvd confirm
+if TYPE_CHECKING:
+    from typing import Any
+
+    from ramses_rf import Gateway
+    from ramses_rf.system import Zone
+    from ramses_tx import Address, DeviceIdT, IndexT, Message
 
 
 BIND_WAITING_TIMEOUT = 300  # how long to wait, listening for an offer
@@ -61,42 +46,25 @@ BIND_REQUEST_TIMEOUT = 5  # how long to wait for an accept after sending an offe
 BIND_CONFIRM_TIMEOUT = 5  # how long to wait for a confirm after sending an accept
 
 
-DEV_MODE = __dev_mode__  # and False
-
 _LOGGER = logging.getLogger(__name__)
-if DEV_MODE:
-    _LOGGER.setLevel(logging.DEBUG)
-
-
-def check_faking_enabled(fnc):
-    def wrapper(self, *args, **kwargs):
-        if not self._faked:
-            raise RuntimeError(f"Faking is not enabled for {self}")
-        return fnc(self, *args, **kwargs)
-
-    return wrapper
 
 
 class DeviceBase(Entity):
     """The Device base class - can also be used for unknown device types."""
 
-    _SLUG: str = DEV_TYPE.DEV  # type: ignore[assignment]
-
-    _STATE_ATTR: str = None  # type: ignore[assignment]
+    _SLUG: str = DevType.DEV
+    _STATE_ATTR: str = None
 
-    def __init__(self, gwy, dev_addr, **kwargs) -> None:
-        _LOGGER.debug("Creating a Device: %s (%s)", dev_addr.id, self.__class__)
-
-        # if not check_valid(dev_addr.id):  # TODO
-        #     raise ValueError(f"Invalid device id: {dev_addr.id}")
-        if dev_addr.id in gwy.device_by_id:
-            raise LookupError(f"Duplicate DEV: {dev_addr.id}")
-        gwy.device_by_id[dev_addr.id] = self
-        gwy.devices.append(self)
+    _bind_context: BindContext | None = None
 
+    def __init__(self, gwy: Gateway, dev_addr: Address, **kwargs: Any) -> None:
         super().__init__(gwy)
 
-        self.id: str = dev_addr.id
+        # FIXME: ZZZ entities must know their parent device ID and their own idx
+        self._z_id = dev_addr.id  # the responsible device is itself
+        self._z_idx = None  # depends upon it's location in the schema
+
+        self.id: DeviceIdT = dev_addr.id
 
         # self.tcs = None  # NOTE: Heat (CH/DHW) devices only
         # self.ctl = None
@@ -105,19 +73,19 @@ class DeviceBase(Entity):
         self.addr = dev_addr
         self.type = dev_addr.type  # DEX  # TODO: remove this attr? use SLUG?
 
-        self._faked: bool = False
+        self._scheme: Vendor = None
 
     def __str__(self) -> str:
         if self._STATE_ATTR:
             return f"{self.id} ({self._SLUG}): {getattr(self, self._STATE_ATTR)}"
         return f"{self.id} ({self._SLUG})"
 
-    def __lt__(self, other) -> bool:
+    def __lt__(self, other: object) -> bool:
         if not hasattr(other, "id"):
             return NotImplemented
-        return self.id < other.id
+        return self.id < other.id  # type: ignore[no-any-return]
 
-    def _update_traits(self, **traits):
+    def _update_traits(self, **traits: Any) -> None:
         """Update a device with new schema attrs.
 
         Raise an exception if the new schema is not a superset of the existing schema.
@@ -130,8 +98,12 @@ class DeviceBase(Entity):
                 raise TypeError(f"Device is not fakable: {self} (traits={traits})")
             self._make_fake()
 
+        self._scheme = traits.get(SZ_SCHEME)
+
     @classmethod
-    def create_from_schema(cls, gwy, dev_addr: Address, **schema):
+    def create_from_schema(
+        cls, gwy: Gateway, dev_addr: Address, **schema: Any
+    ) -> DeviceBase:
         """Create a device (for a GWY) and set its schema attrs (aka traits).
 
         All devices have traits, but also controllers (CTL, UFC) have a system schema.
@@ -149,41 +121,38 @@ class DeviceBase(Entity):
         # sometimes, battery-powered devices will respond to an RQ (e.g. bind mode)
 
         # if discover_flag & Discover.TRAITS:
-        # self._add_discovery_cmd(_mk_cmd(RQ, Code._1FC9, "00", self.id), 60 * 60 * 24)
-        # self._add_discovery_cmd(_mk_cmd(RQ, Code._0016, "00", self.id), 60 * 60)
+        # self._add_discovery_cmd(cmd(RQ, Code._1FC9, "00", self.id), 60 * 60 * 24)
+        # self._add_discovery_cmd(cmd(RQ, Code._0016, "00", self.id), 60 * 60)
 
         pass
 
-    def _make_cmd(self, code, payload="00", **kwargs) -> None:  # type: ignore[override]  # skipcq: PYL-W0221
-        super()._make_cmd(code, self.id, payload=payload, **kwargs)
-
-    def _send_cmd(self, cmd, **kwargs) -> None:
-        if getattr(self, "has_battery", None) and cmd.dst.id == self.id:
+    def _send_cmd(self, cmd: Command, **kwargs: Any) -> None:
+        if self.has_battery and not self.is_faked and cmd.dst.id == self.id:
             _LOGGER.info(f"{cmd} < Sending inadvisable for {self} (it has a battery)")
 
         super()._send_cmd(cmd, **kwargs)
 
     def _handle_msg(self, msg: Message) -> None:
-        assert msg.src is self or (
-            msg.code == Code._1FC9 and msg.payload["phase"] == "offer"
-        ), f"msg from {msg.src} inappropriately routed to {self}"
+        # # assert msg.src is self or (
+        # #     msg.code == Code._1FC9 and msg.payload[SZ_PHASE] == SZ_OFFER
+        # # ), f"msg from {msg.src} inappropriately routed to {self}"
 
         super()._handle_msg(msg)
 
-        if self._SLUG in DEV_TYPE_MAP.PROMOTABLE_SLUGS:
-            # HACK: can get precise class?
+        if self._SLUG in DEV_TYPE_MAP.PROMOTABLE_SLUGS:  # HACK: can get precise class?
             from . import best_dev_role
 
             cls = best_dev_role(
                 self.addr, msg=msg, eavesdrop=self._gwy.config.enable_eavesdrop
             )
-            if cls._SLUG in (DEV_TYPE.DEV, self._SLUG):
+
+            if cls._SLUG in (DevType.DEV, self._SLUG):
                 return  # either a demotion (DEV), or not promotion (HEA/HVC)
 
-            if self._SLUG == DEV_TYPE.HEA and cls._SLUG in DEV_TYPE_MAP.HVAC_SLUGS:
+            if self._SLUG == DevType.HEA and cls._SLUG in DEV_TYPE_MAP.HVAC_SLUGS:
                 return  # TODO: should raise error if CODES_OF_HVAC_DOMAIN_ONLY?
 
-            if self._SLUG == DEV_TYPE.HVC and cls._SLUG not in DEV_TYPE_MAP.HVAC_SLUGS:
+            if self._SLUG == DevType.HVC and cls._SLUG not in DEV_TYPE_MAP.HVAC_SLUGS:
                 return  # TODO: should raise error if CODES_OF_HEAT_DOMAIN_ONLY?
 
             _LOGGER.warning(
@@ -195,13 +164,21 @@ class DeviceBase(Entity):
 
     @property
     def has_battery(self) -> None | bool:  # 1060
-        """Return True if a device is battery powered (excludes battery-backup)."""
+        """Return True if the device is battery powered (excludes battery-backup)."""
 
         return isinstance(self, BatteryState) or Code._1060 in self._msgz
 
     @property
-    def is_faked(self) -> bool:  # TODO: impersonated vs virtual
-        return bool(self._faked)
+    def is_faked(self) -> bool:
+        """Return True if the device is faked."""
+
+        return bool(self._bind_context)  # isinstance(self, Fakeable) and...
+
+    @property
+    def _is_binding(self) -> bool:
+        """Return True if the (faked) device is actively binding."""
+
+        return self._bind_context and self._bind_context.is_binding
 
     @property
     def _is_present(self) -> bool:
@@ -245,19 +222,18 @@ class DeviceBase(Entity):
 
 
 class BatteryState(DeviceBase):  # 1060
-
     BATTERY_LOW = "battery_low"  # boolean
     BATTERY_STATE = "battery_state"  # percentage (0.0-1.0)
 
     @property
     def battery_low(self) -> None | bool:  # 1060
-        if self._faked:
+        if self.is_faked:
             return False
         return self._msg_value(Code._1060, key=self.BATTERY_LOW)
 
     @property
-    def battery_state(self) -> Optional[dict]:  # 1060
-        if self._faked:
+    def battery_state(self) -> dict[str, Any] | None:  # 1060
+        if self.is_faked:
             return None
         return self._msg_value(Code._1060)
 
@@ -277,12 +253,11 @@ class DeviceInfo(DeviceBase):  # 10E0
         if self._SLUG not in CODES_BY_DEV_SLUG or RP in CODES_BY_DEV_SLUG[
             self._SLUG
         ].get(Code._10E0, {}):
-            self._add_discovery_cmd(
-                _mk_cmd(RQ, Code._10E0, "00", self.id), 60 * 60 * 24
-            )
+            cmd = Command.from_attrs(RQ, self.id, Code._10E0, "00")
+            self._add_discovery_cmd(cmd, 60 * 60 * 24)
 
     @property
-    def device_info(self) -> Optional[dict]:  # 10E0
+    def device_info(self) -> dict | None:  # 10E0
         return self._msg_value(Code._10E0)
 
     @property
@@ -299,6 +274,7 @@ class DeviceInfo(DeviceBase):  # 10E0
         return result
 
 
+# NOTE: devices (Thermostat) not attrs (Temperature) are faked
 class Fakeable(DeviceBase):
     """There are two types of Faking: impersonation (of real devices) and full-faking.
 
@@ -310,314 +286,149 @@ class Fakeable(DeviceBase):
     such packets via RF.
     """
 
-    # Faked Round Thermostat binding to a Evohome controller as a zone sensor
-    # STA set to BindState.OFFERING:  sends "1FC9| I|63:262142" to the ether (the controller is listening)
-    # - receives "1FC9| W|34:021943" to: Fakable._bind_request().proc_accept() via callback?
-    # STA set to BindState.ACCEPTING: sends "1FC9| I|01:145038" to the ether (the controller is ignoring?)
-    # - receives "1FC9| I|01:145038" to: Fakable._bind_request().proc_confirm() via callback -- OPTIONAL!!
-    # STA set to BindState.BOUND via callback, and...
-
-    # Faked Evohome controller binding to a Round Thermostat as a zone sensor
-    # CTL set to BindState.LISTENING
-    # - receives "1FC9| I|63:262142" to: Fakable._bind_waiting().proc_offer() via callback?
-    # CTL set to BindState.ACCEPTING: sends "1FC9| W|34:021943" to the ether
-    # - receives "1FC9| I|01:145038" to: Fakable._bind_waiting().proc_confirm() via callback -- OPTIONAL!!
-    # CTL set to BindState.BOUND
-
-    def __init__(self, gwy, *args, **kwargs) -> None:
+    def __init__(self, gwy: Gateway, *args: Any, **kwargs: Any) -> None:
         super().__init__(gwy, *args, **kwargs)
 
-        self._faked: bool = None  # type: ignore[assignment]
-
-        self._1fc9_state: dict[str, Any] = {"state": BindState.UNKNOWN}
+        self._bind_context: BindContext | None = None
 
+        # TOD: this is messy - device schema vs device traits
         if self.id in gwy._include and gwy._include[self.id].get(SZ_FAKED):
             self._make_fake()
 
         if kwargs.get(SZ_FAKED):
             self._make_fake()
 
-    @check_faking_enabled
-    def _bind(self):
-        self._1fc9_state["state"] = BindState.UNBOUND
-
-    def _make_fake(self, bind=None) -> Fakeable:
-        if not self._faked:
-            self._faked = True
-            self._gwy._include[self.id] = {SZ_FAKED: True}
-            _LOGGER.info(f"Faking now enabled for: {self}")  # TODO: be info/debug
-        if bind:
-            self._bind()
-        return self
-
-    def _bind_waiting(self, codes, idx="00", callback: Callable = None) -> None:
-        """Wait for (listen for) a bind handshake."""
-
-        # Bind waiting: BDR set to listen, CTL initiates handshake
-        # 19:30:44.749 051  I --- 01:054173 --:------ 01:054173 1FC9 024 FC-0008-04D39D FC-3150-04D39D FB-3150-04D39D FC-1FC9-04D39D
-        # 19:30:45.342 053  W --- 13:049798 01:054173 --:------ 1FC9 012 00-3EF0-34C286 00-3B00-34C286
-        # 19:30:45.504 049  I --- 01:054173 13:049798 --:------ 1FC9 006 00-FFFF-04D39D
-
-        # Bind waiting: OTB set to listen, CTL initiates handshake
-        # 00:25:02.779 045  I --- 01:145038 --:------ 01:145038 1FC9 024 FC-0008-06368E FC-3150-06368E FB-3150-06368E  FC-1FC9-06368E  # opentherm bridge
-        # 00:25:02.792 045  W --- 10:048122 01:145038 --:------ 1FC9 006 00-3EF0-28BBFA
-        # 00:25:02.944 045  I --- 01:145038 10:048122 --:------ 1FC9 006 00-FFFF-06368E
-
-        _LOGGER.warning(f"Binding {self}: waiting for {codes} for 300 secs")  # info
-        # SUPPORTED_CODES = (Code._0008,)
-
-        # assert code in SUPPORTED_CODES, f"Binding {self}: {code} is not supported"
-        self._1fc9_state["codes"] = codes
-        self._1fc9_state["state"] = BindState.LISTENING
-        self._1fc9_state["timeout"] = self._gwy._dt_now() + td(seconds=300)
-
-    def _bind_request(self, codes, callback: Callable = None) -> None:
-        """Initiate a bind handshake: send the 1st packet of the handshake."""
-
-        # Bind request: CTL set to listen, STA initiates handshake (note 3C09/2309)
-        # 22:13:52.527 070  I --- 34:021943 --:------ 34:021943 1FC9 024 00-2309-8855B7 00-30C9-8855B7 00-0008-8855B7 00-1FC9-8855B7
-        # 22:13:52.540 052  W --- 01:145038 34:021943 --:------ 1FC9 006 00-2309-06368E
-        # 22:13:52.572 071  I --- 34:021943 01:145038 --:------ 1FC9 006 00-2309-8855B7
-
-        # Bind request: CTL set to listen, DHW sensor initiates handshake
-        # 19:45:16.733 045  I --- 07:045960 --:------ 07:045960 1FC9 012 00-1260-1CB388 00-1FC9-1CB388
-        # 19:45:16.896 045  W --- 01:054173 07:045960 --:------ 1FC9 006 00-10A0-04D39D
-        # 19:45:16.919 045  I --- 07:045960 01:054173 --:------ 1FC9 006 00-1260-1CB388
+    def _make_fake(self) -> None:
+        if self._bind_context:
+            return
 
-        _LOGGER.warning(f"Binding {self}: requesting {codes}")  # TODO: info
+        self._bind_context = BindContext(self)
+        self._gwy._include[self.id][SZ_FAKED] = True  # TODO: remove this
+        _LOGGER.info(f"Faking now enabled for: {self}")
 
-        if not isinstance(codes, tuple):
-            codes = (codes,)
+    async def _async_send_cmd(
+        self,
+        cmd: Command,
+        priority: Priority | None = None,
+        qos: QosParams | None = None,
+    ) -> Packet | None:
+        """Wrapper to CC: any relevant Commands to the binding Context."""
 
-        self._1fc9_state["codes"] = codes
-        self._1fc9_state["state"] = BindState.OFFERING
-        self._1fc9_state["timeout"] = self._gwy._dt_now() + td(seconds=60)
+        if self._bind_context and self._bind_context.is_binding:
+            # cmd.code in (Code._1FC9, Code._10E0)
+            self._bind_context.sent_cmd(cmd)  # other codes needed for edge cases
 
-        self._send_cmd(Command.put_bind(I_, codes, self.id))
+        return await super()._async_send_cmd(cmd, priority=priority, qos=qos)
 
     def _handle_msg(self, msg: Message) -> None:
-        def proc_offer_and_accept(msg: Message):  # . process 1st pkt of handshake
-            """Accept a valid offer (if listening).
-
-            If able to do so, update the binding state.
-            """
-            assert msg and msg.payload["phase"] == "offer"
-            assert self._1fc9_state["state"] == BindState.LISTENING
-
-            if self._1fc9_state["timeout"] < self._gwy._dt_now():
-                return BindState.UNKNOWN
-
-            if msg.verb != I_ or msg.src is not msg.dst:  # or msg.dst is self
-                return self._1fc9_state["state"]
-
-            cmd = Command.put_bind(
-                W_,
-                self._1fc9_state["codes"],
-                self.id,
-                idx="00",  # self._1fc9_state["idx"],
-                dst_id=msg.src.id,
-            )
-            self._send_cmd(cmd)
-
-            self._1fc9_state["msg"] = msg  # the offer
-            return BindState.ACCEPTING
-
-        def proc_accept_and_confirm(msg: Message):  # process 2nd pkt of handshake
-            """Confirm a valid accept (if offering).
-
-            If able to do so, update the binding state.
-            """
-            assert msg and msg.payload["phase"] == "accept"
-            assert self._1fc9_state["state"] == BindState.OFFERING
+        """Wrapper to CC: any relevant Packets to the binding Context."""
 
-            if self._1fc9_state["timeout"] < self._gwy._dt_now():
-                return BindState.UNKNOWN
-
-            if msg.verb != W_:
-                return self._1fc9_state["state"]
-
-            cmd = Command.put_bind(I_, None, self.id, dst_id=msg.src.id)
-            self._send_cmd(cmd)
-
-            self._1fc9_state["msg"] = msg  # the offer
-            return BindState.BOUND
-
-        def proc_confirm_and_done(msg: Message):  # . process 3rd pkt of handshake
-            """Process a valid confirmation (if accepting).
-
-            If able to do so, update the binding state.
-            """
-            assert msg and msg.payload["phase"] == "confirm"
-            assert self._1fc9_state["state"] == BindState.ACCEPTING
-
-            if self._1fc9_state["timeout"] < self._gwy._dt_now():
-                return BindState.BOUND  # HACK?
+        super()._handle_msg(msg)
 
-            if msg.verb != I_:
-                return self._1fc9_state["state"]
+        if self._bind_context and self._bind_context.is_binding:
+            # msg.code in (Code._1FC9, Code._10E0)
+            self._bind_context.rcvd_msg(msg)  # maybe other codes needed for edge cases
+
+    async def _wait_for_binding_request(
+        self,
+        accept_codes: Iterable[Code],
+        /,
+        *,
+        idx: IndexT = "00",
+        require_ratify: bool = False,
+    ) -> tuple[Packet, Packet, Packet, Packet | None]:
+        """Listen for a binding and return the Offer, or raise an exception."""
+
+        if not self._bind_context:
+            raise TypeError(f"{self}: Faking not enabled")
+
+        msgs = await self._bind_context.wait_for_binding_request(
+            accept_codes, idx=idx, require_ratify=require_ratify
+        )
+        return msgs
+
+    async def wait_for_binding_request(
+        self,
+        accept_codes: Iterable[Code],
+        /,
+        *,
+        idx: IndexT = "00",
+        require_ratify: bool = False,
+    ) -> tuple[Packet, Packet, Packet, Packet | None]:
+        raise NotImplementedError
 
-            # self._1fc9_state["msg"] = msg  # keep offer, not confirm
-            return BindState.BOUND
+    async def _initiate_binding_process(
+        self,
+        offer_codes: Code | Iterable[Code],
+        /,
+        *,
+        confirm_code: Code | None = None,
+        ratify_cmd: Command | None = None,
+    ) -> tuple[Packet, Packet, Packet, Packet | None]:
+        """Start a binding and return the Accept, or raise an exception."""
+        # confirm_code can be FFFF.
+
+        if not self._bind_context:
+            raise TypeError(f"{self}: Faking not enabled")
+
+        if isinstance(offer_codes, Iterable):
+            codes: tuple[Code] = offer_codes
+        else:
+            codes = tuple([offer_codes])
+
+        msgs = await self._bind_context.initiate_binding_process(
+            codes, confirm_code=confirm_code, ratify_cmd=ratify_cmd
+        )  # TODO: if successful, re-discover schema?
+        return msgs
+
+    async def initiate_binding_process(self) -> Packet:
+        raise NotImplementedError
 
-        if msg.code != Code._1FC9:
-            super()._handle_msg(msg)
-            return
+    @property
+    def oem_code(self) -> str | None:
+        """Return the OEM code (a 2-char ascii str) for this device, if there is one."""
+        # raise NotImplementedError  # self.traits is a @property
+        if not self.traits.get(SZ_OEM_CODE):
+            self.traits[SZ_OEM_CODE] = self._msg_value(Code._10E0, key=SZ_OEM_CODE)
+        return self.traits.get(SZ_OEM_CODE)
 
-        if msg.payload["phase"] == "offer":
-            if msg.src is self:
-                return
-            assert self._1fc9_state["state"] == BindState.LISTENING
-            self._1fc9_state["state"] = proc_offer_and_accept(msg)
 
-        elif msg.payload["phase"] == "accept":
-            if msg.src is self:
-                return
-            assert self._1fc9_state["state"] == BindState.OFFERING
-            self._1fc9_state["state"] = proc_accept_and_confirm(msg)
+class Device(Child, DeviceBase):
+    """The base class for all devices."""
 
-        elif msg.payload["phase"] == "confirm":
-            assert self._1fc9_state["state"] == BindState.ACCEPTING
-            self._1fc9_state["state"] = proc_confirm_and_done(msg)
+    def __init__(self, gwy: Gateway, dev_addr: Address, **kwargs: Any) -> None:
+        _LOGGER.debug("Creating a Device: %s (%s)", dev_addr.id, self.__class__)
+        super().__init__(gwy, dev_addr)
 
-        super()._handle_msg(msg)
+        gwy._add_device(self)
 
 
-class HgiGateway(DeviceInfo):  # HGI (18:)
+class HgiGateway(Device):  # HGI (18:)
     """The HGI80 base class."""
 
-    _SLUG: str = DEV_TYPE.HGI
+    _SLUG: str = DevType.HGI
 
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
-        self.ctl = None
+        self.ctl = None  # FIXME: a mess
         self._child_id = "gw"  # TODO
         self.tcs = None
 
-        self._faked_bdr: Device = None  # type: ignore[assignment]
-        self._faked_ext: Device = None  # type: ignore[assignment]
-        self._faked_thm: Device = None  # type: ignore[assignment]
-
-        # self. _proc_schema(**kwargs)
-
-    # def _proc_schema(self, schema) -> None:
-    #     if schema.get("fake_bdr"):
-    #         self._faked_bdr = self._gwy.get_device(
-    #             self.id, class_=DEV_TYPE.BDR, faked=True
-    #         )  # also for THM, OUT
-
-    def _handle_msg(self, msg: Message) -> None:
-        def fake_addrs(msg, faked_dev):
-            msg.src = faked_dev if msg.src is self else self
-            msg.dst = faked_dev if msg.dst is self else self
-            return msg
-
-        super()._handle_msg(msg)
-
-        # the following is for aliased devices (not fully-faked devices)
-        if msg.code in (Code._3EF0,) and self._faked_bdr:
-            self._faked_bdr._handle_msg(fake_addrs(msg, self._faked_bdr))
-
-        if msg.code in (Code._0002,) and self._faked_ext:
-            self._faked_ext._handle_msg(fake_addrs(msg, self._faked_ext))
-
-        if msg.code in (Code._30C9,) and self._faked_thm:
-            self._faked_thm._handle_msg(fake_addrs(msg, self._faked_thm))
-
-    def _create_fake_dev(self, dev_type, device_id) -> Device:  # TODO:
-        if device_id[:2] != dev_type:
-            raise TypeError(f"Invalid device ID {device_id} for type '{dev_type}:'")
-
-        # dev = self.device_by_id.get(device_id)
-        # if dev:  # TODO: BUG: is broken
-        #     _LOGGER.warning("Destroying %s", dev)
-        #     if dev._parent:
-        #         del dev._parent.child_by_id[dev.id]
-        #         dev._parent.childs.remove(dev)
-        #         dev._parent = None
-        #     del self.device_by_id[dev.id]
-        #     self.devices.remove(dev)
-        #     dev = None
-
-        # dev = self._gwy.get_device(device_id)
-        # dev._make_fake(bind=True)
-        # return dev
-
-        raise NotImplementedError
-
-    def create_fake_bdr(self, device_id=DEFAULT_BDR_ID) -> Device:
-        """Bind a faked relay (BDR91A) to a controller (i.e. to a domain/zone).
-
-        Will alias the gateway (as "13:888888", TBD), or create a fully-faked 13:.
-
-        HGI80s can only alias one device of a type (use_gateway), but evofw3-based
-        gateways can also fully fake multiple devices of the same type.
-        """
-        if device_id in (self.id, None):
-            device_id = DEFAULT_BDR_ID
-        device = self._create_fake_dev(DEV_TYPE_MAP.BDR, device_id=device_id)
-
-        if device.id == DEFAULT_BDR_ID:
-            self._faked_bdr = device
-        return device
-
-    def create_fake_ext(self, device_id=DEFAULT_EXT_ID) -> Device:
-        """Bind a faked external sensor (???) to a controller.
-
-        Will alias the gateway (as "17:888888", TBD), or create a fully-faked 17:.
-
-        HGI80s can only alias one device of a type (use_gateway), but evofw3-based
-        gateways can also fully fake multiple devices of the same type.
-        """
-
-        if device_id in (self.id, None):
-            device_id = DEFAULT_EXT_ID
-        device = self._create_fake_dev(DEV_TYPE_MAP.OUT, device_id=device_id)
-
-        if device.id == DEFAULT_EXT_ID:
-            self._faked_ext = device
-        return device
-
-    def create_fake_thm(self, device_id=DEFAULT_THM_ID) -> Device:
-        """Bind a faked zone sensor (TR87RF) to a controller (i.e. to a zone).
-
-        Will alias the gateway (as "03:888888", TBD), or create a fully-faked 34:,
-        albeit named "03:xxxxxx".
-
-        HGI80s can only alias one device of a type (use_gateway), but evofw3-based
-        gateways can also fully fake multiple devices of the same type.
-        """
-        if device_id in (self.id, None):
-            device_id = DEFAULT_THM_ID
-        device = self._create_fake_dev(DEV_TYPE_MAP.HCW, device_id=device_id)
-
-        if device.id == DEFAULT_THM_ID:
-            self._faked_thm = device
-        return device
-
     @property
-    def schema(self):
-        return {
-            SZ_DEVICE_ID: self.id,
-            "faked_bdr": self._faked_bdr and self._faked_bdr.id,
-            "faked_ext": self._faked_ext and self._faked_ext.id,
-            "faked_thm": self._faked_thm and self._faked_thm.id,
-        }
-
-
-class Device(Child, DeviceBase):
-    pass
+    def schema(self) -> dict[str, Any]:
+        return {}
 
 
-class DeviceHeat(Device):  # Honeywell CH/DHW or compatible
-    """The base class for Honeywell CH/DHW-compatible devices.
+class DeviceHeat(Device):  # Heat domain: Honeywell CH/DHW or compatible
+    """The base class for the heat domain (Honeywell CH/DHW-compatible devices).
 
     Includes UFH and heatpumps (which can also cool).
     """
 
-    _SLUG: str = DEV_TYPE.HEA  # shouldn't be any of these instantiated
+    _SLUG: str = DevType.HEA  # shouldn't be any of these instantiated
 
-    def __init__(self, gwy, dev_addr, **kwargs):
+    def __init__(self, gwy: Gateway, dev_addr: Address, **kwargs: Any) -> None:
         super().__init__(gwy, dev_addr, **kwargs)
 
         self.ctl = None
@@ -639,7 +450,9 @@ class DeviceHeat(Device):  # Honeywell CH/DHW or compatible
             elif self._iz_controller is False:  # TODO: raise CorruptStateError
                 _LOGGER.error(f"{msg!r} # IS_CONTROLLER (01): was FALSE, now True")
 
-    def _make_tcs_controller(self, *, msg=None, **schema) -> None:  # CH/DHW
+    def _make_tcs_controller(
+        self, *, msg: Message | None = None, **schema: Any
+    ) -> None:  # CH/DHW
         """Attach a TCS (create/update as required) after passing it any msg."""
 
         if self.type not in DEV_TYPE_MAP.CONTROLLERS:  # potentially can be controllers
@@ -655,7 +468,6 @@ class DeviceHeat(Device):  # Honeywell CH/DHW or compatible
 
     @property
     def _is_controller(self) -> None | bool:
-
         if self._iz_controller is not None:
             return bool(self._iz_controller)  # True, False, or msg
 
@@ -665,19 +477,19 @@ class DeviceHeat(Device):  # Honeywell CH/DHW or compatible
         return False
 
     @property
-    def zone(self) -> Optional[Entity]:  # should be: Optional[Zone]
+    def zone(self) -> Zone | None:
         """Return the device's parent zone, if known."""
 
         return self._parent
 
 
-class DeviceHvac(Device):  # HVAC (ventilation, PIV, MV/HR)
-    """The Device base class for HVAC (ventilation, PIV, MV/HR)."""
+class DeviceHvac(Device):  # HVAC domain: ventilation, PIV, MV/HR
+    """The Device base class for the HVAC domain (ventilation, PIV, MV/HR)."""
 
-    _SLUG: str = DEV_TYPE.HVC  # these may be instantiated, and promoted later on
+    _SLUG: str = DevType.HVC  # these may be instantiated, and promoted later on
 
-    def __init__(self, *args, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
+    def __init__(self, gwy: Gateway, dev_addr: Address, **kwargs: Any) -> None:
+        super().__init__(gwy, dev_addr, **kwargs)
 
         self._child_id = "hv"  # TODO: domain_id/deprecate
 
@@ -699,7 +511,6 @@ class DeviceHvac(Device):  # HVAC (ventilation, PIV, MV/HR)
     #     if msg.code in (Code._1298, Code._12A0, Code._22F1, Code._22F3):
     #         self._hvac_trick()
 
-    pass
-
 
-BASE_CLASS_BY_SLUG = class_by_attr(__name__, "_SLUG")  # e.g. "HGI": HgiGateway
+# e.g. {"HGI": HgiGateway}
+BASE_CLASS_BY_SLUG: dict[str, type[Device]] = class_by_attr(__name__, "_SLUG")