aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/client/handlers/metadata.py

@@ -0,0 +1,436 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Metadata handler.
+
+Handles metadata, renaming, rooms, functions, install mode, inbox devices,
+and service messages 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.const import InboxDeviceData, Interface, ServiceMessageData, ServiceMessageType, SystemUpdateData
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import BaseHomematicException, ClientException
+from aiohomematic.interfaces import MetadataOperationsProtocol
+from aiohomematic.support import extract_exc_args
+
+if TYPE_CHECKING:
+    from aiohomematic.client import AioJsonRpcAioHttpClient, BaseRpcProxy
+    from aiohomematic.interfaces import ClientDependenciesProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class MetadataHandler(BaseHandler, MetadataOperationsProtocol):
+    """
+    Handler for metadata and system information operations.
+
+    Implements MetadataOperationsProtocol protocol for ISP-compliant client operations.
+
+    Handles:
+    - Metadata read/write operations
+    - Device and channel renaming
+    - Room and function queries
+    - Install mode operations
+    - Inbox device management
+    - Service message queries
+    - System update information
+    - ReGa ID lookups
+    """
+
+    __slots__ = (
+        "_has_functions",
+        "_has_inbox_devices",
+        "_has_install_mode",
+        "_has_metadata",
+        "_has_rega_id_lookup",
+        "_has_rename",
+        "_has_rooms",
+        "_has_service_messages",
+        "_has_system_update_info",
+    )
+
+    def __init__(
+        self,
+        *,
+        client_deps: ClientDependenciesProtocol,
+        interface: Interface,
+        interface_id: str,
+        json_rpc_client: AioJsonRpcAioHttpClient,
+        proxy: BaseRpcProxy,
+        proxy_read: BaseRpcProxy,
+        has_functions: bool,
+        has_inbox_devices: bool,
+        has_install_mode: bool,
+        has_metadata: bool,
+        has_rega_id_lookup: bool,
+        has_rename: bool,
+        has_rooms: bool,
+        has_service_messages: bool,
+        has_system_update_info: bool,
+    ) -> None:
+        """Initialize the metadata 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_functions: Final = has_functions
+        self._has_inbox_devices: Final = has_inbox_devices
+        self._has_install_mode: Final = has_install_mode
+        self._has_metadata: Final = has_metadata
+        self._has_rega_id_lookup: Final = has_rega_id_lookup
+        self._has_rename: Final = has_rename
+        self._has_rooms: Final = has_rooms
+        self._has_service_messages: Final = has_service_messages
+        self._has_system_update_info: Final = has_system_update_info
+
+    @inspector(re_raise=False)
+    async def accept_device_in_inbox(self, *, device_address: str) -> bool:
+        """
+        Accept a device from the CCU inbox, completing its pairing process.
+
+        The inbox contains newly paired devices waiting for user confirmation.
+        Accepting moves the device to the active device list.
+
+        Args:
+            device_address: SGTIN or address of the inbox device.
+
+        Returns:
+            True if accepted successfully, False if not supported or failed.
+
+        """
+        if not self._has_inbox_devices:
+            _LOGGER.debug("ACCEPT_DEVICE_IN_INBOX: Not supported by client for %s", self._interface_id)
+            return False
+
+        return await self._json_rpc_client.accept_device_in_inbox(device_address=device_address)
+
+    @inspector(re_raise=False, no_raise_return={})
+    async def get_all_functions(self) -> dict[str, set[str]]:
+        """
+        Return function assignments for all channels.
+
+        Functions are user-defined groupings in the CCU (e.g., "Lighting", "Heating").
+        Maps each channel's ReGa ID to its assigned functions.
+
+        Returns:
+            Dict mapping channel address to set of function names.
+
+        """
+        if not self._has_functions:
+            _LOGGER.debug("GET_ALL_FUNCTIONS: Not supported by client for %s", self._interface_id)
+            return {}
+
+        functions: dict[str, set[str]] = {}
+        rega_ids_function = await self._json_rpc_client.get_all_channel_rega_ids_function()
+        for address, rega_id in self._client_deps.cache_coordinator.device_details.device_channel_rega_ids.items():
+            if sections := rega_ids_function.get(rega_id):
+                if address not in functions:
+                    functions[address] = set()
+                functions[address].update(sections)
+        return functions
+
+    @inspector(re_raise=False, no_raise_return={})
+    async def get_all_rooms(self) -> dict[str, set[str]]:
+        """
+        Return room assignments for all channels.
+
+        Rooms are user-defined location groupings in the CCU. Maps each
+        channel's ReGa ID to its assigned rooms.
+
+        Returns:
+            Dict mapping channel address to set of room names.
+
+        """
+        if not self._has_rooms:
+            _LOGGER.debug("GET_ALL_ROOMS: Not supported by client for %s", self._interface_id)
+            return {}
+
+        rooms: dict[str, set[str]] = {}
+        rega_ids_room = await self._json_rpc_client.get_all_channel_rega_ids_room()
+        for address, rega_id in self._client_deps.cache_coordinator.device_details.device_channel_rega_ids.items():
+            if names := rega_ids_room.get(rega_id):
+                if address not in rooms:
+                    rooms[address] = set()
+                rooms[address].update(names)
+        return rooms
+
+    @inspector(re_raise=False, no_raise_return=())
+    async def get_inbox_devices(self) -> tuple[InboxDeviceData, ...]:
+        """
+        Return devices awaiting user acceptance in the CCU inbox.
+
+        After pairing, HmIP devices appear in the inbox until explicitly
+        accepted. Each entry contains device type, address, and SGTIN.
+
+        Returns:
+            Tuple of InboxDeviceData dicts for pending devices.
+
+        """
+        if not self._has_inbox_devices:
+            _LOGGER.debug("GET_INBOX_DEVICES: Not supported by client for %s", self._interface_id)
+            return ()
+
+        return await self._json_rpc_client.get_inbox_devices()
+
+    @inspector
+    async def get_install_mode(self) -> int:
+        """
+        Return remaining seconds in pairing/install mode.
+
+        Install mode allows new devices to be paired with the CCU. Uses JSON-RPC
+        for HmIP-RF interface and XML-RPC for BidCos interfaces.
+
+        Returns:
+            Remaining seconds, or 0 if install mode is off or unsupported.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_install_mode:
+            _LOGGER.debug("GET_INSTALL_MODE: Not supported by client for %s", self._interface_id)
+            return 0
+
+        try:
+            # HmIP-RF uses JSON-RPC, BidCos-RF uses XML-RPC
+            if self._interface == Interface.HMIP_RF:
+                return await self._json_rpc_client.get_install_mode(interface=self._interface)
+
+            if (remaining_time := await self._proxy.getInstallMode()) is not None:
+                return int(remaining_time)
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.get_install_mode.failed",
+                    interface_id=self._interface_id,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc
+        return 0
+
+    @inspector
+    async def get_metadata(self, *, address: str, data_id: str) -> dict[str, Any]:
+        """
+        Return backend metadata for a device or channel.
+
+        Metadata is key-value storage attached to Homematic objects, used by
+        some backends for configuration data.
+
+        Args:
+            address: Device or channel address.
+            data_id: Metadata key identifier.
+
+        Returns:
+            Metadata value dict, or empty dict if unsupported.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_metadata:
+            _LOGGER.debug("GET_METADATA: Not supported by client for %s", self._interface_id)
+            return {}
+
+        try:
+            return cast(dict[str, Any], await self._proxy.getMetadata(address, data_id))
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.get_metadata.failed",
+                    address=address,
+                    data_id=data_id,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc
+
+    @inspector(re_raise=False)
+    async def get_rega_id_by_address(self, *, address: str) -> int | None:
+        """
+        Return the ReGaHSS internal ID for an address.
+
+        ReGa IDs are used by the CCU's scripting engine (ReGaHSS) to identify
+        devices and channels. Required for rename operations and room/function
+        lookups.
+
+        Args:
+            address: Device or channel address.
+
+        Returns:
+            ReGa ID integer, or None if not found or unsupported.
+
+        """
+        if not self._has_rega_id_lookup:
+            _LOGGER.debug("GET_REGA_ID_BY_ADDRESS: Not supported by client for %s", self._interface_id)
+            return None
+
+        return await self._json_rpc_client.get_rega_id_by_address(address=address)
+
+    @inspector(re_raise=False, no_raise_return=())
+    async def get_service_messages(
+        self,
+        *,
+        message_type: ServiceMessageType | None = None,
+    ) -> tuple[ServiceMessageData, ...]:
+        """
+        Get all active service messages from the backend.
+
+        Args:
+            message_type: Filter by message type. If None, return all messages.
+
+        """
+        if not self._has_service_messages:
+            _LOGGER.debug("GET_SERVICE_MESSAGES: Not supported by client for %s", self._interface_id)
+            return ()
+
+        return await self._json_rpc_client.get_service_messages(message_type=message_type)
+
+    @inspector(re_raise=False)
+    async def get_system_update_info(self) -> SystemUpdateData | None:
+        """
+        Return CCU firmware update availability status.
+
+        Checks if a newer CCU firmware version is available for download.
+
+        Returns:
+            SystemUpdateData with version info, or None if unsupported/unavailable.
+
+        """
+        if not self._has_system_update_info:
+            _LOGGER.debug("GET_SYSTEM_UPDATE_INFO: Not supported by client for %s", self._interface_id)
+            return None
+
+        return await self._json_rpc_client.get_system_update_info()
+
+    @inspector(re_raise=False)
+    async def rename_channel(self, *, rega_id: int, new_name: str) -> bool:
+        """
+        Rename a channel in the CCU's ReGaHSS database.
+
+        Args:
+            rega_id: ReGaHSS internal ID of the channel.
+            new_name: New display name for the channel.
+
+        Returns:
+            True if renamed successfully, False if unsupported or failed.
+
+        """
+        if not self._has_rename:
+            _LOGGER.debug("RENAME_CHANNEL: Not supported by client for %s", self._interface_id)
+            return False
+
+        return await self._json_rpc_client.rename_channel(rega_id=rega_id, new_name=new_name)
+
+    @inspector(re_raise=False)
+    async def rename_device(self, *, rega_id: int, new_name: str) -> bool:
+        """
+        Rename a device in the CCU's ReGaHSS database.
+
+        Args:
+            rega_id: ReGaHSS internal ID of the device.
+            new_name: New display name for the device.
+
+        Returns:
+            True if renamed successfully, False if unsupported or failed.
+
+        """
+        if not self._has_rename:
+            _LOGGER.debug("RENAME_DEVICE: Not supported by client for %s", self._interface_id)
+            return False
+
+        return await self._json_rpc_client.rename_device(rega_id=rega_id, new_name=new_name)
+
+    @inspector
+    async def set_install_mode(
+        self,
+        *,
+        on: bool = True,
+        time: int = 60,
+        mode: int = 1,
+        device_address: str | None = None,
+    ) -> bool:
+        """
+        Set the install mode on the backend.
+
+        Args:
+            on: Enable or disable install mode.
+            time: Duration in seconds (default 60).
+            mode: Mode 1=normal, 2=set all ROAMING devices into install mode.
+            device_address: Optional device address/SGTIN to limit pairing.
+
+        Returns:
+            True if successful.
+
+        """
+        if not self._has_install_mode:
+            _LOGGER.debug("SET_INSTALL_MODE: Not supported by client for %s", self._interface_id)
+            return False
+
+        try:
+            # HmIP-RF uses JSON-RPC setInstallModeHmIP, BidCos-RF uses XML-RPC
+            if self._interface == Interface.HMIP_RF:
+                return await self._json_rpc_client.set_install_mode_hmip(
+                    interface=self._interface,
+                    on=on,
+                    time=time,
+                    device_address=device_address,
+                )
+
+            if device_address:
+                await self._proxy.setInstallMode(on, time, device_address)
+            else:
+                await self._proxy.setInstallMode(on, time, mode)
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.set_install_mode.failed",
+                    interface_id=self._interface_id,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc
+        else:
+            return True
+
+    @inspector
+    async def set_metadata(self, *, address: str, data_id: str, value: dict[str, Any]) -> dict[str, Any]:
+        """
+        Write metadata for a device or channel.
+
+        Args:
+            address: Device or channel address.
+            data_id: Metadata key identifier.
+            value: Metadata value dict to store.
+
+        Returns:
+            Result dict from the backend, or empty dict if unsupported.
+
+        Raises:
+            ClientException: If the RPC call fails.
+
+        """
+        if not self._has_metadata:
+            _LOGGER.debug("SET_METADATA: Not supported by client for %s", self._interface_id)
+            return {}
+
+        try:
+            return cast(dict[str, Any], await self._proxy.setMetadata(address, data_id, value))
+        except BaseHomematicException as bhexc:
+            raise ClientException(
+                i18n.tr(
+                    key="exception.client.set_metadata.failed",
+                    address=address,
+                    data_id=data_id,
+                    value=value,
+                    reason=extract_exc_args(exc=bhexc),
+                )
+            ) from bhexc

aiohomematic/client/handlers/programs.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Program handler.
+
+Handles program execution and state management.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Final
+
+from aiohomematic.client.handlers.base import BaseHandler
+from aiohomematic.const import DescriptionMarker, ProgramData
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces import ProgramOperationsProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+
+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 ProgramHandler(BaseHandler, ProgramOperationsProtocol):
+    """
+    Handler for program operations.
+
+    Implements ProgramOperationsProtocol protocol for ISP-compliant client operations.
+
+    Handles:
+    - Getting all programs
+    - Executing programs
+    - Setting program state
+    - Checking program IDs
+    """
+
+    __slots__ = ("_has_programs",)
+
+    def __init__(
+        self,
+        *,
+        client_deps: ClientDependenciesProtocol,
+        interface: Interface,
+        interface_id: str,
+        json_rpc_client: AioJsonRpcAioHttpClient,
+        proxy: BaseRpcProxy,
+        proxy_read: BaseRpcProxy,
+        has_programs: bool,
+    ) -> None:
+        """Initialize the program 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_programs: Final = has_programs
+
+    has_programs: Final = DelegatedProperty[bool](path="_has_programs")
+
+    @inspector
+    async def execute_program(self, *, pid: str) -> bool:
+        """
+        Trigger execution of a CCU program.
+
+        CCU programs are user-defined scripts created in the CCU's web interface.
+        This method triggers immediate execution of the program.
+
+        Args:
+            pid: Program ID (ReGa internal identifier).
+
+        Returns:
+            True if execution was triggered, False if unsupported.
+
+        """
+        if not self._has_programs:
+            _LOGGER.debug("EXECUTE_PROGRAM: Not supported by client for %s", self._interface_id)
+            return False
+
+        return await self._json_rpc_client.execute_program(pid=pid)
+
+    @inspector(re_raise=False)
+    async def get_all_programs(
+        self,
+        *,
+        markers: tuple[DescriptionMarker | str, ...],
+    ) -> tuple[ProgramData, ...]:
+        """
+        Return all CCU programs matching the given markers.
+
+        Programs can be filtered by markers in their description field. Only
+        programs containing at least one of the specified markers are returned.
+
+        Args:
+            markers: Tuple of DescriptionMarker values or strings to filter by.
+
+        Returns:
+            Tuple of ProgramData dicts containing id, name, description, etc.
+
+        """
+        if not self._has_programs:
+            _LOGGER.debug("GET_ALL_PROGRAMS: Not supported by client for %s", self._interface_id)
+            return ()
+
+        return await self._json_rpc_client.get_all_programs(markers=markers)
+
+    @inspector
+    async def has_program_ids(self, *, rega_id: int) -> bool:
+        """
+        Check if a channel is used in any CCU programs.
+
+        Args:
+            rega_id: ReGaHSS internal ID of the channel to check.
+
+        Returns:
+            True if the channel is referenced in at least one program.
+
+        """
+        if not self._has_programs:
+            _LOGGER.debug("HAS_PROGRAM_IDS: Not supported by client for %s", self._interface_id)
+            return False
+
+        return await self._json_rpc_client.has_program_ids(rega_id=rega_id)
+
+    @inspector
+    async def set_program_state(self, *, pid: str, state: bool) -> bool:
+        """
+        Enable or disable a CCU program.
+
+        Args:
+            pid: Program ID (ReGa internal identifier).
+            state: True to enable, False to disable the program.
+
+        Returns:
+            True if the state was changed successfully.
+
+        """
+        return await self._json_rpc_client.set_program_state(pid=pid, state=state)

aiohomematic/client/handlers/sysvars.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+System variable handler.
+
+Handles system variable CRUD operations.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Final
+
+from aiohomematic.client.handlers.base import BaseHandler
+from aiohomematic.const import DescriptionMarker, SystemVariableData
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces import SystemVariableOperationsProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class SystemVariableHandler(BaseHandler, SystemVariableOperationsProtocol):
+    """
+    Handler for system variable operations.
+
+    Implements SystemVariableOperationsProtocol protocol for ISP-compliant client operations.
+
+    Handles:
+    - Getting all system variables
+    - Getting single system variable
+    - Setting system variables
+    - Deleting system variables
+    """
+
+    __slots__ = ()
+
+    @inspector
+    async def delete_system_variable(self, *, name: str) -> bool:
+        """
+        Delete a system variable from the CCU.
+
+        Args:
+            name: Name of the system variable to delete.
+
+        Returns:
+            True if deleted successfully.
+
+        """
+        return await self._json_rpc_client.delete_system_variable(name=name)
+
+    @inspector(re_raise=False)
+    async def get_all_system_variables(
+        self,
+        *,
+        markers: tuple[DescriptionMarker | str, ...],
+    ) -> tuple[SystemVariableData, ...] | None:
+        """
+        Return all CCU system variables matching the given markers.
+
+        System variables are global variables stored on the CCU that can be
+        used in programs and scripts. Variables can be filtered by markers
+        in their description field.
+
+        Args:
+            markers: Tuple of DescriptionMarker values or strings to filter by.
+
+        Returns:
+            Tuple of SystemVariableData dicts, or None on error.
+
+        """
+        return await self._json_rpc_client.get_all_system_variables(markers=markers)
+
+    @inspector
+    async def get_system_variable(self, *, name: str) -> Any:
+        """
+        Return the current value of a system variable.
+
+        Args:
+            name: Name of the system variable.
+
+        Returns:
+            Current value (type depends on variable definition).
+
+        """
+        return await self._json_rpc_client.get_system_variable(name=name)
+
+    @inspector(measure_performance=True)
+    async def set_system_variable(self, *, legacy_name: str, value: Any) -> bool:
+        """
+        Set the value of a system variable.
+
+        Args:
+            legacy_name: Original name of the system variable.
+            value: New value to set (must match variable's type definition).
+
+        Returns:
+            True if the value was set successfully.
+
+        """
+        return await self._json_rpc_client.set_system_variable(legacy_name=legacy_name, value=value)