ramses-rf 0.52.0__py3-none-any.whl → 0.52.2__py3-none-any.whl

ramses_rf/__init__.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
+`ramses_rf` takes care of the device (upper) layer.
 
 Works with (amongst others):
 - evohome (up to 12 zones)

ramses_rf/database.py

@@ -1,5 +1,25 @@
 #!/usr/bin/env python3
-"""RAMSES RF - Message database and index."""
+"""
+RAMSES RF - Message database and index.
+
+.. table:: Database Query Methods[^1][#fn1]
+   :widths: auto
+
+   =====  ============  ===========  ==========  ====  ========================
+    ix    method name   args         returns     uses  used by
+   =====  ============  ===========  ==========  ====  ========================
+   i1     get           Msg, kwargs  tuple(Msg)  i3
+   i2     contains      kwargs       bool        i4
+   i3     _select_from  kwargs       tuple(Msg)  i4
+   i4     qry_dtms      kwargs       list(dtm)
+   i5     qry           sql, kwargs  tuple(Msg)        _msgs()
+   i6     qry_field     sql, kwargs  tuple(fld)        e4, e5
+   i7     get_rp_codes  src, dst     list(Code)        Discovery-supported_cmds
+   =====  ============  ===========  ==========  ====  ========================
+
+[#fn1] A word of explanation.
+[^1]: ex = entity_base.py query methods
+"""
 
 from __future__ import annotations
 
@@ -62,9 +82,10 @@ def payload_keys(parsed_payload: list[dict] | dict) -> str:  # type: ignore[type
 
 
 class MessageIndex:
-    """A simple in-memory SQLite3 database for indexing RF messages.
-    Index holds the latest message to & from all devices by header
-    (example of a hdr: 000C|RP|01:223036|0208)."""
+    """A central in-memory SQLite3 database for indexing RF messages.
+    Index holds all the latest messages to & from all devices by `dtm`
+    (timestamp) and `hdr` header
+    (example of a hdr: ``000C|RP|01:223036|0208``)."""
 
     _housekeeping_task: asyncio.Task[None]
 
@@ -72,7 +93,8 @@ class MessageIndex:
         """Instantiate a message database/index."""
 
         self.maintain = maintain
-        self._msgs: MsgDdT = OrderedDict()  # stores all messages for retrieval. Filled & cleaned up in housekeeping_loop.
+        self._msgs: MsgDdT = OrderedDict()  # stores all messages for retrieval.
+        # Filled & cleaned up in housekeeping_loop.
 
         # Connect to a SQLite DB in memory
         self._cx = sqlite3.connect(
@@ -122,16 +144,17 @@ class MessageIndex:
     def _setup_db_schema(self) -> None:
         """Set up the message database schema.
 
-        messages TABLE Fields:
-
-        - dtm  message timestamp
-        - verb " I", "RQ" etc.
-        - src  message origin address
-        - dst  message destination address
-        - code packet code aka command class e.g. _0005, _31DA
-        - ctx  message context, created from payload as index + extra markers (Heat)
-        - hdr  packet header e.g. 000C|RP|01:223036|0208 (see: src/ramses_tx/frame.py)
-        - plk the keys stored in the parsed payload, separated by the | char
+        .. note::
+            messages TABLE Fields:
+
+            - dtm  message timestamp
+            - verb " I", "RQ" etc.
+            - src  message origin address
+            - dst  message destination address
+            - code packet code aka command class e.g. _0005, _31DA
+            - ctx  message context, created from payload as index + extra markers (Heat)
+            - hdr  packet header e.g. 000C|RP|01:223036|0208 (see: src/ramses_tx/frame.py)
+            - plk the keys stored in the parsed payload, separated by the | char
         """
 
         self._cu.execute(
@@ -160,7 +183,7 @@ class MessageIndex:
 
     async def _housekeeping_loop(self) -> None:
         """Periodically remove stale messages from the index,
-        unless self.maintain is False."""
+        unless `self.maintain` is False."""
 
         async def housekeeping(dt_now: dt, _cutoff: td = td(days=1)) -> None:
             """
@@ -196,6 +219,7 @@ class MessageIndex:
         """
         Add a single message to the MessageIndex.
         Logs a warning if there is a duplicate dtm.
+
         :returns: any message that was removed because it had the same header
         """
         # TODO: eventually, may be better to use SqlAlchemy
@@ -224,22 +248,26 @@ class MessageIndex:
             pass  # self._lock.release()
 
         if (
-            dup and msg.src is not msg.src
-        ):  # when src==dst, expect to add duplicate, don't check
-            _LOGGER.warning(
+            dup and msg.src is not msg.dst and not msg.dst.id.startswith("18:")  # HGI
+        ):  # when src==dst, expect to add duplicate, don't warn
+            _LOGGER.debug(
                 "Overwrote dtm (%s) for %s: %s (contrived log?)",
                 msg.dtm,
                 msg._pkt._hdr,
                 dup[0]._pkt,
             )
         if old is not None:
-            _LOGGER.info("Old msg replaced: %s", old)
+            _LOGGER.debug("Old msg replaced: %s", old)
 
         return old
 
     def add_record(self, src: str, code: str = "", verb: str = "") -> None:
         """
-        Add a single record to the MessageIndex with timestamp now() and no Message contents.
+        Add a single record to the MessageIndex with timestamp `now()` and no Message contents.
+
+        :param src: device id to use as source address
+        :param code: device id to use as destination address (can be identical)
+        :param verb: two letter verb str to use
         """
         # Used by OtbGateway init, via entity_base.py
         dtm: DtmStrT = dt.strftime(dt.now(), "%Y-%m-%dT%H:%M:%S")  # type: ignore[assignment]
@@ -274,6 +302,7 @@ class MessageIndex:
     def _insert_into(self, msg: Message) -> Message | None:
         """
         Insert a message into the index.
+
         :returns: any message replaced (by same hdr)
         """
         assert msg._pkt._hdr is not None, "Skipping: Packet has no hdr: {msg._pkt}"
@@ -305,7 +334,7 @@ class MessageIndex:
                 payload_keys(msg.payload),
             ),
         )
-        _LOGGER.info(f"Added {msg} to gwy.msg_db")
+        _LOGGER.debug(f"Added {msg} to gwy.msg_db")
 
         return _old_msgs[0] if _old_msgs else None
 
@@ -348,6 +377,7 @@ class MessageIndex:
 
     def _delete_from(self, **kwargs: bool | dt | str) -> tuple[Message, ...]:
         """Remove message(s) from the index.
+
         :returns: any messages that were removed"""
 
         msgs = self._select_from(**kwargs)
@@ -359,32 +389,14 @@ class MessageIndex:
 
         return msgs
 
-    # MessageIndex msg_db query methods > copy to docs/source/ramses_rf.rst
-    # (ex = entity_base.py query methods
-    #
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | ix |method name   | args        | returns    | uses | used by                  |
-    # +====+==============+=============+============+======+==========================+
-    # | i1 | get          | Msg/kwargs  | tuple[Msg] | i3   |                          |
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | i2 | contains     | kwargs      | bool       | i4   |                          |
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | i3 | _select_from | kwargs      | tuple[Msg] | i4   |                          |
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | i4 | qry_dtms     | kwargs      | list(dtm)  |      |                          |
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | i5 | qry          | sql, kwargs | tuple[Msg] |      | _msgs()                  |
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | i6 | qry_field    | sql, kwargs | tuple[fld] |      | e4, e5                   |
-    # +----+--------------+-------------+------------+------+--------------------------+
-    # | i7 | get_rp_codes | src, dst    | list[Code] |      | Discovery#supported_cmds |
-    # +----+--------------+-------------+------------+------+--------------------------+
+    # MessageIndex msg_db query methods
 
     def get(
         self, msg: Message | None = None, **kwargs: bool | dt | str
     ) -> tuple[Message, ...]:
         """
         Public method to get a set of message(s) from the index.
+
         :param msg: Message to return, by dtm (expect a single result as dtm is unique key)
         :param kwargs: data table field names and criteria, e.g. (hdr=...)
         :return: tuple of matching Messages
@@ -401,6 +413,7 @@ class MessageIndex:
     def contains(self, **kwargs: bool | dt | str) -> bool:
         """
         Check if the MessageIndex contains at least 1 record that matches the provided fields.
+
         :param kwargs: (exact) SQLite table field_name: required_value pairs
         :return: True if at least one message fitting the given conditions is present, False when qry returned empty
         """
@@ -410,6 +423,7 @@ class MessageIndex:
     def _select_from(self, **kwargs: bool | dt | str) -> tuple[Message, ...]:
         """
         Select message(s) using the MessageIndex.
+
         :param kwargs: (exact) SQLite table field_name: required_value pairs
         :returns: a tuple of qualifying messages
         """
@@ -422,6 +436,7 @@ class MessageIndex:
     def qry_dtms(self, **kwargs: bool | dt | str) -> list[Any]:
         """
         Select from the ImageIndex a list of dtms that match the provided arguments.
+
         :param kwargs: data table field names and criteria
         :return: list of unformatted dtms that match, useful for msg lookup, or an empty list if 0 matches
         """
@@ -444,6 +459,7 @@ class MessageIndex:
     def qry(self, sql: str, parameters: tuple[str, ...]) -> tuple[Message, ...]:
         """
         Get a tuple of messages from _msgs using the index, given sql and parameters.
+
         :param sql: a bespoke SQL query SELECT string that should return dtm as first field
         :param parameters: tuple of kwargs with the selection filter
         :return: a tuple of qualifying messages
@@ -468,12 +484,13 @@ class MessageIndex:
             if ts in self._msgs:
                 lst.append(self._msgs[ts])
             else:  # happens in tests with artificial msg from heat
-                _LOGGER.warning("MessageIndex timestamp %s not in device messages", ts)
+                _LOGGER.info("MessageIndex timestamp %s not in device messages", ts)
         return tuple(lst)
 
     def get_rp_codes(self, parameters: tuple[str, ...]) -> list[Code]:
         """
         Get a list of Codes from the index, given parameters.
+
         :param parameters: tuple of additional kwargs
         :return: list of Code: value pairs
         """
@@ -499,6 +516,7 @@ class MessageIndex:
     ) -> list[tuple[dt | str, str]]:
         """
         Get a list of fields from the index, given select sql and parameters.
+
         :param sql: a bespoke SQL query SELECT string
         :param parameters: tuple of additional kwargs
         :return: list of key: value pairs as defined in sql
@@ -529,7 +547,7 @@ class MessageIndex:
                 # if include_expired or not self._msgs[ts].HAS_EXPIRED:  # not working
                 lst.append(self._msgs[ts])
             else:  # happens in tests with dummy msg from heat init
-                _LOGGER.warning("MessageIndex ts %s not in device messages", ts)
+                _LOGGER.info("MessageIndex ts %s not in device messages", ts)
         return tuple(lst)
 
     def clr(self) -> None:

ramses_rf/device/heat.py

@@ -1263,6 +1263,7 @@ class BdrSwitch(Actuator, RelayDemand):  # BDR (13):
     """The BDR class, such as a BDR91.
 
     BDR91s can be used in six distinct modes, including:
+
     - x2 boiler controller (FC/TPI): either traditional, or newer heat pump-aware
     - x1 electric heat zones (0x/ELE)
     - x1 zone valve zones (0x/VAL)

ramses_rf/device/hvac.py

@@ -728,12 +728,15 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
         In HomeAssistant, ramses_cc, you can set a bound device in the device configuration.
 
         System schema and known devices example:
-        "32:153289":
-          bound: "37:168270"
-          class: FAN
-        "37:168270":
-          class: REM
-          faked: true
+
+        .. code-block::
+
+            "32:153289":
+              bound: "37:168270"
+              class: FAN
+            "37:168270":
+              class: REM
+              faked: true
 
         :param device_id: The unique identifier of the device to bind
         :type device_id: str
@@ -927,7 +930,7 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
             """
             res_mode: list = self._msg_qry(sql)
             # SQLite query on MessageIndex
-            _LOGGER.info(f"{res_mode} # FAN_MODE FETCHED from MessageIndex")
+            _LOGGER.debug(f"{res_mode} # FAN_MODE FETCHED from MessageIndex")
 
             sql = f"""
                 SELECT code from messages WHERE verb in (' I', 'RP')
@@ -936,7 +939,7 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
             """
             res_rate: list = self._msg_qry(sql)
             # SQLite query on MessageIndex
-            _LOGGER.info(
+            _LOGGER.debug(
                 f"{res_rate} # FAN_RATE FETCHED from MessageIndex"
             )  # DEBUG always empty?
 
@@ -1142,7 +1145,7 @@ def class_dev_hvac(
 ) -> type[DeviceHvac]:
     """Return a device class, but only if the device must be from the HVAC group.
 
-    May return a base clase, DeviceHvac, which will need promotion.
+    May return a base class, `DeviceHvac`, which will need promotion.
     """
 
     if not eavesdrop:
@@ -1206,54 +1209,111 @@ _REMOTES = {
 # see: https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/src/IthoPacket.h
 
 """
-# CVE/HRU remote (536-0124) [RFT W: 3 modes, timer]
-    "away":       (Code._22F1, 00, 01|04"),  # how to invoke?
-    "low":        (Code._22F1, 00, 02|04"),  # aka eco
-    "medium":     (Code._22F1, 00, 03|04"),  # aka auto (with sensors) - is that only for 63?
-    "high":       (Code._22F1, 00, 04|04"),  # aka full
-
-    "timer_1":    (Code._22F3, 00, 00|0A"),  # 10 minutes full speed
-    "timer_2":    (Code._22F3, 00, 00|14"),  # 20 minutes full speed
-    "timer_3":    (Code._22F3, 00, 00|1E"),  # 30 minutes full speed
-
-# RFT-AUTO (536-0150) [RFT CAR: 2 modes, auto, timer]: idx = 63, essentially same as above, but also...
-    "auto_night": (Code._22F8, 63, 02|03"),  # additional - press auto x2
-
-# RFT-RV (04-00046), RFT-CO2 (04-00045) - sensors with control
-    "medium":     (Code._22F1, 00, 03|07"), 1=away, 2=low?
-    "auto":       (Code._22F1, 00, 05|07"), 4=high
-    "auto_night": (Code._22F1, 00, 0B|0B"),
-
-    "timer_1":    (Code._22F3, 00, 00|0A, 00|00, 0000"),  # 10 minutes
-    "timer_2":    (Code._22F3, 00, 00|14, 00|00, 0000"),  # 20 minutes
-    "timer_3":    (Code._22F3, 00, 00|1E, 00|00, 0000"),  # 30 minutes
-
-# RFT-PIR (545-7550) - presence sensor
-
-# RFT_DF: DemandFlow remote (536-0146)
-    "timer_1":    (Code._22F3, 00, 42|03, 03|03"),  # 0b01-000-010 = 3 hrs, back to last mode
-    "timer_2":    (Code._22F3, 00, 42|06, 03|03"),  # 0b01-000-010 = 6 hrs, back to last mode
-    "timer_3":    (Code._22F3, 00, 42|09, 03|03"),  # 0b01-000-010 = 9 hrs, back to last mode
-    "cook_30":    (Code._22F3, 00, 02|1E, 02|03"),  # 30 mins (press 1x)
-    "cook_60":    (Code._22F3, 00, 02|3C, 02|03"),  # 60 mins (press 2x)
-
-    "low":        (Code._22F8, 00, 01|02"),  # ?eco     co2 <= 1200 ppm?
-    "high":       (Code._22F8, 00, 02|02"),  # ?comfort co2 <= 1000 ppm?
-
-# Join commands:
-    "CVERFT":     (Code._1FC9,  00, Code._22F1, 0x000000,                        01, Code._10E0, 0x000000"),  # CVE/HRU remote    (536-0124)
-    "AUTORFT":    (Code._1FC9,  63, Code._22F8, 0x000000,                        01, Code._10E0, 0x000000"),  # AUTO RFT          (536-0150)
-    "DF":         (Code._1FC9,  00, Code._22F8, 0x000000,                        00, Code._10E0, 0x000000"),  # DemandFlow remote (536-0146)
-    "RV":         (Code._1FC9,  00, Code._12A0, 0x000000,                        01, Code._10E0, 0x000000,  00, Code._31E0, 0x000000,  00, Code._1FC9, 0x000000"),  # RFT-RV   (04-00046)
-    "CO2":        (Code._1FC9,  00, Code._1298, 0x000000,  00, Code._2E10, 0x000000,  01, Code._10E0, 0x000000,  00, Code._31E0, 0x000000,  00, Code._1FC9, 0x000000"),  # RFT-CO2  (04-00045)
-
-# Leave commands:
-    "Others":      (Code._1FC9, 00, Code._1FC9, 0x000000"),  # standard leave command
-    "AUTORFT":     (Code._1FC9, 63, Code._1FC9, 0x000000"),  # leave command of AUTO RFT (536-0150)
-
-    # RQ 0x00
-    # I_ 0x01
-    # W_ 0x02
-    # RP 0x03
+Itho Remote (model) enums.
+
+CVE/HRU remote (536-0124) RFT W: 3 modes, timer
+-------------------------------------------------
+
+.. table:: 536-0124
+   :widths: auto
+
+   ===========  =========================  ================================================
+    "away":     (Code._22F1, 00, 01|04"),  how to invoke?
+    "low":      (Code._22F1, 00, 02|04"),  aka eco
+    "medium":   (Code._22F1, 00, 03|04"),  aka auto (with sensors) - is that only for 63?
+    "high":     (Code._22F1, 00, 04|04"),  aka full
+
+    "timer_1":  (Code._22F3, 00, 00|0A"),  10 minutes full speed
+    "timer_2":  (Code._22F3, 00, 00|14"),  20 minutes full speed
+    "timer_3":  (Code._22F3, 00, 00|1E"),  30 minutes full speed
+   ===========  =========================  ================================================
+
+RFT-AUTO (536-0150) RFT CAR: 2 modes, auto, timer: idx = 63, essentially same as above, but also...
+-----------------------------------------------------------------------------------------------------
+
+.. table:: 536-0150
+   :widths: auto
+
+   =============  =========================  ================================================
+   "auto_night":  (Code._22F8, 63, 02|03"),  additional - press auto x2
+   =============  =========================  ================================================
+
+RFT-RV (04-00046), RFT-CO2 (04-00045) - sensors with control
+------------------------------------------------------------
+
+.. table:: 04-00046
+   :widths: auto
+
+   ==============  ========================================   =============
+    "medium":      (Code._22F1, 00, 03|07"),                  1=away, 2=low?
+    "auto":        (Code._22F1, 00, 05|07"),                  4=high
+    "auto_night":  (Code._22F1, 00, 0B|0B"),
+
+    "timer_1":     (Code._22F3, 00, 00|0A, 00|00, 0000"),     10 minutes
+    "timer_2":     (Code._22F3, 00, 00|14, 00|00, 0000"),     20 minutes
+    "timer_3":     (Code._22F3, 00, 00|1E, 00|00, 0000"),     30 minutes
+   ==============  ========================================   =============
+
+RFT-PIR (545-7550) - presence sensor
+------------------------------------
+
+RFT_DF: DemandFlow remote (536-0146)
+------------------------------------
+
+.. table:: 536-0146
+   :widths: auto
+
+   ===========  ================================  =========================================
+    "timer_1":  (Code._22F3, 00, 42|03, 03|03"),  0b01-000-010 = 3 hrs, back to last mode
+    "timer_2":  (Code._22F3, 00, 42|06, 03|03"),  0b01-000-010 = 6 hrs, back to last mode
+    "timer_3":  (Code._22F3, 00, 42|09, 03|03"),  0b01-000-010 = 9 hrs, back to last mode
+    "cook_30":  (Code._22F3, 00, 02|1E, 02|03"),  30 mins (press 1x)
+    "cook_60":  (Code._22F3, 00, 02|3C, 02|03"),  60 mins (press 2x)
+
+    "low":      (Code._22F8, 00, 01|02"),         ?eco     co2 <= 1200 ppm?
+    "high":     (Code._22F8, 00, 02|02"),         ?comfort co2 <= 1000 ppm?
+   ===========  ================================  =========================================
+
+
+Join commands:
+--------------
+
+.. table:: join per accessory type
+   :widths: auto
+
+   ==========  =================  =====================  =========================  ==========================  =========================  ==========================  =================  ==========
+   type        set 1              set 2                  set 3                      set 4                       set 5                      set 6                       description        art #
+   ==========  =================  =====================  =========================  ==========================  =========================  ==========================  =================  ==========
+   "CVERFT":   (Code._1FC9,  00,  Code._22F1, 0x000000,                             01, Code._10E0, 0x000000")                                                         CVE/HRU remote     (536-0124)
+   "AUTORFT":  (Code._1FC9,  63,  Code._22F8, 0x000000,                             01, Code._10E0, 0x000000")                                                         AUTO RFT           (536-0150)
+   "DF":       (Code._1FC9,  00,  Code._22F8, 0x000000,                             00, Code._10E0, 0x000000")                                                         DemandFlow remote  (536-0146)
+   "RV":       (Code._1FC9,  00,  Code._12A0, 0x000000,                             01, Code._10E0, 0x000000,   00, Code._31E0, 0x000000,  00, Code._1FC9, 0x000000")  RFT-RV             (04-00046)
+   "CO2":      (Code._1FC9,  00,  Code._1298, 0x000000,  00, Code._2E10, 0x000000,  01, Code._10E0, 0x000000,   00, Code._31E0, 0x000000,  00, Code._1FC9, 0x000000")  RFT-CO2            (04-00045)
+   ==========  =================  =====================  =========================  ==========================  =========================  ==========================  =================  ==========
+
+Leave commands:
+---------------
+
+.. table:: leave per accessory type
+   :widths: auto
+
+   ==========  =================  ======================  =========================  ==========
+   type        set 1              set 2                   description                art #
+   ==========  =================  ======================  =========================  ==========
+   "Others":   (Code._1FC9, 00,   Code._1FC9, 0x000000")  standard leave command
+   "AUTORFT":  (Code._1FC9, 63,   Code._1FC9, 0x000000")  leave command of AUTO RFT  (536-0150)
+   ==========  =================  ======================  =========================  ==========
+
+.. table:: verbs
+   :widths: 2, 4
+
+   ======  ========
+   verb    byte
+   ======  ========
+   ``RQ``  ``0x00``
+   ``I_``  ``0x01``
+   ``W_``  ``0x02``
+   ``RP``  ``0x03``
+   ======  ========
 
 """

ramses_rf/dispatcher.py

@@ -186,6 +186,12 @@ def process_msg(gwy: Gateway, msg: Message) -> None:
     # which requires a valid payload only for 000C.
 
     def logger_xxxx(msg: Message) -> None:
+        """
+        Log msg according to src, code, log.debug setting.
+
+        :param msg: the Message being processed
+        :return: None
+        """
         if _DBG_FORCE_LOG_MESSAGES:
             _LOGGER.warning(msg)
         elif msg.src != gwy.hgi or (msg.code != Code._PUZZ and msg.verb != RQ):
@@ -268,10 +274,9 @@ def process_msg(gwy: Gateway, msg: Message) -> None:
 
     else:
         logger_xxxx(msg)
-        # if gwy.msg_db:
-        #     gwy.msg_db.add(
-        #         msg
-        #     )  # why add it? passes all tests without
+        if gwy.msg_db:
+            gwy.msg_db.add(msg)
+            # why add it? enable for evohome
 
 
 # TODO: this needs cleaning up (e.g. handle intervening packet)

ramses_rf/entity_base.py

@@ -67,7 +67,8 @@ if TYPE_CHECKING:
 
 
 _QOS_TX_LIMIT = 12  # TODO: needs work
-_ID_SLICE = 12  # was 9 for base address only, 12 for _02 sub/params_test?
+_ID_SLICE = 9  # base address only, legacy _msgs 9
+_SQL_SLICE = 12  # msg_db dst field query 12
 _SZ_LAST_PKT: Final = "last_msg"
 _SZ_NEXT_DUE: Final = "next_due"
 _SZ_TIMEOUT: Final = "timeout"
@@ -171,7 +172,31 @@ class _Entity:
 
 
 class _MessageDB(_Entity):
-    """Maintain/utilize an entity's state database."""
+    """Maintain/utilize an entity's state database.
+
+        EntityBase msg_db query methods
+
+        (ix = database.py.MessageIndex method)
+
+    .. table:: Database Query Methods
+       :widths: auto
+
+       ====  ======================  ====================  ============  ==========  ==========
+        e.   method name             args                  returns       uses        used by
+       ====  ======================  ====================  ============  ==========  ==========
+       e1    _get_msg_by_hdr         hdr                   Message       i3          discover
+       e2    _msg_value              code(s), Msg, args    dict[k,v]     e3,e4
+       e3    _msg_value_code         code, verb, key       dict[k,v]     e4,e5,e6    e6
+       e4    _msg_value_msg          Msg, (code)           dict[k,v]                 e2,e3
+       e5    _msg_qry_by_code_key    code, key, (verb=)                              e6,
+       e6    _msg_value_qry_by_code  key   code, key       str/float     e3,e5
+       e7    _msg_qry                sql                                             e8
+       e8    _msg_count              sql                                 e7
+       e9    supported_cmds                                list(Codes)   i7
+       e10   _msgs()                                                     i5
+       ====  ======================  ====================  ============  ==========  ==========
+
+    """
 
     _gwy: Gateway
     ctl: Controller
@@ -193,18 +218,18 @@ class _MessageDB(_Entity):
         self._msgs_: dict[
             Code, Message
         ] = {}  # TODO(eb): deprecated, used in test, remove Q1 2026
-        if not self._gwy.msg_db:  # TODO(eb): deprecated since 0.52.0, remove Q1 2026
+        if not self._gwy.msg_db:  # TODO(eb): deprecated since 0.52.1, remove Q1 2026
             self._msgz_: dict[
                 Code, dict[VerbT, dict[bool | str | None, Message]]
             ] = {}  # code/verb/ctx,
 
-        # As of 0.52.0 we use SQLite MessageIndex, see ramses_rf/database.py
+        # As of 0.52.1 we use SQLite MessageIndex, see ramses_rf/database.py
         # _msgz_ (nested) was only used in this module. Note:
         # _msgz (now rebuilt from _msgs) also used in: client, base, device.heat
 
     def _handle_msg(self, msg: Message) -> None:
         """Store a msg in the DBs.
-        Uses SQLite MessageIndex since 0.52.0
+        Uses SQLite MessageIndex since 0.52.1
         """
 
         if not (
@@ -219,7 +244,13 @@ class _MessageDB(_Entity):
             return  # don't store the rest
 
         if self._gwy.msg_db:  # central SQLite MessageIndex
-            self._gwy.msg_db.add(msg)
+            _LOGGER.debug(
+                "For %s (z_id %s) add msg %s, src %s, dst %s to msg_db.",
+                self.id,
+                self._z_id,
+                msg.src,
+                msg.dst,
+            )
             debug_code: Code = Code._3150
             if msg.code == debug_code and msg.src.id.startswith("01:"):
                 _LOGGER.debug(
@@ -232,11 +263,12 @@ class _MessageDB(_Entity):
                 # Result in test log: lookup fails
                 # msg.src = 01:073976 (CTL)
                 # Added msg from 01:073976 (CTL) with code 0005 to _gwy.msg_db
-                # query is for: 01:073976  < no suffix
+                # query is for: 01:073976  < no suffix, extended lookup to [:12] chars
+            self._gwy.msg_db.add(msg)
 
             # ignore any replaced message that might be returned
         else:  # TODO(eb): remove Q1 2026
-            if msg.code not in self._msgz_:  # deprecated since 0.52.0
+            if msg.code not in self._msgz_:  # deprecated since 0.52.1
                 # Store msg verb + ctx by code in nested self._msgz_ Dict
                 self._msgz_[msg.code] = {msg.verb: {msg._pkt._ctx: msg}}
             elif msg.verb not in self._msgz_[msg.code]:
@@ -247,7 +279,7 @@ class _MessageDB(_Entity):
                 self._msgz_[msg.code][msg.verb][msg._pkt._ctx] = msg
 
         # Also store msg by code in flat self._msgs_ dict (stores the latest I/RP msgs by code)
-        # TODO(eb): deprecated since 0.52.0, remove next block _msgs_ Q1 2026
+        # TODO(eb): deprecated since 0.52.1, remove next block _msgs_ Q1 2026
         if msg.verb in (I_, RP):  # drop RQ's
             # if msg.code == Code._3150 and msg.src.id.startswith(
             #     "02:"
@@ -270,7 +302,12 @@ class _MessageDB(_Entity):
                         # safeguard against lookup failures ("sim" packets?)
                         msg_list_qry.append(self._msgs[c])
                     else:
-                        _LOGGER.debug("Could not fetch self._msgs[%s]", c)
+                        _LOGGER.debug(
+                            "_msg_list could not fetch self._msgs[%s] for %s (z_id %s)",
+                            c,
+                            self.id,
+                            self._z_id,
+                        )
             return msg_list_qry
         # else create from legacy nested dict
         return [m for c in self._msgz.values() for v in c.values() for m in v.values()]
@@ -315,32 +352,7 @@ class _MessageDB(_Entity):
                 with contextlib.suppress(KeyError):
                     del obj._msgz_[msg.code][msg.verb][msg._pkt._ctx]
 
-    # EntityBase msg_db query methods > copy to docs/source/ramses_rf.rst
-    # (ix = database.py.MessageIndex method)
-    #
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e. |method name           | args               | returns    | uses     | used by  |
-    # +====+======================+====================+============+==========+==========+
-    # | e1 | _get_msg_by_hdr      | hdr                | Message    | i3       | discover |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e2 | _msg_value           | code(s), Msg, args | dict[k,v]  | e3,e4    |          |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e3 | _msg_value_code      | code, verb, key    | dict[k,v]  | e4,e5,e6 | e6       |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e4 | _msg_value_msg       | Msg, (code)        | dict[k,v]  |          | e2,e3    |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e5 | _msg_qry_by_code_key | code, key, (verb=) |            |          | e6,      |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e6 | _msg_value_qry_by_code_key | code, key    | str/float  | e3,e5    |          |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e7 | _msg_qry             | sql                |            |          | e8       |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e8 | _msg_count           | sql                |            | e7       |          |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e9 | supported_cmds       |                    | list(Codes)| i7       |          |
-    # +----+----------------------+--------------------+------------+----------+----------+
-    # | e10| _msgs()              |                    |            | i5       |          |
-    # +----+----------------------+--------------------+------------+----------+----------+
+    ### entity_base query methods
 
     def _get_msg_by_hdr(self, hdr: HeaderT) -> Message | None:
         """Return a msg, if any, that matches a given header."""
@@ -399,7 +411,7 @@ class _MessageDB(_Entity):
 
         assert isinstance(code, Message), (
             f"Invalid format: _msg_value({code})"
-        )  # catch invalidly formatted code, only handle Message
+        )  # catch invalidly formatted code, only handle Message from here
         return self._msg_value_msg(code, *args, **kwargs)
 
     def _msg_value_code(
@@ -410,7 +422,7 @@ class _MessageDB(_Entity):
         **kwargs: Any,
     ) -> dict | list | None:
         """
-        Query the message database using the SQLite index for the most recent
+        Query the message dict or the SQLite index for the most recent
         key: value pairs(s) for a given code.
 
         :param code: filter messages by Code or a tuple of Codes, optional
@@ -442,9 +454,8 @@ class _MessageDB(_Entity):
 
         elif isinstance(code, tuple):
             msgs = [m for m in self._msgs.values() if m.code in code]
-            msg = (
-                max(msgs) if msgs else None
-            )  # return highest = latest? value found in code:value pairs
+            msg = max(msgs) if msgs else None
+            # return highest = latest? value found in code:value pairs
         else:
             msg = self._msgs.get(code)
 
@@ -458,7 +469,7 @@ class _MessageDB(_Entity):
         domain_id: str | None = None,
     ) -> dict | list | None:
         """
-        Get from a Message all or a specific key with its value,
+        Get from a Message all or a specific key with its value(s),
         optionally filtering for a zone or a domain
 
         :param msg: a Message to inspect
@@ -500,17 +511,17 @@ class _MessageDB(_Entity):
             or (idx == SZ_DOMAIN_ID)
         ), (
             f"full dict:{msg_dict}, payload:{msg.payload} < Coding error: key='{idx}', val='{val}'"
-        )  # should not be there (BUG TODO(eb): but it is when using SQLite MessageIndex)
+        )  # should not be there (TODO(eb): BUG but occurs when using SQLite MessageIndex)
 
-        if key == "*":  # from a SQLite wildcard query, return first=only? k,v
-            return msg_dict
-        if key:
-            return msg_dict.get(key)
-        return {
-            k: v
-            for k, v in msg_dict.items()
-            if k not in ("dhw_idx", SZ_DOMAIN_ID, SZ_ZONE_IDX) and k[:1] != "_"
-        }
+        if (
+            key == "*" or not key
+        ):  # from a SQLite wildcard query, return first=only? k,v
+            return {
+                k: v
+                for k, v in msg_dict.items()
+                if k not in ("dhw_idx", SZ_DOMAIN_ID, SZ_ZONE_IDX) and k[:1] != "_"
+            }
+        return msg_dict.get(key)
 
     # SQLite methods, since 0.52.0
 
@@ -518,7 +529,6 @@ class _MessageDB(_Entity):
         """
         Retrieve from the MessageIndex a list of Code keys involving this device.
 
-        :param kwargs: not used as of 0.52.0
         :return: list of Codes or empty list when query returned empty
         """
         if self._gwy.msg_db:
@@ -530,7 +540,7 @@ class _MessageDB(_Entity):
             res: list[Code] = []
 
             for rec in self._gwy.msg_db.qry_field(
-                sql, (self.id[:_ID_SLICE], self.id[:_ID_SLICE])
+                sql, (self.id[:_SQL_SLICE], self.id[:_SQL_SLICE])
             ):
                 _LOGGER.debug("Fetched from index: %s", rec[0])
                 # Example: "Fetched from index: code 1FD4"
@@ -550,7 +560,7 @@ class _MessageDB(_Entity):
         Retrieve from the MessageIndex the most current Code for a code(s) &
         keyword combination involving this device.
 
-        :param code: (optional) a message Code to use, e.g. 31DA or a tuple of Codes
+        :param code: (optional) a message Code to use, e.g. Code._31DA or a tuple of Codes
         :param key: (optional) message keyword to fetch, e.g. SZ_HUMIDITY
         :param kwargs: optional verb='vb' single verb
         :return: Code of most recent query result message or None when query returned empty
@@ -581,9 +591,11 @@ class _MessageDB(_Entity):
             res = None
 
             for rec in self._gwy.msg_db.qry_field(
-                sql, (vb, self.id[:_ID_SLICE], self.id[:_ID_SLICE], code_qry, key)
+                sql, (vb, self.id[:_SQL_SLICE], self.id[:_SQL_SLICE], code_qry, key)
             ):
-                _LOGGER.debug("Fetched from index: %s", rec)
+                _LOGGER.debug(
+                    "_msg_qry_by_code_key fetched rec: %s, code: %s", rec, code_qry
+                )
                 assert isinstance(rec[0], dt)  # mypy hint
                 if rec[0] > latest:  # dtm, only use most recent
                     res = Code(rec[1])
@@ -605,7 +617,7 @@ class _MessageDB(_Entity):
 
         :param code: (optional) a single message Code to use, e.g. 31DA
         :param key: (optional) message keyword to fetch the value for, e.g. SZ_HUMIDITY or * (wildcard)
-        :param kwargs: not used as of 0.52.0
+        :param kwargs: not used as of 0.52.1
         :return: a single string or float value or None when qry returned empty
         """
         val_msg: dict | list | None = None
@@ -642,7 +654,7 @@ class _MessageDB(_Entity):
             # """SELECT code from messages WHERE verb in (' I', 'RP') AND (src = ? OR dst = ?)
             # AND (code = '31DA' OR ...) AND (plk LIKE '%{SZ_FAN_INFO}%' OR ...)""" = 2 params
             for rec in self._gwy.msg_db.qry_field(
-                sql, (self.id[:_ID_SLICE], self.id[:_ID_SLICE])
+                sql, (self.id[:_SQL_SLICE], self.id[:_SQL_SLICE])
             ):
                 _pl = self._msgs[Code(rec[0])].payload
                 # add payload dict to res(ults)
@@ -698,7 +710,7 @@ class _MessageDB(_Entity):
         _msg_dict = {  # ? use ctx (context) instead of just the address?
             m.code: m
             for m in self._gwy.msg_db.qry(
-                sql, (self.id[:_ID_SLICE], self.id[:_ID_SLICE])
+                sql, (self.id[:_SQL_SLICE], self.id[:_SQL_SLICE])
             )  # e.g. 01:123456_HW
         }
         # if CTL, remove 3150, 3220 heat_demand, both are only stored on children
@@ -774,12 +786,12 @@ class _Discovery(_MessageDB):
                 code: CODES_SCHEMA[code][SZ_NAME]
                 for code in sorted(
                     self._gwy.msg_db.get_rp_codes(
-                        (self.id[:_ID_SLICE], self.id[:_ID_SLICE])
+                        (self.id[:_SQL_SLICE], self.id[:_SQL_SLICE])
                     )
                 )
                 if self._is_not_deprecated_cmd(code)
             }
-        return {  # TODO(eb): deprecated since 0.52.0, remove Q1 2026
+        return {  # TODO(eb): deprecated since 0.52.1, remove Q1 2026
             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_not_deprecated_cmd(code)
@@ -806,7 +818,7 @@ class _Discovery(_MessageDB):
                 AND (src = ? OR dst = ?)
             """
             for rec in self._gwy.msg_db.qry_field(
-                sql, (self.id[:_ID_SLICE], self.id[:_ID_SLICE])
+                sql, (self.id[:_SQL_SLICE], self.id[:_SQL_SLICE])
             ):
                 _LOGGER.debug("Fetched OT ctx from index: %s", rec[0])
                 res.append(rec[0])
@@ -937,8 +949,8 @@ class _Discovery(_MessageDB):
                             sql,
                             (
                                 task[_SZ_COMMAND].code,
-                                self.tcs.id[:_ID_SLICE],
-                                self.tcs.id[:_ID_SLICE],
+                                self.tcs.id[:_ID_SLICE],  # OK? not _SQL_SLICE?
+                                self.tcs.id[:_ID_SLICE],  # OK? not _SQL_SLICE?
                             ),
                         )[0]  # expect 1 Message in returned tuple
                     else:  # TODO(eb) remove next Q1 2026

ramses_rf/gateway.py

@@ -175,6 +175,7 @@ class Gateway(Engine):
 
         # initialize SQLite index, set in _tx/Engine
         if self._sqlite_index:  # TODO(eb): default to ON in Q4 2025
+            _LOGGER.info("Ramses RF starts SQLite MessageIndex")
             self.create_sqlite_message_index()  # if activated in ramses_cc > Engine
 
         # temporarily turn on discovery, remember original state
@@ -212,7 +213,7 @@ class Gateway(Engine):
     def _pause(self, *args: Any) -> None:
         """Pause the (unpaused) gateway (disables sending/discovery).
 
-        There is the option to save other objects, as *args.
+        There is the option to save other objects, as `args`.
         """
         _LOGGER.debug("Gateway: Pausing engine...")
 
@@ -227,7 +228,7 @@ class Gateway(Engine):
     def _resume(self) -> tuple[Any]:
         """Resume the (paused) gateway (enables sending/discovery, if applicable).
 
-        Will restore other objects, as *args.
+        Will restore other objects, as `args`.
         """
         args: tuple[Any]
 

ramses_rf/schemas.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
-Schema processor for upper layer.
+:term:`Schema` processor for upper layer.
 """
 
 from __future__ import annotations

ramses_rf/version.py

@@ -1,4 +1,4 @@
 """RAMSES RF - a RAMSES-II protocol decoder & analyser (application layer)."""
 
-__version__ = "0.52.0"
+__version__ = "0.52.2"
 VERSION = __version__

{ramses_rf-0.52.0.dist-info → ramses_rf-0.52.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ramses_rf
-Version: 0.52.0
+Version: 0.52.2
 Summary: A stateful RAMSES-II protocol decoder & analyser.
 Project-URL: Homepage, https://github.com/ramses-rf/ramses_rf
 Project-URL: Bug Tracker, https://github.com/ramses-rf/ramses_rf/issues

{ramses_rf-0.52.0.dist-info → ramses_rf-0.52.2.dist-info}/RECORD

@@ -4,52 +4,52 @@ ramses_cli/debug.py,sha256=vgR0lOHoYjWarN948dI617WZZGNuqHbeq6Tc16Da7b4,608
 ramses_cli/discovery.py,sha256=MWoahBnAAVzfK2S7EDLsY2WYqN_ZK9L-lktrj8_4cb0,12978
 ramses_cli/utils/cat_slow.py,sha256=AhUpM5gnegCitNKU-JGHn-DrRzSi-49ZR1Qw6lxe_t8,607
 ramses_cli/utils/convert.py,sha256=D_YiCyX5na9pgC-_NhBlW9N1dgRKUK-uLtLBfofjzZM,1804
-ramses_rf/__init__.py,sha256=VG3E9GHbtC6lx6E1DMQJeFitHnydMKJyPxQBethdrzg,1193
+ramses_rf/__init__.py,sha256=vp2TyFGqc1fGQHsevhmaw0QEmSSCnZx7fqizKiEwHtw,1245
 ramses_rf/binding_fsm.py,sha256=uZAOl3i19KCXqqlaLJWkEqMMP7NJBhVPW3xTikQD1fY,25996
 ramses_rf/const.py,sha256=L3z31CZ-xqno6oZp_h-67CB_5tDDqTwSWXsqRtsjMcs,5460
-ramses_rf/database.py,sha256=21M1XV7qTQaydqInctf7vX-PAVdrM4xmJoaXX8oB87s,20748
-ramses_rf/dispatcher.py,sha256=UqilAoL6T85ZFPkcpvcfuidNbusONngQoCVWHV6vOzk,11277
-ramses_rf/entity_base.py,sha256=eLGhJTv8FDHjXmsywUhn1imEhdo0bFgAHP_KLNl_HiE,56004
+ramses_rf/database.py,sha256=pfCOt6wvABAaW275mNLoRnObFSQ9nT5d7PtDLMTvgr4,20340
+ramses_rf/dispatcher.py,sha256=YjEU-QrBLo9IfoEhJo2ikg_FxOaMYoWvzelr9Vi-JZ8,11398
+ramses_rf/entity_base.py,sha256=OPdQEeJ5zk49FKCFmRui4urFQVR2tLBS1iWCTWeZkNo,55712
 ramses_rf/exceptions.py,sha256=mt_T7irqHSDKir6KLaf6oDglUIdrw0S40JbOrWJk5jc,3657
-ramses_rf/gateway.py,sha256=1MRmqpDlhE1SFm25dSvnSTX_dUoi9Pz--qycJIJyFAU,21151
+ramses_rf/gateway.py,sha256=VYZqMppU_kDYhT3EUmqpHf0LuLXPMH7ASx9jylAopWE,21218
 ramses_rf/helpers.py,sha256=TNk_QkpIOB3alOp1sqnA9LOzi4fuDCeapNlW3zTzNas,4250
 ramses_rf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ramses_rf/schemas.py,sha256=UhvRhV4nZ3kvrLLM3wwIguQUIjIgd_AKvp2wkTSpNEA,13468
-ramses_rf/version.py,sha256=ggzTkhC_7XHqI8ONDXEhJk9tXE1LLvMfYJyCrJzF8KI,125
+ramses_rf/schemas.py,sha256=jvpx0hZiMhaogyxbxnrbxS7m2GekKK4DFfVTNs7h-WQ,13476
+ramses_rf/version.py,sha256=3xbuWkwVUOezgu-nlN98fGrnAgqtfivOcMVKjCTSBds,125
 ramses_rf/device/__init__.py,sha256=sUbH5dhbYFXSoM_TPFRutpRutBRpup7_cQ9smPtDTy8,4858
 ramses_rf/device/base.py,sha256=Yx0LZwMEb49naY8FolZ8HEBFb6XCPQBTVN_TWyO2nKg,17777
-ramses_rf/device/heat.py,sha256=UmZuA-5czrfoClVEeUAPWgze5obWNQpYI7ZPQpVJB6s,54704
-ramses_rf/device/hvac.py,sha256=of8wWHhJOX0KcvVqqlyJLArKrv1ST7rlbL7kLV9v_0Q,45603
+ramses_rf/device/heat.py,sha256=hvTX32Evp23vqjXu-YHqTuneem4_QBRSxCkYR7dg4VI,54705
+ramses_rf/device/hvac.py,sha256=gdpVACUvtq6ERMI0mwRhqIJtKYEmybzJA2NeyN1ELrs,48431
 ramses_rf/system/__init__.py,sha256=uZLKio3gLlBzePa2aDQ1nxkcp1YXOGrn6iHTG8LiNIw,711
 ramses_rf/system/faultlog.py,sha256=GdGmVGT3137KsTlV_nhccgIFEmYu6DFsLTn4S-8JSok,12799
 ramses_rf/system/heat.py,sha256=3jaFEChU-HlWCRMY1y7u09s7AH4hT0pC63hnqwdmZOc,39223
 ramses_rf/system/schedule.py,sha256=Ts6tdZPTQLV5NkgwA73tPa5QUsnZNIIuYoKC-8VsXDk,18808
 ramses_rf/system/zones.py,sha256=9AH7ooN5QfiqvWuor2P1Dn8aILjQb2RWL9rWqDH1IjA,36075
-ramses_tx/__init__.py,sha256=qNMTe8hBkIuecvtCiekUB0pKdD8atb0SjWxVNVe3yhE,3538
+ramses_tx/__init__.py,sha256=sqnjM7pUGJDmec6igTtKViSB8FLX49B5gwhAmcY9ERY,3596
 ramses_tx/address.py,sha256=F5ZE-EbPNNom1fW9XXUILvD7DYSMBxNJvsHVliT5gjw,8452
-ramses_tx/command.py,sha256=r9dNaofjjOQXZSUrZjsNpvEukNn4rSGy0OLr2Dyd2TI,125129
+ramses_tx/command.py,sha256=tqVECwd_QokEcRv2MSk7TUU4JSBzCZcJh1eQ0jIGgoY,125122
 ramses_tx/const.py,sha256=pnxq5upXvLUizv9Ye_I1llD9rAa3wddHgsSkc91AIUc,30300
 ramses_tx/exceptions.py,sha256=FJSU9YkvpKjs3yeTqUJX1o3TPFSe_B01gRGIh9b3PNc,2632
 ramses_tx/fingerprints.py,sha256=nfftA1E62HQnb-eLt2EqjEi_la0DAoT0wt-PtTMie0s,11974
 ramses_tx/frame.py,sha256=GzNsXr15YLeidJYGtk_xPqsZQh4ehDDlUCtT6rTDhT8,22046
-ramses_tx/gateway.py,sha256=ztPg3fMgn-fM15dLxrw5PG34SCxD7eR3pdz1xwvz7Ag,11345
+ramses_tx/gateway.py,sha256=8o9NyEAyIui3B6HA0R8o64u4U8NZFlNl0TQ6rhwMoCk,11369
 ramses_tx/helpers.py,sha256=J4OCRckp3JshGQTvvqEskFjB1hPS7uA_opVsuIqmZds,32915
 ramses_tx/logger.py,sha256=qYbUoNPnPaFWKVsYvLG6uTVuPTdZ8HsMzBbGx0DpBqc,10177
 ramses_tx/message.py,sha256=-moQ8v3HVlNSl-x3U0DDfDcj8WQ7vLqclMNxsohbmnw,13449
 ramses_tx/opentherm.py,sha256=58PXz9l5x8Ou6Fm3y-R_UnGHCYahoi2RKIDdYStUMzk,42378
 ramses_tx/packet.py,sha256=_qHiPFWpQpKueZOgf1jJ93Y09iZjo3LZWStLglVkXg4,7370
-ramses_tx/parsers.py,sha256=e6IwVEMLv2EL8gbZaM2s-qA3E2AN8dCwdIgfEbFo730,111029
+ramses_tx/parsers.py,sha256=Z0ochrNyO2l8SAP0oJxN-tx2nJluEaNP_uJCIm_lsA8,111279
 ramses_tx/protocol.py,sha256=9R3aCzuiWEyXmugmB5tyR_RhBlgfnpUXj7AsMP9BzzU,28867
 ramses_tx/protocol_fsm.py,sha256=ZKtehCr_4TaDdfdlfidFLJaOVTYtaEq5h4tLqNIhb9s,26827
 ramses_tx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ramses_tx/ramses.py,sha256=NG81GBNZlap-Gi9ac-r6OFE-KaHvXsgPDWy-I2Irr-4,53698
-ramses_tx/schemas.py,sha256=IYCDH0jp3446Gtl_378aBmWyXN90e-uYudfkZkOKR24,13147
-ramses_tx/transport.py,sha256=bGprlfuuwBgQ1bmBRSrcicuk7s-jVqyuKpZCfQ-sSpw,58469
+ramses_tx/schemas.py,sha256=U8SkwbW41zac0MQe0NgP6qTUqymmbeCG-UHPEw_GAv0,13267
+ramses_tx/transport.py,sha256=kyvnVf2RpuA_8YRO6C4S60YHctDag0ywfoMzb0wWDGY,58552
 ramses_tx/typed_dicts.py,sha256=w-0V5t2Q3GiNUOrRAWiW9GtSwbta_7luME6GfIb1zhI,10869
 ramses_tx/typing.py,sha256=eF2SlPWhNhEFQj6WX2AhTXiyRQVXYnFutiepllYl2rI,5042
-ramses_tx/version.py,sha256=8xCh-Ia7WXZkWWEs7lVuk13x3NbC3HoNuHvR_G1KCB4,123
-ramses_rf-0.52.0.dist-info/METADATA,sha256=ADZlDrTcgK0-xOW4D1A-2CRfakYnaGOOClGRshQYBwg,4000
-ramses_rf-0.52.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ramses_rf-0.52.0.dist-info/entry_points.txt,sha256=NnyK29baOCNg8DinPYiZ368h7MTH7bgTW26z2A1NeIE,50
-ramses_rf-0.52.0.dist-info/licenses/LICENSE,sha256=-Kc35W7l1UkdiQ4314_yVWv7vDDrg7IrJfMLUiq6Nfs,1074
-ramses_rf-0.52.0.dist-info/RECORD,,
+ramses_tx/version.py,sha256=NEkkAJQW7Hx8GmvkR9BZpLSOi30OMi9Awth13sWXuTQ,123
+ramses_rf-0.52.2.dist-info/METADATA,sha256=Fm3vwa0FvFkMEHz44B8FDq0PjboTn_g9sGHyK7HiydA,4000
+ramses_rf-0.52.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ramses_rf-0.52.2.dist-info/entry_points.txt,sha256=NnyK29baOCNg8DinPYiZ368h7MTH7bgTW26z2A1NeIE,50
+ramses_rf-0.52.2.dist-info/licenses/LICENSE,sha256=-Kc35W7l1UkdiQ4314_yVWv7vDDrg7IrJfMLUiq6Nfs,1074
+ramses_rf-0.52.2.dist-info/RECORD,,

ramses_tx/__init__.py

@@ -1,5 +1,7 @@
 #!/usr/bin/env python3
-"""RAMSES RF - a RAMSES-II protocol decoder & analyser."""
+"""RAMSES RF - a RAMSES-II protocol decoder & analyser.
+`ramses_tx` takes care of the RF protocol (lower) layer.
+"""
 
 from __future__ import annotations
 

ramses_tx/command.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
-"""RAMSES RF - a RAMSES-II protocol decoder & analyser.
+"""
+RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
 This module provides the `Command` class for constructing and managing RAMSES-II protocol
 commands (packets) that are to be sent to HVAC devices. It includes methods for creating
@@ -1394,7 +1395,7 @@ class Command(Frame):
 
         :param ctl_id: The device ID of the DHW controller
         :type ctl_id: DeviceIdT | str
-        :param **kwargs: Additional parameters (currently only 'dhw_idx' is supported)
+        :param kwargs: Additional parameters (currently only 'dhw_idx' is supported)
         :key dhw_idx: The DHW circuit index (0 or 1, defaults to 0 for single-DHW systems)
         :type dhw_idx: int, optional
         :return: A Command object for the RQ|1F41 message
@@ -1438,7 +1439,7 @@ class Command(Frame):
         :type until: datetime | str | None
         :param duration: Duration in seconds for temporary mode (alternative to 'until')
         :type duration: int | None
-        :param **kwargs: Additional parameters (currently only 'dhw_idx' is supported)
+        :param kwargs: Additional parameters (currently only 'dhw_idx' is supported)
         :key dhw_idx: The DHW circuit index (0 or 1, defaults to 0 for single-DHW systems)
         :type dhw_idx: int, optional
         :return: A Command object for the W|1F41 message
@@ -1501,7 +1502,7 @@ class Command(Frame):
         :type codes: Code | Iterable[Code] | None
         :param dst_id: Optional destination device ID (defaults to broadcast)
         :type dst_id: DeviceIdT | str | None
-        :param **kwargs: Additional parameters
+        :param kwargs: Additional parameters
         :key oem_code: OEM code for bind offers (only used with I-type messages)
         :type oem_code: str, optional
         :return: A Command object for the bind operation
@@ -2531,7 +2532,7 @@ class Command(Frame):
         :type supply_flow: float | None
         :param exhaust_flow: Current exhaust air flow rate (if available)
         :type exhaust_flow: float | None
-        :param **kwargs: Additional parameters (reserved for future use)
+        :param kwargs: Additional parameters (reserved for future use)
         :return: A configured Command object for the HVAC fan status update
         :rtype: Command
 

ramses_tx/gateway.py

@@ -113,7 +113,7 @@ class Engine:
             self._include,
             self._exclude,
         )
-        self._sqlite_index = kwargs.pop(SZ_SQLITE_INDEX)
+        self._sqlite_index = kwargs.pop(SZ_SQLITE_INDEX, False)  # default True?
         self._kwargs: dict[str, Any] = kwargs  # HACK
 
         self._engine_lock = Lock()  # FIXME: threading lock, or asyncio lock?

ramses_tx/parsers.py

@@ -3,9 +3,11 @@
 
 NOTES: aspirations on a consistent Schema, going forward:
 
-  :mode/state: | :bool:  | :mutex (infinitive. vs -ing):      | :flags:
-mode (config.) | enabled | disabled, heat, cool, heat_cool... | ch_enabled, dhw_enabled
-state (action) | active  | idle, heating, cooling...          | is_heating, is_cooling
+==============  ========  ===================================  ========================
+  :mode/state:   :bool:    :mutex (infinitive. vs -ing):        :flags:
+mode (config.)   enabled   disabled, heat, cool, heat_cool...   ch_enabled, dhw_enabled
+state (action)   active    idle, heating, cooling...            is_heating, is_cooling
+==============  ========  ===================================  ========================
 
 - prefer: enabled: True over xx_enabled: True (if only ever 1 flag)
 - prefer:  active: True over is_heating: True (if only ever 1 flag)
@@ -362,8 +364,9 @@ def parser_0009(payload: str, msg: Message) -> dict | list[dict]:  # TODO: only
 
     The failsafe mode defines the relay behaviour if the RF communication is lost (e.g.
     when a room thermostat stops communicating due to discharged batteries):
-        False (disabled) - if RF comms are lost, relay will be held in OFF position
-        True  (enabled)  - if RF comms are lost, relay will cycle at 20% ON, 80% OFF
+
+    - False (disabled) - if RF comms are lost, relay will be held in OFF position
+    - True  (enabled)  - if RF comms are lost, relay will cycle at 20% ON, 80% OFF
 
     This setting may need to be enabled to ensure frost protect mode.
     """
@@ -2289,45 +2292,46 @@ def parser_31da(payload: str, msg: Message) -> PayDictT._31DA:
 def parser_31e0(payload: str, msg: Message) -> dict | list[dict]:  # TODO: only dict
     """Notes are.
 
-    van means “of”.
+    "van" means "of".
     - 0 = min. van min. potm would be:
     - 0 = minimum of minimum potentiometer
 
     See: https://www.industrialcontrolsonline.com/honeywell-t991a
     - modulates air temperatures in ducts
-
-    case 0x31E0:  ' 12768:
-    {
-        string str4;
-        unchecked
-        {
-            result.Fan = Conversions.ToString((double)(int)data[checked(start + 1)] / 2.0);
-            str4 = "";
-        }
-        str4 = (data[start + 2] & 0xF) switch
-        {
-            0 => str4 + "0 = min. potm. ",
-            1 => str4 + "0 = min. van min. potm ",
-            2 => str4 + "0 = min. fan ",
-            _ => "",
-        };
-        switch (data[start + 2] & 0xF0)
-        {
-        case 16:
-            str4 += "100 = max. potm";
-            break;
-        case 32:
-            str4 += "100 = max. van max. potm ";
-            break;
-        case 48:
-            str4 += "100 = max. fan ";
-            break;
-        }
-        result.Data = str4;
-        break;
-    }
     """
 
+    # coding note:
+    # case 0x31E0:  ' 12768:
+    # {
+    #     string str4;
+    #     unchecked
+    #     {
+    #         result.Fan = Conversions.ToString((double)(int)data[checked(start + 1)] / 2.0);
+    #         str4 = "";
+    #     }
+    #     str4 = (data[start + 2] & 0xF) switch
+    #     {
+    #         0 => str4 + "0 = min. potm. ",
+    #         1 => str4 + "0 = min. van min. potm ",
+    #         2 => str4 + "0 = min. fan ",
+    #         _ => "",
+    #     };
+    #     switch (data[start + 2] & 0xF0)
+    #     {
+    #     case 16:
+    #         str4 += "100 = max. potm";
+    #         break;
+    #     case 32:
+    #         str4 += "100 = max. van max. potm ";
+    #         break;
+    #     case 48:
+    #         str4 += "100 = max. fan ";
+    #         break;
+    #     }
+    #     result.Data = str4;
+    #     break;
+    # }
+
     # .I --- 37:005302 32:132403 --:------ 31E0 008 00-0000-00 01-0064-00  # RF15 CO2 to Orcon HRC400 series SmartComfort Valve
 
     # .I --- 29:146052 32:023459 --:------ 31E0 003 00-0000

ramses_tx/schemas.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
-Schema processor for protocol (lower) layer.
+:term:`Schema` processor for protocol (lower) layer.
 """
 
 from __future__ import annotations
@@ -73,13 +73,17 @@ class PktLogConfigT(TypedDict):
 def sch_packet_log_dict_factory(
     default_backups: int = 0,
 ) -> dict[vol.Required, vol.Any]:
-    """Return a packet log dict with a configurable default rotation policy.
+    """
+    :return: a packet log dict with a configurable default rotation policy.
 
-    usage:
+    Usage:
+
+    .. code-block::
+
+        SCH_PACKET_LOG_7 = vol.Schema(
+            packet_log_dict_factory(default_backups=7), extra=vol.PREVENT_EXTRA
+        )
 
-    SCH_PACKET_LOG_7 = vol.Schema(
-        packet_log_dict_factory(default_backups=7), extra=vol.PREVENT_EXTRA
-    )
     """
 
     SCH_PACKET_LOG_CONFIG = vol.Schema(
@@ -162,11 +166,13 @@ class PortConfigT(TypedDict):
 def sch_serial_port_dict_factory() -> dict[vol.Required, vol.Any]:
     """Return a serial port dict.
 
-    usage:
+    Usage:
 
-    SCH_SERIAL_PORT = vol.Schema(
-        sch_serial_port_dict_factory(), extra=vol.PREVENT_EXTRA
-    )
+    .. code-block::
+
+        SCH_SERIAL_PORT = vol.Schema(
+            sch_serial_port_dict_factory(), extra=vol.PREVENT_EXTRA
+        )
     """
 
     SCH_SERIAL_PORT_NAME = str
@@ -252,11 +258,13 @@ def sch_global_traits_dict_factory(
 ) -> tuple[dict[vol.Optional, vol.Any], vol.Any]:
     """Return a global traits dict with a configurable extra traits.
 
-    usage:
+    Usage:
 
-    SCH_GLOBAL_TRAITS = vol.Schema(
-        sch_global_traits_dict(heat=traits), extra=vol.PREVENT_EXTRA
-    )
+    .. code-block::
+
+        SCH_GLOBAL_TRAITS = vol.Schema(
+            sch_global_traits_dict(heat=traits), extra=vol.PREVENT_EXTRA
+        )
     """
 
     heat_traits = heat_traits or {}
@@ -348,7 +356,8 @@ def select_device_filter_mode(
     known_list: DeviceListT,
     block_list: DeviceListT,
 ) -> bool:
-    """Determine which device filter to use, if any.
+    """
+    Determine which device filter to use, if any.
 
     Either:
      - block if device_id in block_list (could be empty), otherwise

ramses_tx/transport.py

@@ -3,30 +3,38 @@
 
 Operates at the pkt layer of: app - msg - pkt - h/w
 
-For ser2net, use the following YAML with: ser2net -c misc/ser2net.yaml
-  connection: &con00
-  accepter: telnet(rfc2217),tcp,5001
-  timeout: 0
-  connector: serialdev,/dev/ttyUSB0,115200n81,local
-  options:
-    max-connections: 3
-
-For socat, see:
-  socat -dd pty,raw,echo=0 pty,raw,echo=0
-  python client.py monitor /dev/pts/0
-  cat packet.log | cut -d ' ' -f 2- | unix2dos > /dev/pts/1
+For ser2net, use the following YAML with: ``ser2net -c misc/ser2net.yaml``
+
+.. code-block::
+
+    connection: &con00
+    accepter: telnet(rfc2217),tcp,5001
+    timeout: 0
+    connector: serialdev,/dev/ttyUSB0,115200n81,local
+    options:
+        max-connections: 3
+
+For ``socat``, see:
+
+.. code-block::
+
+    socat -dd pty,raw,echo=0 pty,raw,echo=0
+    python client.py monitor /dev/pts/0
+    cat packet.log | cut -d ' ' -f 2- | unix2dos > /dev/pts/1
 
 For re-flashing evofw3 via Arduino IDE on *my* atmega328p (YMMV):
- - Board:      atmega328p (SW UART)
- - Bootloader: Old Bootloader
- - Processor:  atmega328p (5V, 16 MHz)
- - Host:       57600 (or 115200, YMMV)
- - Pinout:     Nano
+
+  - Board:      atmega328p (SW UART)
+  - Bootloader: Old Bootloader
+  - Processor:  atmega328p (5V, 16 MHz)
+  - Host:       57600 (or 115200, YMMV)
+  - Pinout:     Nano
 
 For re-flashing evofw3 via Arduino IDE on *my* atmega32u4 (YMMV):
- - Board:      atmega32u4 (HW UART)
- - Processor:  atmega32u4 (5V, 16 MHz)
- - Pinout:     Pro Micro
+
+  - Board:      atmega32u4 (HW UART)
+  - Processor:  atmega32u4 (5V, 16 MHz)
+  - Pinout:     Pro Micro
 """
 
 from __future__ import annotations
@@ -250,11 +258,12 @@ async def is_hgi80(serial_port: SerPortNameT) -> bool | None:
 
 
 def _normalise(pkt_line: str) -> str:
-    """Perform any (transparent) frame-level hacks, as required at (near-)RF layer.
+    """
+    Perform any (transparent) frame-level hacks, as required at (near-)RF layer.
 
     Goals:
     - ensure an evofw3 provides the same output as a HGI80 (none, presently)
-    - handle 'strange' packets (e.g. I|08:|0008)
+    - handle 'strange' packets (e.g. ``I|08:|0008``)
     """
 
     # TODO: deprecate as only for ramses_esp <0.4.0

ramses_tx/version.py

@@ -1,4 +1,4 @@
 """RAMSES RF - a RAMSES-II protocol decoder & analyser (transport layer)."""
 
-__version__ = "0.52.0"
+__version__ = "0.52.2"
 VERSION = __version__