ramses-rf 0.52.5__py3-none-any.whl → 0.53.1__py3-none-any.whl

ramses_cli/__init__.py

@@ -12,7 +12,7 @@ _DBG_FORCE_CLI_DEBUGGING: Final[bool] = (
 )
 
 
-if _DBG_FORCE_CLI_DEBUGGING:
+if _DBG_FORCE_CLI_DEBUGGING:  # pragma: no cover
     from .debug import start_debugging
 
     start_debugging(True)

ramses_cli/client.py

@@ -7,7 +7,8 @@ import asyncio
 import json
 import logging
 import sys
-from typing import Any, Final
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Final, Literal
 
 import click
 from colorama import Fore, Style, init as colorama_init
@@ -47,6 +48,10 @@ from ramses_rf.const import (  # noqa: F401, isort: skip, pylint: disable=unused
     Code,
 )
 
+if TYPE_CHECKING:
+    from _typeshed import SupportsRead
+
+
 _PROFILE_LIBRARY = False  # NOTE: for profiling of library
 
 if _PROFILE_LIBRARY:
@@ -85,28 +90,46 @@ COLORS = {
     W_: Style.BRIGHT + Fore.MAGENTA,
 }
 
-CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
+CONTEXT_SETTINGS: dict[str, Any] = dict(help_option_names=["-h", "--help"])
 
 LIB_KEYS = tuple(SCH_GLOBAL_CONFIG({}).keys()) + (SZ_SERIAL_PORT,)
 LIB_CFG_KEYS = tuple(SCH_GLOBAL_CONFIG({})[SZ_CONFIG].keys()) + (SZ_EVOFW_FLAG,)
 
 
-def normalise_config(lib_config: dict) -> tuple[str, dict]:
-    """Convert a HA config dict into the client library's own format."""
+def normalise_config(
+    lib_config: dict[str, dict[str, str | bool | None]],
+) -> tuple[str | None, dict[str, Any] | None]:
+    """Convert a HA config dict into the client library's own format.
+
+    :param lib_config: The configuration dictionary from Home Assistant.
+    :return: A tuple containing the serial port (if any) and the normalized configuration dictionary.
+    """
 
     serial_port = lib_config.pop(SZ_SERIAL_PORT, None)
 
     # fix for: https://github.com/ramses-rf/ramses_rf/issues/96
-    packet_log = lib_config.get(SZ_PACKET_LOG)
-    if isinstance(packet_log, str):
+    packet_log: str | Mapping[str, str | bool | None] | None = lib_config.get(
+        SZ_PACKET_LOG
+    )
+    if packet_log is None:
+        packet_log = {}
+    elif isinstance(packet_log, str):
         packet_log = {SZ_FILE_NAME: packet_log}
+    assert isinstance(packet_log, dict)
     lib_config[SZ_PACKET_LOG] = packet_log
 
-    return serial_port, lib_config
+    return serial_port, lib_config  # type: ignore[return-value]
 
 
-def split_kwargs(obj: tuple[dict, dict], kwargs: dict) -> tuple[dict, dict]:
-    """Split kwargs into cli/library kwargs."""
+def split_kwargs(
+    obj: tuple[dict[str, Any], dict[str, Any]], kwargs: dict[str, Any]
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Split kwargs into cli/library kwargs.
+
+    :param obj: A tuple containing the current CLI and library configuration dictionaries.
+    :param kwargs: The keyword arguments to split.
+    :return: A tuple containing the updated CLI and library configuration dictionaries.
+    """
     cli_kwargs, lib_kwargs = obj
 
     cli_kwargs.update(
@@ -119,9 +142,19 @@ def split_kwargs(obj: tuple[dict, dict], kwargs: dict) -> tuple[dict, dict]:
 
 
 class DeviceIdParamType(click.ParamType):
+    """A Click parameter type for Device IDs."""
+
     name = "device_id"
 
-    def convert(self, value: str, param, ctx):
+    def convert(self, value: str, param: Any, ctx: click.Context | None) -> str:
+        """Convert the value to a Device ID.
+
+        :param value: The value to convert.
+        :param param: The parameter being converted.
+        :param ctx: The Click context.
+        :return: The converted Device ID.
+        :raises click.BadParameter: If the value is not a valid Device ID.
+        """
         if is_valid_dev_id(value):
             return value.upper()
         self.fail(f"{value!r} is not a valid device_id", param, ctx)
@@ -176,8 +209,20 @@ class DeviceIdParamType(click.ParamType):
     help="display crazy things",
 )
 @click.pass_context
-def cli(ctx, config_file=None, eavesdrop: None | bool = None, **kwargs: Any) -> None:
-    """A CLI for the ramses_rf library."""
+def cli(
+    ctx: click.Context,
+    /,
+    config_file: SupportsRead[str | bytes] | None = None,
+    eavesdrop: None | bool = None,
+    **kwargs: Any,
+) -> None:
+    """A CLI for the ramses_rf library.
+
+    :param ctx: The Click context.
+    :param config_file: An optional configuration file to load.
+    :param eavesdrop: Whether to enable eavesdropping mode.
+    :param kwargs: Additional keyword arguments.
+    """
 
     if kwargs[SZ_DBG_MODE] > 0:  # Do first
         start_debugging(kwargs[SZ_DBG_MODE] == 1)
@@ -187,7 +232,7 @@ def cli(ctx, config_file=None, eavesdrop: None | bool = None, **kwargs: Any) ->
     if eavesdrop is not None:
         lib_kwargs[SZ_CONFIG][SZ_ENABLE_EAVESDROP] = eavesdrop
 
-    if config_file:  # TODO: validate with voluptuous, use YAML
+    if config_file:  # TODO: validate file with voluptuous, use YAML
         lib_kwargs = deep_merge(
             lib_kwargs, json.load(config_file)
         )  # CLI takes precedence
@@ -197,6 +242,8 @@ def cli(ctx, config_file=None, eavesdrop: None | bool = None, **kwargs: Any) ->
 
 # Args/Params for packet log only
 class FileCommand(click.Command):  # client.py parse <file>
+    """A Click Command class for file-based operations."""
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.params.insert(  # input_file name/path only
@@ -216,6 +263,8 @@ class FileCommand(click.Command):  # client.py parse <file>
 class PortCommand(
     click.Command
 ):  # client.py <command> <port> --packet-log xxx --evofw3-flag xxx
+    """A Click Command class for serial port operations."""
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.params.insert(0, click.Argument(("serial-port",)))
@@ -251,8 +300,15 @@ class PortCommand(
 # 1/4: PARSE (a file, +/- eavesdrop)
 @click.command(cls=FileCommand)  # parse a packet log file, then stop
 @click.pass_obj
-def parse(obj, **kwargs: Any):
-    """Command to parse a log file containing messages/packets."""
+def parse(
+    obj: Any, /, **kwargs: Any
+) -> tuple[Literal["parse"], dict[str, str], dict[str, str]]:
+    """Command to parse a log file containing messages/packets.
+
+    :param obj: The context object containing configuration.
+    :param kwargs: Additional keyword arguments.
+    :return: A tuple containing the command name, library configuration, and CLI configuration.
+    """
     config, lib_config = split_kwargs(obj, kwargs)
 
     lib_config[SZ_INPUT_FILE] = config.pop(SZ_INPUT_FILE)  # just the file path
@@ -277,8 +333,16 @@ def parse(obj, **kwargs: Any):
     "--poll-devices", type=click.STRING, help="e.g. 'device_id, device_id, ...'"
 )
 @click.pass_obj
-def monitor(obj, discover: None | bool = None, **kwargs: Any):
-    """Monitor (eavesdrop and/or probe) a serial port for messages/packets."""
+def monitor(
+    obj: Any, /, discover: None | bool = None, **kwargs: Any
+) -> tuple[Literal["monitor"], dict[str, str], dict[str, str]]:
+    """Monitor (eavesdrop and/or probe) a serial port for messages/packets.
+
+    :param obj: The context object containing configuration.
+    :param discover: Whether to enable discovery. If None, inferred from other arguments.
+    :param kwargs: Additional keyword arguments.
+    :return: A tuple containing the command name, library configuration, and CLI configuration.
+    """
     config, lib_config = split_kwargs(obj, kwargs)
 
     if discover is None:
@@ -315,10 +379,16 @@ def monitor(obj, discover: None | bool = None, **kwargs: Any):
     help="controller_id, filename.json",
 )
 @click.pass_obj
-def execute(obj, **kwargs: Any):
+def execute(
+    obj: Any, /, **kwargs: Any
+) -> tuple[Literal["execute"], dict[str | None, str | dict[str, Any]], dict[str, str]]:
     """Execute any specified scripts, return the results, then quit.
 
     Disables discovery, and enforces a strict allow_list.
+
+    :param obj: A tuple containing the CLI and library configuration dictionaries.
+    :param kwargs: Additional arguments passed to the command.
+    :return: A tuple containing the command string, library config, and CLI config.
     """
     config, lib_config = split_kwargs(obj, kwargs)
 
@@ -326,29 +396,37 @@ def execute(obj, **kwargs: Any):
     lib_config[SZ_CONFIG][SZ_DISABLE_DISCOVERY] = True
     lib_config[SZ_CONFIG][SZ_DISABLE_QOS] = False
 
+    known_list: dict[str | None, dict[str, Any]] = {}
     if kwargs[GET_FAULTS]:
         known_list = {kwargs[GET_FAULTS]: {}}
     elif kwargs[GET_SCHED][0]:
         known_list = {kwargs[GET_SCHED][0]: {}}
     elif kwargs[SET_SCHED][0]:
         known_list = {kwargs[SET_SCHED][0]: {}}
-    else:
-        known_list = {}
 
     if known_list:
         print(" - known list is force-configured/enforced")
         lib_config[SZ_KNOWN_LIST] = known_list
         lib_config[SZ_CONFIG][SZ_ENFORCE_KNOWN_LIST] = True
 
-    return EXECUTE, lib_config, config
+    return EXECUTE, lib_config, config  # type: ignore[return-value]
 
 
 #
 # 4/4: LISTEN (to RF, +/- eavesdrop - NO sending/discovery)
 @click.command(cls=PortCommand)  # (optionally) execute a command, then listen
 @click.pass_obj
-def listen(obj, **kwargs: Any):
-    """Listen to (eavesdrop only) a serial port for messages/packets."""
+def listen(
+    obj: Any, /, **kwargs: Any
+) -> tuple[
+    Literal["listen"], dict[str, str | dict[str, str | None] | None], dict[str, Any]
+]:
+    """Listen to (eavesdrop only) a serial port for messages/packets.
+
+    :param obj: The context object containing configuration.
+    :param kwargs: Additional keyword arguments.
+    :return: A tuple containing the command name, library configuration, and CLI configuration.
+    """
     config, lib_config = split_kwargs(obj, kwargs)
 
     print(" - sending is force-disabled")
@@ -358,20 +436,27 @@ def listen(obj, **kwargs: Any):
 
 
 def print_results(gwy: Gateway, **kwargs: Any) -> None:
+    """Print the results of execution commands (faults, schedules).
+
+    :param gwy: The gateway instance.
+    :param kwargs: The command arguments.
+    """
     if kwargs[GET_FAULTS]:
         fault_log = gwy.system_by_id[kwargs[GET_FAULTS]]._faultlog.faultlog
 
-        if fault_log is None:
-            print("No fault log, or failed to get the fault log.")
-        else:
+        if fault_log:
             [print(f"{k:02X}", v) for k, v in fault_log.items()]
+        else:
+            print("No fault log, or failed to get the fault log.")
 
     if kwargs[GET_SCHED][0]:
         system_id, zone_idx = kwargs[GET_SCHED]
         if zone_idx == "HW":
-            zone = gwy.system_by_id[system_id].dhw
+            dhw = gwy.system_by_id[system_id].dhw
+            zone: Any = dhw
         else:
             zone = gwy.system_by_id[system_id].zone_by_idx[zone_idx]
+        assert zone
         schedule = zone.schedule
 
         if schedule is None:
@@ -387,6 +472,10 @@ def print_results(gwy: Gateway, **kwargs: Any) -> None:
 
 
 def _save_state(gwy: Gateway) -> None:
+    """Save the gateway state to files.
+
+    :param gwy: The gateway instance.
+    """
     schema, msgs = gwy.get_state()
 
     with open("state_msgs.log", "w") as f:
@@ -397,6 +486,11 @@ def _save_state(gwy: Gateway) -> None:
 
 
 def _print_engine_state(gwy: Gateway, **kwargs: Any) -> None:
+    """Print the current engine state (schema and packets).
+
+    :param gwy: The gateway instance.
+    :param kwargs: Command arguments to determine verbosity.
+    """
     (schema, packets) = gwy.get_state(include_expired=True)
 
     if kwargs["print_state"] > 0:
@@ -406,6 +500,11 @@ def _print_engine_state(gwy: Gateway, **kwargs: Any) -> None:
 
 
 def print_summary(gwy: Gateway, **kwargs: Any) -> None:
+    """Print a summary of the system state, schema, params, and status.
+
+    :param gwy: The gateway instance.
+    :param kwargs: Command arguments to determine what to display.
+    """
     entity = gwy.tcs or gwy
 
     if kwargs.get("show_schema"):
@@ -445,8 +544,8 @@ def print_summary(gwy: Gateway, **kwargs: Any) -> None:
                     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 msg_code, verbs in device._msgz.items():
+                    if msg_code in (Code._0005, Code._000C):
                         for verb in verbs.values():
                             for pkt in verb.values():
                                 print(f"{pkt}")
@@ -455,19 +554,24 @@ def print_summary(gwy: Gateway, **kwargs: Any) -> None:
             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
+            else:  # TODO(eb): Q1 2026 replace next legacy block by
                 #  raise NotImplementedError
-                for code in device._msgz.values():
-                    for verb in code.values():
+                for cd in device._msgz.values():
+                    for verb in cd.values():
                         for pkt in verb.values():
                             print(f"{pkt}")
             print()
 
 
-async def async_main(command: str, lib_kwargs: dict, **kwargs: Any) -> None:
-    """Do certain things."""
+async def async_main(command: str, lib_kwargs: dict[str, Any], **kwargs: Any) -> None:
+    """Execute the main asynchronous logic for the CLI.
+
+    :param command: The command to execute (e.g., "execute", "monitor", "listen", "parse").
+    :param lib_kwargs: Configuration arguments for the library.
+    :param kwargs: Additional CLI arguments.
+    """
 
-    def handle_msg(msg: Message) -> None:
+    def handle_msg(_msg: Message) -> None:
         """Process the message as it arrives (a callback).
 
         In this case, the message is merely printed.
@@ -475,39 +579,53 @@ async def async_main(command: str, lib_kwargs: dict, **kwargs: Any) -> None:
 
         if kwargs["long_format"]:  # HACK for test/dev
             print(
-                f"{msg.dtm.isoformat(timespec='microseconds')} ... {msg!r}"
-                f"  # {msg.payload}"  # or f'  # ("{msg.src!r}", "{msg.dst!r}")'
+                f"{_msg.dtm.isoformat(timespec='microseconds')} ... {_msg!r}"
+                f"  # {_msg.payload}"  # or f'  # ("{msg.src!r}", "{msg.dst!r}")'
             )
             return
 
-        dtm = f"{msg.dtm:%H:%M:%S.%f}"[:-3]
+        dtm = f"{_msg.dtm:%H:%M:%S.%f}"[:-3]
         con_cols = CONSOLE_COLS
 
-        if msg.code == Code._PUZZ:
-            print(f"{Style.BRIGHT}{Fore.YELLOW}{dtm} {msg}"[:con_cols])
-        elif msg.src and msg.src.type == DEV_TYPE_MAP.HGI:
-            print(f"{Style.BRIGHT}{COLORS.get(msg.verb)}{dtm} {msg}"[:con_cols])
-        elif msg.code == Code._1F09 and msg.verb == I_:
-            print(f"{Fore.YELLOW}{dtm} {msg}"[:con_cols])
-        elif msg.code in (Code._000A, Code._2309, Code._30C9) and msg._has_array:
-            print(f"{Fore.YELLOW}{dtm} {msg}"[:con_cols])
+        if _msg.code == Code._PUZZ:
+            print(f"{Style.BRIGHT}{Fore.YELLOW}{dtm} {_msg}"[:con_cols])
+        elif _msg.src and _msg.src.type == DEV_TYPE_MAP.HGI:
+            print(f"{Style.BRIGHT}{COLORS.get(_msg.verb)}{dtm} {_msg}"[:con_cols])
+        elif _msg.code == Code._1F09 and _msg.verb == I_:
+            print(f"{Fore.YELLOW}{dtm} {_msg}"[:con_cols])
+        elif _msg.code in (Code._000A, Code._2309, Code._30C9) and _msg._has_array:
+            print(f"{Fore.YELLOW}{dtm} {_msg}"[:con_cols])
         else:
-            print(f"{COLORS.get(msg.verb)}{dtm} {msg}"[:con_cols])
+            print(f"{COLORS.get(_msg.verb)}{dtm} {_msg}"[:con_cols])
 
-    serial_port, lib_kwargs = normalise_config(lib_kwargs)
+    serial_port, lib_kwargs = normalise_config(lib_kwargs)  # type: ignore[assignment]
 
     if kwargs["restore_schema"]:
         print(" - restoring client schema from a HA cache...")
-        state = json.load(kwargs["restore_schema"])["data"]["client_state"]
+        state: dict[str, Any] = json.load(kwargs["restore_schema"])["data"][
+            "client_state"
+        ]
         lib_kwargs = lib_kwargs | state["schema"]
 
+    # Explicitly extract input_file if present to ensure it's passed as a named arg
+    input_file = lib_kwargs.pop(SZ_INPUT_FILE, None)
+
     # if serial_port == "/dev/ttyMOCK":
     #     from tests.deprecated.mocked_rf import MockGateway  # FIXME: for test/dev
     #     gwy = MockGateway(serial_port, **lib_kwargs)
     # else:
-    gwy = Gateway(serial_port, **lib_kwargs)  # passes action to gateway
 
-    if lib_kwargs[SZ_CONFIG][SZ_REDUCE_PROCESSING] < DONT_CREATE_MESSAGES:
+    # Instantiate Gateway, note: transport_factory is the default, so we don't need to pass it
+    gwy = Gateway(
+        serial_port,
+        input_file=input_file,
+        **lib_kwargs,
+    )  # passes action to gateway
+
+    if (
+        int(lib_kwargs.get(SZ_CONFIG, {}).get(SZ_REDUCE_PROCESSING, 0))
+        < DONT_CREATE_MESSAGES
+    ):
         # library will not send MSGs to STDOUT, so we'll send PKTs instead
         colorama_init(autoreset=True)  # WIP: remove strip=True
         gwy.add_msg_handler(handle_msg)
@@ -532,10 +650,10 @@ async def async_main(command: str, lib_kwargs: dict, **kwargs: Any) -> None:
 
         elif command == MONITOR:
             _ = spawn_scripts(gwy, **kwargs)
-            await gwy._protocol._wait_connection_lost
+            await asyncio.wait_for(gwy._protocol._wait_connection_lost, 1.0)  # type: ignore[arg-type]
 
         elif command in (LISTEN, PARSE):
-            await gwy._protocol._wait_connection_lost
+            await asyncio.wait_for(gwy._protocol._wait_connection_lost, 1.0)  # type: ignore[arg-type]
 
     except asyncio.CancelledError:
         msg = "ended via: CancelledError (e.g. SIGINT)"
@@ -570,7 +688,12 @@ cli.add_command(execute)
 cli.add_command(listen)
 
 
-def main() -> None:
+def main() -> None:  # pragma: no cover
+    """Entry point for the CLI.
+
+    Parses arguments, sets up the event loop (including Windows-specific policies),
+    and runs the main asynchronous loop (optionally with profiling).
+    """
     print("\r\nclient.py: Starting ramses_rf...")
 
     try:
@@ -605,5 +728,5 @@ def main() -> None:
     print(" - finished ramses_rf.\r\n")
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     main()

ramses_cli/discovery.py

@@ -17,10 +17,6 @@ from ramses_rf.device import Fakeable
 from ramses_tx import CODES_SCHEMA, Command, DeviceIdT, Priority
 from ramses_tx.opentherm import OTB_DATA_IDS
 
-# Beware, none of this is reliable - it is all subject to random change
-# However, these serve as examples how to use the other modules
-
-
 from ramses_rf.const import (  # noqa: F401, isort: skip, pylint: disable=unused-import
     I_,
     RP,
@@ -44,22 +40,19 @@ SCAN_FULL: Final = "scan_full"
 SCAN_HARD: Final = "scan_hard"
 SCAN_XXXX: Final = "scan_xxxx"
 
-# DEVICE_ID_REGEX = re.compile(DEVICE_ID_REGEX.ANY)
-
-
 _LOGGER = logging.getLogger(__name__)
 
 
 def script_decorator(fnc: Callable[..., Any]) -> Callable[..., Any]:
     @functools.wraps(fnc)
-    def wrapper(gwy: Gateway, *args: Any, **kwargs: Any) -> None:
+    async def wrapper(gwy: Gateway, *args: Any, **kwargs: Any) -> None:
         gwy.send_cmd(
             Command._puzzle(message="Script begins:"),
             priority=Priority.HIGHEST,
             num_repeats=3,
         )
 
-        fnc(gwy, *args, **kwargs)
+        await fnc(gwy, *args, **kwargs)
 
         gwy.send_cmd(
             Command._puzzle(message="Script done."),
@@ -67,8 +60,6 @@ def script_decorator(fnc: Callable[..., Any]) -> Callable[..., Any]:
             num_repeats=3,
         )
 
-        return None
-
     return wrapper
 
 
@@ -93,7 +84,12 @@ def spawn_scripts(gwy: Gateway, **kwargs: Any) -> list[asyncio.Task[None]]:
             _LOGGER.warning(f"Script: {kwargs[EXEC_SCR][0]}() - unknown script")
         else:
             _LOGGER.info(f"Script: {kwargs[EXEC_SCR][0]}().- starts...")
-            tasks += [asyncio.create_task(script(gwy, kwargs[EXEC_SCR][1]))]
+            # script_poll_device returns a list of tasks, others return a coroutine
+            result = script(gwy, kwargs[EXEC_SCR][1])
+            if isinstance(result, list):
+                tasks.extend(result)
+            else:
+                tasks.append(asyncio.create_task(result))
 
     gwy._tasks.extend(tasks)
     return tasks
@@ -104,14 +100,6 @@ async def exec_cmd(gwy: Gateway, **kwargs: Any) -> None:
     await gwy.async_send_cmd(cmd, priority=Priority.HIGH, wait_for_reply=True)
 
 
-# @script_decorator
-# async def script_scan_001(gwy: Gateway, dev_id: DeviceIdT):
-#     _LOGGER.warning("scan_001() invoked - expect a lot of nonsense")
-#     for idx in range(0x10):
-#         gwy.send_cmd(Command.from_attrs(W_, dev_id, Code._000E, f"{idx:02X}0050"))
-#         gwy.send_cmd(Command.from_attrs(RQ, dev_id, Code._000E, f"{idx:02X}00C8"))
-
-
 async def get_faults(
     gwy: Gateway, ctl_id: DeviceIdT, start: int = 0, limit: int = 0x3F
 ) -> None:
@@ -199,7 +187,7 @@ def script_poll_device(gwy: Gateway, dev_id: DeviceIdT) -> list[asyncio.Task[Non
 async def script_scan_disc(gwy: Gateway, dev_id: DeviceIdT) -> None:
     _LOGGER.warning("scan_disc() invoked...")
 
-    await gwy.get_device(dev_id).discover()  # discover_flag=Discover.DEFAULT)
+    await gwy.get_device(dev_id).discover()
 
 
 @script_decorator
@@ -340,9 +328,7 @@ async def script_scan_otb_hard(gwy: Gateway, dev_id: DeviceIdT) -> None:
 
 
 @script_decorator
-async def script_scan_otb_map(
-    gwy: Gateway, dev_id: DeviceIdT
-) -> None:  # Tested only upon a R8820A
+async def script_scan_otb_map(gwy: Gateway, dev_id: DeviceIdT) -> None:
     _LOGGER.warning("script_scan_otb_map invoked - expect a lot of nonsense")
 
     RAMSES_TO_OPENTHERM = {
@@ -364,9 +350,7 @@ async def script_scan_otb_map(
 
 
 @script_decorator
-async def script_scan_otb_ramses(
-    gwy: Gateway, dev_id: DeviceIdT
-) -> None:  # Tested only upon a R8820A
+async def script_scan_otb_ramses(gwy: Gateway, dev_id: DeviceIdT) -> None:
     _LOGGER.warning("script_scan_otb_ramses invoked - expect a lot of nonsense")
 
     _CODES = (
@@ -394,7 +378,7 @@ async def script_scan_otb_ramses(
         Code._3223,
         Code._3EF0,  # rel. modulation level  / RelativeModulationLevel (also, below)
         Code._3EF1,  # rel. modulation level  / RelativeModulationLevel
-    )  # excl. 3150, 3220
+    )
 
     for c in _CODES:
         gwy.send_cmd(Command.from_attrs(RQ, dev_id, c, "00"), priority=Priority.LOW)

ramses_rf/__init__.py

@@ -56,6 +56,8 @@ __all__ = [
     "VerbT",
     #
     "exceptions",
+    #
+    "GracefulExit",
 ]
 
 _LOGGER = logging.getLogger(__name__)

ramses_rf/database.py

@@ -272,18 +272,21 @@ class MessageIndex:
 
         return old
 
-    def add_record(self, src: str, code: str = "", verb: str = "") -> None:
+    def add_record(
+        self, src: str, code: str = "", verb: str = "", payload: str = "00"
+    ) -> None:
         """
         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
+        :param payload: payload str to use
         """
-        # Used by OtbGateway init, via entity_base.py
+        # Used by OtbGateway init, via entity_base.py (code=_3220)
         _now: dt = dt.now()
         dtm: DtmStrT = _now.isoformat(timespec="microseconds")  # type: ignore[assignment]
-        hdr = f"{code}|{verb}|{src}|00"  # dummy record has no contents
+        hdr = f"{code}|{verb}|{src}|{payload}"
 
         dup = self._delete_from(hdr=hdr)
 

ramses_rf/device/heat.py

@@ -668,11 +668,13 @@ class OtbGateway(Actuator, HeatDemand):  # OTB (10): 3220 (22D9, others)
         self._child_id = FC  # NOTE: domain_id
 
         # TODO(eb): cleanup
-        if self._gwy.msg_db:
-            self._add_record(id=self.id, code=Code._3220, verb="RP")
-        # 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:
+        if not self._gwy.msg_db:
+            # self._add_record(
+            #     id=self.id, code=Code._3220, verb="RP", payload="00C0060101"
+            # )  # is parsed but pollutes the client.py
+            # 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

ramses_rf/entity_base.py

@@ -324,12 +324,16 @@ class _MessageDB(_Entity):
         ]
 
     def _add_record(
-        self, id: DeviceIdT, code: Code | None = None, verb: str = " I"
+        self,
+        id: DeviceIdT,
+        code: Code | None = None,
+        verb: str = " I",
+        payload: str = "00",
     ) -> None:
         """Add a (dummy) record to the central SQLite MessageIndex."""
-        # used by heat.py init
+        # used by heat.py.OtbGateway init
         if self._gwy.msg_db:
-            self._gwy.msg_db.add_record(id, code=str(code), verb=verb)
+            self._gwy.msg_db.add_record(id, code=str(code), verb=verb, payload=payload)
         # else:
         #     _LOGGER.warning("Missing MessageIndex")
         # raise NotImplementedError
@@ -1048,7 +1052,9 @@ class _Discovery(_MessageDB):
                                 f"No msg found for hdr {hdr}, task code {task[_SZ_COMMAND].code}"
                             )
                     else:  # TODO(eb) remove next Q1 2026
-                        msgs += [self.tcs._msgz[task[_SZ_COMMAND].code][I_][True]]
+                        # CRITICAL FIX: self.tcs might be None during early discovery
+                        if self.tcs:
+                            msgs += [self.tcs._msgz[task[_SZ_COMMAND].code][I_][True]]
                         # raise NotImplementedError
             except KeyError:
                 pass