aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/__init__.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+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 data point 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 data point 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 = await config.create_central()
+    await central.start()
+
+    # Access devices and data points
+    device = central.device_coordinator.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]  # kwonly: disable
+    """Handle signal to shut down central."""
+    _LOGGER.info(i18n.tr(key="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(key="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/_log_context_protocol.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Log context protocol interface.
+
+This module is intentionally minimal to avoid circular imports.
+It's imported by property_decorators.py which is near the bottom of the import chain.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LogContextProtocol(Protocol):
+    """
+    Protocol for objects providing log context.
+
+    Implemented by LogContextMixin and used by property_decorators.py
+    to avoid circular imports.
+    """
+
+    @property
+    @abstractmethod
+    def log_context(self) -> Mapping[str, Any]:
+        """Return the log context for this object."""

aiohomematic/api.py

@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Simplified facade API for common Homematic operations.
+
+This module provides `HomematicAPI`, a high-level facade that wraps the most
+commonly used operations from `CentralUnit`. It offers a streamlined interface
+for typical use cases without requiring deep knowledge of the internal architecture.
+
+Quick start
+-----------
+Using the async context manager (recommended)::
+
+    from aiohomematic.api import HomematicAPI
+
+    async with HomematicAPI.connect(
+        host="192.168.1.100",
+        username="Admin",
+        password="secret",
+    ) as api:
+        # List all devices
+        for device in api.list_devices():
+            print(f"{device.address}: {device.name}")
+
+        # Read and write values
+        value = await api.read_value(channel_address="VCU0000001:1", parameter="STATE")
+        await api.write_value(channel_address="VCU0000001:1", parameter="STATE", value=True)
+
+    # Connection is automatically closed when exiting the context
+
+Manual lifecycle management::
+
+    from aiohomematic.api import HomematicAPI
+    from aiohomematic.central import CentralConfig
+
+    config = CentralConfig.for_ccu(
+        host="192.168.1.100",
+        username="Admin",
+        password="secret",
+    )
+    api = HomematicAPI(config=config)
+    await api.start()
+
+    try:
+        for device in api.list_devices():
+            print(f"{device.address}: {device.name}")
+    finally:
+        await api.stop()
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from types import TracebackType
+from typing import Any, Final, Self
+
+from aiohomematic.central import CentralConfig, CentralUnit
+from aiohomematic.central.events import DataPointValueReceivedEvent
+from aiohomematic.const import ParamsetKey
+from aiohomematic.interfaces import DeviceProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+from aiohomematic.support import get_device_address
+from aiohomematic.type_aliases import UnsubscribeCallback
+
+# Type alias for update callback
+UpdateCallback = Callable[[str, str, Any], None]
+
+
+class HomematicAPI:
+    """
+    Simplified facade for common Homematic operations.
+
+    This class provides a high-level interface for interacting with Homematic
+    devices without requiring deep knowledge of the internal architecture.
+    It wraps the most commonly used operations from CentralUnit.
+
+    Attributes:
+        central: The underlying CentralUnit instance.
+        config: The configuration used to create this API instance.
+
+    """
+
+    def __init__(self, *, config: CentralConfig) -> None:
+        """
+        Initialize the HomematicAPI.
+
+        Args:
+            config: Configuration for the central unit. Use CentralConfig.for_ccu()
+                or CentralConfig.for_homegear() for simplified setup.
+
+        """
+        self._config: Final = config
+        self._central: CentralUnit | None = None
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager and start the API."""
+        await self.start()
+        return self
+
+    async def __aexit__(  # kwonly: disable
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the async context manager and stop the API."""
+        await self.stop()
+
+    @classmethod
+    def connect(
+        cls,
+        *,
+        host: str,
+        username: str,
+        password: str,
+        central_id: str | None = None,
+        tls: bool = False,
+        verify_tls: bool = True,
+        backend: str = "ccu",
+    ) -> Self:
+        """
+        Create a HomematicAPI instance for use as an async context manager.
+
+        This is the recommended way to use the API, as it ensures proper
+        cleanup even when exceptions occur.
+
+        Args:
+            host: The hostname or IP address of the Homematic backend.
+            username: The username for authentication.
+            password: The password for authentication.
+            central_id: Optional unique identifier for this central (defaults to host).
+            tls: Whether to use TLS encryption (default: False).
+            verify_tls: Whether to verify TLS certificates (default: True).
+            backend: The backend type, either "ccu" or "homegear" (default: "ccu").
+
+        Returns:
+            A HomematicAPI instance that can be used as an async context manager.
+
+        Example:
+            async with HomematicAPI.connect(
+                host="192.168.1.100",
+                username="Admin",
+                password="secret",
+            ) as api:
+                for device in api.list_devices():
+                    print(device.address)
+
+            # Connection is automatically closed
+
+        Raises:
+            ValueError: If backend is not "ccu" or "homegear".
+
+        """
+        if backend == "ccu":
+            config = CentralConfig.for_ccu(
+                name=central_id or host,
+                host=host,
+                username=username,
+                password=password,
+                central_id=central_id or host,
+                tls=tls,
+                verify_tls=verify_tls,
+            )
+        elif backend == "homegear":
+            config = CentralConfig.for_homegear(
+                name=central_id or host,
+                host=host,
+                username=username,
+                password=password,
+                central_id=central_id or host,
+                tls=tls,
+                verify_tls=verify_tls,
+            )
+        else:
+            msg = f"Unknown backend: {backend}. Use 'ccu' or 'homegear'."
+            raise ValueError(msg)
+
+        return cls(config=config)
+
+    @staticmethod
+    async def _do_fetch_all_device_data(*, client: Any) -> None:
+        """Fetch all device data for a single client."""
+        await client.fetch_all_device_data()
+
+    @staticmethod
+    async def _do_get_value(
+        *,
+        client: Any,
+        channel_address: str,
+        paramset_key: ParamsetKey,
+        parameter: str,
+    ) -> Any:
+        """Get a value from a client."""
+        return await client.get_value(
+            channel_address=channel_address,
+            paramset_key=paramset_key,
+            parameter=parameter,
+        )
+
+    @staticmethod
+    async def _do_set_value(
+        *,
+        client: Any,
+        channel_address: str,
+        paramset_key: ParamsetKey,
+        parameter: str,
+        value: Any,
+    ) -> None:
+        """Set a value on a client."""
+        await client.set_value(
+            channel_address=channel_address,
+            paramset_key=paramset_key,
+            parameter=parameter,
+            value=value,
+        )
+
+    config: Final = DelegatedProperty[CentralConfig](path="_config")
+
+    @property
+    def central(self) -> CentralUnit:
+        """Return the underlying CentralUnit instance."""
+        if self._central is None:
+            msg = "API not started. Call start() first."
+            raise RuntimeError(msg)
+        return self._central
+
+    @property
+    def is_connected(self) -> bool:
+        """Return True if connected to the backend."""
+        return (
+            self._central is not None
+            and self._central.client_coordinator.has_clients
+            and not self._central.connection_state.has_any_issue
+        )
+
+    def get_device(self, *, address: str) -> DeviceProtocol | None:
+        """
+        Get a device by its address.
+
+        Args:
+            address: The device address (e.g., "VCU0000001").
+
+        Returns:
+            The Device object, or None if not found.
+
+        Example:
+            device = api.get_device(address="VCU0000001")
+            if device:
+                print(f"Found: {device.name}")
+
+        """
+        return self.central.device_coordinator.get_device(address=address)
+
+    def list_devices(self) -> Iterable[DeviceProtocol]:
+        """
+        List all known devices.
+
+        Returns:
+            Iterable of Device objects.
+
+        Example:
+            for device in api.list_devices():
+                print(f"{device.address}: {device.name} ({device.model})")
+
+        """
+        return self.central.device_registry.devices
+
+    async def read_value(
+        self,
+        *,
+        channel_address: str,
+        parameter: str,
+        paramset_key: ParamsetKey = ParamsetKey.VALUES,
+    ) -> Any:
+        """
+        Read a parameter value from a device channel.
+
+        This method automatically retries on transient network errors.
+
+        Args:
+            channel_address: The channel address (e.g., "VCU0000001:1").
+            parameter: The parameter name (e.g., "STATE", "LEVEL").
+            paramset_key: The paramset key (default: VALUES).
+
+        Returns:
+            The current parameter value.
+
+        Example:
+            # Read switch state
+            state = await api.read_value(channel_address="VCU0000001:1", parameter="STATE")
+
+            # Read dimmer level
+            level = await api.read_value(channel_address="VCU0000002:1", parameter="LEVEL")
+
+        """
+        device_address = get_device_address(address=channel_address)
+        if (device := self.central.device_coordinator.get_device(address=device_address)) is None:
+            msg = f"Device not found for address: {device_address}"
+            raise ValueError(msg)
+        client = self.central.client_coordinator.get_client(interface_id=device.interface_id)
+        return await self._do_get_value(
+            client=client,
+            channel_address=channel_address,
+            paramset_key=paramset_key,
+            parameter=parameter,
+        )
+
+    async def refresh_data(self) -> None:
+        """
+        Refresh data from all devices.
+
+        This fetches the latest values from all connected devices.
+        Each client fetch automatically retries on transient network errors.
+        """
+        for client in self.central.client_coordinator.clients:
+            await self._do_fetch_all_device_data(client=client)
+
+    async def start(self) -> None:
+        """
+        Start the API and connect to the Homematic backend.
+
+        This creates the central unit, initializes clients, and starts
+        the background scheduler for connection health checks.
+        """
+        self._central = await self._config.create_central()
+        await self._central.start()
+
+    async def stop(self) -> None:
+        """
+        Stop the API and disconnect from the backend.
+
+        This stops all clients, the XML-RPC server, and the background scheduler.
+        """
+        if self._central is not None:
+            await self._central.stop()
+            self._central = None
+
+    def subscribe_to_updates(self, *, callback: UpdateCallback) -> UnsubscribeCallback:
+        """
+        Subscribe to data point value updates.
+
+        The callback is invoked whenever a data point value changes.
+
+        Args:
+            callback: Function called with (channel_address, parameter, value)
+                when a data point is updated.
+
+        Returns:
+            An unsubscribe function to remove the callback.
+
+        Example:
+            def on_update(address: str, parameter: str, value: Any) -> None:
+                print(f"{address}.{parameter} = {value}")
+
+            unsubscribe = api.subscribe_to_updates(callback=on_update)
+
+            # Later, to stop receiving updates:
+            unsubscribe()
+
+        """
+
+        async def event_handler(*, event: DataPointValueReceivedEvent) -> None:
+            callback(event.dpk.channel_address, event.dpk.parameter, event.value)
+
+        return self.central.event_bus.subscribe(
+            event_type=DataPointValueReceivedEvent,
+            event_key=None,
+            handler=event_handler,
+        )
+
+    async def write_value(
+        self,
+        *,
+        channel_address: str,
+        parameter: str,
+        value: Any,
+        paramset_key: ParamsetKey = ParamsetKey.VALUES,
+    ) -> None:
+        """
+        Write a parameter value to a device channel.
+
+        This method automatically retries on transient network errors.
+
+        Args:
+            channel_address: The channel address (e.g., "VCU0000001:1").
+            parameter: The parameter name (e.g., "STATE", "LEVEL").
+            value: The value to write.
+            paramset_key: The paramset key (default: VALUES).
+
+        Example:
+            # Turn on a switch
+            await api.write_value(channel_address="VCU0000001:1", parameter="STATE", value=True)
+
+            # Set dimmer to 50%
+            await api.write_value(channel_address="VCU0000002:1", parameter="LEVEL", value=0.5)
+
+        """
+        device_address = get_device_address(address=channel_address)
+        if (device := self.central.device_coordinator.get_device(address=device_address)) is None:
+            msg = f"Device not found for address: {device_address}"
+            raise ValueError(msg)
+        client = self.central.client_coordinator.get_client(interface_id=device.interface_id)
+        await self._do_set_value(
+            client=client,
+            channel_address=channel_address,
+            paramset_key=paramset_key,
+            parameter=parameter,
+            value=value,
+        )