aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/model/custom/__init__.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Custom data points for AioHomematic.
+
+This subpackage provides higher-level, device-specific data points that combine
+multiple backend parameters into single, meaningful data points (for example: a
+thermostat, a blind with tilt, a fixed-color light, a lock, a siren, a switch,
+or an irrigation valve). It also contains discovery helpers and a schema-based
+validation for model-specific configurations.
+
+What this package does
+- Discovery: create_custom_data_points() inspects a device model and, if a
+  matching custom definition exists and the device is not ignored for customs,
+  creates the appropriate custom data point(s) and attaches them to the device.
+- Definitions: The definition module holds the catalog of supported models and
+  the rules that describe which parameters form each custom data point. It exposes
+  helpers to query availability, enumerate required parameters, and validate the
+  definition schema.
+- Specializations: Rich custom data point classes for climate, light, cover,
+  lock, siren, switch, and irrigation valve provide tailored behavior and an API
+  focused on user intent (e.g., set_temperature, open_tilt, set_profile,
+  turn_on with effect, lock/open, vent, etc.).
+
+How it relates to the generic layer
+Custom data points build on top of generic data points. While the generic layer
+maps one backend parameter to one data point, this package groups multiple
+parameters across channels (where needed) into a single higher-level data point. The
+result is a simpler interface for automations and UIs, while still allowing the
+underlying generic data points to be created when desired.
+
+Public API entry points commonly used by integrators
+- create_custom_data_points(device): Run discovery and attach custom data points.
+- data_point_definition_exists(model): Check if a custom definition is available.
+- get_required_parameters(): Return all parameters that must be fetched to allow
+  custom data points to function properly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aiohomematic.const import ServiceScope
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces.model import DeviceProtocol
+from aiohomematic.model.custom.climate import (
+    PROFILE_PREFIX,
+    BaseCustomDpClimate,
+    ClimateActivity,
+    ClimateMode,
+    ClimateProfile,
+    CustomDpIpThermostat,
+    CustomDpRfThermostat,
+    CustomDpSimpleRfThermostat,
+)
+from aiohomematic.model.custom.cover import (
+    CustomDpBlind,
+    CustomDpCover,
+    CustomDpGarage,
+    CustomDpIpBlind,
+    CustomDpWindowDrive,
+)
+from aiohomematic.model.custom.data_point import CustomDataPoint
+from aiohomematic.model.custom.definition import (
+    create_custom_data_points as _create_custom_data_points_for_channel,
+    data_point_definition_exists,
+    get_required_parameters,
+)
+from aiohomematic.model.custom.light import (
+    FIXED_COLOR_TO_HS_CONVERTER,
+    CustomDpColorDimmer,
+    CustomDpColorDimmerEffect,
+    CustomDpColorTempDimmer,
+    CustomDpDimmer,
+    CustomDpIpDrgDaliLight,
+    CustomDpIpFixedColorLight,
+    CustomDpIpRGBWLight,
+    CustomDpSoundPlayerLed,
+    LightOffArgs,
+    LightOnArgs,
+    SoundPlayerLedOnArgs,
+    hs_color_to_fixed_converter,
+)
+from aiohomematic.model.custom.lock import (
+    BaseCustomDpLock,
+    CustomDpButtonLock,
+    CustomDpIpLock,
+    CustomDpRfLock,
+    LockState,
+)
+
+# New type-safe profile and registry modules
+from aiohomematic.model.custom.profile import (
+    DEFAULT_DATA_POINTS,
+    PROFILE_CONFIGS,
+    ChannelGroupConfig,
+    ProfileConfig,
+    ProfileRegistry,
+    RebasedChannelGroupConfig,
+    get_profile_config,
+    rebase_channel_group,
+)
+from aiohomematic.model.custom.registry import DeviceConfig, DeviceProfileRegistry, ExtendedDeviceConfig
+from aiohomematic.model.custom.siren import (
+    BaseCustomDpSiren,
+    CustomDpIpSiren,
+    CustomDpIpSirenSmoke,
+    CustomDpSoundPlayer,
+    PlaySoundArgs,
+    SirenOnArgs,
+)
+from aiohomematic.model.custom.switch import CustomDpSwitch
+from aiohomematic.model.custom.text_display import CustomDpTextDisplay, TextDisplayArgs
+from aiohomematic.model.custom.valve import CustomDpIpIrrigationValve
+
+__all__ = [
+    # Climate
+    "BaseCustomDpClimate",
+    "ClimateActivity",
+    "ClimateMode",
+    "ClimateProfile",
+    "CustomDpIpThermostat",
+    "CustomDpRfThermostat",
+    "CustomDpSimpleRfThermostat",
+    "PROFILE_PREFIX",
+    # Cover
+    "CustomDpBlind",
+    "CustomDpCover",
+    "CustomDpGarage",
+    "CustomDpIpBlind",
+    "CustomDpWindowDrive",
+    # Data point
+    "CustomDataPoint",
+    # Definition
+    "create_custom_data_points",
+    "data_point_definition_exists",
+    "get_required_parameters",
+    # Light
+    "CustomDpColorDimmer",
+    "CustomDpColorDimmerEffect",
+    "CustomDpColorTempDimmer",
+    "CustomDpDimmer",
+    "CustomDpIpDrgDaliLight",
+    "CustomDpIpFixedColorLight",
+    "CustomDpIpRGBWLight",
+    "FIXED_COLOR_TO_HS_CONVERTER",
+    "LightOffArgs",
+    "LightOnArgs",
+    "hs_color_to_fixed_converter",
+    # Lock
+    "BaseCustomDpLock",
+    "CustomDpButtonLock",
+    "CustomDpIpLock",
+    "CustomDpRfLock",
+    "LockState",
+    # Profile
+    "ChannelGroupConfig",
+    "DEFAULT_DATA_POINTS",
+    "PROFILE_CONFIGS",
+    "ProfileConfig",
+    "ProfileRegistry",
+    "RebasedChannelGroupConfig",
+    "get_profile_config",
+    "rebase_channel_group",
+    # Registry
+    "DeviceConfig",
+    "DeviceProfileRegistry",
+    "ExtendedDeviceConfig",
+    # Siren
+    "BaseCustomDpSiren",
+    "CustomDpIpSiren",
+    "CustomDpIpSirenSmoke",
+    "SirenOnArgs",
+    # Sound player
+    "CustomDpSoundPlayer",
+    "CustomDpSoundPlayerLed",
+    "PlaySoundArgs",
+    "SoundPlayerLedOnArgs",
+    # Switch
+    "CustomDpSwitch",
+    # Text display
+    "CustomDpTextDisplay",
+    "TextDisplayArgs",
+    # Valve
+    "CustomDpIpIrrigationValve",
+]
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+@inspector(scope=ServiceScope.INTERNAL)
+def create_custom_data_points(*, device: DeviceProtocol) -> None:
+    """Decide which data point category should be used, and create the required data points."""
+    if device.ignore_for_custom_data_point:
+        _LOGGER.debug(
+            "CREATE_CUSTOM_DATA_POINTS: Ignoring for custom data point: %s, %s, %s due to ignored",
+            device.interface_id,
+            device,
+            device.model,
+        )
+        return
+
+    if data_point_definition_exists(model=device.model):
+        _LOGGER.debug(
+            "CREATE_CUSTOM_DATA_POINTS: Handling custom data point integration: %s, %s, %s",
+            device.interface_id,
+            device,
+            device.model,
+        )
+
+        # Create custom data points for each channel
+        for channel in device.channels.values():
+            _create_custom_data_points_for_channel(channel=channel)

aiohomematic/model/custom/capabilities/__init__.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Entity capabilities dataclasses.
+
+Provides frozen dataclasses for static capability flags of custom entities.
+Dynamic capabilities that change at runtime use has_* properties on the entity class.
+
+Public API
+----------
+- LightCapabilities: Capability flags for light entities
+- SirenCapabilities: Capability flags for siren entities
+- LockCapabilities: Capability flags for lock entities
+- ClimateCapabilities: Capability flags for climate entities
+"""
+
+from __future__ import annotations
+
+from aiohomematic.model.custom.capabilities.climate import (
+    BASIC_CLIMATE_CAPABILITIES,
+    IP_THERMOSTAT_CAPABILITIES,
+    ClimateCapabilities,
+)
+from aiohomematic.model.custom.capabilities.light import (
+    COLOR_DIMMER_CAPABILITIES,
+    COLOR_TEMP_DIMMER_CAPABILITIES,
+    DIMMER_CAPABILITIES,
+    FIXED_COLOR_LIGHT_CAPABILITIES,
+    RGBW_LIGHT_CAPABILITIES,
+    LightCapabilities,
+)
+from aiohomematic.model.custom.capabilities.lock import (
+    BUTTON_LOCK_CAPABILITIES,
+    IP_LOCK_CAPABILITIES,
+    SMART_DOOR_LOCK_CAPABILITIES,
+    LockCapabilities,
+)
+from aiohomematic.model.custom.capabilities.siren import (
+    BASIC_SIREN_CAPABILITIES,
+    SMOKE_SENSOR_SIREN_CAPABILITIES,
+    SOUND_PLAYER_CAPABILITIES,
+    SirenCapabilities,
+)
+
+__all__ = [
+    # Light
+    "COLOR_DIMMER_CAPABILITIES",
+    "COLOR_TEMP_DIMMER_CAPABILITIES",
+    "DIMMER_CAPABILITIES",
+    "FIXED_COLOR_LIGHT_CAPABILITIES",
+    "LightCapabilities",
+    "RGBW_LIGHT_CAPABILITIES",
+    # Siren
+    "BASIC_SIREN_CAPABILITIES",
+    "SMOKE_SENSOR_SIREN_CAPABILITIES",
+    "SOUND_PLAYER_CAPABILITIES",
+    "SirenCapabilities",
+    # Lock
+    "BUTTON_LOCK_CAPABILITIES",
+    "IP_LOCK_CAPABILITIES",
+    "LockCapabilities",
+    "SMART_DOOR_LOCK_CAPABILITIES",
+    # Climate
+    "BASIC_CLIMATE_CAPABILITIES",
+    "ClimateCapabilities",
+    "IP_THERMOSTAT_CAPABILITIES",
+]

aiohomematic/model/custom/capabilities/climate.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Climate capabilities dataclass.
+
+Contains static capability flags for climate entities.
+
+Public API
+----------
+- ClimateCapabilities: Frozen dataclass with climate capability flags
+- BASIC_CLIMATE_CAPABILITIES: Basic climate capabilities
+- IP_THERMOSTAT_CAPABILITIES: IP thermostat capabilities
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = [
+    "BASIC_CLIMATE_CAPABILITIES",
+    "ClimateCapabilities",
+    "IP_THERMOSTAT_CAPABILITIES",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ClimateCapabilities:
+    """
+    Immutable capability flags for climate entities.
+
+    All capabilities are static and determined by device type.
+    """
+
+    profiles: bool = False  # Supports heating profiles/schedules
+
+
+# Predefined capability sets for different climate device types
+
+BASIC_CLIMATE_CAPABILITIES: Final = ClimateCapabilities(profiles=False)
+IP_THERMOSTAT_CAPABILITIES: Final = ClimateCapabilities(profiles=True)

aiohomematic/model/custom/capabilities/light.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Light capabilities dataclass.
+
+Contains static capability flags for light entities. Dynamic capabilities
+that depend on runtime state (like device_operation_mode) use has_* properties
+on the entity class instead.
+
+Public API
+----------
+- LightCapabilities: Frozen dataclass with light capability flags
+- DIMMER_CAPABILITIES: Basic dimmer capabilities
+- COLOR_DIMMER_CAPABILITIES: Color dimmer capabilities
+- COLOR_TEMP_DIMMER_CAPABILITIES: Color temperature dimmer capabilities
+- FIXED_COLOR_LIGHT_CAPABILITIES: Fixed color light capabilities
+- RGBW_LIGHT_CAPABILITIES: RGBW light capabilities (dynamic features via has_*)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = [
+    "COLOR_DIMMER_CAPABILITIES",
+    "COLOR_TEMP_DIMMER_CAPABILITIES",
+    "DIMMER_CAPABILITIES",
+    "FIXED_COLOR_LIGHT_CAPABILITIES",
+    "LightCapabilities",
+    "RGBW_LIGHT_CAPABILITIES",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class LightCapabilities:
+    """
+    Immutable capability flags for light entities.
+
+    Contains ONLY static capabilities that don't change at runtime.
+    For CustomDpIpRGBWLight, color_temperature/hs_color/effects depend on
+    device_operation_mode and use has_* properties instead.
+    """
+
+    # Core features
+    brightness: bool = True  # All lights support brightness by default
+    transition: bool = False  # Ramp time support
+
+    # Color features (static detection based on DataPoint presence)
+    color_temperature: bool = False  # Has color temperature DataPoint
+    hs_color: bool = False  # Has hue/saturation DataPoints
+    effects: bool = False  # Has effect DataPoint
+
+
+# Predefined capability sets for different light types
+
+DIMMER_CAPABILITIES: Final = LightCapabilities(
+    brightness=True,
+    transition=True,
+)
+
+COLOR_DIMMER_CAPABILITIES: Final = LightCapabilities(
+    brightness=True,
+    transition=True,
+    hs_color=True,
+)
+
+COLOR_TEMP_DIMMER_CAPABILITIES: Final = LightCapabilities(
+    brightness=True,
+    transition=True,
+    color_temperature=True,
+)
+
+FIXED_COLOR_LIGHT_CAPABILITIES: Final = LightCapabilities(
+    brightness=True,
+    transition=True,
+    # Fixed color uses color property but not hs_color
+)
+
+# RGBW lights have dynamic capabilities based on device_operation_mode
+# Static capabilities only include brightness/transition
+# Color features are checked via has_* properties at runtime
+RGBW_LIGHT_CAPABILITIES: Final = LightCapabilities(
+    brightness=True,
+    transition=True,
+    # color_temperature, hs_color, effects are dynamic - use has_* properties
+)

aiohomematic/model/custom/capabilities/lock.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Lock capabilities dataclass.
+
+Contains static capability flags for lock entities.
+
+Public API
+----------
+- LockCapabilities: Frozen dataclass with lock capability flags
+- IP_LOCK_CAPABILITIES: IP lock capabilities
+- BUTTON_LOCK_CAPABILITIES: Button lock capabilities
+- SMART_DOOR_LOCK_CAPABILITIES: Smart door lock capabilities
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = [
+    "BUTTON_LOCK_CAPABILITIES",
+    "IP_LOCK_CAPABILITIES",
+    "LockCapabilities",
+    "SMART_DOOR_LOCK_CAPABILITIES",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class LockCapabilities:
+    """
+    Immutable capability flags for lock entities.
+
+    All capabilities are static and determined by device type.
+    """
+
+    open: bool = False  # Can be opened (not just locked/unlocked)
+
+
+# Predefined capability sets for different lock types
+
+IP_LOCK_CAPABILITIES: Final = LockCapabilities(open=True)
+BUTTON_LOCK_CAPABILITIES: Final = LockCapabilities(open=False)
+SMART_DOOR_LOCK_CAPABILITIES: Final = LockCapabilities(open=True)

aiohomematic/model/custom/capabilities/siren.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Siren capabilities dataclass.
+
+Contains static capability flags for siren entities.
+
+Public API
+----------
+- SirenCapabilities: Frozen dataclass with siren capability flags
+- BASIC_SIREN_CAPABILITIES: Standard siren capabilities
+- SMOKE_SENSOR_SIREN_CAPABILITIES: Smoke sensor siren capabilities
+- SOUND_PLAYER_CAPABILITIES: Sound player capabilities
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = [
+    "BASIC_SIREN_CAPABILITIES",
+    "SMOKE_SENSOR_SIREN_CAPABILITIES",
+    "SOUND_PLAYER_CAPABILITIES",
+    "SirenCapabilities",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class SirenCapabilities:
+    """
+    Immutable capability flags for siren entities.
+
+    All capabilities are static and determined at initialization
+    based on device type and available DataPoints.
+    """
+
+    duration: bool = False  # Supports duration parameter for alarm
+    lights: bool = False  # Has optical alarm selection DataPoint
+    tones: bool = False  # Has acoustic alarm selection DataPoint
+    soundfiles: bool = False  # Has soundfile selection DataPoint (sound players)
+
+
+# Predefined capability sets for different siren types
+
+BASIC_SIREN_CAPABILITIES: Final = SirenCapabilities(
+    duration=True,
+    lights=True,
+    tones=True,
+)
+
+SMOKE_SENSOR_SIREN_CAPABILITIES: Final = SirenCapabilities(
+    duration=False,
+    lights=False,
+    tones=True,
+)
+
+SOUND_PLAYER_CAPABILITIES: Final = SirenCapabilities(
+    duration=True,
+    lights=False,
+    tones=False,
+    soundfiles=True,
+)