aiohomematic 2025.10.8__py3-none-any.whl → 2025.10.10__py3-none-any.whl

aiohomematic/__init__.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 AioHomematic: a Python 3 library to interact with Homematic and HomematicIP backends.
 
@@ -9,10 +9,10 @@ This package provides a high-level API to discover devices and channels, read an
 parameters (data points), receive events, and manage programs and system variables.
 
 Key layers and responsibilities:
-- aiohomematic.central: Orchestrates clients, caches, device creation and events.
+- aiohomematic.central: Orchestrates clients, store, device creation and events.
 - aiohomematic.client: Interface-specific clients (JSON-RPC/XML-RPC, Homegear) handling IO.
 - aiohomematic.model: Data point abstraction for generic, hub, and calculated entities.
-- aiohomematic.caches: Persistent and runtime caches for descriptions, values, and metadata.
+- aiohomematic.store: Persistent and runtime store for descriptions, values, and metadata.
 
 Typical usage is to construct a CentralConfig, create a CentralUnit and start it, then
 consume data points and events or issue write commands via the exposed API.

aiohomematic/async_support.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """Module with support for loop interaction."""
 
 from __future__ import annotations

aiohomematic/central/__init__.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 Central unit and core orchestration for Homematic CCU and compatible backends.
 
@@ -9,8 +9,8 @@ This package provides the central coordination layer for aiohomematic. It models
 Homematic CCU (or compatible backend such as Homegear) and orchestrates
 interfaces, devices, channels, data points, events, and background jobs.
 
-The central unit ties together the various submodules: caches, client adapters
-(JSON-RPC/XML-RPC), device and data point models, and visibility/description caches.
+The central unit ties together the various submodules: store, client adapters
+(JSON-RPC/XML-RPC), device and data point models, and visibility/description store.
 It exposes high-level APIs to query and manipulate the backend state while
 encapsulating transport and scheduling details.
 
@@ -52,7 +52,7 @@ Example (simplified):
     )
 
     central = cfg.create_central()
-    central.start()           # start XML-RPC server, create/init clients, load caches
+    central.start()           # start XML-RPC server, create/init clients, load store
     # ... interact with devices / data points via central ...
     central.stop()
 
@@ -79,13 +79,9 @@ import voluptuous as vol
 
 from aiohomematic import client as hmcl
 from aiohomematic.async_support import Looper, loop_check
-from aiohomematic.caches.dynamic import CentralDataCache, DeviceDetailsCache
-from aiohomematic.caches.persistent import DeviceDescriptionCache, ParamsetDescriptionCache
-from aiohomematic.caches.visibility import ParameterVisibilityCache
 from aiohomematic.central import rpc_server as rpc
 from aiohomematic.central.decorators import callback_backend_system, callback_event
-from aiohomematic.client.json_rpc import AioJsonRpcAioHttpClient
-from aiohomematic.client.rpc_proxy import AioXmlRpcProxy
+from aiohomematic.client import AioJsonRpcAioHttpClient, BaseRpcProxy
 from aiohomematic.const import (
     CALLBACK_TYPE,
     CATEGORIES,
@@ -100,9 +96,11 @@ from aiohomematic.const import (
     DEFAULT_IGNORE_CUSTOM_DEVICE_DEFINITION_MODELS,
     DEFAULT_INTERFACES_REQUIRING_PERIODIC_REFRESH,
     DEFAULT_MAX_READ_WORKERS,
+    DEFAULT_OPTIONAL_SETTINGS,
     DEFAULT_PERIODIC_REFRESH_INTERVAL,
     DEFAULT_PROGRAM_MARKERS,
-    DEFAULT_STORAGE_FOLDER,
+    DEFAULT_SESSION_RECORDER_START_FOR_SECONDS,
+    DEFAULT_STORAGE_DIRECTORY,
     DEFAULT_SYS_SCAN_INTERVAL,
     DEFAULT_SYSVAR_MARKERS,
     DEFAULT_TLS,
@@ -134,6 +132,7 @@ from aiohomematic.const import (
     Interface,
     InterfaceEventType,
     Operations,
+    OptionalSettings,
     Parameter,
     ParamsetKey,
     ProxyInitState,
@@ -163,6 +162,14 @@ from aiohomematic.model.hub import (
     ProgramDpType,
 )
 from aiohomematic.property_decorators import info_property
+from aiohomematic.store import (
+    CentralDataCache,
+    DeviceDescriptionCache,
+    DeviceDetailsCache,
+    ParameterVisibilityCache,
+    ParamsetDescriptionCache,
+    SessionRecorder,
+)
 from aiohomematic.support import (
     LogContextMixin,
     PayloadMixin,
@@ -181,7 +188,7 @@ _LOGGER_EVENT: Final = logging.getLogger(f"{__package__}.event")
 
 # {central_name, central}
 CENTRAL_INSTANCES: Final[dict[str, CentralUnit]] = {}
-ConnectionProblemIssuer = AioJsonRpcAioHttpClient | AioXmlRpcProxy
+ConnectionProblemIssuer = AioJsonRpcAioHttpClient | BaseRpcProxy
 
 INTERFACE_EVENT_SCHEMA = vol.Schema(
     {
@@ -218,7 +225,9 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         self._device_descriptions: Final = DeviceDescriptionCache(central=self)
         self._paramset_descriptions: Final = ParamsetDescriptionCache(central=self)
         self._parameter_visibility: Final = ParameterVisibilityCache(central=self)
-
+        self._recorder: Final = SessionRecorder(
+            central=self, ttl_seconds=600, active=central_config.session_recorder_start
+        )
         self._primary_client: hmcl.Client | None = None
         # {interface_id, client}
         self._clients: Final[dict[str, hmcl.Client]] = {}
@@ -344,6 +353,11 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         """Return parameter_visibility cache."""
         return self._parameter_visibility
 
+    @property
+    def recorder(self) -> SessionRecorder:
+        """Return the session recorder."""
+        return self._recorder
+
     @property
     def poll_clients(self) -> tuple[hmcl.Client, ...]:
         """Return clients that need to poll data."""
@@ -458,10 +472,13 @@ class CentralUnit(LogContextMixin, PayloadMixin):
                 return channel
         return None
 
-    async def save_caches(
-        self, *, save_device_descriptions: bool = False, save_paramset_descriptions: bool = False
+    async def save_files(
+        self,
+        *,
+        save_device_descriptions: bool = False,
+        save_paramset_descriptions: bool = False,
     ) -> None:
-        """Save persistent caches."""
+        """Save persistent files to disk."""
         if save_device_descriptions:
             await self._device_descriptions.save()
         if save_paramset_descriptions:
@@ -479,6 +496,15 @@ class CentralUnit(LogContextMixin, PayloadMixin):
             _LOGGER.debug("START: Central %s already started", self.name)
             return
 
+        if self._config.session_recorder_start:
+            await self._recorder.deactivate(
+                delay=self._config.session_recorder_start_for_seconds,
+                auto_save=True,
+                randomize_output=self._config.session_recorder_randomize_output,
+                use_ts_in_file_name=False,
+            )
+            _LOGGER.debug("START: Starting Recorder for %s seconds", self._config.session_recorder_start_for_seconds)
+
         self._state = CentralUnitState.INITIALIZING
         _LOGGER.debug("START: Initializing Central %s", self.name)
         if self._config.enabled_interface_configs and (
@@ -536,7 +562,7 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         self._state = CentralUnitState.STOPPING
         _LOGGER.debug("STOP: Stopping Central %s", self.name)
 
-        await self.save_caches(save_device_descriptions=True, save_paramset_descriptions=True)
+        await self.save_files(save_device_descriptions=True, save_paramset_descriptions=True)
         self._stop_scheduler()
         await self._stop_clients()
         if self._json_rpc_client and self._json_rpc_client.is_activated:
@@ -952,13 +978,13 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         return len(self._clients) > 0
 
     async def _load_caches(self) -> bool:
-        """Load files to caches."""
+        """Load files to store."""
         if DataOperationResult.LOAD_FAIL in (
             await self._device_descriptions.load(),
             await self._paramset_descriptions.load(),
         ):
-            _LOGGER.warning("LOAD_CACHES failed: Unable to load caches for %s. Clearing files", self.name)
-            await self.clear_caches()
+            _LOGGER.warning("LOAD_CACHES failed: Unable to load store for %s. Clearing files", self.name)
+            await self.clear_files()
             return False
         await self._device_details.load()
         await self._data_cache.load()
@@ -1047,7 +1073,7 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         for address in addresses:
             if device := self._devices.get(address):
                 self.remove_device(device=device)
-        await self.save_caches(save_device_descriptions=True, save_paramset_descriptions=True)
+        await self.save_files(save_device_descriptions=True, save_paramset_descriptions=True)
 
     @callback_backend_system(system_event=BackendSystemEvent.NEW_DEVICES)
     async def add_new_devices(self, *, interface_id: str, device_descriptions: tuple[DeviceDescription, ...]) -> None:
@@ -1149,7 +1175,7 @@ class CentralUnit(LogContextMixin, PayloadMixin):
                         extract_exc_args(exc=exc),
                     )
 
-            await self.save_caches(
+            await self.save_files(
                 save_device_descriptions=save_descriptions,
                 save_paramset_descriptions=save_descriptions,
             )
@@ -1607,10 +1633,11 @@ class CentralUnit(LogContextMixin, PayloadMixin):
             )
         return candidates
 
-    async def clear_caches(self) -> None:
-        """Clear all stored data."""
+    async def clear_files(self) -> None:
+        """Remove all stored files and caches."""
         await self._device_descriptions.clear()
         await self._paramset_descriptions.clear()
+        await self._recorder.clear()
         self._device_details.clear()
         self._data_cache.clear()
 
@@ -1985,10 +2012,11 @@ class CentralConfig:
         listen_ip_addr: str | None = None,
         listen_port_xml_rpc: int | None = None,
         max_read_workers: int = DEFAULT_MAX_READ_WORKERS,
+        optional_settings: tuple[OptionalSettings | str, ...] = DEFAULT_OPTIONAL_SETTINGS,
         periodic_refresh_interval: int = DEFAULT_PERIODIC_REFRESH_INTERVAL,
         program_markers: tuple[DescriptionMarker | str, ...] = DEFAULT_PROGRAM_MARKERS,
         start_direct: bool = False,
-        storage_folder: str = DEFAULT_STORAGE_FOLDER,
+        storage_directory: str = DEFAULT_STORAGE_DIRECTORY,
         sys_scan_interval: int = DEFAULT_SYS_SCAN_INTERVAL,
         sysvar_markers: tuple[DescriptionMarker | str, ...] = DEFAULT_SYSVAR_MARKERS,
         tls: bool = DEFAULT_TLS,
@@ -1998,6 +2026,7 @@ class CentralConfig:
     ) -> None:
         """Init the client config."""
         self._interface_configs: Final = interface_configs
+        self._optional_settings: Final = frozenset(optional_settings or ())
         self.requires_xml_rpc_server: Final = any(
             ic for ic in interface_configs if ic.rpc_server == RpcServerType.XML_RPC
         )
@@ -2023,7 +2052,16 @@ class CentralConfig:
         self.periodic_refresh_interval = periodic_refresh_interval
         self.program_markers: Final = program_markers
         self.start_direct: Final = start_direct
-        self.storage_folder: Final = storage_folder
+        self.session_recorder_randomize_output = (
+            OptionalSettings.SR_DISABLE_RANDOMIZE_OUTPUT not in self._optional_settings
+        )
+        self.session_recorder_start_for_seconds: Final = (
+            DEFAULT_SESSION_RECORDER_START_FOR_SECONDS
+            if OptionalSettings.SR_RECORD_SYSTEM_INIT in self._optional_settings
+            else 0
+        )
+        self.session_recorder_start = self.session_recorder_start_for_seconds > 0
+        self.storage_directory: Final = storage_directory
         self.sys_scan_interval: Final = sys_scan_interval
         self.sysvar_markers: Final = sysvar_markers
         self.tls: Final = tls
@@ -2058,7 +2096,7 @@ class CentralConfig:
 
     @property
     def use_caches(self) -> bool:
-        """Return if caches should be used."""
+        """Return if store should be used."""
         return self.start_direct is False
 
     def check_config(self) -> None:
@@ -2068,7 +2106,7 @@ class CentralConfig:
             host=self.host,
             username=self.username,
             password=self.password,
-            storage_folder=self.storage_folder,
+            storage_directory=self.storage_directory,
             callback_host=self.callback_host,
             callback_port_xml_rpc=self.callback_port_xml_rpc,
             json_port=self.json_port,
@@ -2105,6 +2143,7 @@ class CentralConfig:
             client_session=self.client_session,
             tls=self.tls,
             verify_tls=self.verify_tls,
+            session_recorder=central.recorder,
         )
 
 
@@ -2122,7 +2161,7 @@ class CentralConnectionState:
             self._json_issues.append(iid)
             _LOGGER.debug("add_issue: add issue  [%s] for JsonRpcAioHttpClient", iid)
             return True
-        if isinstance(issuer, AioXmlRpcProxy) and iid not in self._rpc_proxy_issues:
+        if isinstance(issuer, BaseRpcProxy) and iid not in self._rpc_proxy_issues:
             self._rpc_proxy_issues.append(iid)
             _LOGGER.debug("add_issue: add issue [%s] for %s", iid, issuer.interface_id)
             return True
@@ -2134,7 +2173,7 @@ class CentralConnectionState:
             self._json_issues.remove(iid)
             _LOGGER.debug("remove_issue: removing issue [%s] for JsonRpcAioHttpClient", iid)
             return True
-        if isinstance(issuer, AioXmlRpcProxy) and issuer.interface_id in self._rpc_proxy_issues:
+        if isinstance(issuer, BaseRpcProxy) and issuer.interface_id in self._rpc_proxy_issues:
             self._rpc_proxy_issues.remove(iid)
             _LOGGER.debug("remove_issue: removing issue [%s] for %s", iid, issuer.interface_id)
             return True
@@ -2144,7 +2183,7 @@ class CentralConnectionState:
         """Add issue to collection."""
         if isinstance(issuer, AioJsonRpcAioHttpClient):
             return iid in self._json_issues
-        if isinstance(issuer, (AioXmlRpcProxy)):
+        if isinstance(issuer, (BaseRpcProxy)):
             return iid in self._rpc_proxy_issues
 
     def handle_exception_log(

aiohomematic/central/decorators.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """Decorators for central used within aiohomematic."""
 
 from __future__ import annotations

aiohomematic/central/rpc_server.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 XML-RPC server module.
 

aiohomematic/client/__init__.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 Client adapters for communicating with Homematic CCU and compatible backends.
 
@@ -55,12 +55,11 @@ import logging
 from typing import Any, Final, cast
 
 from aiohomematic import central as hmcu
-from aiohomematic.caches.dynamic import CommandCache, PingPongCache
+from aiohomematic.client.json_rpc import AioJsonRpcAioHttpClient
 from aiohomematic.client.rpc_proxy import AioXmlRpcProxy, BaseRpcProxy
 from aiohomematic.const import (
     CALLBACK_WARN_INTERVAL,
     DATETIME_FORMAT_MILLIS,
-    DEFAULT_CUSTOM_ID,
     DEFAULT_MAX_WORKERS,
     DP_KEY_VALUE,
     DUMMY_SERIAL,
@@ -81,6 +80,7 @@ from aiohomematic.const import (
     ForcedDeviceAvailability,
     Interface,
     InterfaceEventType,
+    InternalCustomID,
     Operations,
     ParameterData,
     ParameterType,
@@ -97,6 +97,7 @@ from aiohomematic.exceptions import BaseHomematicException, ClientException, NoC
 from aiohomematic.model.device import Device
 from aiohomematic.model.support import convert_value
 from aiohomematic.property_decorators import hm_property
+from aiohomematic.store import CommandCache, PingPongCache
 from aiohomematic.support import (
     LogContextMixin,
     build_xml_rpc_headers,
@@ -108,7 +109,13 @@ from aiohomematic.support import (
     supports_rx_mode,
 )
 
-__all__ = ["Client", "InterfaceConfig", "create_client", "get_client"]
+__all__ = [
+    "AioJsonRpcAioHttpClient",
+    "BaseRpcProxy",
+    "Client",
+    "InterfaceConfig",
+    "ClientConfig",
+]
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -132,7 +139,7 @@ _CCU_JSON_VALUE_TYPE: Final = {
 class Client(ABC, LogContextMixin):
     """Client object to access the backends via XML-RPC or JSON-RPC."""
 
-    def __init__(self, *, client_config: _ClientConfig) -> None:
+    def __init__(self, *, client_config: ClientConfig) -> None:
         """Initialize the Client."""
         self._config: Final = client_config
         self._last_value_send_cache = CommandCache(interface_id=client_config.interface_id)
@@ -1086,7 +1093,7 @@ class Client(ABC, LogContextMixin):
                 device_address,
             )
             return
-        await self.central.save_caches(save_paramset_descriptions=True)
+        await self.central.save_files(save_paramset_descriptions=True)
 
     def __str__(self) -> str:
         """Provide some useful information."""
@@ -1096,7 +1103,7 @@ class Client(ABC, LogContextMixin):
 class ClientCCU(Client):
     """Client implementation for CCU backend."""
 
-    def __init__(self, *, client_config: _ClientConfig) -> None:
+    def __init__(self, *, client_config: ClientConfig) -> None:
         """Initialize the Client."""
         self._json_rpc_client: Final = client_config.central.json_rpc_client
         super().__init__(client_config=client_config)
@@ -1591,7 +1598,7 @@ class ClientHomegear(Client):
         return SystemInformation(available_interfaces=(Interface.BIDCOS_RF,), serial=f"{self.interface}_{DUMMY_SERIAL}")
 
 
-class _ClientConfig:
+class ClientConfig:
     """Config for a Client."""
 
     def __init__(
@@ -1600,6 +1607,7 @@ class _ClientConfig:
         central: hmcu.CentralUnit,
         interface_config: InterfaceConfig,
     ) -> None:
+        """Initialize the config."""
         self.central: Final = central
         self.version: str = "0"
         self.system_information = SystemInformation()
@@ -1667,6 +1675,7 @@ class _ClientConfig:
     async def create_rpc_proxy(
         self, *, interface: Interface, auth_enabled: bool | None = None, max_workers: int = DEFAULT_MAX_WORKERS
     ) -> BaseRpcProxy:
+        """Return a RPC proxy for the backend communication."""
         return await self._create_xml_rpc_proxy(auth_enabled=auth_enabled, max_workers=max_workers)
 
     async def _create_xml_rpc_proxy(
@@ -1690,16 +1699,13 @@ class _ClientConfig:
             headers=xml_rpc_headers,
             tls=config.tls,
             verify_tls=config.verify_tls,
+            session_recorder=self.central.recorder,
         )
         await xml_proxy.do_init()
         return xml_proxy
 
     async def _create_simple_rpc_proxy(self, *, interface: Interface) -> BaseRpcProxy:
         """Return a RPC proxy for the backend communication."""
-        return await self._create_xml_rpc_proxy()
-
-    async def _create_simple_xml_rpc_proxy(self) -> AioXmlRpcProxy:
-        """Return a XmlRPC proxy for the backend communication."""
         return await self._create_xml_rpc_proxy(auth_enabled=True, max_workers=0)
 
 
@@ -1744,7 +1750,7 @@ async def create_client(
     interface_config: InterfaceConfig,
 ) -> Client:
     """Return a new client for with a given interface_config."""
-    return await _ClientConfig(central=central, interface_config=interface_config).create_client()
+    return await ClientConfig(central=central, interface_config=interface_config).create_client()
 
 
 def get_client(interface_id: str) -> Client | None:
@@ -1809,7 +1815,9 @@ async def _track_single_data_point_state_change_or_timeout(
             )
             return
         if (
-            unsub := dp.register_data_point_updated_callback(cb=_async_event_changed, custom_id=DEFAULT_CUSTOM_ID)
+            unsub := dp.register_data_point_updated_callback(
+                cb=_async_event_changed, custom_id=InternalCustomID.DEFAULT
+            )
         ) is None:
             return
 

aiohomematic/client/_rpc_errors.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 Error mapping helpers for RPC transports.
 

aiohomematic/client/json_rpc.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 Asynchronous JSON-RPC client for Homematic CCU-compatible backends.
 
@@ -24,7 +24,7 @@ used directly for advanced tasks. Typical flow:
 Notes
 -----
 - Some JSON-RPC methods are backend/firmware dependent. The client detects and
-  caches supported methods at runtime.
+  store supported methods at runtime.
 - Binary/text encodings are handled carefully (UTF-8 / ISO-8859-1) for script IO.
 
 """
@@ -92,6 +92,7 @@ from aiohomematic.exceptions import (
 )
 from aiohomematic.model.support import convert_value
 from aiohomematic.property_decorators import hm_property
+from aiohomematic.store import SessionRecorder
 from aiohomematic.support import (
     LogContextMixin,
     cleanup_text_from_html_tags,
@@ -192,6 +193,7 @@ class AioJsonRpcAioHttpClient(LogContextMixin):
         client_session: ClientSession | None,
         tls: bool = False,
         verify_tls: bool = False,
+        session_recorder: SessionRecorder | None = None,
     ) -> None:
         """Session setup."""
         self._client_session: Final = (
@@ -210,6 +212,7 @@ class AioJsonRpcAioHttpClient(LogContextMixin):
         self._script_cache: Final[dict[str, str]] = {}
         self._last_session_id_refresh: datetime | None = None
         self._session_id: str | None = None
+        self._session_recorder: Final = session_recorder
         self._supported_methods: tuple[str, ...] | None = None
         self._sema: Final = Semaphore(value=MAX_CONCURRENT_HTTP_SESSIONS)
 
@@ -431,7 +434,7 @@ class AioJsonRpcAioHttpClient(LogContextMixin):
 
             if response.status == 200:
                 json_response = await asyncio.shield(self._get_json_reponse(response=response))
-
+                self._record_session(method=method, params=params, response=json_response)
                 if error := json_response[_JsonKey.ERROR]:
                     # Map JSON-RPC error to actionable exception with context
                     ctx = RpcContext(protocol="json-rpc", method=str(method), host=self._url)
@@ -466,6 +469,7 @@ class AioJsonRpcAioHttpClient(LogContextMixin):
                 raise exc
             raise ClientException(message)
         except BaseHomematicException as bhe:
+            self._record_session(method=method, params=params, exc=bhe)
             if method in (_JsonRpcMethod.SESSION_LOGIN, _JsonRpcMethod.SESSION_LOGOUT, _JsonRpcMethod.SESSION_RENEW):
                 self.clear_session()
             # Domain error at boundary -> warning
@@ -531,6 +535,28 @@ class AioJsonRpcAioHttpClient(LogContextMixin):
             )
             raise ClientException(exc) from exc
 
+    def _record_session(
+        self,
+        *,
+        method: str,
+        params: Mapping[str, Any],
+        response: dict[str, Any] | None = None,
+        exc: Exception | None = None,
+    ) -> bool:
+        """Record the session."""
+        if method == _JsonRpcMethod.SESSION_LOGIN and isinstance(params, dict):
+            if params.get(_JsonKey.USERNAME):
+                params[_JsonKey.USERNAME] = "********"
+            if params.get(_JsonKey.PASSWORD):
+                params[_JsonKey.PASSWORD] = "********"
+
+        if self._session_recorder and self._session_recorder.active:
+            self._session_recorder.add_json_rpc_session(
+                method=method, params=dict(params), response=response, session_exc=exc
+            )
+            return True
+        return False
+
     async def _get_json_reponse(self, *, response: ClientResponse) -> dict[str, Any] | Any:
         """Return the json object from response."""
         try:

aiohomematic/client/rpc_proxy.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+# Copyright (c) 2021-2025
 """
 XML-RPC transport proxy with concurrency control and connection awareness.
 
@@ -43,6 +43,7 @@ from aiohomematic.exceptions import (
     NoConnectionException,
     UnsupportedException,
 )
+from aiohomematic.store import SessionRecorder
 from aiohomematic.support import extract_exc_args, get_tls_context, log_boundary_error
 
 _LOGGER: Final = logging.getLogger(__name__)
@@ -96,10 +97,12 @@ class BaseRpcProxy(ABC):
         magic_method: Callable,
         tls: bool = False,
         verify_tls: bool = False,
+        session_recorder: SessionRecorder | None = None,
     ) -> None:
         """Initialize new proxy for server and get local ip."""
         self._interface_id: Final = interface_id
         self._connection_state: Final = connection_state
+        self._session_recorder: Final = session_recorder
         self._magic_method: Final = magic_method
         self._looper: Final = Looper()
         self._proxy_executor: Final = (
@@ -136,6 +139,17 @@ class BaseRpcProxy(ABC):
         """Magic method dispatcher."""
         return self._magic_method(self._async_request, *args, **kwargs)
 
+    def _record_session(
+        self, *, method: str, params: tuple[Any, ...], response: Any | None = None, exc: Exception | None = None
+    ) -> bool:
+        """Record the session."""
+        if method in (_RpcMethod.PING,):
+            return False
+        if self._session_recorder and self._session_recorder.active:
+            self._session_recorder.add_xml_rpc_session(method=method, params=params, response=response, session_exc=exc)
+            return True
+        return False
+
 
 # noinspection PyProtectedMember,PyUnresolvedReferences
 class AioXmlRpcProxy(BaseRpcProxy, xmlrpc.client.ServerProxy):
@@ -151,6 +165,7 @@ class AioXmlRpcProxy(BaseRpcProxy, xmlrpc.client.ServerProxy):
         headers: list[tuple[str, str]],
         tls: bool = False,
         verify_tls: bool = False,
+        session_recorder: SessionRecorder | None = None,
     ) -> None:
         """Initialize new proxy for server and get local ip."""
         super().__init__(
@@ -160,6 +175,7 @@ class AioXmlRpcProxy(BaseRpcProxy, xmlrpc.client.ServerProxy):
             magic_method=xmlrpc.client._Method,
             tls=tls,
             verify_tls=verify_tls,
+            session_recorder=session_recorder,
         )
 
         xmlrpc.client.ServerProxy.__init__(
@@ -193,10 +209,12 @@ class AioXmlRpcProxy(BaseRpcProxy, xmlrpc.client.ServerProxy):
                         executor=self._proxy_executor,
                     )
                 )
+                self._record_session(method=method, params=args[1], response=result)
                 self._connection_state.remove_issue(issuer=self, iid=self._interface_id)
                 return result
             raise NoConnectionException(f"No connection to {self._interface_id}")
-        except BaseHomematicException:
+        except BaseHomematicException as bhe:
+            self._record_session(method=args[0], params=args[1:], exc=bhe)
             raise
         except SSLError as sslerr:
             message = f"SSLError on {self._interface_id}: {extract_exc_args(exc=sslerr)}"