aiohomematic 2025.12.7__tar.gz

aiohomematic-2025.12.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiohomematic-2025.12.7/MANIFEST.in

@@ -0,0 +1,14 @@
+# MANIFEST.in
+
+# Include the main package and important files
+graft aiohomematic
+include README.md
+include LICENSE
+
+# Exclude tests and build artifacts
+prune tests
+prune build
+prune dist
+
+# IMPORTANT: exclude support package from the sdist tarball
+prune aiohomematic_test_support

aiohomematic-2025.12.7/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: aiohomematic
+Version: 2025.12.7
+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,openccu,homegear
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.12.0
+Requires-Dist: orjson>=3.11.0
+Requires-Dist: python-slugify>=8.0.0
+Requires-Dist: voluptuous>=0.15.0
+Dynamic: license-file
+
+[![releasebadge]][release]
+[![License][license-shield]](LICENSE.md)
+[![GitHub Sponsors][sponsorsbadge]][sponsors]
+
+# AIO Homematic
+
+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
+   - Use latest version of Home Assistant.
+   - A CCU3, OpenCCU, 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 TLS and don't use verify if self‑signed.
+   - Always enter credentials.
+   - 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). Callbacks are only required for special network setups.
+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/OpenCCU/OpenCCU/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.central.event: display received events from the backend
+  - 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**)
+  - aiohomematic.performance: display some performance metrics (enabled when DEBUG is enabled)
+- 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.
+
+[license-shield]: https://img.shields.io/github/license/SukramJ/aiohomematic.svg?style=for-the-badge
+[release]: https://github.com/SukramJ/aiohomematic/releases
+[releasebadge]: https://img.shields.io/github/v/release/SukramJ/aiohomematic?style=for-the-badge
+[sponsorsbadge]: https://img.shields.io/github/sponsors/SukramJ?style=for-the-badge&label=GitHub%20Sponsors&color=green
+[sponsors]: https://github.com/sponsors/SukramJ

aiohomematic-2025.12.7/README.md

@@ -0,0 +1,109 @@
+[![releasebadge]][release]
+[![License][license-shield]](LICENSE.md)
+[![GitHub Sponsors][sponsorsbadge]][sponsors]
+
+# AIO Homematic
+
+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
+   - Use latest version of Home Assistant.
+   - A CCU3, OpenCCU, 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 TLS and don't use verify if self‑signed.
+   - Always enter credentials.
+   - 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). Callbacks are only required for special network setups.
+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/OpenCCU/OpenCCU/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.central.event: display received events from the backend
+  - 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**)
+  - aiohomematic.performance: display some performance metrics (enabled when DEBUG is enabled)
+- 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.
+
+[license-shield]: https://img.shields.io/github/license/SukramJ/aiohomematic.svg?style=for-the-badge
+[release]: https://github.com/SukramJ/aiohomematic/releases
+[releasebadge]: https://img.shields.io/github/v/release/SukramJ/aiohomematic?style=for-the-badge
+[sponsorsbadge]: https://img.shields.io/github/sponsors/SukramJ?style=for-the-badge&label=GitHub%20Sponsors&color=green
+[sponsors]: https://github.com/sponsors/SukramJ

aiohomematic-2025.12.7/aiohomematic/__init__.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+AioHomematic: async Python library for Homematic and HomematicIP backends.
+
+Overview
+--------
+This package provides a comprehensive async library for interacting with Homematic CCU
+and HomematicIP systems. It enables device discovery, data point manipulation, event
+handling, and management of programs and system variables.
+
+The library is designed for integration with Home Assistant but can be used standalone.
+It features automatic entity discovery, flexible customization through device-specific
+implementations, and fast startup through intelligent caching.
+
+Architecture
+------------
+The library is organized into four main layers:
+
+- **aiohomematic.central**: Central orchestration managing client lifecycles, device
+  creation, event handling, and background tasks.
+- **aiohomematic.client**: Protocol adapters (JSON-RPC/XML-RPC) for backend communication.
+- **aiohomematic.model**: Runtime representation of devices, channels, and data points
+  with generic, custom, calculated, and hub entity types.
+- **aiohomematic.store**: Persistence layer for device descriptions, paramsets, and
+  runtime caches.
+
+Public API
+----------
+- `__version__`: Library version string.
+
+The primary entry point is `CentralConfig` and `CentralUnit` from `aiohomematic.central`.
+
+Quick start
+-----------
+Typical usage pattern:
+
+    from aiohomematic.central import CentralConfig
+    from aiohomematic.client import InterfaceConfig, Interface
+
+    config = CentralConfig(
+        name="ccu-main",
+        host="192.168.1.100",
+        username="admin",
+        password="secret",
+        central_id="unique-id",
+        interface_configs={
+            InterfaceConfig(
+                central_name="ccu-main",
+                interface=Interface.HMIP_RF,
+                port=2010,
+            ),
+        },
+    )
+
+    central = config.create_central()
+    await central.start()
+
+    # Access devices and data points
+    device = central.get_device_by_address("VCU0000001")
+
+    await central.stop()
+
+Notes
+-----
+Public API at the top-level package is defined by `__all__`.
+
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import sys
+import threading
+from typing import Final
+
+from aiohomematic import central as hmcu, i18n, validator as _ahm_validator
+from aiohomematic.const import VERSION
+
+if sys.stdout.isatty():
+    logging.basicConfig(level=logging.INFO)
+
+__version__: Final = VERSION
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+# pylint: disable=unused-argument
+# noinspection PyUnusedLocal
+def signal_handler(sig, frame):  # type: ignore[no-untyped-def]
+    """Handle signal to shut down central."""
+    _LOGGER.info(i18n.tr("log.core.signal.shutdown", sig=str(sig)))
+    signal.signal(signal.SIGINT, signal.SIG_DFL)
+    for central in hmcu.CENTRAL_INSTANCES.values():
+        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(i18n.tr("exception.startup.validation_failed", reason=_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.12.7/aiohomematic/async_support.py

@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+Async event loop utilities and task management.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Collection
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures._base import CancelledError
+import contextlib
+from functools import wraps
+import logging
+from time import monotonic
+from typing import Any, Final, cast
+
+from aiohomematic.const import BLOCK_LOG_TIMEOUT
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.interfaces import TaskScheduler
+import aiohomematic.support as hms
+from aiohomematic.support import extract_exc_args
+from aiohomematic.type_aliases import AsyncTaskFactoryAny, CallableAny, CoroutineAny
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class Looper(TaskScheduler):
+    """Helper class for event loop support."""
+
+    def __init__(self) -> None:
+        """Initialize the loop helper."""
+        self._tasks: Final[set[asyncio.Future[Any]]] = set()
+        self._loop = asyncio.get_event_loop()
+
+    def async_add_executor_job[T](
+        self,
+        target: Callable[..., T],
+        *args: Any,
+        name: str,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> asyncio.Future[T]:
+        """Add an executor job from within the event_loop."""
+        try:
+            task = self._loop.run_in_executor(executor, target, *args)
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.remove)
+        except (TimeoutError, CancelledError) as err:  # pragma: no cover
+            message = f"async_add_executor_job: task cancelled for {name} [{extract_exc_args(exc=err)}]"
+            _LOGGER.debug(message)
+            raise AioHomematicException(message) from err
+        return task
+
+    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=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(  # i18n-log: ignore
+                        "Shutdown timeout reached; task still pending: %s", task
+                    )
+                break
+
+            pending_after_wait = await self._await_and_log_pending(pending=tasks, deadline=deadline)
+
+            # If deadline has been reached and tasks are still pending, log and break
+            if deadline is not None and monotonic() >= deadline and pending_after_wait:
+                for task in pending_after_wait:
+                    _LOGGER.warning(  # i18n-log: ignore
+                        "Shutdown timeout reached; task still pending: %s", task
+                    )
+                break
+
+            if start_time is None:
+                # Avoid calling monotonic() until we know
+                # we may need to start logging blocked tasks.
+                start_time = 0
+            elif start_time == 0:
+                # If we have waited twice then we set the start
+                # time
+                start_time = monotonic()
+            elif monotonic() - start_time > BLOCK_LOG_TIMEOUT:
+                # We have waited at least three loops and new tasks
+                # continue to block. At this point we start
+                # logging all waiting tasks.
+                for task in tasks:
+                    _LOGGER.debug("Waiting for task: %s", task)
+
+    def cancel_tasks(self) -> None:
+        """Cancel running tasks."""
+        for task in self._tasks.copy():
+            if not task.cancelled():
+                task.cancel()
+
+    def create_task(self, *, target: CoroutineAny | AsyncTaskFactoryAny, name: str) -> None:
+        """
+        Schedule a coroutine to run in the loop.
+
+        Accepts either an already-created coroutine object or a zero-argument
+        callable that returns a coroutine. The callable form defers coroutine
+        creation until inside the event loop, which avoids "was never awaited"
+        warnings if callers only inspect the parameters (e.g. in tests).
+        """
+        try:
+            self._loop.call_soon_threadsafe(self._async_create_task, target, name)
+        except CancelledError:
+            # Scheduling failed; if a coroutine object was provided, close it to
+            # avoid 'was never awaited' warnings.
+            if asyncio.iscoroutine(target):
+                with contextlib.suppress(Exception):
+                    getattr(target, "close", lambda: None)()
+            _LOGGER.debug("create_task: task cancelled for %s", name)
+            return
+
+    def run_coroutine(self, *, coro: CoroutineAny, name: str) -> Any:
+        """Call coroutine from sync."""
+        try:
+            return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+        except CancelledError:  # pragma: no cover
+            _LOGGER.debug(
+                "run_coroutine: coroutine interrupted for %s",
+                name,
+            )
+            return None
+
+    def _async_create_task(  # kwonly: disable
+        self, target: CoroutineAny | AsyncTaskFactoryAny, name: str
+    ) -> asyncio.Task[Any]:
+        """Create a task from within the event loop. Must be run in the event loop."""
+        # If target is a callable, call it here to create the coroutine inside the loop
+        coro: CoroutineAny = target if asyncio.iscoroutine(target) else target()
+        task = self._loop.create_task(coro, name=name)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.remove)
+        return task
+
+    async def _await_and_log_pending(
+        self, *, pending: Collection[asyncio.Future[Any]], deadline: float | None
+    ) -> set[asyncio.Future[Any]]:
+        """
+        Await and log tasks that take a long time, respecting an optional deadline.
+
+        Returns the set of pending tasks if the deadline has been reached (or zero timeout),
+        allowing the caller to decide about timeout logging. Returns an empty set if no tasks are pending.
+        """
+        wait_time = 0.0
+        pending_set: set[asyncio.Future[Any]] = set(pending)
+        while pending_set:
+            if deadline is None:
+                timeout = BLOCK_LOG_TIMEOUT
+            else:
+                remaining = int(max(0.0, deadline - monotonic()))
+                if (timeout := min(BLOCK_LOG_TIMEOUT, remaining)) == 0.0:
+                    # Deadline reached; return current pending to caller for warning log
+                    return pending_set
+            done, still_pending = await asyncio.wait(pending_set, timeout=timeout)
+            if not (pending_set := set(still_pending)):
+                return set()
+            wait_time += timeout
+            for task in pending_set:
+                _LOGGER.debug("Waited %s seconds for task: %s", wait_time, task)
+            # If the deadline was reached during the wait, let caller handle warning
+            if deadline is not None and monotonic() >= deadline:
+                return pending_set
+        return set()
+
+
+def cancelling(*, task: asyncio.Future[Any]) -> bool:
+    """Return True if task is cancelling."""
+    return bool((cancelling_ := getattr(task, "cancelling", None)) and cancelling_())
+
+
+def loop_check[**P, R](func: Callable[P, R]) -> Callable[P, R]:
+    """
+    Annotation to mark method that must be run within the event loop.
+
+    Always wraps the function, but only performs loop checks when debug is enabled.
+    This allows tests to monkeypatch aiohomematic.support.debug_enabled at runtime.
+    """
+    _with_loop: set[CallableAny] = set()
+
+    @wraps(func)
+    def wrapper_loop_check(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap loop check."""
+        return_value = func(*args, **kwargs)
+
+        # Only perform the (potentially expensive) loop check when debug is enabled.
+        if hms.debug_enabled():
+            try:
+                asyncio.get_running_loop()
+                loop_running = True
+            except Exception:
+                loop_running = False
+
+            if not loop_running and func not in _with_loop:
+                _with_loop.add(func)
+                _LOGGER.error(  # i18n-log: ignore
+                    "Method %s must run in the event_loop. No loop detected.",
+                    func.__name__,
+                )
+
+        return return_value
+
+    setattr(func, "_loop_check", True)
+    return cast(Callable[P, R], wrapper_loop_check)