window contact first try

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"]