aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/client/handlers/firmware.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Firmware handler.
+
+Handles device and system firmware update operations.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Final
+
+from aiohomematic import i18n
+from aiohomematic.client.handlers.base import BaseHandler
+from aiohomematic.const import ProductGroup
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import BaseHomematicException, ClientException
+from aiohomematic.interfaces import FirmwareOperationsProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+from aiohomematic.support import extract_exc_args
+
+if TYPE_CHECKING:
+    from aiohomematic.client import AioJsonRpcAioHttpClient, BaseRpcProxy
+    from aiohomematic.const import Interface
+    from aiohomematic.interfaces import ClientDependenciesProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class FirmwareHandler(BaseHandler, FirmwareOperationsProtocol):
+    """
+    Handler for firmware update operations.
+
+    Implements FirmwareOperationsProtocol protocol for ISP-compliant client operations.
+
+    Handles:
+    - Updating device firmware
+    - Triggering system firmware updates
+    """
+
+    __slots__ = (
+        "_has_device_firmware_update",
+        "_has_firmware_update_trigger",
+    )
+
+    def __init__(
+        self,
+        *,
+        client_deps: ClientDependenciesProtocol,
+        interface: Interface,
+        interface_id: str,
+        json_rpc_client: AioJsonRpcAioHttpClient,
+        proxy: BaseRpcProxy,
+        proxy_read: BaseRpcProxy,
+        has_device_firmware_update: bool,
+        has_firmware_update_trigger: bool,
+    ) -> None:
+        """Initialize the firmware handler."""
+        super().__init__(
+            client_deps=client_deps,
+            interface=interface,
+            interface_id=interface_id,
+            json_rpc_client=json_rpc_client,
+            proxy=proxy,
+            proxy_read=proxy_read,
+        )
+        self._has_device_firmware_update: Final = has_device_firmware_update
+        self._has_firmware_update_trigger: Final = has_firmware_update_trigger
+
+    has_device_firmware_update: Final = DelegatedProperty[bool](path="_has_device_firmware_update")
+    has_firmware_update_trigger: Final = DelegatedProperty[bool](path="_has_firmware_update_trigger")
+
+    @inspector(re_raise=False)
+    async def trigger_firmware_update(self) -> bool:
+        """
+        Trigger the CCU system firmware update process.
+
+        Initiates the CCU's own firmware update (not device firmware). The CCU
+        will download and install available system updates.
+
+        Returns:
+            True if the update was triggered successfully, False if unsupported.
+
+        """
+        if not self._has_firmware_update_trigger:
+            _LOGGER.debug("TRIGGER_FIRMWARE_UPDATE: Not supported by client for %s", self._interface_id)
+            return False
+
+        return await self._json_rpc_client.trigger_firmware_update()
+
+    @inspector
+    async def update_device_firmware(self, *, device_address: str) -> bool:
+        """
+        Update firmware on a single Homematic device.
+
+        Uses installFirmware() for HmIP/HmIPW devices and updateFirmware() for
+        BidCos devices. The device must have a firmware update available.
+
+        Args:
+            device_address: Device address (e.g., "VCU0000001").
+
+        Returns:
+            True if the update was initiated successfully, False if device not
+            found or update unsupported.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_device_firmware_update:
+            _LOGGER.debug("UPDATE_DEVICE_FIRMWARE: Not supported by client for %s", self._interface_id)
+            return False
+
+        if device := self._client_deps.device_coordinator.get_device(address=device_address):
+            _LOGGER.info(
+                i18n.tr(
+                    key="log.client.update_device_firmware.try",
+                    device_address=device_address,
+                )
+            )
+            try:
+                update_result = (
+                    await self._proxy.installFirmware(device_address)
+                    if device.product_group in (ProductGroup.HMIPW, ProductGroup.HMIP)
+                    else await self._proxy.updateFirmware(device_address)
+                )
+                result = bool(update_result) if isinstance(update_result, bool) else bool(update_result[0])
+                _LOGGER.info(
+                    i18n.tr(
+                        key="log.client.update_device_firmware.result",
+                        device_address=device_address,
+                        result=("success" if result else "failed"),
+                    )
+                )
+            except BaseHomematicException as bhexc:
+                raise ClientException(
+                    i18n.tr(
+                        key="exception.client.update_device_firmware.failed",
+                        reason=extract_exc_args(exc=bhexc),
+                    )
+                ) from bhexc
+            return result
+        return False

aiohomematic/client/handlers/link_mgmt.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Link management handler.
+
+Handles device linking operations.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Final, cast
+
+from aiohomematic import i18n
+from aiohomematic.client.handlers.base import BaseHandler
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import BaseHomematicException, ClientException
+from aiohomematic.interfaces import LinkOperationsProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+from aiohomematic.support import extract_exc_args
+
+if TYPE_CHECKING:
+    from aiohomematic.client import AioJsonRpcAioHttpClient, BaseRpcProxy
+    from aiohomematic.const import Interface
+    from aiohomematic.interfaces import ClientDependenciesProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class LinkHandler(BaseHandler, LinkOperationsProtocol):
+    """
+    Handler for device linking operations.
+
+    Implements LinkOperationsProtocol protocol for ISP-compliant client operations.
+
+    Handles:
+    - Adding links between devices
+    - Removing links between devices
+    - Querying link information and peers
+    """
+
+    __slots__ = ("_has_linking",)
+
+    def __init__(
+        self,
+        *,
+        client_deps: ClientDependenciesProtocol,
+        interface: Interface,
+        interface_id: str,
+        json_rpc_client: AioJsonRpcAioHttpClient,
+        proxy: BaseRpcProxy,
+        proxy_read: BaseRpcProxy,
+        has_linking: bool,
+    ) -> None:
+        """Initialize the link management handler."""
+        super().__init__(
+            client_deps=client_deps,
+            interface=interface,
+            interface_id=interface_id,
+            json_rpc_client=json_rpc_client,
+            proxy=proxy,
+            proxy_read=proxy_read,
+        )
+        self._has_linking: Final = has_linking
+
+    has_linking: Final = DelegatedProperty[bool](path="_has_linking")
+
+    @inspector
+    async def add_link(
+        self,
+        *,
+        sender_address: str,
+        receiver_address: str,
+        name: str,
+        description: str,
+    ) -> None:
+        """
+        Create a direct link between two device channels.
+
+        Direct links allow devices to communicate without the CCU. The sender
+        triggers actions on the receiver (e.g., a button press turning on a light).
+
+        Args:
+            sender_address: Source channel address (e.g., "VCU0000001:1").
+            receiver_address: Target channel address (e.g., "VCU0000002:1").
+            name: User-defined link name.
+            description: User-defined link description.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_linking:
+            _LOGGER.debug("ADD_LINK: Not supported by client for %s", self._interface_id)
+            return
+
+        try:
+            await self._proxy.addLink(sender_address, receiver_address, name, description)
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.add_link.failed",
+                    sender=sender_address,
+                    receiver=receiver_address,
+                    name=name,
+                    description=description,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc
+
+    @inspector
+    async def get_link_peers(self, *, address: str) -> tuple[str, ...]:
+        """
+        Return addresses of all channels linked to the given address.
+
+        Args:
+            address: Channel address to query (e.g., "VCU0000001:1").
+
+        Returns:
+            Tuple of peer channel addresses that are linked to this channel.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_linking:
+            _LOGGER.debug("GET_LINK_PEERS: Not supported by client for %s", self._interface_id)
+            return ()
+
+        try:
+            return tuple(links) if (links := await self._proxy.getLinkPeers(address)) else ()
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.get_link_peers.failed",
+                    address=address,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc
+
+    @inspector
+    async def get_links(self, *, address: str, flags: int) -> dict[str, Any]:
+        """
+        Return detailed link information for a channel.
+
+        Args:
+            address: Channel address to query (e.g., "VCU0000001:1").
+            flags: Bitmask controlling returned information (backend-specific).
+
+        Returns:
+            Dict containing link details including sender, receiver, and paramsets.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_linking:
+            _LOGGER.debug("GET_LINKS: Not supported by client for %s", self._interface_id)
+            return {}
+
+        try:
+            return cast(dict[str, Any], await self._proxy.getLinks(address, flags))
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.get_links.failed",
+                    address=address,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc
+
+    @inspector
+    async def remove_link(self, *, sender_address: str, receiver_address: str) -> None:
+        """
+        Remove a direct link between two device channels.
+
+        Args:
+            sender_address: Source channel address (e.g., "VCU0000001:1").
+            receiver_address: Target channel address (e.g., "VCU0000002:1").
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_linking:
+            _LOGGER.debug("REMOVE_LINK: Not supported by client for %s", self._interface_id)
+            return
+
+        try:
+            await self._proxy.removeLink(sender_address, receiver_address)
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.remove_link.failed",
+                    sender=sender_address,
+                    receiver=receiver_address,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc