aiohomematic 2025.8.9__tar.gz → 2025.9.1__tar.gz

{aiohomematic-2025.8.9 → aiohomematic-2025.9.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Daniel Perna, SukramJ
+Copyright (c) 2021-2025 Daniel Perna, SukramJ
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

aiohomematic-2025.9.1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: aiohomematic
+Version: 2025.9.1
+Summary: Homematic interface for Home Assistant running on Python 3.
+Home-page: https://github.com/sukramj/aiohomematic
+Author-email: SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>
+License: MIT License
+Project-URL: Source Code, https://github.com/sukramj/aiohomematic
+Project-URL: Bug Reports, https://github.com/sukramj/aiohomematic/issues
+Project-URL: Docs: Dev, https://github.com/sukramj/aiohomematic
+Project-URL: Forum, https://github.com/sukramj/aiohomematic/discussions
+Keywords: home,automation,homematic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.10.0
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: python-slugify>=8.0.0
+Requires-Dist: voluptuous>=0.14.0
+Dynamic: license-file
+
+# AIO Homematic (hahomematic)
+
+A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring [HomeMatic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
+
+This project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.
+
+## How it works
+
+Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:
+
+- Fetches and caches device paramsets (VALUES) for fast successive startups.
+- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
+- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.
+
+## Key features
+
+- Automatic entity discovery from device/channel parameters.
+- Extensible via custom entity classes for complex devices.
+- Caching of paramsets to speed up restarts.
+- Designed to integrate with Home Assistant.
+
+## Quickstart for Home Assistant
+
+Use the Home Assistant custom integration "Homematic(IP) Local", which is powered by aiohomematic.
+
+1. Prerequisites
+   - Home Assistant 2024.6 or newer recommended.
+   - A CCU3, RaspberryMatic, or Homegear instance reachable from Home Assistant.
+   - For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.
+2. Install the integration
+   - Add the custom repository and install: https://github.com/sukramj/homematicip_local
+   - Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation
+3. Configure via Home Assistant UI
+   - In Home Assistant: Settings → Devices & Services → Add Integration → search for "Homematic(IP) Local".
+   - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable SSL and accept the certificate if self‑signed.
+   - Provide credentials if your CCU requires them.
+   - Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).
+4. Network callbacks
+   - The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). The default callback port is 43439; you can adjust it in advanced options.
+5. Verify
+   - After setup, devices should appear under Devices & Services → Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.
+
+If you need to use aiohomematic directly in Python, see the Public API and example below.
+
+## Requirements
+
+Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:
+
+- CCU2: 2.53.27
+- CCU3: 3.53.26
+
+See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.
+
+## Public API and imports
+
+- The public API of aiohomematic is explicitly defined via **all** in each module and subpackage.
+- Backwards‑compatible imports should target these modules:
+  - aiohomematic.central: CentralUnit, CentralConfig and related schemas
+  - aiohomematic.client: Client, InterfaceConfig, create_client, get_client
+  - aiohomematic.model: device/data point abstractions (see subpackages for details)
+  - aiohomematic.exceptions: library exception types intended for consumers
+  - aiohomematic.const: constants and enums (stable subset; see module **all**)
+- The top‑level package only exposes **version** to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.
+
+Example:
+
+    from aiohomematic.central import CentralConfig
+    from aiohomematic import client as hmcl
+
+    cfg = CentralConfig(
+        central_id="ccu-main",
+        host="ccu.local",
+        username="admin",
+        password="secret",
+        default_callback_port=43439,
+        interface_configs={hmcl.InterfaceConfig(interface=hmcl.Interface.HMIP, port=2010, enabled=True)},
+    )
+    central = cfg.create_central()
+
+## Useful links
+
+- Changelog: [see](changelog.md) for release history and latest changes.
+- Definition of calculated data points: [see](docs/calculated_data_points.md)
+- Naming: [see](docs/naming.md) for how device, channel and data point names are created.
+- Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local
+- Input select helper: [see](docs/input_select_helper.md) for an overview of how to use the input select helper.
+- Troubleshooting with Home Assistant: [see](docs/homeassistant_troubleshooting.md) for common issues and how to debug them.
+- Unignore mechanism: [see](docs/unignore.md) for how to unignore devices that are ignored by default.
+
+## Useful developer links
+
+- Architecture overview: [see](docs/architecture.md) for an overview of the architecture of the library.
+- Data flow: [see](docs/data_flow.md) for an overview of how data flows through the library.
+- Extending the model: [see](docs/extension_points.md) for adding custom device profiles and calculated data points.
+- Home Assistant lifecycle (discovery, updates, teardown): [see](docs/homeassistant_lifecycle.md) for details on how the integration works and how to debug issues.
+- RSSI fix: [see](docs/rssi_fix.md) for how RSSI values are fixed for Home Assistant.
+- Sequence diagrams: [see](docs/sequence_diagrams.md) for a sequence diagram of how the library works.

aiohomematic-2025.9.1/README.md

@@ -0,0 +1,97 @@
+# AIO Homematic (hahomematic)
+
+A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring [HomeMatic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
+
+This project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.
+
+## How it works
+
+Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:
+
+- Fetches and caches device paramsets (VALUES) for fast successive startups.
+- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
+- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.
+
+## Key features
+
+- Automatic entity discovery from device/channel parameters.
+- Extensible via custom entity classes for complex devices.
+- Caching of paramsets to speed up restarts.
+- Designed to integrate with Home Assistant.
+
+## Quickstart for Home Assistant
+
+Use the Home Assistant custom integration "Homematic(IP) Local", which is powered by aiohomematic.
+
+1. Prerequisites
+   - Home Assistant 2024.6 or newer recommended.
+   - A CCU3, RaspberryMatic, or Homegear instance reachable from Home Assistant.
+   - For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.
+2. Install the integration
+   - Add the custom repository and install: https://github.com/sukramj/homematicip_local
+   - Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation
+3. Configure via Home Assistant UI
+   - In Home Assistant: Settings → Devices & Services → Add Integration → search for "Homematic(IP) Local".
+   - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable SSL and accept the certificate if self‑signed.
+   - Provide credentials if your CCU requires them.
+   - Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).
+4. Network callbacks
+   - The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). The default callback port is 43439; you can adjust it in advanced options.
+5. Verify
+   - After setup, devices should appear under Devices & Services → Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.
+
+If you need to use aiohomematic directly in Python, see the Public API and example below.
+
+## Requirements
+
+Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:
+
+- CCU2: 2.53.27
+- CCU3: 3.53.26
+
+See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.
+
+## Public API and imports
+
+- The public API of aiohomematic is explicitly defined via **all** in each module and subpackage.
+- Backwards‑compatible imports should target these modules:
+  - aiohomematic.central: CentralUnit, CentralConfig and related schemas
+  - aiohomematic.client: Client, InterfaceConfig, create_client, get_client
+  - aiohomematic.model: device/data point abstractions (see subpackages for details)
+  - aiohomematic.exceptions: library exception types intended for consumers
+  - aiohomematic.const: constants and enums (stable subset; see module **all**)
+- The top‑level package only exposes **version** to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.
+
+Example:
+
+    from aiohomematic.central import CentralConfig
+    from aiohomematic import client as hmcl
+
+    cfg = CentralConfig(
+        central_id="ccu-main",
+        host="ccu.local",
+        username="admin",
+        password="secret",
+        default_callback_port=43439,
+        interface_configs={hmcl.InterfaceConfig(interface=hmcl.Interface.HMIP, port=2010, enabled=True)},
+    )
+    central = cfg.create_central()
+
+## Useful links
+
+- Changelog: [see](changelog.md) for release history and latest changes.
+- Definition of calculated data points: [see](docs/calculated_data_points.md)
+- Naming: [see](docs/naming.md) for how device, channel and data point names are created.
+- Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local
+- Input select helper: [see](docs/input_select_helper.md) for an overview of how to use the input select helper.
+- Troubleshooting with Home Assistant: [see](docs/homeassistant_troubleshooting.md) for common issues and how to debug them.
+- Unignore mechanism: [see](docs/unignore.md) for how to unignore devices that are ignored by default.
+
+## Useful developer links
+
+- Architecture overview: [see](docs/architecture.md) for an overview of the architecture of the library.
+- Data flow: [see](docs/data_flow.md) for an overview of how data flows through the library.
+- Extending the model: [see](docs/extension_points.md) for adding custom device profiles and calculated data points.
+- Home Assistant lifecycle (discovery, updates, teardown): [see](docs/homeassistant_lifecycle.md) for details on how the integration works and how to debug issues.
+- RSSI fix: [see](docs/rssi_fix.md) for how RSSI values are fixed for Home Assistant.
+- Sequence diagrams: [see](docs/sequence_diagrams.md) for a sequence diagram of how the library works.

{aiohomematic-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/aiohomematic/caches/__init__.py

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

{aiohomematic-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/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"{__package__}.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-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/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-2025.8.9 → aiohomematic-2025.9.1}/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.