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

{ramses_rf/protocol → ramses_tx}/frame.py

@@ -1,22 +1,22 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
 Provide the base class for commands (constructed/sent packets) and packets.
 """
+
 from __future__ import annotations
 
 import logging
+from typing import TYPE_CHECKING
 
-from .address import NON_DEV_ADDR, NUL_DEV_ADDR, Address, pkt_addrs
-from .const import COMMAND_REGEX, DEV_ROLE_MAP, DEV_TYPE_MAP, __dev_mode__
-from .exceptions import InvalidPacketError, InvalidPayloadError
+from . import exceptions as exc
+from .address import ALL_DEV_ADDR, NON_DEV_ADDR, Address, pkt_addrs
+from .const import COMMAND_REGEX, DEV_ROLE_MAP, DEV_TYPE_MAP
 from .ramses import (
-    CODE_IDX_COMPLEX,
+    CODE_IDX_ARE_COMPLEX,
+    CODE_IDX_ARE_NONE,
+    CODE_IDX_ARE_SIMPLE,
     CODE_IDX_DOMAIN,
-    CODE_IDX_NONE,
-    CODE_IDX_SIMPLE,
     CODES_ONLY_FROM_CTL,
     CODES_SCHEMA,
     CODES_WITH_ARRAYS,
@@ -25,34 +25,31 @@ from .ramses import (
 
 # TODO: add _has_idx (as func return only one type, or raise)
 
-
-# skipcq: PY-W2000
 from .const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     I_,
     RP,
     RQ,
     W_,
+    Code,
+)
+from .const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     F8,
     F9,
     FA,
     FC,
     FF,
-    Code,
 )
 
+if TYPE_CHECKING:
+    from .const import VerbT
 
-DEV_MODE = __dev_mode__ and False
 
 _LOGGER = logging.getLogger(__name__)
-if DEV_MODE:
-    _LOGGER.setLevel(logging.DEBUG)
 
 
-_CodeT = str
-_DeviceIdT = str
-_HeaderT = str
-_PayloadT = str
-_VerbT = str
+HeaderT = str
+PayloadT = str
+_PktIdxT = str
 
 
 class Frame:
@@ -61,17 +58,9 @@ class Frame:
     `RQ --- 01:078710 10:067219 --:------ 3220 005 0000050000`
     """
 
-    _frame: str
-
-    verb: _VerbT
-    seqn: str  # TODO: or, better as int?
-    src: Address
-    dst: Address
+    src: Address  # Address | Device
+    dst: Address  # Address | Device
     _addrs: tuple[Address, Address, Address]
-    code: _CodeT
-    len_: str
-    _len: int  # int(len(payload) / 2)
-    payload: _PayloadT
 
     def __init__(self, frame: str) -> None:
         """Create a frame from a string.
@@ -79,30 +68,28 @@ class Frame:
         Will raise InvalidPacketError if it is invalid.
         """
 
-        self._frame = frame
-        if not isinstance(self._frame, str):
-            raise InvalidPacketError(f"Bad frame: not a string: {type(self._frame)}")
+        self._frame: str = frame
         if not COMMAND_REGEX.match(self._frame):
-            raise InvalidPacketError("Bad frame: invalid structure")
+            raise exc.PacketInvalid(f"Bad frame: invalid structure: >>>{frame}<<<")
 
         fields = frame.lstrip().split(" ")
 
-        self.verb = frame[:2]  # cant use fields[0] as leading space ' I'
-        self.seqn = fields[1]  # frame[3:6]
-        self.code = fields[5]  # frame[37:41]
-        self.len_ = fields[6]  # frame[42:45]
-        self.payload = fields[7]  # frame[46:].split(" ")[0]
-        self._len = int(len(self.payload) / 2)
+        self.verb: VerbT = frame[:2]  # type: ignore[assignment]
+        self.seqn: str = fields[1]  # . frame[3:6]
+        self.code: Code = fields[5]  # type: ignore[assignment]
+        self.len_: str = fields[6]  # . frame[42:45]  FIXME: len_, _len & len(payload)/2
+        self.payload: PayloadT = fields[7]  # frame[46:].split(" ")[0]
+        self._len: int = int(len(self.payload) / 2)
 
         try:
             self.src, self.dst, *self._addrs = pkt_addrs(  # type: ignore[assignment]
                 " ".join(fields[i] for i in range(2, 5))  # frame[7:36]
             )
-        except InvalidPacketError as exc:  # will be: InvalidAddrSetError
-            raise InvalidPacketError(f"Bad frame: invalid address set {exc}")
+        except exc.PacketInvalid as err:  # will be: InvalidAddrSetError
+            raise exc.PacketInvalid("Bad frame: invalid address set") from err
 
         if len(self.payload) != int(self.len_) * 2:
-            raise InvalidPacketError(
+            raise exc.PacketInvalid(
                 f"Bad frame: invalid payload: "
                 f"len({self.payload}) is not int('{self.len_}' * 2))"
             )
@@ -115,54 +102,46 @@ class Frame:
         self._has_ctl_: bool = None  # type: ignore[assignment]  # TODO: remove
         self._has_payload_: bool = None  # type: ignore[assignment]
 
-        self._repr = None
-
-    @classmethod  # for internal use only
-    def _from_attrs(
-        cls, verb: _VerbT, *addrs, code: _CodeT, payload: _PayloadT, seqn=None
-    ):
-        """Create a frame from its attributes (args, kwargs)."""
+        self._repr: str = None  # type: ignore[assignment]
 
-        seqn = seqn or "---"
-        len_ = f"{int(len(payload) / 2):03d}"
-
-        try:
-            return cls(" ".join((verb, seqn, *addrs, code, len_, payload)))
-        except TypeError as exc:
-            raise InvalidPacketError(f"Bad frame: invalid attr: {exc}")
-
-    def _validate(self, *, strict_checking: bool = None) -> None:
+    # FIXME: this is messy
+    def _validate(self, *, strict_checking: bool = False) -> None:
         """Validate the frame: it may be a cmd or a (response) pkt.
 
         Raise an exception InvalidPacketError (InvalidAddrSetError) if it is not valid.
         """
 
-        if (seqn := self._frame[3:6]) == "...":
-            raise InvalidPacketError(f"Bad frame: deprecated seqn: {seqn}")
-
-        if not strict_checking:
-            return
-
         if len(self._frame[46:].split(" ")[0]) != int(self._frame[42:45]) * 2:
-            raise InvalidPacketError("Bad frame: payload length mismatch")
+            raise exc.PacketInvalid("Bad frame: Payload length mismatch")
 
         try:
-            self.src, self.dst, *self._addrs = pkt_addrs(self._frame[7:36])  # type: ignore[assignment]
-        except InvalidPacketError as exc:  # will be: InvalidAddrSetError
-            raise InvalidPacketError(f"Bad frame: invalid address set: {exc}")
+            # self.src, self.dst, *self._addrs = pkt_addrs(self._frame[7:36])
+            src, dst, *addrs = pkt_addrs(self._frame[7:36])
+        except exc.PacketInvalid as err:  # will be: InvalidAddrSetError
+            raise exc.PacketInvalid("Bad frame: Invalid address set") from err
 
-        if True:  # below is done at a higher layer
+        if not strict_checking:
             return
 
-        if (code := self._frame[37.41]) not in CODES_SCHEMA:
-            raise InvalidPacketError(f"Bad frame: unknown code: {code}")
+        try:  # Strict checking: helps users avoid to constructing bad commands
+            if addrs[0] == NON_DEV_ADDR:
+                assert self.verb == I_, "wrong verb or dst addr should be present"
+            elif addrs[2] == NON_DEV_ADDR:
+                assert self.verb == I_ or src is not dst, (
+                    "wrong verb or dst addr should not be src"
+                )
+            elif addrs[0] is addrs[2]:
+                assert self.verb == I_, "wrong verb or dst addr should not be src"
+            else:
+                assert self.verb in (I_, W_), "wrong verb or dst addr should be src"
+        except AssertionError as err:
+            raise exc.PacketInvalid(f"Bad frame: Invalid address set: {err}") from err
 
     def __repr__(self) -> str:
         """Return a unambiguous string representation of this object."""
-        # repr(self) == repr(cls(repr(self)))
 
         if self._repr is None:
-            self._repr = " ".join(
+            self._repr = " ".join(  # type: ignore[unreachable]
                 (
                     self.verb,
                     self.seqn,
@@ -180,8 +159,13 @@ class Frame:
 
         try:
             return f"{self!r} # {self._hdr}"  # code|ver|device_id|context
-        except AttributeError as exc:
-            return f"{self!r} < {exc}"
+        except AttributeError as err:
+            return f"{self!r} < {err}"
+
+    def __eq__(self, other: object) -> bool:
+        if not hasattr(other, "_frame"):
+            return NotImplemented
+        return self._frame[4:] == other._frame[4:]  # type: ignore[no-any-return]
 
     @property
     def _has_array(self) -> None | bool:  # TODO: a mess - has false negatives
@@ -193,7 +177,7 @@ class Frame:
         2309/30C9/000A packets).
         """
 
-        if self._has_array_ is not None:  # HACK: overriden by detect_array(msg, prev)
+        if self._has_array_ is not None:  # HACK: overridden by detect_array(msg, prev)
             return self._has_array_
 
         # False -ves (array length is 1) are an acceptable compromise to extensive checking
@@ -202,7 +186,7 @@ class Frame:
         # .I --- 01:145038 --:------ 01:145038 1FC9 018 07000806368E-FC3B0006368E-071FC906368E
         # .I --- 01:145038 --:------ 01:145038 1FC9 018 FA000806368E-FC3B0006368E-FA1FC906368E
         # .I --- 34:092243 --:------ 34:092243 1FC9 030 0030C9896853-002309896853-001060896853-0010E0896853-001FC9896853
-        if self.code == Code._1FC9:
+        if self.code == Code._1FC9:  # type: ignore[unreachable]
             self._has_array_ = self.verb != RQ  # safe to treat all as array, even len=1
             return self._has_array_  # don't do any checks for 1FC9 (they will fail)
 
@@ -230,9 +214,9 @@ class Frame:
         if self._has_array_:
             len_ = CODES_WITH_ARRAYS[self.code][0]
 
-            assert (
-                self._len % len_ == 0
-            ), f"{self} < array has length ({self._len}) that is not multiple of {len_}"
+            assert self._len % len_ == 0, (
+                f"{self} < array has length ({self._len}) that is not multiple of {len_}"
+            )
             assert (
                 self.src.type in (DEV_TYPE_MAP.DTS, DEV_TYPE_MAP.DT2)
                 or self.src == self.dst  # DEX
@@ -259,12 +243,17 @@ class Frame:
     def _has_ctl(self) -> None | bool:
         """Return True if the packet is to/from a controller."""
 
+        # NB: the difference between these (_has_ctl, src, dst, -:-) and above (_has_ctl, src, -:-, src)
+        # 2000-01-01T03:00:00.000000 ...  I --- 37:123456 --:------ 37:123456 31DA 030 00C8400518646427102AF82EE031FFFFFFC800C8C83FFF64640AFF0AFF00
+        # 2022-11-20T08:32:06.904058 063 RP --- 32:134446 37:171685 --:------ 31DA 030 00EF007FFF2F1B0226069A07EEFFE4F8000038988F0000EFEF1F2420FC00
+        # Maybe only use this for CH/DHW, and not HVAC?
+
         if self._has_ctl_ is not None:
             return self._has_ctl_
 
         # TODO: handle RQ/RP to/from HGI/RFG, handle HVAC
 
-        if {self.src.type, self.dst.type} & {
+        if {self.src.type, self.dst.type} & {  # type: ignore[unreachable]
             DEV_TYPE_MAP.CTL,
             DEV_TYPE_MAP.UFC,
             DEV_TYPE_MAP.PRG,
@@ -317,12 +306,13 @@ class Frame:
 
         # .I --- 34:021943 63:262142 --:------ 10E0 038 000001C8380A01... # unknown
         # .I --- 32:168090 30:082155 --:------ 31E0 004 0000C800          # unknown
+
         if self._has_ctl_ is None:
-            if DEV_MODE and DEV_TYPE_MAP.HGI not in (
-                self.src.type,
-                self.dst.type,
-            ):  # DEX
-                _LOGGER.warning(f"{self} # has_ctl - undetermined (99)")
+            # if DEV_MODE and DEV_TYPE_MAP.HGI not in (
+            #     self.src.type,
+            #     self.dst.type,
+            # ):  # DEX
+            #     _LOGGER.warning(f"{self} # has_ctl - undetermined (99)")
             self._has_ctl_ = False
 
         return self._has_ctl_
@@ -343,7 +333,7 @@ class Frame:
         if self._has_payload_ is not None:
             return self._has_payload_
 
-        self._has_payload_ = not any(
+        self._has_payload_ = not any(  # type: ignore[unreachable]
             (
                 self._len == 1,
                 self.verb == RQ and self.code in RQ_NO_PAYLOAD,
@@ -381,44 +371,51 @@ class Frame:
         Used to store packets in the entity's message DB. It is a superset of _idx.
         """
 
-        if self._ctx_ is None:
-            if self.code in (
-                Code._0005,
-                Code._000C,
-            ):  # zone_idx, zone_type (device_role)
-                self._ctx_ = self.payload[:4]
-            elif self.code == Code._0404:  # zone_idx, frag_idx
-                self._ctx_ = self._idx + self.payload[10:12]
-            else:
-                self._ctx_ = self._idx
+        if self._ctx_ is not None:
+            return self._ctx_
+
+        if self.code in (  # type: ignore[unreachable]
+            Code._0005,
+            Code._000C,
+        ):  # zone_idx, zone_type (device_role)
+            self._ctx_ = self.payload[:4]
+        elif self.code == Code._0404:  # zone_idx, frag_idx
+            self._ctx_ = self._idx + self.payload[10:12]
+        else:
+            self._ctx_ = self._idx
         return self._ctx_
 
     @property
-    def _hdr(self) -> _HeaderT:  # incl. self._ctx
+    def _hdr(self) -> HeaderT:  # incl. self._ctx
         """Return the QoS header (fingerprint) of this packet (i.e. device_id/code/hdr).
 
         Used for QoS (timeouts, retries), callbacks, etc.
         """
 
-        if self._hdr_ is None:
-            self._hdr_ = "|".join((self.code, self.verb))  # HACK: RecursionError
-            self._hdr_ = pkt_header(self)
+        if self._hdr_ is not None:
+            return self._hdr_
+
+        # FIXME: HACK: sometimes RecursionError
+        self._hdr_ = "|".join((self.code, self.verb))  # type: ignore[unreachable]
+        self._hdr_ = pkt_header(self)
         return self._hdr_
 
     @property
-    def _idx(self) -> bool | str:
+    def _idx(self) -> bool | str:  # FIXME: a mess
         """Return the payload's index, if any (e.g. zone_idx, domain_id  or log_idx).
 
         Used to route a packet to the correct entity's (i.e. zone/domain) msg handler.
         """
 
-        if self._idx_ is None:
-            self._idx_ = _pkt_idx(self) or False
+        if self._idx_ is not None:
+            return self._idx_
+
+        self._idx_ = _pkt_idx(self) or False  # type: ignore[unreachable]
         return self._idx_
 
 
 # TODO: a mess - has false negatives
-def _pkt_idx(pkt) -> None | bool | str:  # _has_array, _has_ctl
+def _pkt_idx(pkt: Frame) -> None | bool | str:  # _has_array, _has_ctl
     """Return the payload's 2-byte context (e.g. zone_idx, domain_id or log_idx).
 
     May return a 2-byte string (usu. pkt.payload[:2]), or:
@@ -440,14 +437,14 @@ def _pkt_idx(pkt) -> None | bool | str:  # _has_array, _has_ctl
 
     if pkt.code == Code._000C:  # zone_idx/domain_id (complex, payload[0:4])
         if pkt.payload[2:4] == DEV_ROLE_MAP.APP:  # "000F"
-            return FC
+            return str(FC)  # mypy
         if pkt.payload[0:4] == f"01{DEV_ROLE_MAP.HTG}":  # "010E"
-            return F9
+            return str(F9)  # mypy
         if pkt.payload[2:4] in (
             DEV_ROLE_MAP.DHW,
             DEV_ROLE_MAP.HTG,
         ):  # "000D", "000E"
-            return FA
+            return str(FA)  # mypy
         return pkt.payload[:2]
 
     if pkt.code == Code._0404:  # assumes only 1 DHW zone (can be 2, but never seen)
@@ -462,15 +459,16 @@ def _pkt_idx(pkt) -> None | bool | str:  # _has_array, _has_ctl
     if pkt.code == Code._3220:  # msg_id/data_id (payload[4:6])
         return pkt.payload[4:6]
 
-    if pkt.code in CODE_IDX_COMPLEX:
+    if pkt.code in CODE_IDX_ARE_COMPLEX:  # these should be handled above
         raise NotImplementedError(f"{pkt} # CODE_IDX_COMPLEX")  # a coding error
 
     # mutex 1/4, CODE_IDX_NONE: always returns False
-    if pkt.code in CODE_IDX_NONE:  # returns False
-        if CODES_SCHEMA[pkt.code].get(pkt.verb, "")[:3] == "^00" and (
-            pkt.payload[:2] != "00"
+    if pkt.code in CODE_IDX_ARE_NONE:  # returns False
+        if (
+            CODES_SCHEMA[pkt.code].get(pkt.verb, "")[:3] == "^00"
+            and pkt.payload[:2] != "00"
         ):
-            raise InvalidPayloadError(
+            raise exc.PacketPayloadInvalid(
                 f"Packet idx is {pkt.payload[:2]}, but expecting no idx (00) (0xAA)"
             )
         return False
@@ -482,13 +480,13 @@ def _pkt_idx(pkt) -> None | bool | str:  # _has_array, _has_ctl
     # TODO: is this needed?: exceptions to CODE_IDX_SIMPLE
     if pkt.payload[:2] in (F8, F9, FA, FC):  # TODO: F6, F7?, FB, FD
         if pkt.code not in CODE_IDX_DOMAIN:
-            raise InvalidPayloadError(
+            raise exc.PacketPayloadInvalid(
                 f"Packet idx is {pkt.payload[:2]}, but not expecting a domain id"
             )
         return pkt.payload[:2]
 
     if (
-        pkt._has_ctl
+        pkt._has_ctl  # TODO: exclude HVAC?
     ):  # risk of false -ves, TODO: pkt.src.type == DEV_TYPE_MAP.HGI too?  # DEX
         # 02:    22C9: would be picked up as an array, if len==1 counted
         # 03:    # .I 028 03:094242 --:------ 03:094242 30C9 003 010B22  # ctl
@@ -496,15 +494,15 @@ def _pkt_idx(pkt) -> None | bool | str:  # _has_array, _has_ctl
         # 23:    0009|10A0
         return pkt.payload[:2]  # tcs._max_zones checked elsewhere
 
-    # if pkt.code in (Code._31D9,):
-    #     return pkt.payload[:2]
+    if pkt.code in (Code._31D9, Code._31DA):
+        return pkt.payload[:2]
 
     if pkt.payload[:2] != "00":
-        raise InvalidPayloadError(
+        raise exc.PacketPayloadInvalid(
             f"Packet idx is {pkt.payload[:2]}, but expecting no idx (00) (0xAB)"
         )  # TODO: add a test for this
 
-    if pkt.code in CODE_IDX_SIMPLE:
+    if pkt.code in CODE_IDX_ARE_SIMPLE:
         return None  # False  # TODO: return None (less precise) or risk false -ves?
 
     # mutex 4/4, CODE_IDX_UNKNOWN: an unknown code
@@ -512,9 +510,7 @@ def _pkt_idx(pkt) -> None | bool | str:  # _has_array, _has_ctl
     return None
 
 
-def pkt_header(
-    pkt, rx_header: bool = None
-) -> None | _HeaderT:  # NOTE: used in command.py
+def pkt_header(pkt: Frame, /, rx_header: bool = False) -> None | HeaderT:
     """Return the header of a packet (all packets have a header).
 
     Used for QoS, and others.
@@ -532,10 +528,10 @@ def pkt_header(
 
     if pkt.code == Code._1FC9:
         # .I --- 34:021943 --:------ 34:021943 1FC9 024 00-2309-8855B7 00-1FC9-8855B7
-        # .W --- 01:145038 34:021943 --:------ 1FC9 006 00-2309-06368E  # wont know src until it arrives
+        # .W --- 01:145038 34:021943 --:------ 1FC9 006 00-2309-06368E  # won't know src until it arrives
         # .I --- 34:021943 01:145038 --:------ 1FC9 006 00-2309-8855B7
         if not rx_header:
-            device_id = NUL_DEV_ADDR.id if pkt.src == pkt.dst else pkt.dst.id
+            device_id = ALL_DEV_ADDR.id if pkt.src == pkt.dst else pkt.dst.id
             return "|".join((pkt.code, pkt.verb, device_id))
         if pkt.src == pkt.dst:  # and pkt.verb == I_:
             return "|".join((pkt.code, W_, pkt.src.id))
@@ -545,15 +541,20 @@ def pkt_header(
         #     return "|".join((pkt.code, RP, pkt.dst.id))
         return None
 
-    addr = pkt.dst if pkt.src.type == DEV_TYPE_MAP.HGI else pkt.src  # DEX
-    if not rx_header:
-        header = "|".join((pkt.code, pkt.verb, addr.id))
+    # RQ and W use the dst.id rather than the src.id, as:
+    # - cmd.src could be 18:000730, and echo .src will have changed to (say) 18:123456
+    # - cmd.dst is the effector
 
-    elif pkt.verb in (I_, RP) or pkt.src == pkt.dst:  # announcements, etc.: no response
-        return None
+    if rx_header:
+        if pkt.verb in (I_, RP) or pkt.src == pkt.dst:  # say: xxxx| W|00:000000|xx
+            return None  # no response expected
+        header = "|".join((pkt.code, RP if pkt.verb == RQ else I_, pkt.dst.id))
+
+    elif pkt.verb in (I_, RP) or pkt.src == pkt.dst:
+        header = "|".join((pkt.code, pkt.verb, pkt.src.id))
 
-    else:  # RQ/RP, or W/I
-        header = "|".join((pkt.code, RP if pkt.verb == RQ else I_, addr.id))
+    else:
+        header = "|".join((pkt.code, pkt.verb, pkt.dst.id))
 
     try:
         return f"{header}|{pkt._ctx}" if isinstance(pkt._ctx, str) else header