window contact first try

packages/home_capabilities/__init__.py

@@ -4,6 +4,8 @@ from packages.home_capabilities.light import CAP_VERSION as LIGHT_VERSION
 from packages.home_capabilities.light import LightState
 from packages.home_capabilities.thermostat import CAP_VERSION as THERMOSTAT_VERSION
 from packages.home_capabilities.thermostat import ThermostatState
+from packages.home_capabilities.contact_sensor import CAP_VERSION as CONTACT_SENSOR_VERSION
+from packages.home_capabilities.contact_sensor import ContactState
 from packages.home_capabilities.layout import DeviceTile, Room, UiLayout, load_layout
 
 __all__ = [
@@ -11,6 +13,8 @@ __all__ = [
     "LIGHT_VERSION",
     "ThermostatState",
     "THERMOSTAT_VERSION",
+    "ContactState",
+    "CONTACT_SENSOR_VERSION",
     "DeviceTile",
     "Room",
     "UiLayout",

packages/home_capabilities/contact_sensor.py

@@ -0,0 +1,96 @@
+"""Contact Sensor Capability - Fensterkontakt (read-only).
+
+This module defines the ContactState model for door/window contact sensors.
+These sensors report their open/closed state and are read-only devices.
+
+Capability Version: contact_sensor@1.0.0
+"""
+
+from datetime import datetime
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+# Capability metadata
+CAP_VERSION = "contact_sensor@1.0.0"
+DISPLAY_NAME = "Contact Sensor"
+
+
+class ContactState(BaseModel):
+    """State model for contact sensors (door/window sensors).
+    
+    Contact sensors are read-only devices that report whether a door or window
+    is open or closed. They typically also report battery level and signal quality.
+    
+    Attributes:
+        contact: Current state of the contact ("open" or "closed")
+        battery: Battery level percentage (0-100), optional
+        linkquality: MQTT link quality indicator, optional
+        device_temperature: Internal device temperature in °C, optional
+        voltage: Battery voltage in mV, optional
+        ts: Timestamp of the state reading, optional
+    
+    Examples:
+        >>> ContactState(contact="open")
+        ContactState(contact='open', battery=None, ...)
+        
+        >>> ContactState(contact="closed", battery=95, linkquality=87)
+        ContactState(contact='closed', battery=95, linkquality=87, ...)
+    """
+    
+    contact: Literal["open", "closed"] = Field(
+        ...,
+        description="Contact state: 'open' for open door/window, 'closed' for closed"
+    )
+    
+    battery: Annotated[int, Field(ge=0, le=100)] | None = Field(
+        None,
+        description="Battery level in percent (0-100)"
+    )
+    
+    linkquality: int | None = Field(
+        None,
+        description="Link quality indicator (typically 0-255)"
+    )
+    
+    device_temperature: float | None = Field(
+        None,
+        description="Internal device temperature in degrees Celsius"
+    )
+    
+    voltage: int | None = Field(
+        None,
+        description="Battery voltage in millivolts"
+    )
+    
+    ts: datetime | None = Field(
+        None,
+        description="Timestamp of the state reading"
+    )
+    
+    @staticmethod
+    def normalize_bool(is_open: bool) -> "ContactState":
+        """Convert boolean to ContactState.
+        
+        Helper method to convert a boolean value to a ContactState instance.
+        Useful when integrating with systems that use True/False for contact state.
+        
+        Args:
+            is_open: True if contact is open, False if closed
+        
+        Returns:
+            ContactState instance with appropriate contact value
+        
+        Examples:
+            >>> ContactState.normalize_bool(True)
+            ContactState(contact='open', ...)
+            
+            >>> ContactState.normalize_bool(False)
+            ContactState(contact='closed', ...)
+        """
+        return ContactState(contact="open" if is_open else "closed")
+
+
+# Public API
+__all__ = ["ContactState", "CAP_VERSION", "DISPLAY_NAME"]