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

ramses_rf/const.py

@@ -1,123 +1,142 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 """RAMSES RF - a RAMSES-II protocol decoder & analyser."""
+
 from __future__ import annotations
 
-from types import SimpleNamespace
+from enum import IntEnum
+from typing import TYPE_CHECKING, Final
+
+from ramses_tx.const import (  # noqa: F401
+    DEFAULT_MAX_ZONES as DEFAULT_MAX_ZONES,
+    DEVICE_ID_REGEX as DEVICE_ID_REGEX,
+    DOMAIN_TYPE_MAP as DOMAIN_TYPE_MAP,
+    FAN_MODE as FAN_MODE,  # deprecated, use SZ_FAN_MODE, to be removed in Q1 2026
+    SYS_MODE_MAP as SYS_MODE_MAP,
+    SZ_ACCEPT as SZ_ACCEPT,
+    SZ_ACTUATORS as SZ_ACTUATORS,
+    SZ_AIR_QUALITY as SZ_AIR_QUALITY,
+    SZ_AIR_QUALITY_BASIS as SZ_AIR_QUALITY_BASIS,
+    SZ_BOOST_TIMER as SZ_BOOST_TIMER,
+    SZ_BYPASS_MODE as SZ_BYPASS_MODE,
+    SZ_BYPASS_POSITION as SZ_BYPASS_POSITION,
+    SZ_BYPASS_STATE as SZ_BYPASS_STATE,
+    SZ_CHANGE_COUNTER as SZ_CHANGE_COUNTER,
+    SZ_CO2_LEVEL as SZ_CO2_LEVEL,
+    SZ_CONFIRM as SZ_CONFIRM,
+    SZ_DATETIME as SZ_DATETIME,
+    SZ_DEVICE_ID as SZ_DEVICE_ID,
+    SZ_DEVICE_ROLE as SZ_DEVICE_ROLE,
+    SZ_DEVICES as SZ_DEVICES,
+    SZ_DHW_IDX as SZ_DHW_IDX,
+    SZ_DOMAIN_ID as SZ_DOMAIN_ID,
+    SZ_DURATION as SZ_DURATION,
+    SZ_EXHAUST_FAN_SPEED as SZ_EXHAUST_FAN_SPEED,
+    SZ_EXHAUST_FLOW as SZ_EXHAUST_FLOW,
+    SZ_EXHAUST_TEMP as SZ_EXHAUST_TEMP,
+    SZ_FAN_INFO as SZ_FAN_INFO,
+    SZ_FAN_MODE as SZ_FAN_MODE,
+    SZ_FAN_RATE as SZ_FAN_RATE,
+    SZ_FILTER_REMAINING as SZ_FILTER_REMAINING,
+    SZ_FRAG_LENGTH as SZ_FRAG_LENGTH,
+    SZ_FRAG_NUMBER as SZ_FRAG_NUMBER,
+    SZ_FRAGMENT as SZ_FRAGMENT,
+    SZ_HEAT_DEMAND as SZ_HEAT_DEMAND,
+    SZ_INDOOR_HUMIDITY as SZ_INDOOR_HUMIDITY,
+    SZ_INDOOR_TEMP as SZ_INDOOR_TEMP,
+    SZ_LANGUAGE as SZ_LANGUAGE,
+    SZ_MODE as SZ_MODE,
+    SZ_NAME as SZ_NAME,
+    SZ_OEM_CODE as SZ_OEM_CODE,
+    SZ_OFFER as SZ_OFFER,
+    SZ_OUTDOOR_HUMIDITY as SZ_OUTDOOR_HUMIDITY,
+    SZ_OUTDOOR_TEMP as SZ_OUTDOOR_TEMP,
+    SZ_PAYLOAD as SZ_PAYLOAD,
+    SZ_PHASE as SZ_PHASE,
+    SZ_POST_HEAT as SZ_POST_HEAT,
+    SZ_PRE_HEAT as SZ_PRE_HEAT,
+    SZ_PRESENCE_DETECTED as SZ_PRESENCE_DETECTED,
+    SZ_PRESSURE as SZ_PRESSURE,
+    SZ_RELAY_DEMAND as SZ_RELAY_DEMAND,
+    SZ_RELAY_FAILSAFE as SZ_RELAY_FAILSAFE,
+    SZ_REMAINING_DAYS as SZ_REMAINING_DAYS,
+    SZ_REMAINING_MINS as SZ_REMAINING_MINS,
+    SZ_REMAINING_PERCENT as SZ_REMAINING_PERCENT,
+    SZ_SCHEDULE as SZ_SCHEDULE,
+    SZ_SENSOR as SZ_SENSOR,
+    SZ_SETPOINT as SZ_SETPOINT,
+    SZ_SPEED_CAPABILITIES as SZ_SPEED_CAPABILITIES,
+    SZ_SUPPLY_FAN_SPEED as SZ_SUPPLY_FAN_SPEED,
+    SZ_SUPPLY_FLOW as SZ_SUPPLY_FLOW,
+    SZ_SUPPLY_TEMP as SZ_SUPPLY_TEMP,
+    SZ_SYSTEM_MODE as SZ_SYSTEM_MODE,
+    SZ_TEMPERATURE as SZ_TEMPERATURE,
+    SZ_TOTAL_FRAGS as SZ_TOTAL_FRAGS,
+    SZ_UFH_IDX as SZ_UFH_IDX,
+    SZ_UNKNOWN as SZ_UNKNOWN,
+    SZ_UNTIL as SZ_UNTIL,
+    SZ_VALUE as SZ_VALUE,
+    SZ_WINDOW_OPEN as SZ_WINDOW_OPEN,
+    SZ_ZONE_CLASS as SZ_ZONE_CLASS,
+    SZ_ZONE_IDX as SZ_ZONE_IDX,
+    SZ_ZONE_MASK as SZ_ZONE_MASK,
+    SZ_ZONE_TYPE as SZ_ZONE_TYPE,
+    SZ_ZONES as SZ_ZONES,
+    ZON_MODE_MAP as ZON_MODE_MAP,
+    SystemType as SystemType,
+)
 
-from .protocol.const import (  # noqa: F401
-    DEFAULT_MAX_ZONES,
-    DEVICE_ID_REGEX,
-    DOMAIN_TYPE_MAP,
-    FAN_MODE,
-    SYS_MODE_MAP,
-    SZ_ACTUATORS,
-    SZ_AIR_QUALITY,
-    SZ_AIR_QUALITY_BASE,
-    SZ_BOOST_TIMER,
-    SZ_BYPASS_POSITION,
-    SZ_CHANGE_COUNTER,
-    SZ_CO2_LEVEL,
-    SZ_DATETIME,
-    SZ_DEVICE_ID,
-    SZ_DEVICE_ROLE,
-    SZ_DEVICES,
-    SZ_DHW_IDX,
-    SZ_DOMAIN_ID,
-    SZ_DURATION,
-    SZ_EXHAUST_FAN_SPEED,
-    SZ_EXHAUST_FLOW,
-    SZ_EXHAUST_TEMPERATURE,
-    SZ_FAN_INFO,
-    SZ_FAN_MODE,
-    SZ_FRAG_LENGTH,
-    SZ_FRAG_NUMBER,
-    SZ_FRAGMENT,
-    SZ_HEAT_DEMAND,
-    SZ_INDOOR_HUMIDITY,
-    SZ_INDOOR_TEMPERATURE,
-    SZ_LANGUAGE,
-    SZ_MODE,
-    SZ_NAME,
-    SZ_OUTDOOR_HUMIDITY,
-    SZ_OUTDOOR_TEMPERATURE,
-    SZ_PAYLOAD,
-    SZ_POST_HEAT,
-    SZ_PRE_HEAT,
-    SZ_PRESENCE_DETECTED,
-    SZ_PRESSURE,
-    SZ_PRIORITY,
-    SZ_RELAY_DEMAND,
-    SZ_RELAY_FAILSAFE,
-    SZ_REMAINING_TIME,
-    SZ_RETRIES,
-    SZ_SCHEDULE,
-    SZ_SENSOR,
-    SZ_SETPOINT,
-    SZ_SPEED_CAP,
-    SZ_SUPPLY_FAN_SPEED,
-    SZ_SUPPLY_FLOW,
-    SZ_SUPPLY_TEMPERATURE,
-    SZ_SYSTEM_MODE,
-    SZ_TEMPERATURE,
-    SZ_TOTAL_FRAGS,
-    SZ_UFH_IDX,
-    SZ_UNKNOWN,
-    SZ_UNTIL,
-    SZ_VALUE,
-    SZ_WINDOW_OPEN,
-    SZ_ZONE_CLASS,
-    SZ_ZONE_IDX,
-    SZ_ZONE_MASK,
-    SZ_ZONE_TYPE,
-    SZ_ZONES,
-    ZON_MODE_MAP,
-    SystemType,
+from ramses_tx.const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
+    I_ as I_,
+    RP as RP,
+    RQ as RQ,
+    W_ as W_,
+    Code as Code,
+    IndexT as IndexT,
+    VerbT as VerbT,
 )
 
-# skipcq: PY-W2000
-from .protocol import (  # noqa: F401, isort: skip, pylint: disable=unused-import
-    I_,
-    RP,
-    RQ,
-    W_,
-    F9,
-    FA,
-    FC,
-    FF,
-    DEV_ROLE,
-    DEV_ROLE_MAP,
-    DEV_TYPE,
-    DEV_TYPE_MAP,
-    ZON_ROLE,
-    ZON_ROLE_MAP,
-    Code,
+from ramses_tx.const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
+    F9 as F9,
+    FA as FA,
+    FC as FC,
+    FF as FF,
+    DEV_ROLE_MAP as DEV_ROLE_MAP,
+    DEV_TYPE_MAP as DEV_TYPE_MAP,
+    ZON_ROLE_MAP as ZON_ROLE_MAP,
+    DevRole as DevRole,
+    DevType as DevType,
+    ZoneRole as ZoneRole,
 )
 
+if TYPE_CHECKING:
+    from ramses_tx.const import (  # noqa: F401, pylint: disable=unused-import
+        IndexT,
+        VerbT,
+    )
 
-__dev_mode__ = False
-# DEV_MODE = __dev_mode__
 
-Discover = SimpleNamespace(
-    NOTHING=0,
-    SCHEMA=1,
-    PARAMS=2,
-    STATUS=4,
-    FAULTS=8,
-    SCHEDS=16,
-    TRAITS=32,
-    DEFAULT=(1 + 2 + 4),
-)
+__dev_mode__ = False  # NOTE: this is const.py
+
+
+class Discover(IntEnum):
+    NOTHING = 0
+    SCHEMA = 1
+    PARAMS = 2
+    STATUS = 4
+    FAULTS = 8
+    SCHEDS = 16
+    TRAITS = 32
+    DEFAULT = 1 + 2 + 4
+
 
-DONT_CREATE_MESSAGES = 3
-DONT_CREATE_ENTITIES = 2
-DONT_UPDATE_ENTITIES = 1
+DONT_CREATE_MESSAGES: Final[int] = 3
+DONT_CREATE_ENTITIES: Final[int] = 2
+DONT_UPDATE_ENTITIES: Final[int] = 1
 
-SCHED_REFRESH_INTERVAL = 3  # minutes
+SCHED_REFRESH_INTERVAL: Final[int] = 3  # minutes
 
 # Status codes for Worcester Bosch boilers - OT|OEM diagnostic code
-WB_STATUS_CODES = {
+WB_STATUS_CODES: Final[dict[str, str]] = {
     "200": "CH system is being heated.",
     "201": "DHW system is being heated.",
     "202": "Anti rapid cycle mode. The boiler has commenced anti-cycle period for CH.",

ramses_rf/database.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""RAMSES RF - Message database and index."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sqlite3
+from collections import OrderedDict
+from datetime import datetime as dt, timedelta as td
+from typing import NewType, TypedDict
+
+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
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class MessageIndex:
+    """A simple in-memory SQLite3 database for indexing messages."""
+
+    def __init__(self) -> None:
+        """Instantiate a message database/index."""
+
+        self._msgs: MsgDdT = OrderedDict()
+
+        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
+        self._setup_db_schema()
+
+        self._lock = asyncio.Lock()
+        self._last_housekeeping: dt = None  # type: ignore[assignment]
+        self._housekeeping_task: asyncio.Task[None] = None  # type: ignore[assignment]
+
+        self.start()
+
+    def __repr__(self) -> str:
+        return f"MessageIndex({len(self._msgs)} messages)"
+
+    def start(self) -> None:
+        """Start the housekeeper loop."""
+
+        if self._housekeeping_task and not self._housekeeping_task.done():
+            return
+
+        self._housekeeping_task = asyncio.create_task(
+            self._housekeeping_loop(), name=f"{self.__class__.__name__}.housekeeper"
+        )
+
+    def stop(self) -> None:
+        """Stop the housekeeper loop."""
+
+        if self._housekeeping_task and not self._housekeeping_task.done():
+            self._housekeeping_task.cancel()  # stop the housekeeper
+
+        self._cx.commit()  # just in case
+        # self._cx.close()  # may still need to do queries after engine has stopped?
+
+    @property
+    def msgs(self) -> MsgDdT:
+        """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())
+
+        sqlite3.register_converter("dtm", convert_datetime)
+
+    def _setup_db_schema(self) -> None:
+        """Setup the dayabase schema."""
+
+        self._cu.execute(
+            """
+            CREATE TABLE messages (
+                dtm    TEXT(26) NOT NULL PRIMARY KEY,
+                verb   TEXT(2)  NOT NULL,
+                src    TEXT(9)  NOT NULL,
+                dst    TEXT(9)  NOT NULL,
+                code   TEXT(4)  NOT NULL,
+                ctx    TEXT     NOT NULL,
+                hdr    TEXT     NOT NULL UNIQUE
+            )
+            """
+        )
+
+        self._cu.execute("CREATE INDEX idx_verb ON messages (verb)")
+        self._cu.execute("CREATE INDEX idx_src ON messages (src)")
+        self._cu.execute("CREATE INDEX idx_dst ON messages (dst)")
+        self._cu.execute("CREATE INDEX idx_code ON messages (code)")
+        self._cu.execute("CREATE INDEX idx_ctx ON messages (ctx)")
+        self._cu.execute("CREATE INDEX idx_hdr ON messages (hdr)")
+
+        self._cx.commit()
+
+    async def _housekeeping_loop(self) -> None:
+        """Periodically remove stale messages from the index."""
+
+        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()
+                self._cu.execute("DELETE FROM messages WHERE dtm < ?", (dtm,))
+                msgs = OrderedDict({row[0]: self._msgs[row[0]] for row in rows})
+                self._cx.commit()
+
+            except sqlite3.Error:  # need to tighten?
+                self._cx.rollback()
+            else:
+                self._msgs = msgs
+            finally:
+                pass  # self._lock.release()
+
+        while True:
+            self._last_housekeeping = dt.now()
+            await asyncio.sleep(3600)
+            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.
+        """  # TODO: eventually, may be better to use SqlAlchemy
+
+        dup: tuple[Message, ...] = tuple()  # avoid UnboundLocalError
+        old: Message | None = None  # avoid UnboundLocalError
+
+        try:  # TODO: remove, or use only when source is a packet log?
+            # await self._lock.acquire()
+            dup = self._delete_from(  # HACK: because of contrived pkt logs
+                dtm=msg.dtm.isoformat(timespec="microseconds")
+            )
+            old = self._insert_into(msg)  # will delete old msg by hdr
+
+        except sqlite3.Error:  # UNIQUE constraint failed: ? messages.dtm (so: HACK)
+            self._cx.rollback()
+
+        else:
+            dtm: DtmStrT = msg.dtm.isoformat(timespec="microseconds")  # type: ignore[assignment]
+            self._msgs[dtm] = msg
+
+        finally:
+            pass  # self._lock.release()
+
+        if dup:
+            _LOGGER.warning(
+                "Overwrote dtm for %s: %s (contrived log?)", msg._pkt._hdr, dup[0]._pkt
+            )
+
+        return old
+
+    def _insert_into(self, msg: Message) -> Message | None:
+        """Insert a message into the index (and return any message replaced by hdr)."""
+
+        msgs = self._delete_from(hdr=msg._pkt._hdr)
+
+        sql = """
+            INSERT INTO messages (dtm, verb, src, dst, code, ctx, hdr)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """
+
+        self._cu.execute(
+            sql,
+            (
+                msg.dtm,
+                msg.verb,
+                msg.src.id,
+                msg.dst.id,
+                msg.code,
+                msg._pkt._ctx,
+                msg._pkt._hdr,
+            ),
+        )
+
+        return msgs[0] if msgs else None
+
+    def rem(self, msg: Message | None = None, **kwargs: str) -> tuple[Message, ...]:
+        """Remove a set of message(s) from the index.
+
+        Returns any messages that were removed.
+        """
+
+        if bool(msg) ^ bool(kwargs):
+            raise ValueError("Either a Message or kwargs should be provided, not both")
+        if msg:
+            kwargs["dtm"] = msg.dtm.isoformat(timespec="microseconds")
+
+        try:  # make this operation atomic, i.e. update self._msgs only on success
+            # await self._lock.acquire()
+            msgs = self._delete_from(**kwargs)
+
+        except sqlite3.Error:  # need to tighten?
+            self._cx.rollback()
+
+        else:
+            for msg in msgs:
+                dtm: DtmStrT = msg.dtm.isoformat(timespec="microseconds")  # type: ignore[assignment]
+                self._msgs.pop(dtm)
+
+        finally:
+            pass  # self._lock.release()
+
+        return msgs
+
+    def _delete_from(self, **kwargs: str) -> tuple[Message, ...]:
+        """Remove message(s) from the index (and return any messages removed)."""
+
+        msgs = self._select_from(**kwargs)
+
+        sql = "DELETE FROM messages WHERE "
+        sql += " AND ".join(f"{k} = ?" for k in kwargs)
+
+        self._cu.execute(sql, tuple(kwargs.values()))
+
+        return msgs
+
+    def get(self, msg: Message | None = None, **kwargs: str) -> tuple[Message, ...]:
+        """Return a set of message(s) from the index."""
+
+        if not (bool(msg) ^ bool(kwargs)):
+            raise ValueError("Either a Message or kwargs should be provided, not both")
+        if msg:
+            kwargs["dtm"] = msg.dtm.isoformat(timespec="microseconds")
+
+        return self._select_from(**kwargs)
+
+    def _select_from(self, **kwargs: str) -> tuple[Message, ...]:
+        """Select message(s) from the index (and return any such messages)."""
+
+        sql = "SELECT dtm FROM messages WHERE "
+        sql += " AND ".join(f"{k} = ?" for k in kwargs)
+
+        self._cu.execute(sql, tuple(kwargs.values()))
+
+        return tuple(self._msgs[row[0]] for row in self._cu.fetchall())
+
+    def qry(self, sql: str, parameters: tuple[str, ...]) -> tuple[Message, ...]:
+        """Return a set of message(s) from the index, given sql and parameters."""
+
+        if "SELECT" not in sql:
+            raise ValueError(f"{self}: Only SELECT queries are allowed")
+
+        self._cu.execute(sql, parameters)
+
+        return tuple(self._msgs[row[0]] for row in self._cu.fetchall())
+
+    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()]
+
+        return tuple(
+            m for m in self._msgs.values() if include_expired or not m._expired
+        )
+
+    def clr(self) -> None:
+        """Clear the message index (remove all messages)."""
+
+        self._cu.execute("DELETE FROM messages")
+        self._cx.commit()
+
+        self._msgs.clear()
+
+    # def _msgs(self, device_id: DeviceIdT) -> tuple[Message, ...]:
+    #     msgs = [msg for msg in self._msgs.values() if msg.src.id == device_id]
+    #     return msgs