ramses-rf 0.51.5__tar.gz → 0.51.6__tar.gz

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/.github/workflows/check-lint.yml

@@ -34,7 +34,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/.github/workflows/check-test.yml

@@ -34,7 +34,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/.github/workflows/check-type.yml

@@ -34,7 +34,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ramses_rf
-Version: 0.51.5
+Version: 0.51.6
 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
@@ -67,6 +67,6 @@ pip install -e .
 
 The CLI is called ``client.py`` and is included in the code root.
 It has options to monitor and parse Ramses-II traffic to screen or a log file, and to parse a file containing Ramses-II messages to the screen.
-See the [client.py CLI wiki page](https://github.com/ramses-rf/ramses_rf/wiki/The-client.py-command-line) for instructions.
+See the [client.py CLI wiki page](https://github.com/ramses-rf/ramses_rf/wiki/2.-The-client.py-command-line) for instructions.
 
 For code development, some more setup is required. Please follow the steps in our [Developer's Resource](README-developers.md)

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/README.md

@@ -46,6 +46,6 @@ pip install -e .
 
 The CLI is called ``client.py`` and is included in the code root.
 It has options to monitor and parse Ramses-II traffic to screen or a log file, and to parse a file containing Ramses-II messages to the screen.
-See the [client.py CLI wiki page](https://github.com/ramses-rf/ramses_rf/wiki/The-client.py-command-line) for instructions.
+See the [client.py CLI wiki page](https://github.com/ramses-rf/ramses_rf/wiki/2.-The-client.py-command-line) for instructions.
 
 For code development, some more setup is required. Please follow the steps in our [Developer's Resource](README-developers.md)

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_cli/client.py

@@ -483,7 +483,6 @@ async def async_main(command: str, lib_kwargs: dict, **kwargs: Any) -> None:
             print(f"{COLORS.get(msg.verb)}{dtm} {msg}"[:con_cols])
 
     serial_port, lib_kwargs = normalise_config(lib_kwargs)
-    assert isinstance(lib_kwargs.get(SZ_INPUT_FILE), str)
 
     if kwargs["restore_schema"]:
         print(" - restoring client schema from a HA cache...")

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/database.py

@@ -29,6 +29,22 @@ class Params(TypedDict):
 _LOGGER = logging.getLogger(__name__)
 
 
+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."""
+        return val.isoformat(timespec="microseconds")
+
+    sqlite3.register_adapter(dt, adapt_datetime_iso)
+
+    def convert_datetime(val: bytes) -> dt:
+        """Convert ISO 8601 datetime to datetime.datetime object."""
+        return dt.fromisoformat(val.decode())
+
+    sqlite3.register_converter("dtm", convert_datetime)
+
+
 class MessageIndex:
     """A simple in-memory SQLite3 database for indexing messages."""
 
@@ -40,7 +56,7 @@ class MessageIndex:
         self._cx = sqlite3.connect(":memory:")  # Connect to a SQLite DB in memory
         self._cu = self._cx.cursor()  # Create a cursor
 
-        self._setup_db_adapters()  # dtm adapter/converter
+        _setup_db_adapters()  # dtm adapter/converter
         self._setup_db_schema()
 
         self._lock = asyncio.Lock()
@@ -76,23 +92,19 @@ class MessageIndex:
         """Return the messages in the index in a threadsafe way."""
         return self._msgs
 
-    def _setup_db_adapters(self) -> None:
-        """Setup the database adapters and converters."""
-
-        def adapt_datetime_iso(val: dt) -> str:
-            """Adapt datetime.datetime to timezone-naive ISO 8601 datetime."""
-            return val.isoformat(timespec="microseconds")
-
-        sqlite3.register_adapter(dt, adapt_datetime_iso)
-
-        def convert_datetime(val: bytes) -> dt:
-            """Convert ISO 8601 datetime to datetime.datetime object."""
-            return dt.fromisoformat(val.decode())
+    def _setup_db_schema(self) -> None:
+        """Set up the message database schema.
 
-        sqlite3.register_converter("dtm", convert_datetime)
+        Fields:
 
-    def _setup_db_schema(self) -> None:
-        """Setup the dayabase schema."""
+        - 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)
+        """
 
         self._cu.execute(
             """
@@ -120,14 +132,14 @@ class MessageIndex:
     async def _housekeeping_loop(self) -> None:
         """Periodically remove stale messages from the index."""
 
-        def housekeeping(dt_now: dt, _cutoff: td = td(days=1)) -> None:
+        async def housekeeping(dt_now: dt, _cutoff: td = td(days=1)) -> None:
             dtm = (dt_now - _cutoff).isoformat(timespec="microseconds")
 
             self._cu.execute("SELECT dtm FROM messages WHERE dtm => ?", (dtm,))
             rows = self._cu.fetchall()
 
             try:  # make this operation atomic, i.e. update self._msgs only on success
-                # await self._lock.acquire()
+                await self._lock.acquire()
                 self._cu.execute("DELETE FROM messages WHERE dtm < ?", (dtm,))
                 msgs = OrderedDict({row[0]: self._msgs[row[0]] for row in rows})
                 self._cx.commit()
@@ -137,19 +149,19 @@ class MessageIndex:
             else:
                 self._msgs = msgs
             finally:
-                pass  # self._lock.release()
+                self._lock.release()
 
         while True:
             self._last_housekeeping = dt.now()
             await asyncio.sleep(3600)
-            housekeeping(self._last_housekeeping)
+            await housekeeping(self._last_housekeeping)
 
     def add(self, msg: Message) -> Message | None:
         """Add a single message to the index.
 
         Returns any message that was removed because it had the same header.
 
-        Throws a warning is there is a duplicate dtm.
+        Throws a warning if there is a duplicate dtm.
         """  # TODO: eventually, may be better to use SqlAlchemy
 
         dup: tuple[Message, ...] = tuple()  # avoid UnboundLocalError
@@ -204,7 +216,9 @@ class MessageIndex:
 
         return msgs[0] if msgs else None
 
-    def rem(self, msg: Message | None = None, **kwargs: str) -> tuple[Message, ...]:
+    def rem(
+        self, msg: Message | None = None, **kwargs: str
+    ) -> tuple[Message, ...] | None:
         """Remove a set of message(s) from the index.
 
         Returns any messages that were removed.
@@ -215,6 +229,7 @@ class MessageIndex:
         if msg:
             kwargs["dtm"] = msg.dtm.isoformat(timespec="microseconds")
 
+        msgs = None
         try:  # make this operation atomic, i.e. update self._msgs only on success
             # await self._lock.acquire()
             msgs = self._delete_from(**kwargs)
@@ -277,8 +292,8 @@ class MessageIndex:
     def all(self, include_expired: bool = False) -> tuple[Message, ...]:
         """Return all messages from the index."""
 
-        # self.cursor.execute("SELECT * FROM messages")
-        # return [self._megs[row[0]] for row in self.cursor.fetchall()]
+        # self._cu.execute("SELECT * FROM messages")
+        # return tuple(self._msgs[row[0]] for row in self._cu.fetchall())
 
         return tuple(
             m for m in self._msgs.values() if include_expired or not m._expired

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/device/base.py

@@ -62,7 +62,7 @@ class DeviceBase(Entity):
 
         # FIXME: ZZZ entities must know their parent device ID and their own idx
         self._z_id = dev_addr.id  # the responsible device is itself
-        self._z_idx = None  # depends upon it's location in the schema
+        self._z_idx = None  # depends upon its location in the schema
 
         self.id: DeviceIdT = dev_addr.id
 
@@ -95,7 +95,7 @@ class DeviceBase(Entity):
 
         if traits.get(SZ_FAKED):  # class & alias are done elsewhere
             if not isinstance(self, Fakeable):
-                raise TypeError(f"Device is not fakable: {self} (traits={traits})")
+                raise TypeError(f"Device is not fakeable: {self} (traits={traits})")
             self._make_fake()
 
         self._scheme = traits.get(SZ_SCHEME)

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/device/hvac.py

@@ -449,10 +449,10 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A]
     def fan_info(self) -> str | None:
         """
         Extract fan info description from _31D9 or _31DA message payload, e.g. "speed 2, medium".
-        By its name, the result is automatically displayed in HA Climate UI.
+        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 mode, speed
+        :return: a string describing fan mode, speed
         """
         if Code._31D9 in self._msgs:
             # Itho, Vasco D60 and ClimaRad (MiniBox fan) send mode/speed in _31D9
@@ -466,9 +466,10 @@ class HvacVentilator(FilterChange):  # FAN: RP/31DA, I/31D[9A]
     @property
     def indoor_humidity(self) -> float | None:
         """
-        Extract humidity value from _12A0 or _31DA JSON message payload
+        Extract indoor_humidity from MessageIndex _12A0 or _31DA payload
+        Just a demo for SQLite query helper at the moment.
 
-        :return: percentage <= 1.0
+        :return: float RH value from 0.0 to 1.0 = 100%
         """
         if Code._12A0 in self._msgs and isinstance(
             self._msgs[Code._12A0].payload, list

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/dispatcher.py

@@ -268,8 +268,8 @@ def process_msg(gwy: Gateway, msg: Message) -> None:
 
     else:
         logger_xxxx(msg)
-        if gwy._zzz:
-            gwy._zzz.add(msg)
+        if gwy.msg_db:
+            gwy.msg_db.add(msg)
 
 
 # TODO: this needs cleaning up (e.g. handle intervening packet)

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/entity_base.py

@@ -190,7 +190,7 @@ class _MessageDB(_Entity):
     def __init__(self, gwy: Gateway) -> None:
         super().__init__(gwy)
 
-        self._msgs_: dict[Code, Message] = {}  # code, should be code/ctx? ?deprecate
+        self._msgs_: dict[Code, Message] = {}  # code, should be code/ctx?
         self._msgz_: dict[
             Code, dict[VerbT, dict[bool | str | None, Message]]
         ] = {}  # code/verb/ctx, should be code/ctx/verb?
@@ -205,19 +205,19 @@ class _MessageDB(_Entity):
         ):
             return  # ZZZ: don't store these
 
+        # Store msg by code in flat self._msgs_ Dict (deprecated since 0.50.3)
         if msg.verb in (I_, RP):
             self._msgs_[msg.code] = msg
 
         if msg.code not in self._msgz_:
+            # Store msg verb + ctx by code in nested self._msgz_ Dict (deprecated)
             self._msgz_[msg.code] = {msg.verb: {msg._pkt._ctx: msg}}
         elif msg.verb not in self._msgz_[msg.code]:
+            # Same, 1 level deeper
             self._msgz_[msg.code][msg.verb] = {msg._pkt._ctx: msg}
-        else:  # if not self._gwy._zzz:
+        else:
+            # Same, replacing previous message
             self._msgz_[msg.code][msg.verb][msg._pkt._ctx] = msg
-        # elif (
-        #     self._msgz[msg.code][msg.verb][msg._pkt._ctx] is not msg
-        # ):  # MsgIdx ensures this
-        #     assert False  # TODO: remove
 
     @property
     def _msg_db(self) -> list[Message]:  # flattened version of _msgz[code][verb][indx]
@@ -228,7 +228,7 @@ class _MessageDB(_Entity):
          - a compound ctx (e.g. 0005/000C/0418)
          - True (an array of elements, each with its own idx),
          - False (no idx, is usu. 00),
-         - None (not deteminable, rare)
+         - None (not determinable, rare)
         """
         return [m for c in self._msgz.values() for v in c.values() for m in v.values()]
 
@@ -239,8 +239,8 @@ class _MessageDB(_Entity):
 
         obj: _MessageDB
 
-        if self._gwy._zzz:
-            self._gwy._zzz.rem(msg)
+        if self._gwy.msg_db:  # central SQLite MessageIndex
+            self._gwy.msg_db.rem(msg)
 
         entities: list[_MessageDB] = []
         if isinstance(msg.src, Device):
@@ -261,8 +261,8 @@ class _MessageDB(_Entity):
     def _get_msg_by_hdr(self, hdr: HeaderT) -> Message | None:
         """Return a msg, if any, that matches a header."""
 
-        # if self._gwy._zzz:
-        #     msgs = self._gwy._zzz.get(hdr=hdr)
+        # if self._gwy.msg_db:  # central SQLite MessageIndex
+        #     msgs = self._gwy.msg_db.get(hdr=hdr)
         #     return msgs[0] if msgs else None
 
         msg: Message
@@ -394,19 +394,29 @@ class _MessageDB(_Entity):
 
     @property
     def _msgs(self) -> dict[Code, Message]:
-        if not self._gwy._zzz:
+        """
+        Get a flat Dict af all I/RP messages logged with this device as src or dst.
+
+        :return: nested Dict of messages by Code
+        """
+        if not self._gwy.msg_db:  # no central SQLite MessageIndex
             return self._msgs_
 
         sql = """
             SELECT dtm from messages WHERE verb in (' I', 'RP') AND (src = ? OR dst = ?)
         """
-        return {  # ? use context instead?
-            m.code: m for m in self._gwy._zzz.qry(sql, (self.id[:9], self.id[:9]))
+        return {  # ? use ctx (context) instead of just the address?
+            m.code: m for m in self._gwy.msg_db.qry(sql, (self.id[:9], self.id[:9]))
         }  # e.g. 01:123456_HW
 
     @property
     def _msgz(self) -> dict[Code, dict[VerbT, dict[bool | str | None, Message]]]:
-        if not self._gwy._zzz:
+        """
+        Get a nested Dict of all I/RP messages logged with this device as src or dst.
+
+        :return: Dict of messages, nested by Code, Verb, Context
+        """
+        if not self._gwy.msg_db:  # no central SQLite MessageIndex
             return self._msgz_
 
         msgs_1: dict[Code, dict[VerbT, dict[bool | str | None, Message]]] = {}
@@ -437,7 +447,7 @@ class _Discovery(_MessageDB):
         self._supported_cmds_ctx: dict[str, bool | None] = {}
 
         if not gwy.config.disable_discovery:
-            # self._start_discovery_poller()  # Can't use derived classes dont exist yet
+            # self._start_discovery_poller()  # Can't use derived classes don't exist yet
             gwy._loop.call_soon(self._start_discovery_poller)
 
     @property  # TODO: needs tidy up
@@ -464,7 +474,7 @@ class _Discovery(_MessageDB):
         def _to_data_id(msg_id: MsgId | str) -> OtDataId:
             return int(msg_id, 16)  # type: ignore[return-value]
 
-        def _to_msg_id(data_id: OtDataId | int) -> MsgId:
+        def _to_msg_id(data_id: OtDataId | int) -> MsgId:  # not used
             return f"{data_id:02X}"  # type: ignore[return-value]
 
         return {
@@ -639,7 +649,7 @@ class _Discovery(_MessageDB):
                 task[_SZ_NEXT_DUE] = msg.dtm + task[_SZ_INTERVAL]
 
             if task[_SZ_NEXT_DUE] > dt_now:
-                continue  # if (most recent) last_msg is is not yet due...
+                continue  # if (most recent) last_msg is not yet due...
 
             # since we may do I/O, check if the code|msg_id is deprecated
             task[_SZ_NEXT_DUE] = dt_now + task[_SZ_INTERVAL]  # might undeprecate later
@@ -733,25 +743,6 @@ class Parent(Entity):  # A System, Zone, DhwZone or a UfhController
         self.child_by_id: dict[str, Child] = {}
         self.childs: list[Child] = []
 
-    # def _handle_msg(self, msg: Message) -> None:
-    #     def eavesdrop_ufh_circuits():
-    #         if msg.code == Code._22C9:
-    #             # .I --- 02:044446 --:------ 02:044446 22C9 024 00-076C0A28-01 01-06720A28-01 02-06A40A28-01 03-06A40A2-801  # NOTE: fragments
-    #             # .I --- 02:044446 --:------ 02:044446 22C9 006 04-07D00A28-01                                               # [{'ufh_idx': '04',...
-    #             circuit_idxs = [c[SZ_UFH_IDX] for c in msg.payload]
-
-    #             for cct_idx in circuit_idxs:
-    #                 self.get_circuit(cct_idx, msg=msg)
-
-    #             # BUG: this will fail with > 4 circuits, as uses two pkts for this msg
-    #             # if [c for c in self.child_by_id if c not in circuit_idxs]:
-    #             #     raise CorruptStateError
-
-    #     super()._handle_msg(msg)
-
-    #     if self._gwy.config.enable_eavesdrop:
-    #         eavesdrop_ufh_circuits()
-
     @property
     def zone_idx(self) -> str:
         """Return the domain id.

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/gateway.py

@@ -129,7 +129,7 @@ class Gateway(Engine):
         self.devices: list[Device] = []
         self.device_by_id: dict[DeviceIdT, Device] = {}
 
-        self._zzz: MessageIndex | None = None  # MessageIndex()
+        self.msg_db: MessageIndex | None = None  # MessageIndex()
 
     def __repr__(self) -> str:
         if not self.ser_name:
@@ -196,8 +196,8 @@ class Gateway(Engine):
     async def stop(self) -> None:
         """Stop the Gateway and tidy up."""
 
-        if self._zzz:
-            self._zzz.stop()
+        if self.msg_db:
+            self.msg_db.stop()
         await super().stop()
 
     def _pause(self, *args: Any) -> None:
@@ -255,10 +255,10 @@ class Gateway(Engine):
             msgs.extend([m for z in system.zones for m in z._msgs.values()])
             # msgs.extend([m for z in system.dhw for m in z._msgs.values()])  # TODO
 
-        if self._zzz:
+        if self.msg_db:
             pkts = {
                 f"{repr(msg._pkt)[:26]}": f"{repr(msg._pkt)[27:]}"
-                for msg in self._zzz.all(include_expired=True)
+                for msg in self.msg_db.all(include_expired=True)
                 if wanted_msg(msg, include_expired=include_expired)
             }
 
@@ -405,7 +405,7 @@ class Gateway(Engine):
                     _LOGGER.warning(f"The device is not fakeable: {dev}")
 
         # TODO: the exact order of the following may need refining...
-        # TODO: some will be done my devices themselves?
+        # TODO: some will be done by devices themselves?
 
         # if schema:  # Step 2: Only controllers have a schema...
         #     dev._update_schema(**schema)  # TODO: schema/traits
@@ -422,7 +422,7 @@ class Gateway(Engine):
         self,
         device_id: DeviceIdT,
         create_device: bool = False,
-    ) -> Device:
+    ) -> Device | Fakeable:
         """Create a faked device."""
 
         if not is_valid_dev_id(device_id):
@@ -437,7 +437,7 @@ class Gateway(Engine):
             dev._make_fake()
             return dev
 
-        raise TypeError(f"The device is not fakable: {device_id}")
+        raise TypeError(f"The device is not fakeable: {device_id}")
 
     @property
     def tcs(self) -> Evohome | None:
@@ -547,14 +547,6 @@ class Gateway(Engine):
 
     def _msg_handler(self, msg: Message) -> None:
         """A callback to handle messages from the protocol stack."""
-        # TODO: Remove this
-        # # HACK: if CLI, double-logging with client.py proc_msg() & setLevel(DEBUG)
-        # if (log_level := _LOGGER.getEffectiveLevel()) < logging.INFO:
-        #     _LOGGER.info(msg)
-        # elif log_level <= logging.INFO and not (
-        #     msg.verb == RQ and msg.src.type == DEV_TYPE_MAP.HGI
-        # ):
-        #     _LOGGER.info(msg)
 
         super()._msg_handler(msg)
 

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/system/zones.py

@@ -699,8 +699,10 @@ class Zone(ZoneSchedule):
     def name(self) -> str | None:  # 0004
         """Return the name of the zone."""
 
-        if self._gwy._zzz:
-            msgs = self._gwy._zzz.get(code=Code._0004, src=self._z_id, ctx=self._z_idx)
+        if self._gwy.msg_db:
+            msgs = self._gwy.msg_db.get(
+                code=Code._0004, src=self._z_id, ctx=self._z_idx
+            )
             return msgs[0].payload.get(SZ_NAME) if msgs else None
 
         return self._msg_value(Code._0004, key=SZ_NAME)  # type: ignore[no-any-return]

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_rf/version.py

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

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_tx/__init__.py

@@ -138,7 +138,7 @@ if TYPE_CHECKING:
 async def set_pkt_logging_config(**config: Any) -> Logger:
     """
     Set up ramses packet logging to a file or port.
-    Must runs async in executor to prevent HA blocking call opening packet log file (issue #200)
+    Must run async in executor to prevent HA blocking call opening packet log file (issue #200)
 
     :param config: if file_name is included, opens packet_log file
     :return: a logging.Logger

{ramses_rf-0.51.5 → ramses_rf-0.51.6}/ramses_tx/address.py

@@ -45,7 +45,7 @@ class Address:
         #     device_id = NON_DEVICE_ID
 
         self.id = device_id  # TODO: check is a valid id...
-        self.type = device_id[:2]  # dex, NOTE: remove last
+        self.type = device_id[:2]  # dex, drops 2nd part, incl. ":"
         self._hex_id: str = None  # type: ignore[assignment]
 
         if not self.is_valid(device_id):