aiohomematic 2025.8.9__py3-none-any.whl → 2025.8.10__py3-none-any.whl

aiohomematic/__init__.py

@@ -1,6 +1,10 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 AioHomematic: a Python 3 library to interact with HomeMatic and HomematicIP backends.
 
+Public API at the top-level package is defined by __all__.
+
 This package provides a high-level API to discover devices and channels, read and write
 parameters (data points), receive events, and manage programs and system variables.
 
@@ -23,7 +27,7 @@ import sys
 import threading
 from typing import Final
 
-from aiohomematic import central as hmcu
+from aiohomematic import central as hmcu, validator as _ahm_validator
 from aiohomematic.const import VERSION
 
 if sys.stdout.isatty():
@@ -43,5 +47,15 @@ def signal_handler(sig, frame):  # type: ignore[no-untyped-def]
         asyncio.run_coroutine_threadsafe(central.stop(), asyncio.get_running_loop())
 
 
+# Perform lightweight startup validation once on import
+try:
+    _ahm_validator.validate_startup()
+except Exception as _exc:  # pragma: no cover
+    # Fail-fast with a clear message if validation fails during import
+    raise RuntimeError(f"AioHomematic startup validation failed: {_exc}") from _exc
+
 if threading.current_thread() is threading.main_thread() and sys.stdout.isatty():
     signal.signal(signal.SIGINT, signal_handler)
+
+# Define public API for the top-level package
+__all__ = ["__version__"]

aiohomematic/async_support.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module with support for loop interaction."""
 
 from __future__ import annotations
@@ -26,13 +28,24 @@ class Looper:
         self._tasks: Final[set[asyncio.Future[Any]]] = set()
         self._loop = asyncio.get_event_loop()
 
-    async def block_till_done(self) -> None:
-        """Block until all pending work is done."""
+    async def block_till_done(self, wait_time: float | None = None) -> None:
+        """
+        Block until all pending work is done.
+
+        If wait_time is set, stop waiting after the given number of seconds and log remaining tasks.
+        """
         # To flush out any call_soon_threadsafe
         await asyncio.sleep(0)
         start_time: float | None = None
+        deadline: float | None = (monotonic() + wait_time) if wait_time is not None else None
         current_task = asyncio.current_task()
         while tasks := [task for task in self._tasks if task is not current_task and not cancelling(task)]:
+            # If we have a deadline and have exceeded it, log remaining tasks and break
+            if deadline is not None and monotonic() >= deadline:
+                for task in tasks:
+                    _LOGGER.warning("Shutdown timeout reached; task still pending: %s", task)
+                break
+
             await self._await_and_log_pending(tasks)
 
             if start_time is None:

aiohomematic/caches/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Cache packages for AioHomematic.
 

aiohomematic/caches/dynamic.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Dynamic caches used at runtime by the central unit and clients.
 

aiohomematic/caches/persistent.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Persistent caches used to persist HomeMatic metadata between runs.
 

aiohomematic/caches/visibility.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Parameter visibility rules and cache for HomeMatic data points.
 

aiohomematic/central/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Central unit and core orchestration for HomeMatic CCU and compatible backends.
 
@@ -119,6 +121,7 @@ from aiohomematic.const import (
     TIMEOUT,
     UN_IGNORE_WILDCARD,
     BackendSystemEvent,
+    CentralUnitState,
     DataOperationResult,
     DataPointCategory,
     DataPointKey,
@@ -163,6 +166,7 @@ from aiohomematic.support import check_config, extract_exc_args, get_channel_no,
 __all__ = ["CentralConfig", "CentralUnit", "INTERFACE_EVENT_SCHEMA"]
 
 _LOGGER: Final = logging.getLogger(__name__)
+_LOGGER_EVENT: Final = logging.getLogger(f"{__name__}_event")
 
 # {central_name, central}
 CENTRAL_INSTANCES: Final[dict[str, CentralUnit]] = {}
@@ -184,7 +188,7 @@ class CentralUnit(PayloadMixin):
 
     def __init__(self, central_config: CentralConfig) -> None:
         """Init the central unit."""
-        self._started: bool = False
+        self._state: CentralUnitState = CentralUnitState.NEW
         self._clients_started: bool = False
         self._device_add_semaphore: Final = asyncio.Semaphore()
         self._connection_state: Final = CentralConnectionState()
@@ -379,9 +383,9 @@ class CentralUnit(PayloadMixin):
         )
 
     @property
-    def started(self) -> bool:
-        """Return if the central is started."""
-        return self._started
+    def state(self) -> CentralUnitState:
+        """Return the central state."""
+        return self._state
 
     @property
     def supports_ping_pong(self) -> bool:
@@ -455,9 +459,17 @@ class CentralUnit(PayloadMixin):
     async def start(self) -> None:
         """Start processing of the central unit."""
 
-        if self._started:
+        _LOGGER.debug("START: Central %s is %s", self.name, self._state)
+        if self._state == CentralUnitState.INITIALIZING:
+            _LOGGER.debug("START: Central %s already starting", self.name)
+            return
+
+        if self._state == CentralUnitState.RUNNING:
             _LOGGER.debug("START: Central %s already started", self.name)
             return
+
+        self._state = CentralUnitState.INITIALIZING
+        _LOGGER.debug("START: Initializing Central %s", self.name)
         if self._config.enabled_interface_configs and (
             ip_addr := await self._identify_ip_addr(port=self._config.connection_check_port)
         ):
@@ -479,6 +491,7 @@ class CentralUnit(PayloadMixin):
                 self._listen_port = xml_rpc_server.listen_port
                 self._xml_rpc_server.add_central(self)
         except OSError as oserr:
+            self._state = CentralUnitState.STOPPED_BY_ERROR
             raise AioHomematicException(
                 f"START: Failed to start central unit {self.name}: {extract_exc_args(exc=oserr)}"
             ) from oserr
@@ -492,13 +505,24 @@ class CentralUnit(PayloadMixin):
             if self._config.enable_server:
                 self._start_scheduler()
 
-        self._started = True
+        self._state = CentralUnitState.RUNNING
+        _LOGGER.debug("START: Central %s is %s", self.name, self._state)
 
     async def stop(self) -> None:
         """Stop processing of the central unit."""
-        if not self._started:
+        _LOGGER.debug("STOP: Central %s is %s", self.name, self._state)
+        if self._state == CentralUnitState.STOPPING:
+            _LOGGER.debug("STOP: Central %s is already stopping", self.name)
+            return
+        if self._state == CentralUnitState.STOPPED:
+            _LOGGER.debug("STOP: Central %s is already stopped", self.name)
+            return
+        if self._state != CentralUnitState.RUNNING:
             _LOGGER.debug("STOP: Central %s not started", self.name)
             return
+        self._state = CentralUnitState.STOPPING
+        _LOGGER.debug("STOP: Stopping Central %s", self.name)
+
         await self.save_caches(save_device_descriptions=True, save_paramset_descriptions=True)
         self._stop_scheduler()
         await self._stop_clients()
@@ -522,8 +546,8 @@ class CentralUnit(PayloadMixin):
 
         # cancel outstanding tasks to speed up teardown
         self.looper.cancel_tasks()
-        # wait until tasks are finished
-        await self.looper.block_till_done()
+        # wait until tasks are finished (with wait_time safeguard)
+        await self.looper.block_till_done(wait_time=5.0)
 
         # Wait briefly for any auxiliary threads to finish without blocking forever
         max_wait_seconds = 5.0
@@ -532,7 +556,8 @@ class CentralUnit(PayloadMixin):
         while self._has_active_threads and waited < max_wait_seconds:
             await asyncio.sleep(interval)
             waited += interval
-        self._started = False
+        self._state = CentralUnitState.STOPPED
+        _LOGGER.debug("STOP: Central %s is %s", self.name, self._state)
 
     async def restart_clients(self) -> None:
         """Restart clients."""
@@ -1074,7 +1099,7 @@ class CentralUnit(PayloadMixin):
     @callback_event
     async def data_point_event(self, interface_id: str, channel_address: str, parameter: str, value: Any) -> None:
         """If a device emits some sort event, we will handle it here."""
-        _LOGGER.debug(
+        _LOGGER_EVENT.debug(
             "EVENT: interface_id = %s, channel_address = %s, parameter = %s, value = %s",
             interface_id,
             channel_address,
@@ -1112,7 +1137,7 @@ class CentralUnit(PayloadMixin):
                     if callable(callback_handler):
                         await callback_handler(value)
             except RuntimeError as rterr:  # pragma: no cover
-                _LOGGER.debug(
+                _LOGGER_EVENT.debug(
                     "EVENT: RuntimeError [%s]. Failed to call callback for: %s, %s, %s",
                     extract_exc_args(exc=rterr),
                     interface_id,
@@ -1120,7 +1145,7 @@ class CentralUnit(PayloadMixin):
                     parameter,
                 )
             except Exception as exc:  # pragma: no cover
-                _LOGGER.warning(
+                _LOGGER_EVENT.warning(
                     "EVENT failed: Unable to call callback for: %s, %s, %s, %s",
                     interface_id,
                     channel_address,
@@ -1130,7 +1155,7 @@ class CentralUnit(PayloadMixin):
 
     def data_point_path_event(self, state_path: str, value: str) -> None:
         """If a device emits some sort event, we will handle it here."""
-        _LOGGER.debug(
+        _LOGGER_EVENT.debug(
             "DATA_POINT_PATH_EVENT: topic = %s, payload = %s",
             state_path,
             value,
@@ -1149,7 +1174,7 @@ class CentralUnit(PayloadMixin):
 
     def sysvar_data_point_path_event(self, state_path: str, value: str) -> None:
         """If a device emits some sort event, we will handle it here."""
-        _LOGGER.debug(
+        _LOGGER_EVENT.debug(
             "SYSVAR_DATA_POINT_PATH_EVENT: topic = %s, payload = %s",
             state_path,
             value,
@@ -1161,13 +1186,13 @@ class CentralUnit(PayloadMixin):
                 if callable(callback_handler):
                     self._looper.create_task(callback_handler(value), name=f"sysvar-data-point-event-{state_path}")
             except RuntimeError as rterr:  # pragma: no cover
-                _LOGGER.debug(
+                _LOGGER_EVENT.debug(
                     "EVENT: RuntimeError [%s]. Failed to call callback for: %s",
                     extract_exc_args(exc=rterr),
                     state_path,
                 )
             except Exception as exc:  # pragma: no cover
-                _LOGGER.warning(
+                _LOGGER_EVENT.warning(
                     "EVENT failed: Unable to call callback for: %s, %s",
                     state_path,
                     extract_exc_args(exc=exc),
@@ -1621,7 +1646,7 @@ class _Scheduler(threading.Thread):
     async def _run_scheduler_tasks(self) -> None:
         """Run all tasks."""
         while self._active:
-            if not self._central.started:
+            if self._central.state != CentralUnitState.RUNNING:
                 _LOGGER.debug("SCHEDULER: Waiting till central %s is started", self._central.name)
                 await asyncio.sleep(SCHEDULER_NOT_STARTED_SLEEP)
                 continue

aiohomematic/central/decorators.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Decorators for central used within aiohomematic."""
 
 from __future__ import annotations
@@ -17,6 +19,9 @@ from aiohomematic.support import extract_exc_args
 
 _LOGGER: Final = logging.getLogger(__name__)
 _INTERFACE_ID: Final = "interface_id"
+_CHANNEL_ADDRESS: Final = "channel_address"
+_PARAMETER: Final = "parameter"
+_VALUE: Final = "value"
 
 
 def callback_backend_system(system_event: BackendSystemEvent) -> Callable:
@@ -83,28 +88,68 @@ def callback_backend_system(system_event: BackendSystemEvent) -> Callable:
     return decorator_backend_system_callback
 
 
-def callback_event[**P, R](
-    func: Callable[P, R],
-) -> Callable:
+def callback_event[**P, R](func: Callable[P, R]) -> Callable:
     """Check if event_callback is set and call it AFTER original function."""
 
-    @wraps(func)
-    async def async_wrapper_event_callback(*args: P.args, **kwargs: P.kwargs) -> R:
-        """Wrap callback events."""
-        return_value = cast(R, await func(*args, **kwargs))  # type: ignore[misc]
-        _exec_event_callback(*args, **kwargs)
-        return return_value
-
     def _exec_event_callback(*args: Any, **kwargs: Any) -> None:
         """Execute the callback for a data_point event."""
         try:
-            args = args[1:]
-            interface_id: str = args[0] if len(args) > 1 else str(kwargs[_INTERFACE_ID])
+            # Expected signature: (self, interface_id, channel_address, parameter, value)
+            interface_id: str
+            if len(args) > 1:
+                interface_id = cast(str, args[1])
+                channel_address = cast(str, args[2])
+                parameter = cast(str, args[3])
+                value = args[4] if len(args) > 4 else kwargs.get(_VALUE)
+            else:
+                interface_id = cast(str, kwargs[_INTERFACE_ID])
+                channel_address = cast(str, kwargs[_CHANNEL_ADDRESS])
+                parameter = cast(str, kwargs[_PARAMETER])
+                value = kwargs[_VALUE]
+
             if client := hmcl.get_client(interface_id=interface_id):
                 client.modified_at = datetime.now()
-                client.central.fire_backend_parameter_callback(*args, **kwargs)
+                client.central.fire_backend_parameter_callback(
+                    interface_id=interface_id, channel_address=channel_address, parameter=parameter, value=value
+                )
         except Exception as exc:  # pragma: no cover
-            _LOGGER.warning("EXEC_DATA_POINT_EVENT_CALLBACK failed: Unable to reduce kwargs for event_callback")
+            _LOGGER.warning("EXEC_DATA_POINT_EVENT_CALLBACK failed: Unable to process args/kwargs for event_callback")
             raise AioHomematicException(f"args-exception event_callback [{extract_exc_args(exc=exc)}]") from exc
 
-    return async_wrapper_event_callback
+    def _schedule_or_exec(*args: Any, **kwargs: Any) -> None:
+        """Schedule event callback on central looper when possible, else execute inline."""
+        try:
+            # Prefer scheduling on the CentralUnit looper when available to avoid blocking hot path
+            unit = args[0]
+            if isinstance(unit, hmcu.CentralUnit):
+                unit.looper.create_task(
+                    _async_wrap_sync(_exec_event_callback, *args, **kwargs),
+                    name="wrapper_event_callback",
+                )
+                return
+        except Exception:
+            # Fall through to inline execution on any error
+            pass
+        _exec_event_callback(*args, **kwargs)
+
+    @wraps(func)
+    async def async_wrapper_event_callback(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap async callback events."""
+        return_value = cast(R, await func(*args, **kwargs))  # type: ignore[misc]
+        _schedule_or_exec(*args, **kwargs)
+        return return_value
+
+    @wraps(func)
+    def wrapper_event_callback(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap sync callback events."""
+        return_value = func(*args, **kwargs)
+        _schedule_or_exec(*args, **kwargs)
+        return return_value
+
+    # Helper to create a trivial coroutine from a sync callable
+    async def _async_wrap_sync(cb: Callable[..., None], *a: Any, **kw: Any) -> None:
+        cb(*a, **kw)
+
+    if inspect.iscoroutinefunction(func):
+        return async_wrapper_event_callback
+    return wrapper_event_callback

aiohomematic/central/xml_rpc_server.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 XML-RPC server module.
 
@@ -16,7 +18,7 @@ from xmlrpc.server import SimpleXMLRPCRequestHandler, SimpleXMLRPCServer
 from aiohomematic import central as hmcu
 from aiohomematic.central.decorators import callback_backend_system
 from aiohomematic.const import IP_ANY_V4, PORT_ANY, BackendSystemEvent
-from aiohomematic.support import find_free_port
+from aiohomematic.support import find_free_port, log_boundary_error
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -45,6 +47,18 @@ class RPCFunctions:
     @callback_backend_system(system_event=BackendSystemEvent.ERROR)
     def error(self, interface_id: str, error_code: str, msg: str) -> None:
         """When some error occurs the CCU / Homegear will send its error message here."""
+        # Structured boundary log (warning level). XML-RPC server received error notification.
+        try:
+            raise RuntimeError(str(msg))
+        except RuntimeError as err:
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="xml-rpc-server",
+                action="error",
+                err=err,
+                level=logging.WARNING,
+                context={"interface_id": interface_id, "error_code": int(error_code)},
+            )
         _LOGGER.warning(
             "ERROR failed: interface_id = %s, error_code = %i, message = %s",
             interface_id,

aiohomematic/client/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Client adapters for communicating with HomeMatic CCU and compatible backends.
 

aiohomematic/client/_rpc_errors.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""
+Error mapping helpers for RPC transports.
+
+This module centralizes small, transport-agnostic utilities to turn backend
+errors into domain-specific exceptions with useful context. It is used by both
+JSON-RPC and XML-RPC clients.
+
+Key types and functions
+- RpcContext: Lightweight context container that formats protocol/method/host
+  for readable error messages and logs.
+- map_jsonrpc_error: Maps a JSON-RPC error object to an appropriate exception
+  (AuthFailure, InternalBackendException, ClientException).
+- map_transport_error: Maps generic transport-level exceptions like OSError to
+  domain exceptions (NoConnectionException/ClientException).
+- map_xmlrpc_fault: Maps XML-RPC faults to domain exceptions with context.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from aiohomematic.exceptions import AuthFailure, ClientException, InternalBackendException, NoConnectionException
+
+
+@dataclass(slots=True)
+class RpcContext:
+    protocol: str
+    method: str
+    host: str | None = None
+    interface: str | None = None
+    params: Mapping[str, Any] | None = None
+
+    def fmt(self) -> str:
+        """Format context for error messages."""
+        parts: list[str] = [f"protocol={self.protocol}", f"method={self.method}"]
+        if self.interface:
+            parts.append(f"interface={self.interface}")
+        if self.host:
+            parts.append(f"host={self.host}")
+        return ", ".join(parts)
+
+
+def map_jsonrpc_error(error: Mapping[str, Any], ctx: RpcContext) -> Exception:
+    """Map JSON-RPC error to exception."""
+    # JSON-RPC 2.0 like error: {code, message, data?}
+    code = int(error.get("code", 0))
+    message = str(error.get("message", ""))
+    # Enrich message with context
+    base_msg = f"{message} ({ctx.fmt()})"
+
+    # Map common codes
+    if message.startswith("access denied") or code in (401, -32001):
+        return AuthFailure(base_msg)
+    if "internal error" in message.lower() or code in (-32603, 500):
+        return InternalBackendException(base_msg)
+    # Generic client exception for others
+    return ClientException(base_msg)
+
+
+def map_transport_error(exc: BaseException, ctx: RpcContext) -> Exception:
+    """Map transport error to exception."""
+    msg = f"{exc} ({ctx.fmt()})"
+    if isinstance(exc, OSError):
+        return NoConnectionException(msg)
+    return ClientException(msg)
+
+
+def map_xmlrpc_fault(code: int, fault_string: str, ctx: RpcContext) -> Exception:
+    """Map XML-RPC fault to exception."""
+    # Enrich message with context
+    fault_msg = f"XMLRPC Fault {code}: {fault_string} ({ctx.fmt()})"
+    # Simple mappings
+    if "unauthorized" in fault_string.lower():
+        return AuthFailure(fault_msg)
+    if "internal" in fault_string.lower():
+        return InternalBackendException(fault_msg)
+    return ClientException(fault_msg)

aiohomematic/client/json_rpc.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Asynchronous JSON-RPC client for HomeMatic CCU-compatible backends.
 
@@ -29,6 +31,7 @@ Notes
 
 from __future__ import annotations
 
+import asyncio
 from asyncio import Semaphore
 from collections.abc import Mapping
 from datetime import datetime
@@ -54,6 +57,7 @@ import orjson
 
 from aiohomematic import central as hmcu
 from aiohomematic.async_support import Looper
+from aiohomematic.client._rpc_errors import RpcContext, map_jsonrpc_error
 from aiohomematic.const import (
     ALWAYS_ENABLE_SYSVARS_BY_ID,
     DEFAULT_INCLUDE_INTERNAL_PROGRAMS,
@@ -78,7 +82,6 @@ from aiohomematic.const import (
     SysvarType,
 )
 from aiohomematic.exceptions import (
-    AuthFailure,
     BaseHomematicException,
     ClientException,
     InternalBackendException,
@@ -91,6 +94,7 @@ from aiohomematic.support import (
     element_matches_key,
     extract_exc_args,
     get_tls_context,
+    log_boundary_error,
     parse_sys_var,
 )
 
@@ -402,38 +406,59 @@ class JsonRpcAioHttpClient:
             )
             if method in _PARALLEL_EXECUTION_LIMITED_JSONRPC_METHODS:
                 async with self._sema:
-                    if (response := await post_call()) is None:
+                    if (response := await asyncio.shield(post_call())) is None:
                         raise ClientException("POST method failed with no response")
-            elif (response := await post_call()) is None:
+            elif (response := await asyncio.shield(post_call())) is None:
                 raise ClientException("POST method failed with no response")
 
             if response.status == 200:
-                json_response = await self._get_json_reponse(response=response)
+                json_response = await asyncio.shield(self._get_json_reponse(response=response))
 
                 if error := json_response[_JsonKey.ERROR]:
-                    error_message = error[_JsonKey.MESSAGE]
-                    message = f"POST method '{method}' failed: {error_message}"
-                    if error_message.startswith("access denied"):
-                        _LOGGER.debug(message)
-                        raise AuthFailure(message)
-                    if "internal error" in error_message:
-                        message = f"An internal error happened within your backend (Fix or ignore it): {message}"
-                        _LOGGER.debug(message)
-                        raise InternalBackendException(message)
-                    _LOGGER.debug(message)
-                    raise ClientException(message)
+                    # Map JSON-RPC error to actionable exception with context
+                    ctx = RpcContext(protocol="json-rpc", method=str(method), host=self._url)
+                    exc = map_jsonrpc_error(error=error, ctx=ctx)
+                    # Structured boundary log at warning level (recoverable per-call failure)
+                    log_boundary_error(
+                        logger=_LOGGER,
+                        boundary="json-rpc",
+                        action=str(method),
+                        err=exc,
+                        level=logging.WARNING,
+                        context={"url": self._url},
+                    )
+                    _LOGGER.debug("POST: %s", exc)
+                    raise exc
 
                 return json_response
 
             message = f"Status: {response.status}"
-            json_response = await self._get_json_reponse(response=response)
+            json_response = await asyncio.shield(self._get_json_reponse(response=response))
             if error := json_response[_JsonKey.ERROR]:
-                error_message = error[_JsonKey.MESSAGE]
-                message = f"{message}: {error_message}"
+                ctx = RpcContext(protocol="json-rpc", method=str(method), host=self._url)
+                exc = map_jsonrpc_error(error=error, ctx=ctx)
+                log_boundary_error(
+                    logger=_LOGGER,
+                    boundary="json-rpc",
+                    action=str(method),
+                    err=exc,
+                    level=logging.WARNING,
+                    context={"url": self._url, "status": response.status},
+                )
+                raise exc
             raise ClientException(message)
-        except BaseHomematicException:
+        except BaseHomematicException as bhe:
             if method in (_JsonRpcMethod.SESSION_LOGIN, _JsonRpcMethod.SESSION_LOGOUT, _JsonRpcMethod.SESSION_RENEW):
                 self.clear_session()
+            # Domain error at boundary -> warning
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=bhe,
+                level=logging.WARNING,
+                context={"url": self._url},
+            )
             raise
         except ClientConnectorCertificateError as cccerr:
             self.clear_session()
@@ -443,12 +468,36 @@ class JsonRpcAioHttpClient:
                     f"{message}. Possible reason: 'Automatic forwarding to HTTPS' is enabled in backend, "
                     f"but this integration is not configured to use TLS"
                 )
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=cccerr,
+                level=logging.ERROR,
+                context={"url": self._url},
+            )
             raise ClientException(message) from cccerr
         except (ClientError, OSError) as err:
             self.clear_session()
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=err,
+                level=logging.ERROR,
+                context={"url": self._url},
+            )
             raise NoConnectionException(err) from err
         except (TypeError, Exception) as exc:
             self.clear_session()
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=exc,
+                level=logging.ERROR,
+                context={"url": self._url},
+            )
             raise ClientException(exc) from exc
 
     async def _get_json_reponse(self, response: ClientResponse) -> dict[str, Any] | Any: