ADR 0019: Derived Binary Sensors from Enum Data Points¶

# In aiohomematic/model/custom/siren.py
@state_property
def is_on(self) -> bool | None:
    """Return if siren is on."""
    return bool(self._dp_smoke_detector_alarm_status.value != _SMOKE_DETECTOR_ALARM_STATUS_IDLE_OFF)

# aiohomematic/model/calculated/derived_binary_sensor.py

@dataclass(frozen=True, kw_only=True, slots=True)
class DerivedBinarySensorMapping:
    """Definition of a derived binary sensor mapping rule."""

    model: str | tuple[str, ...]  # Device model(s) this applies to
    source_parameter: Parameter   # Source enum parameter
    source_channel_no: int        # Channel where source parameter lives
    on_values: frozenset[str]     # Enum values that map to ON (binary True)
    off_values: frozenset[str] | None = None  # Optional: explicit OFF values
                                              # If None: all values not in on_values
    calculated_parameter: CalculatedParameter  # Unique identifier for derived DP


# Registration API
class DerivedBinarySensorRegistry:
    """Registry for derived binary sensor mappings."""

    @classmethod
    def register(
        cls,
        *,
        model: str | tuple[str, ...],
        source_parameter: Parameter,
        source_channel_no: int,
        on_values: frozenset[str],
        calculated_parameter: CalculatedParameter,
        off_values: frozenset[str] | None = None,
    ) -> None:
        """Register a derived binary sensor mapping."""
        ...

    @classmethod
    def get_mappings_for_model(cls, *, model: str) -> tuple[DerivedBinarySensorMapping, ...]:
        """Return all derived binary sensor mappings for a device model."""
        ...

# In aiohomematic/model/calculated/derived_binary_sensor.py

# HmIP-SRH: Window Handle Sensor → Window Open Binary Sensor
DerivedBinarySensorRegistry.register(
    model="HmIP-SRH",
    source_parameter=Parameter.STATE,
    source_channel_no=1,
    on_values=frozenset({"TILTED", "OPEN"}),
    calculated_parameter=CalculatedParameter.WINDOW_OPEN,
)

# HmIP-SWSD: Smoke Detector → Smoke Alarm Binary Sensor
DerivedBinarySensorRegistry.register(
    model="HmIP-SWSD",
    source_parameter=Parameter.SMOKE_DETECTOR_ALARM_STATUS,
    source_channel_no=1,
    on_values=frozenset({"PRIMARY_ALARM", "INTRUSION_ALARM", "SECONDARY_ALARM"}),
    calculated_parameter=CalculatedParameter.SMOKE_ALARM,
)

class DerivedBinarySensor(CalculatedDataPoint[bool | None]):
    """
    Calculated binary sensor derived from an enum data point.

    This class implements a generic derived binary sensor that maps
    enum values to boolean states based on declarative mapping rules.
    """

    __slots__ = ("_mapping", "_dp_source")

    _category = DataPointCategory.BINARY_SENSOR

    def __init__(
        self,
        *,
        channel: ChannelProtocol,
        mapping: DerivedBinarySensorMapping,
    ) -> None:
        """Initialize the derived binary sensor."""
        self._mapping: Final = mapping
        self._calculated_parameter = mapping.calculated_parameter
        super().__init__(channel=channel)
        self._type = ParameterType.BOOL

        # Resolve source data point
        self._dp_source = self._add_data_point(
            parameter=mapping.source_parameter,
            paramset_key=ParamsetKey.VALUES,
            dpt=DpSelect,
        )

    @staticmethod
    def is_relevant_for_model(*, channel: ChannelProtocol) -> bool:
        """Return if any derived binary sensor is relevant for this channel."""
        # Delegated to factory - this method checks individual mappings
        return False  # Factory handles relevance

    @staticmethod
    def is_relevant_for_mapping(
        *,
        channel: ChannelProtocol,
        mapping: DerivedBinarySensorMapping,
    ) -> bool:
        """Return if a specific mapping is relevant for this channel."""
        # Check model match
        if isinstance(mapping.model, tuple):
            if not element_matches_key(search_elements=mapping.model, compare_with=channel.device.model):
                return False
        elif not element_matches_key(search_elements=(mapping.model,), compare_with=channel.device.model):
            return False

        # Check channel match
        if channel.no != mapping.source_channel_no:
            return False

        # Check source parameter exists
        return channel.get_generic_data_point(
            parameter=mapping.source_parameter,
            paramset_key=ParamsetKey.VALUES,
        ) is not None

    @state_property
    def value(self) -> bool | None:
        """Return the derived binary value."""
        if (source_value := self._dp_source.value) is None:
            return None
        return source_value in self._mapping.on_values

# In aiohomematic/model/calculated/__init__.py

def create_derived_binary_sensors(
    *,
    channel: ChannelProtocol,
) -> tuple[DerivedBinarySensor, ...]:
    """Create all relevant derived binary sensors for a channel."""
    derived_sensors: list[DerivedBinarySensor] = []

    for mapping in DerivedBinarySensorRegistry.get_mappings_for_model(model=channel.device.model):
        if DerivedBinarySensor.is_relevant_for_mapping(channel=channel, mapping=mapping):
            derived_sensors.append(
                DerivedBinarySensor(channel=channel, mapping=mapping)
            )

    return tuple(derived_sensors)

# In aiohomematic/const.py

class CalculatedParameter(StrEnum):
    """Enum with calculated Homematic parameters."""

    # Existing
    APPARENT_TEMPERATURE = "APPARENT_TEMPERATURE"
    DEW_POINT = "DEW_POINT"
    DEW_POINT_SPREAD = "DEW_POINT_SPREAD"
    ENTHALPY = "ENTHALPY"
    FROST_POINT = "FROST_POINT"
    OPERATING_VOLTAGE_LEVEL = "OPERATING_VOLTAGE_LEVEL"
    VAPOR_CONCENTRATION = "VAPOR_CONCENTRATION"

    # New: Derived binary sensors
    SMOKE_ALARM = "SMOKE_ALARM"
    WINDOW_OPEN = "WINDOW_OPEN"
    # Future: Add more as needed

# In aiohomematic/const.py
class CalculatedParameter(StrEnum):
    MY_NEW_SENSOR = "MY_NEW_SENSOR"

# In aiohomematic/model/calculated/derived_binary_sensor.py
DerivedBinarySensorRegistry.register(
    model="HmIP-XYZ",
    source_parameter=Parameter.MY_ENUM_PARAM,
    source_channel_no=1,
    on_values=frozenset({"VALUE_A", "VALUE_B"}),
    calculated_parameter=CalculatedParameter.MY_NEW_SENSOR,
)

# In tests/test_model_calculated_derived_binary_sensor.py
async def test_my_new_sensor_mapping(...) -> None:
    ...