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

ramses_cli/client.py

@@ -438,17 +438,29 @@ def print_summary(gwy: Gateway, **kwargs: Any) -> None:
 
     if kwargs.get("show_crazys"):
         for device in [d for d in gwy.devices if d.type == DEV_TYPE_MAP.CTL]:
-            for code, verbs in device._msgz.items():
-                if code in (Code._0005, Code._000C):
-                    for verb in verbs.values():
-                        for pkt in verb.values():
-                            print(f"{pkt}")
+            if gwy.msg_db:
+                for msg in gwy.msg_db.get(device=device.id, code=Code._0005):
+                    print(f"{msg._pkt}")
+                for msg in gwy.msg_db.get(device=device.id, code=Code._000C):
+                    print(f"{msg._pkt}")
+            else:  # TODO(eb): replace next block by
+                #  raise NotImplementedError
+                for code, verbs in device._msgz.items():
+                    if code in (Code._0005, Code._000C):
+                        for verb in verbs.values():
+                            for pkt in verb.values():
+                                print(f"{pkt}")
             print()
         for device in [d for d in gwy.devices if d.type == DEV_TYPE_MAP.UFC]:
-            for code in device._msgz.values():
-                for verb in code.values():
-                    for pkt in verb.values():
-                        print(f"{pkt}")
+            if gwy.msg_db:
+                for msg in gwy.msg_db.get(device=device.id):
+                    print(f"{msg._pkt}")
+            else:  # TODO(eb): replace next block by
+                #  raise NotImplementedError
+                for code in device._msgz.values():
+                    for verb in code.values():
+                        for pkt in verb.values():
+                            print(f"{pkt}")
             print()
 
 

ramses_cli/discovery.py

@@ -394,7 +394,7 @@ async def script_scan_otb_ramses(
         Code._3223,
         Code._3EF0,  # rel. modulation level  / RelativeModulationLevel (also, below)
         Code._3EF1,  # rel. modulation level  / RelativeModulationLevel
-    )  # excl. 3220
+    )  # excl. 3150, 3220
 
     for c in _CODES:
         gwy.send_cmd(Command.from_attrs(RQ, dev_id, c, "00"), priority=Priority.LOW)

ramses_rf/database.py

@@ -8,24 +8,13 @@ import logging
 import sqlite3
 from collections import OrderedDict
 from datetime import datetime as dt, timedelta as td
-from typing import Any, NewType, TypedDict
+from typing import TYPE_CHECKING, Any, NewType
 
-from ramses_tx import Message
-
-DtmStrT = NewType("DtmStrT", str)
-MsgDdT = OrderedDict[DtmStrT, Message]
-
-
-class Params(TypedDict):
-    dtm: dt | str | None
-    verb: str | None
-    src: str | None
-    dst: str | None
-    code: str | None
-    ctx: str | None
-    hdr: str | None
-    plk: str | None
+from ramses_tx import CODES_SCHEMA, Code, Message
 
+if TYPE_CHECKING:
+    DtmStrT = NewType("DtmStrT", str)
+    MsgDdT = OrderedDict[DtmStrT, Message]
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -34,7 +23,7 @@ def _setup_db_adapters() -> None:
     """Set up the database adapters and converters."""
 
     def adapt_datetime_iso(val: dt) -> str:
-        """Adapt datetime.datetime to timezone-naive ISO 8601 datetime to match _msgs_ dtm keys."""
+        """Adapt datetime.datetime to timezone-naive ISO 8601 datetime to match _msgs dtm keys."""
         return val.isoformat(timespec="microseconds")
 
     sqlite3.register_adapter(dt, adapt_datetime_iso)
@@ -77,13 +66,13 @@ class MessageIndex:
     Index holds the latest message to & from all devices by header
     (example of a hdr: 000C|RP|01:223036|0208)."""
 
+    _housekeeping_task: asyncio.Task[None]
+
     def __init__(self, maintain: bool = True) -> None:
         """Instantiate a message database/index."""
 
         self.maintain = maintain
-        self._msgs: MsgDdT = (
-            OrderedDict()
-        )  # stores all messages for retrieval. Filled 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(
@@ -98,7 +87,7 @@ class MessageIndex:
         if self.maintain:
             self._lock = asyncio.Lock()
             self._last_housekeeping: dt = None  # type: ignore[assignment]
-            self._housekeeping_task: asyncio.Task[None] = None  # type: ignore[assignment]
+            self._housekeeping_task = None  # type: ignore[assignment]
 
         self.start()
 
@@ -109,7 +98,7 @@ class MessageIndex:
         """Start the housekeeper loop."""
 
         if self.maintain:
-            if self._housekeeping_task and not self._housekeeping_task.done():
+            if self._housekeeping_task and (not self._housekeeping_task.done()):
                 return
 
             self._housekeeping_task = asyncio.create_task(
@@ -119,7 +108,7 @@ class MessageIndex:
     def stop(self) -> None:
         """Stop the housekeeper loop."""
 
-        if self._housekeeping_task and not self._housekeeping_task.done():
+        if self._housekeeping_task and (not self._housekeeping_task.done()):
             self._housekeeping_task.cancel()  # stop the housekeeper
 
         self._cx.commit()  # just in case
@@ -150,8 +139,8 @@ class MessageIndex:
             CREATE TABLE messages (
                 dtm    DTM      NOT NULL PRIMARY KEY,
                 verb   TEXT(2)  NOT NULL,
-                src    TEXT(9)  NOT NULL,
-                dst    TEXT(9)  NOT NULL,
+                src    TEXT(12) NOT NULL,
+                dst    TEXT(12) NOT NULL,
                 code   TEXT(4)  NOT NULL,
                 ctx    TEXT,
                 hdr    TEXT     NOT NULL UNIQUE,
@@ -175,14 +164,14 @@ class MessageIndex:
 
         async def housekeeping(dt_now: dt, _cutoff: td = td(days=1)) -> None:
             """
-            Delete all messages from the using the MessageIndex older than a given delta.
+            Deletes all messages older than a given delta from the dict using the MessageIndex.
             :param dt_now: current timestamp
             :param _cutoff: the oldest timestamp to retain, default is 24 hours ago
             """
             dtm = dt_now - _cutoff  # .isoformat(timespec="microseconds") < needed?
 
             self._cu.execute("SELECT dtm FROM messages WHERE dtm => ?", (dtm,))
-            rows = self._cu.fetchall()
+            rows = self._cu.fetchall()  # fetch dtm of current messages to retain
 
             try:  # make this operation atomic, i.e. update self._msgs only on success
                 await self._lock.acquire()
@@ -234,7 +223,9 @@ class MessageIndex:
         finally:
             pass  # self._lock.release()
 
-        if dup:
+        if (
+            dup and msg.src is not msg.src
+        ):  # when src==dst, expect to add duplicate, don't check
             _LOGGER.warning(
                 "Overwrote dtm (%s) for %s: %s (contrived log?)",
                 msg.dtm,
@@ -251,7 +242,7 @@ class MessageIndex:
         Add a single record to the MessageIndex with timestamp now() and no Message contents.
         """
         # Used by OtbGateway init, via entity_base.py
-        dtm: DtmStrT = DtmStrT(dt.strftime(dt.now(), "%Y-%m-%dT%H:%M:%S"))
+        dtm: DtmStrT = dt.strftime(dt.now(), "%Y-%m-%dT%H:%M:%S")  # type: ignore[assignment]
         hdr = f"{code}|{verb}|{src}|00"  # dummy record has no contents
 
         dup = self._delete_from(hdr=hdr)
@@ -368,10 +359,36 @@ 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 |
+    # +----+--------------+-------------+------------+------+--------------------------+
+
     def get(
         self, msg: Message | None = None, **kwargs: bool | dt | str
     ) -> tuple[Message, ...]:
-        """Get a set of message(s) from the index."""
+        """
+        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
+        """
 
         if not (bool(msg) ^ bool(kwargs)):
             raise ValueError("Either a Message or kwargs should be provided, not both")
@@ -381,7 +398,33 @@ class MessageIndex:
 
         return self._select_from(**kwargs)
 
+    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
+        """
+
+        return len(self.qry_dtms(**kwargs)) > 0
+
+    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
+        """
+
+        return tuple(
+            self._msgs[row[0].isoformat(timespec="microseconds")]
+            for row in self.qry_dtms(**kwargs)
+        )
+
     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
+        """
         # tweak kwargs as stored in SQLite, inverse from _insert_into():
         kw = {key: value for key, value in kwargs.items() if key != "ctx"}
         if "ctx" in kwargs:
@@ -398,28 +441,13 @@ class MessageIndex:
         self._cu.execute(sql, tuple(kw.values()))
         return self._cu.fetchall()
 
-    def contains(self, **kwargs: bool | dt | str) -> bool:
+    def qry(self, sql: str, parameters: tuple[str, ...]) -> tuple[Message, ...]:
         """
-        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
+        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
         """
-        # adapted from _select_from()
-
-        return len(self.qry_dtms(**kwargs)) > 0
-
-    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"""
-
-        return tuple(
-            self._msgs[row[0].isoformat(timespec="microseconds")]
-            for row in self.qry_dtms(**kwargs)
-        )
-
-    def qry(self, sql: str, parameters: tuple[str, ...]) -> tuple[Message, ...]:
-        """Get a tuple of messages from the index, given sql and parameters."""
 
         if "SELECT" not in sql:
             raise ValueError(f"{self}: Only SELECT queries are allowed")
@@ -429,7 +457,9 @@ class MessageIndex:
         lst: list[Message] = []
         # stamp = list(self._msgs)[0] if len(self._msgs) > 0 else "N/A"  # for debug
         for row in self._cu.fetchall():
-            ts: DtmStrT = row[0].isoformat(timespec="microseconds")
+            ts: DtmStrT = row[0].isoformat(
+                timespec="microseconds"
+            )  # must reformat from DTM
             # _LOGGER.debug(
             #     f"QRY Msg key raw: {row[0]} Reformatted: {ts} _msgs stamp format: {stamp}"
             # )
@@ -438,21 +468,46 @@ class MessageIndex:
             if ts in self._msgs:
                 lst.append(self._msgs[ts])
             else:  # happens in tests with artificial msg from heat
-                _LOGGER.warning("MessageIndex ts %s not in device messages", ts)
+                _LOGGER.warning("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
+        """
+
+        def get_code(code: str) -> Code:
+            for Cd in CODES_SCHEMA:
+                if code == Cd:
+                    return Cd
+            raise LookupError(f"Failed to find matching code for {code}")
+
+        sql = """
+                SELECT code from messages WHERE verb is 'RP' AND (src = ? OR dst = ?)
+            """
+        if "SELECT" not in sql:
+            raise ValueError(f"{self}: Only SELECT queries are allowed")
+
+        self._cu.execute(sql, parameters)
+        res = self._cu.fetchall()
+        return [get_code(res[0]) for res[0] in self._cu.fetchall()]
+
     def qry_field(
         self, sql: str, parameters: tuple[str, ...]
     ) -> list[tuple[dt | str, str]]:
         """
-        Get a list of message field values from the index, given sql and parameters.
+        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
         """
 
         if "SELECT" not in sql:
             raise ValueError(f"{self}: Only SELECT queries are allowed")
 
         self._cu.execute(sql, parameters)
-
         return self._cu.fetchall()
 
     def all(self, include_expired: bool = False) -> tuple[Message, ...]:

ramses_rf/device/base.py

@@ -60,7 +60,7 @@ class DeviceBase(Entity):
     def __init__(self, gwy: Gateway, dev_addr: Address, **kwargs: Any) -> None:
         super().__init__(gwy)
 
-        # FIXME: ZZZ entities must know their parent device ID and their own idx
+        # FIXME: gwy.msg_db entities must know their parent device ID and their own idx
         self._z_id = dev_addr.id  # the responsible device is itself
         self._z_idx = None  # depends upon its location in the schema
 
@@ -76,8 +76,9 @@ class DeviceBase(Entity):
         self._scheme: Vendor = None
 
     def __str__(self) -> str:
-        if self._STATE_ATTR:
-            return f"{self.id} ({self._SLUG}): {getattr(self, self._STATE_ATTR)}"
+        if self._STATE_ATTR and hasattr(self, self._STATE_ATTR):
+            state: float | None = getattr(self, self._STATE_ATTR)
+            return f"{self.id} ({self._SLUG}): {state}"
         return f"{self.id} ({self._SLUG})"
 
     def __lt__(self, other: object) -> bool:
@@ -165,7 +166,11 @@ class DeviceBase(Entity):
     @property
     def has_battery(self) -> None | bool:  # 1060
         """Return True if the device is battery powered (excludes battery-backup)."""
-
+        if self._gwy.msg_db:
+            code_list = self._msg_dev_qry()
+            return isinstance(self, BatteryState) or (
+                code_list is not None and Code._1060 in code_list
+            )  # TODO(eb): clean up next line Q1 2026
         return isinstance(self, BatteryState) or Code._1060 in self._msgz
 
     @property
@@ -204,7 +209,7 @@ class DeviceBase(Entity):
 
     @property
     def traits(self) -> dict[str, Any]:
-        """Return the traits of the device."""
+        """Get the traits of the device."""
 
         result = super().traits
 

ramses_rf/device/heat.py

@@ -144,7 +144,7 @@ class Actuator(DeviceHeat):  # 3EF0, 3EF1 (for 10:/13:)
         if self._gwy.config.disable_discovery:
             return
 
-        # TODO: why are we doing this here? Should simply use dscovery poller!
+        # TODO: why are we doing this here? Should simply use discovery poller!
         if msg.code == Code._3EF0 and msg.verb == I_ and not self.is_faked:
             # lf._send_cmd(Command.get_relay_demand(self.id), qos=QOS_LOW)
             self._send_cmd(
@@ -429,7 +429,7 @@ class UfhController(Parent, DeviceHeat):  # UFC (02):
     def _handle_msg(self, msg: Message) -> None:
         super()._handle_msg(msg)
 
-        # Several assumptions ar emade, regarding 000C pkts:
+        # Several assumptions are made, regarding 000C pkts:
         # - UFC bound only to CTL (not, e.g. SEN)
         # - all circuits bound to the same controller
 
@@ -450,7 +450,7 @@ class UfhController(Parent, DeviceHeat):  # UFC (02):
                 #     )
                 #     self._send_cmd(cmd)
 
-        elif msg.code == Code._0008:  # relay_demand, TODO: use msg DB?
+        elif msg.code == Code._0008:  # relay_demand, TODO: use msgIndex DB?
             if msg.payload.get(SZ_DOMAIN_ID) == FC:
                 self._relay_demand = msg
             else:  # FA
@@ -491,7 +491,6 @@ class UfhController(Parent, DeviceHeat):  # UFC (02):
 
         # elif msg.code not in (Code._10E0, Code._22D0):
         #     print("xxx")
-
         # "0008|FA/FC", "22C9|array", "22D0|none", "3150|ZZ/array(/FC?)"
 
     # TODO: should be a private method
@@ -635,7 +634,7 @@ def _to_msg_id(data_id: OtDataId) -> MsgId:
     return f"{data_id:02X}"
 
 
-# NOTE: config.use_native_ot should enforces sends, but not reads from _msgz DB
+# NOTE: config.use_native_ot should enforce sends, but not reads from _msgz DB
 class OtbGateway(Actuator, HeatDemand):  # OTB (10): 3220 (22D9, others)
     """The OTB class, specifically an OpenTherm Bridge (R8810A Bridge)."""
 
@@ -668,7 +667,16 @@ class OtbGateway(Actuator, HeatDemand):  # OTB (10): 3220 (22D9, others)
 
         self._child_id = FC  # NOTE: domain_id
 
-        self._msgz[Code._3220] = {RP: {}}  # _msgz[Code._3220][RP][msg_id]
+        # TODO(eb): cleanup
+        # should fix src/ramses_rf/database.py _add_record try/except when activating next line
+        if self._gwy.msg_db:
+            self._add_record(
+                address=self.addr, code=Code._3220, verb="RP"
+            )  # << essential?
+        # adds a "sim" RP opentherm_msg to the SQLite MessageIndex with code _3220
+        # causes exc when fetching ALL, when no "real" msg was added to _msgs_. We skip those.
+        else:
+            self._msgz[Code._3220] = {RP: {}}  # No ctx! (not None)
 
         # lf._use_ot = self._gwy.config.use_native_ot
         self._msgs_ot: dict[MsgId, Message] = {}
@@ -758,7 +766,7 @@ class OtbGateway(Actuator, HeatDemand):  # OTB (10): 3220 (22D9, others)
         if msg.payload.get(SZ_VALUE) is None:
             return
 
-        # msg_id is int in msg payload/opentherm.py, but MsgId (str) is in this module
+        # msg_id is int in msg payload/opentherm.py, but MsgId (str) in this module
         msg_id = _to_msg_id(msg.payload[SZ_MSG_ID])
         self._msgs_ot[msg_id] = msg
 

ramses_rf/device/hvac.py

@@ -426,7 +426,7 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
     Also handles 2411 parameter messages for configuration.
     Since 2411 is not supported by all vendors, discovery is used to determine if it is supported.
     Since more than 1 different parameters can be sent on 2411 messages,
-    we will process these in the dedicated _handle_2411_message method.
+    we process these in the dedicated _handle_2411_message method.
     """
 
     # Itho Daalderop (NL)
@@ -606,7 +606,7 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
         It handles parameter value normalization and validation.
 
         :param msg: The incoming 2411 message
-        :type msg: Message
+        :type msg: Message to process
         """
         if not hasattr(msg, "payload") or not isinstance(msg.payload, dict):
             _LOGGER.debug("Invalid 2411 message format: %s", msg)
@@ -653,7 +653,7 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
         handling for 2411 parameter messages. It updates the device state and
         triggers any necessary callbacks.
 
-        After handling the messages, it calls the initialized callback if set to notify that
+        After handling the messages, it calls the initialized callback - if set - to notify that
         the device was fully initialized.
 
         :param msg: The incoming message to process
@@ -911,14 +911,38 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A], 2411
     @property
     def fan_info(self) -> str | None:
         """
-        Extract fan info description from _31D9 or _31DA message payload, e.g. "speed 2, medium".
+        Extract fan info description from MessageIndex _31D9 or _31DA payload,
+        e.g. "speed 2, medium".
         By its name, the result is picked up by a sensor in HA Climate UI.
         Some manufacturers (Orcon, Vasco) include the fan mode (auto, manual), others don't (Itho).
 
-        :return: a string describing fan mode, speed
-        """
+        :return: string describing fan mode, speed
+        """
+        if self._gwy.msg_db:
+            # Use SQLite query on MessageIndex. res_rate/res_mode not exposed yet
+            sql = f"""
+                SELECT code from messages WHERE verb in (' I', 'RP')
+                AND (src = ? OR dst = ?)
+                AND (plk LIKE '%{SZ_FAN_MODE}%')
+            """
+            res_mode: list = self._msg_qry(sql)
+            # SQLite query on MessageIndex
+            _LOGGER.info(f"{res_mode} # FAN_MODE FETCHED from MessageIndex")
+
+            sql = f"""
+                SELECT code from messages WHERE verb in (' I', 'RP')
+                AND (src = ? OR dst = ?)
+                AND (plk LIKE '%{SZ_FAN_RATE}%')
+            """
+            res_rate: list = self._msg_qry(sql)
+            # SQLite query on MessageIndex
+            _LOGGER.info(
+                f"{res_rate} # FAN_RATE FETCHED from MessageIndex"
+            )  # DEBUG always empty?
+
         if Code._31D9 in self._msgs:
-            # Itho, Vasco D60 and ClimaRad (MiniBox fan) send mode/speed in _31D9
+            # was a dict by Code
+            # Itho, Vasco D60 and ClimaRad MiniBox fan send mode/speed in _31D9
             v: str
             for k, v in self._msgs[Code._31D9].payload.items():
                 if k == SZ_FAN_MODE and len(v) > 2:  # prevent non-lookups to pass

ramses_rf/dispatcher.py

@@ -268,10 +268,10 @@ def process_msg(gwy: Gateway, msg: Message) -> None:
 
     else:
         logger_xxxx(msg)
-        if gwy.msg_db:
-            gwy.msg_db.add(
-                msg
-            )  # why add it anyway? will fail in testst comparing to _msgs
+        # if gwy.msg_db:
+        #     gwy.msg_db.add(
+        #         msg
+        #     )  # why add it? passes all tests without
 
 
 # TODO: this needs cleaning up (e.g. handle intervening packet)