ramses-rf 0.52.5__py3-none-any.whl → 0.53.1__py3-none-any.whl

ramses_tx/const.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
-"""RAMSES RF - a RAMSES-II protocol decoder & analyser."""
+"""RAMSES RF - a RAMSES-II protocol decoder & analyser.
+
+This module contains constants, enums, and helper classes used throughout the
+library to decode and encode RAMSES-II protocol packets.
+"""
 
 from __future__ import annotations
 
@@ -15,16 +19,23 @@ DEV_MODE = __dev_mode__
 DEFAULT_DISABLE_QOS: Final[bool | None] = None
 DEFAULT_WAIT_FOR_REPLY: Final[bool | None] = None
 
-DEFAULT_ECHO_TIMEOUT: Final[float] = 0.50  # waiting for echo pkt after cmd sent
-DEFAULT_RPLY_TIMEOUT: Final[float] = 0.50  # waiting for reply pkt after echo pkt rcvd
+#: Waiting for echo pkt after cmd sent (seconds)
+DEFAULT_ECHO_TIMEOUT: Final[float] = 0.50
+
+#: Waiting for reply pkt after echo pkt rcvd (seconds)
+DEFAULT_RPLY_TIMEOUT: Final[float] = 0.50
 DEFAULT_BUFFER_SIZE: Final[int] = 32
 
-DEFAULT_SEND_TIMEOUT: Final[float] = 20.0  # total waiting for successful send: FIXME
-MAX_SEND_TIMEOUT: Final[float] = 20.0  # for a command to be sent, incl. queuing time
+#: Total waiting for successful send (seconds)
+DEFAULT_SEND_TIMEOUT: Final[float] = 20.0
+#: For a command to be sent, incl. queuing time (seconds)
+MAX_SEND_TIMEOUT: Final[float] = 20.0
 
-MAX_RETRY_LIMIT: Final[int] = 3  # for a command to be re-sent (not incl. 1st send)
+#: For a command to be re-sent (not incl. 1st send)
+MAX_RETRY_LIMIT: Final[int] = 3
 
-MIN_INTER_WRITE_GAP: Final[float] = 0.05  # seconds
+#: Minimum gap between writes (seconds)
+MIN_INTER_WRITE_GAP: Final[float] = 0.05
 DEFAULT_GAP_DURATION: Final[float] = MIN_INTER_WRITE_GAP
 DEFAULT_MAX_RETRIES: Final[int] = 3
 DEFAULT_NUM_REPEATS: Final[int] = 0
@@ -139,6 +150,8 @@ SZ_OTC_ACTIVE: Final = "otc_active"
 
 @verify(EnumCheck.UNIQUE)
 class Priority(IntEnum):
+    """Priority levels for protocol messages."""
+
     LOWEST = 4
     LOW = 2
     DEFAULT = 0
@@ -147,31 +160,60 @@ class Priority(IntEnum):
 
 
 def slug(string: str) -> str:
-    """Convert a string to snake_case."""
+    """Convert a string to snake_case.
+
+    :param string: The input string to convert.
+    :return: The string converted to snake_case (lowercase, with non-alphanumerics replaced by underscores).
+    """
     return re.sub(r"[\W_]+", "_", string.lower())
 
 
 # TODO: FIXME: This is a mess - needs converting to StrEnum
 class AttrDict(dict):  # type: ignore[type-arg]
+    """A read-only dictionary that supports dot-access and two-way lookup.
+
+    This class is typically used to map hex codes (keys) to human-readable slugs (values),
+    while also allowing reverse lookup via dot notation (e.g., ``map.SLUG``).
+
+    .. warning::
+        This class is immutable. Attempting to modify it will raise a :exc:`TypeError`.
+    """
+
     _SZ_AKA_SLUG: Final = "_root_slug"
     _SZ_DEFAULT: Final = "_default"
     _SZ_SLUGS: Final = "SLUGS"
 
-    @classmethod
-    def __readonly(cls, *args: Any, **kwargs: Any) -> NoReturn:
-        raise TypeError(f"'{cls.__class__.__name__}' object is read only")
+    def _readonly(self, *args: Any, **kwargs: Any) -> NoReturn:
+        """Raise TypeError for read-only operations."""
+        raise TypeError(f"'{self.__class__.__name__}' object is read only")
+
+    def __setitem__(self, key: Any, value: Any) -> NoReturn:
+        self._readonly()
 
-    __delitem__ = __readonly
-    __setitem__ = __readonly
-    clear = __readonly
-    pop = __readonly
-    popitem = __readonly
-    setdefault = __readonly
-    update = __readonly
+    def __delitem__(self, key: Any) -> NoReturn:
+        self._readonly()
 
-    del __readonly
+    def clear(self) -> NoReturn:
+        self._readonly()
+
+    def pop(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._readonly()
+
+    def popitem(self) -> NoReturn:
+        self._readonly()
+
+    def setdefault(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._readonly()
+
+    def update(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._readonly()
 
     def __init__(self, main_table: dict[str, dict], attr_table: dict[str, Any]) -> None:  # type: ignore[type-arg]
+        """Initialize the AttrDict.
+
+        :param main_table: A dictionary mapping keys (usually hex codes) to property dictionaries.
+        :param attr_table: A dictionary of additional attributes to expose on the object.
+        """
         self._main_table = main_table
         self._attr_table = attr_table
         self._attr_table[self._SZ_SLUGS] = tuple(sorted(main_table.keys()))
@@ -234,10 +276,17 @@ class AttrDict(dict):  # type: ignore[type-arg]
             return self._forward[name[1:]]
         elif name.isupper() and name.lower() in self._reverse:  # map.DHW_SENSOR -> "0D"
             return self[name.lower()]
-        return self.__getattribute__(name)
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )
 
     def _hex(self, key: str) -> str:
-        """Return the key/ID (2-byte hex string) of the two-way dict (e.g. '04')."""
+        """Return the key/ID (2-byte hex string) of the two-way dict (e.g. '04').
+
+        :param key: The lookup key (can be slug or code).
+        :raises KeyError: If the key is not found.
+        :return: The 2-byte hex string identifier.
+        """
         if key in self._main_table:
             return list(self._main_table[key].keys())[0]  # type: ignore[no-any-return]
         if key in self._reverse:
@@ -245,7 +294,12 @@ class AttrDict(dict):  # type: ignore[type-arg]
         raise KeyError(key)
 
     def _str(self, key: str) -> str:
-        """Return the value (string) of the two-way dict (e.g. 'radiator_valve')."""
+        """Return the value (string) of the two-way dict (e.g. 'radiator_valve').
+
+        :param key: The lookup key.
+        :raises KeyError: If the key is not found.
+        :return: The human-readable slug string.
+        """
         if key in self._main_table:
             return list(self._main_table[key].values())[0]  # type: ignore[no-any-return]
         if key in self:
@@ -256,14 +310,23 @@ class AttrDict(dict):  # type: ignore[type-arg]
     #     return {k: k for k in super().values()}.values()
 
     def slug(self, key: str) -> str:
-        """WIP: Return master slug for a hex key/ID (e.g. 00 -> 'TRV', not 'TR0')."""
+        """Return master slug for a hex key/ID.
+
+        Example: 00 -> 'TRV' (master), not 'TR0'.
+
+        :param key: The hex key to look up.
+        :return: The master slug.
+        """
         slug_ = self._slug_lookup[key]
         # if slug_ in self._attr_table["_TRANSFORMS"]:
         #     return self._attr_table["_TRANSFORMS"][slug_]
         return slug_  # type: ignore[no-any-return]
 
     def slugs(self) -> tuple[str]:
-        """Return the slugs from the main table."""
+        """Return the slugs from the main table.
+
+        :return: A tuple of all available slugs.
+        """
         return self._attr_table[self._SZ_SLUGS]  # type: ignore[no-any-return]
 
 
@@ -271,6 +334,12 @@ def attr_dict_factory(
     main_table: dict[str, dict],  # type: ignore[type-arg]
     attr_table: dict | None = None,  # type: ignore[type-arg]
 ) -> AttrDict:  # is: SlottedAttrDict
+    """Create a new AttrDict instance with a slotted subclass.
+
+    :param main_table: The primary mapping of codes to slugs.
+    :param attr_table: Optional additional attributes to attach to the instance.
+    :return: An instance of a dynamic AttrDict subclass.
+    """
     if attr_table is None:
         attr_table = {}
 
@@ -295,6 +364,8 @@ def attr_dict_factory(
 # slugs for device/zone entity klasses, used by 0005/000C
 @verify(EnumCheck.UNIQUE)
 class DevRole(StrEnum):
+    """Slugs for device/zone entity classes, used by commands 0005/000C."""
+
     #
     # Generic device/zone classes
     ACT = "ACT"  # Generic heating zone actuator group
@@ -345,6 +416,8 @@ DEV_ROLE_MAP = attr_dict_factory(
 # slugs for device entity types, used in device_ids
 @verify(EnumCheck.UNIQUE)
 class DevType(StrEnum):
+    """Slugs for device entity types, used in device_ids."""
+
     #
     # Promotable/Generic devices
     DEV = "DEV"  # xx: Promotable device
@@ -457,6 +530,8 @@ DEV_TYPE_MAP = attr_dict_factory(
 
 # slugs for zone entity klasses, used by 0005/000C
 class ZoneRole(StrEnum):
+    """Slugs for zone entity classes, used by commands 0005/000C."""
+
     #
     # Generic device/zone classes
     ACT = "ACT"  # Generic heating zone actuator group
@@ -645,6 +720,8 @@ MESSAGE_REGEX = re.compile(f"^{r} {v} {r} {d} {d} {d} {c} {l} {p}$")
 
 # Used by 0418/system_fault parser
 class FaultDeviceClass(StrEnum):
+    """Device classes for system faults."""
+
     CONTROLLER = "controller"
     SENSOR = "sensor"
     SETPOINT = "setpoint"
@@ -666,6 +743,8 @@ FAULT_DEVICE_CLASS: Final[dict[str, FaultDeviceClass]] = {
 
 
 class FaultState(StrEnum):
+    """States for system faults."""
+
     FAULT = "fault"
     RESTORE = "restore"
     UNKNOWN_C0 = "unknown_c0"
@@ -680,6 +759,8 @@ FAULT_STATE: Final[dict[str, FaultState]] = {  # a bitmap?
 
 
 class FaultType(StrEnum):
+    """Types of system faults."""
+
     SYSTEM_FAULT = "system_fault"
     MAINS_LOW = "mains_low"
     BATTERY_LOW = "battery_low"
@@ -703,6 +784,8 @@ FAULT_TYPE: Final[dict[str, FaultType]] = {
 
 
 class SystemType(StrEnum):
+    """System types (e.g. Evohome, Hometronics)."""
+
     CHRONOTHERM = "chronotherm"
     EVOHOME = "evohome"
     HOMETRONICS = "hometronics"
@@ -742,6 +825,8 @@ FAN_RATE: Final = "fan_rate"  # percentage, 0.0 - 1.0  # deprecated, use SZ_FAN_
 # Below, verbs & codes - can use Verb/Code/Index for mypy type checking
 @verify(EnumCheck.UNIQUE)
 class VerbT(StrEnum):
+    """Protocol verbs (message types)."""
+
     I_ = " I"
     RQ = "RQ"
     RP = "RP"
@@ -756,6 +841,8 @@ W_: Final = VerbT.W_
 
 @verify(EnumCheck.UNIQUE)
 class MsgId(StrEnum):
+    """Message identifiers."""
+
     _00 = "00"
     _03 = "03"
     _06 = "06"
@@ -791,6 +878,8 @@ class MsgId(StrEnum):
 # StrEnum is intended to include all known codes, see: test suite, code schema in ramses.py
 @verify(EnumCheck.UNIQUE)
 class Code(StrEnum):
+    """Protocol command codes."""
+
     _0001 = "0001"
     _0002 = "0002"
     _0004 = "0004"

ramses_tx/gateway.py

@@ -114,7 +114,9 @@ class Engine:
             self._include,
             self._exclude,
         )
-        self._sqlite_index = kwargs.pop(SZ_SQLITE_INDEX, False)  # default True?
+        self._sqlite_index = kwargs.pop(
+            SZ_SQLITE_INDEX, False
+        )  # TODO Q1 2026: default True
         self._log_all_mqtt = kwargs.pop(SZ_LOG_ALL_MQTT, False)
         self._kwargs: dict[str, Any] = kwargs  # HACK
 

ramses_tx/helpers.py

@@ -149,7 +149,7 @@ def timestamp() -> float:
 
 
 def dt_now() -> dt:
-    """Return the current datetime as a local/naive datetime object.
+    """Get the current datetime as a local/naive datetime object.
 
     This is slower, but potentially more accurate, than dt.now(), and is used mainly for
     packet timestamps.

ramses_tx/message.py

@@ -70,22 +70,24 @@ class MessageBase:
         self.verb: VerbT = pkt.verb
         self.seqn: str = (
             pkt.seqn
-        )  # the msg is part of a set for 1 Code, received in order
+        )  # the msg is part of a set for a Code, received in order
         self.code: Code = pkt.code
         self.len: int = pkt._len
 
-        self._payload = self._validate(
-            self._pkt.payload
-        )  # ? may raise InvalidPacketError
+        self._payload = self._validate(self._pkt.payload)  # ? may raise PacketInvalid
 
         self._str: str = None  # type: ignore[assignment]
 
     def __repr__(self) -> str:
-        """Return an unambiguous string representation of this object."""
+        """
+        :return: an unambiguous string representation of this object.
+        """
         return str(self._pkt)  # repr or str?
 
     def __str__(self) -> str:
-        """Return a brief readable string representation of this object."""
+        """
+        :return: a brief readable string representation of this object.
+        """
 
         def ctx(pkt: Packet) -> str:
             ctx = {True: "[..]", False: "", None: "??"}.get(pkt._ctx, pkt._ctx)  # type: ignore[arg-type]
@@ -128,17 +130,22 @@ class MessageBase:
         return self.dtm < other.dtm
 
     def _name(self, addr: Address) -> str:
-        """Return a friendly name for an Address, or a Device."""
+        """
+        :return: a friendly name for an Address, or a Device.
+        """
         return f" {addr.id}"  # can't do 'CTL:123456' instead of ' 01:123456'
 
     @property
     def payload(self):  # type: ignore[no-untyped-def]  # FIXME -> dict | list:
-        """Return the payload."""
+        """
+        :return: the payload.
+        """
         return self._payload
 
     @property
     def _has_payload(self) -> bool:
-        """Return False if there is no payload (may falsely Return True).
+        """
+        :return: False if there is no payload (may falsely return True).
 
         The message (i.e. the raw payload) may still have an idx.
         """
@@ -234,7 +241,7 @@ class MessageBase:
             return {}
 
         # TODO: also 000C (but is a complex idx)
-        # TODO: also 3150 (when not domain, and will be array if so)
+        # TODO: also 3150 (when not domain; will be array in that case)
         if self.code in (Code._000A, Code._2309) and self.src.type == DEV_TYPE_MAP.UFC:
             assert isinstance(self._pkt._idx, str)  # mypy hint
             return {IDX_NAMES[Code._22C9]: self._pkt._idx}
@@ -250,7 +257,7 @@ class MessageBase:
         """Validate a message packet payload, and parse it if valid.
 
         :return: a dict containing key: value pairs, or a list of those created from the payload
-        :raises an InvalidPacketError exception if it is not valid.
+        :raises PacketInvalid exception if it is not valid.
         """
 
         try:  # parse the payload
@@ -292,7 +299,7 @@ class MessageBase:
 
 
 class Message(MessageBase):
-    """Extend the Message class, so is useful to a stateful Gateway.
+    """Extend the Message class, so it is useful to a stateful Gateway.
 
     Adds _expired attr to the Message class.
     """
@@ -303,7 +310,7 @@ class Message(MessageBase):
     # .HAS_DIED = 1.0  # fraction_expired >= 1.0 (is expected lifespan)
     IS_EXPIRING = 0.8  # fraction_expired >= 0.8 (and < HAS_EXPIRED)
 
-    _gwy: Gateway
+    _gwy: Gateway | None = None
     _fraction_expired: float | None = None
 
     @classmethod
@@ -318,13 +325,19 @@ class Message(MessageBase):
 
     @property
     def _expired(self) -> bool:
-        """Return True if the message is dated (or False otherwise)."""
+        """
+        :return: True if the message is dated, False otherwise
+        """
         # fraction_expired = (dt_now - self.dtm - _TD_SECONDS_003) / self._pkt._lifespan
         # TODO: keep none >7d, even 10E0, etc.
 
         def fraction_expired(lifespan: td) -> float:
-            """Return the packet's age as fraction of its 'normal' life span."""
-            return (self._gwy._dt_now() - self.dtm - _TD_SECS_003) / lifespan
+            """
+            :return: the packet's age as fraction of its 'normal' life span.
+            """
+            if self._gwy:  # self._gwy is set in ramses_tx.gateway.Engine._msg_handler
+                return (self._gwy._dt_now() - self.dtm - _TD_SECS_003) / lifespan
+            return (dt.now() - self.dtm - _TD_SECS_003) / lifespan
 
         # 1. Look for easy win...
         if self._fraction_expired is not None:

ramses_tx/parsers.py

@@ -3291,13 +3291,13 @@ def parser_3220(payload: str, msg: Message) -> dict[str, Any]:
         "FFFF",
     ), f"OpenTherm: Invalid msg-type|data-value: {ot_type}|{payload[6:10]}"
 
-    # HACK: These OT data id can pop in/out of 47AB, which is an invalid value
+    # HACK: These OT data id's can pop in/out of 47AB, which is an invalid value
     if payload[6:] == "47AB" and ot_id in (0x12, 0x13, 0x19, 0x1A, 0x1B, 0x1C):
         ot_value[SZ_VALUE] = None
     # HACK: This OT data id can be 1980, which is an invalid value
     if payload[6:] == "1980" and ot_id:  # CH pressure is 25.5 bar!
         ot_value[SZ_VALUE] = None
-    # HACK: Done above, not in OT.decode_frame() as they isn't in the OT specification
+    # HACK: Done above, not in OT.decode_frame() as values aren't in the OT specification
 
     if ot_type not in _LIST:
         assert ot_type in (

ramses_tx/protocol.py

@@ -251,21 +251,30 @@ class _BaseProtocol(asyncio.Protocol):
 
         # FIX: Patch command with actual HGI ID if it uses the default placeholder
         # NOTE: HGI80s (TI 3410) require the default ID (18:000730), or they will silent-fail
+
         if (
-            self._active_hgi
+            self.hgi_id
             and self._is_evofw3  # Only patch if using evofw3 (not HGI80)
             and cmd._addrs[0].id == HGI_DEV_ADDR.id
-            and self._active_hgi != HGI_DEV_ADDR.id
+            and self.hgi_id != HGI_DEV_ADDR.id
         ):
             # The command uses the default 18:000730, but we know the real ID.
             # Reconstruct the command string with the correct address.
 
+            _LOGGER.debug(
+                f"Patching command with active HGI ID: swapped {HGI_DEV_ADDR.id} -> {self.hgi_id} for {cmd._hdr}"
+            )
+
+            # Get current addresses as strings
+            # The command uses the default 18:000730, but we know the real ID.
+            # Reconstruct the command string with the correct address.
+
             # Get current addresses as strings
             new_addrs = [a.id for a in cmd._addrs]
 
             # ONLY patch the Source Address (Index 0).
             # Leave Dest (Index 1/2) alone to avoid breaking tests that expect 18:000730 there.
-            new_addrs[0] = self._active_hgi
+            new_addrs[0] = self.hgi_id
 
             new_frame = f"{cmd.verb} {cmd.seqn} {new_addrs[0]} {new_addrs[1]} {new_addrs[2]} {cmd.code} {int(cmd.len_):03d} {cmd.payload}"
             cmd = Command(new_frame)
@@ -349,6 +358,7 @@ class _BaseProtocol(asyncio.Protocol):
         """
 
         if self._msg_handler:  # type: ignore[truthy-function]
+            _LOGGER.debug(f"Dispatching valid message to handler: {msg}")
             self._loop.call_soon_threadsafe(self._msg_handler, msg)
         for callback in self._msg_handlers:
             # TODO: if handler's filter returns True:
@@ -389,9 +399,10 @@ class _DeviceIdFilterMixin(_BaseProtocol):
     def hgi_id(self) -> DeviceIdT:
         if not self._transport:
             return self._known_hgi or HGI_DEV_ADDR.id
-        return self._transport.get_extra_info(  # type: ignore[no-any-return]
-            SZ_ACTIVE_HGI, self._known_hgi or HGI_DEV_ADDR.id
-        )
+        # CRITICAL FIX: get_extra_info returns None if key exists but val is None
+        # We must ensure we fallback to the known HGI or default if it returns None
+        hgi = self._transport.get_extra_info(SZ_ACTIVE_HGI)
+        return hgi or self._known_hgi or HGI_DEV_ADDR.id
 
     @staticmethod
     def _extract_known_hgi_id(
@@ -434,7 +445,10 @@ class _DeviceIdFilterMixin(_BaseProtocol):
 
         known_hgi = (explicit_hgis if explicit_hgis else implicit_hgis)[0]
 
-        if include_list[known_hgi].get(SZ_CLASS) != DevType.HGI:
+        if include_list[known_hgi].get(SZ_CLASS) not in (
+            DevType.HGI,
+            DEV_TYPE_MAP[DevType.HGI],
+        ):
             logger(
                 f"The {SZ_KNOWN_LIST} SHOULD include exactly one gateway (HGI): "
                 f"{known_hgi} should specify 'class: HGI', as 18: is also used for HVAC"
@@ -866,7 +880,7 @@ async def create_stack(
     )
 
     transport: RamsesTransportT = await (transport_factory_ or transport_factory)(  # type: ignore[operator]
-        protocol, disable_sending=disable_sending, **kwargs
+        protocol, disable_sending=bool(disable_sending), **kwargs
     )
 
     if not kwargs.get(SZ_PORT_NAME):

ramses_tx/protocol_fsm.py

@@ -146,9 +146,13 @@ class ProtocolContext:
             self._multiplier = min(3, old_val + 1)
 
             if isinstance(self._state, WantEcho):
-                _LOGGER.warning("TOUT.. = %s: echo_timeout=%s", self, delay)
+                _LOGGER.warning(
+                    f"Timeout expired waiting for echo: {self} (delay={delay})"
+                )
             else:  # isinstance(self._state, WantRply):
-                _LOGGER.warning("TOUT.. = %s: rply_timeout=%s", self, delay)
+                _LOGGER.warning(
+                    f"Timeout expired waiting for reply: {self} (delay={delay})"
+                )
 
             assert isinstance(self.is_sending, bool), (
                 f"{self}: Coding error"
@@ -197,8 +201,16 @@ class ProtocolContext:
         #  _fut.cancel() (incl. via a send_cmd(qos.timeout) -> wait_for(timeout))
 
         # Changing the order of the following is fraught with danger
+        # Formatitng: [TRACE_FSM] [State: Old->New] [Reason] | ...
+
+        current_state_name = self._state.__class__.__name__
+        new_state_name = state_class.__name__
+        transition = f"{current_state_name}->{new_state_name}"
+
         if self._fut is None:  # logging only - IsInIdle, Inactive
-            _LOGGER.debug("BEFORE = %s", self)
+            _LOGGER.debug(
+                f"FSM state changed {transition}: no active future (ctx={self})"
+            )
             assert self._cmd is None, f"{self}: Coding error"  # mypy hint
             assert isinstance(self._state, IsInIdle | Inactive | None), (
                 f"{self}: Coding error"
@@ -207,14 +219,18 @@ class ProtocolContext:
         elif self._fut.cancelled() and not isinstance(self._state, IsInIdle):
             # cancelled by wait_for(timeout), cancel("buffer overflow"), or other?
             # was for previous send_cmd if currently IsInIdle (+/- Inactive?)
-            _LOGGER.debug("BEFORE = %s: expired=%s (global)", self, expired)
+            _LOGGER.debug(
+                f"FSM state changed {transition}: future cancelled (expired={expired}, ctx={self})"
+            )
             assert self._cmd is not None, f"{self}: Coding error"  # mypy hint
             assert isinstance(self._state, WantEcho | WantRply), (
                 f"{self}: Coding error"
             )  # mypy hint
 
         elif exception:
-            _LOGGER.debug("BEFORE = %s: exception=%s", self, exception)
+            _LOGGER.debug(
+                f"FSM state changed {transition}: exception occurred (error={exception}, ctx={self})"
+            )
             assert not self._fut.done(), (
                 f"{self}: Coding error ({self._fut})"
             )  # mypy hint
@@ -224,7 +240,9 @@ class ProtocolContext:
             self._fut.set_exception(exception)  # apologise to the sender
 
         elif result:
-            _LOGGER.debug("BEFORE = %s: result=%s", self, result._hdr)
+            _LOGGER.debug(
+                f"FSM state changed {transition}: result received (result={result._hdr}, ctx={self})"
+            )
             assert not self._fut.done(), (
                 f"{self}: Coding error ({self._fut})"
             )  # mypy hint
@@ -234,7 +252,7 @@ class ProtocolContext:
             self._fut.set_result(result)
 
         elif expired:  # by expire_state_on_timeout(echo_timeout/reply_timeout)
-            _LOGGER.debug("BEFORE = %s: expired=%s", self, expired)
+            _LOGGER.debug(f"FSM state changed {transition}: timer expired (ctx={self})")
             assert not self._fut.done(), (
                 f"{self}: Coding error ({self._fut})"
             )  # mypy hint
@@ -246,7 +264,7 @@ class ProtocolContext:
             )
 
         else:  # logging only - WantEcho, WantRply
-            _LOGGER.debug("BEFORE = %s", self)
+            _LOGGER.debug(f"FSM state changed {transition}: successful (ctx={self})")
             assert self._fut is None or self._fut.cancelled() or not self._fut.done(), (
                 f"{self}: Coding error ({self._fut})"
             )  # mypy hint
@@ -281,11 +299,11 @@ class ProtocolContext:
         self._loop.call_soon_threadsafe(effect_state, timed_out)  # calls expire_state
 
         if not isinstance(self._state, WantRply):
-            _LOGGER.debug("AFTER. = %s", self)
+            # _LOGGER.debug("AFTER. = %s", self)
             return
 
         assert self._qos is not None, f"{self}: Coding error"  # mypy hint
-        _LOGGER.debug("AFTER. = %s: wait_for_reply=%s", self, self._qos.wait_for_reply)
+        # _LOGGER.debug("AFTER. = %s: wait_for_reply=%s", self, self._qos.wait_for_reply)
 
     def connection_made(self, transport: RamsesTransportT) -> None:
         # may want to set some instance variables, according to type of transport

ramses_tx/schemas.py

@@ -294,7 +294,7 @@ def sch_global_traits_dict_factory(
     )
     SCH_TRAITS_HEAT = SCH_TRAITS_HEAT.extend(
         heat_traits,
-        extra=vol.PREVENT_EXTRA if heat_traits else vol.REMOVE_EXTRA,
+        extra=vol.PREVENT_EXTRA,  # Always prevent extra keys
     )
 
     # NOTE: voluptuous doesn't like StrEnums, hence str(s)
@@ -314,7 +314,7 @@ def sch_global_traits_dict_factory(
     )
     SCH_TRAITS_HVAC = SCH_TRAITS_HVAC.extend(
         hvac_traits,
-        extra=vol.PREVENT_EXTRA if hvac_traits else vol.REMOVE_EXTRA,
+        extra=vol.PREVENT_EXTRA,  # Always prevent extra keys
     )
 
     SCH_TRAITS = vol.Any(