home-automation/apps/homekit/homekit_mapping.md

`

 - `<!-- REVIEW: Soll temp_humidity als zwei Accessories oder kombiniert abgebildet werden? -->`

Akzeptanz-Kriterien:

• Es existiert am Ende dieses Dokuments eine Markdown-Tabelle mit mindestens allen abstrakten Gerätetypen, die aktuell in devices.yaml / apps/abstraction / apps/api verwendet werden.
• Für jeden Typ sind HomeKit Service und Characteristics ausgefüllt oder mit Status=REVIEW/TODO markiert.
• State-/Set-Mapping ist für alle bereits gut verstandenen Typen (z.B. einfache Lichter, Thermostate, Kontakte, Temp/Humidity-Sensoren) konkret beschrieben.
• Stellen, an denen die aktuelle Implementierung keine klaren Informationen liefert, sind sichtbar mit Status=REVIEW oder TODO gekennzeichnet.
• Copilot ändert an keiner anderen Stelle des Codes etwas, sondern erzeugt nur diese Tabelle/Dokumentation. -->

HomeKit-Accessory-Mapping-Tabelle

Dieses Dokument beschreibt das Mapping zwischen unseren abstrakten Gerätetypen (aus devices.yaml, apps/abstraction und apps/api) und HomeKit-Accessories/Characteristics (HAP-Python).

Mapping-Tabelle

Abstract Type	Features (aus devices.yaml)	HomeKit Service	HomeKit Characteristics	State-Mapping (payload → HK)	Set-Mapping (HK → payload)	Status
light	power, brightness, color_hsb	LightBulb	On, Brightness, Hue, Saturation	payload.power -> On (true/false) payload.brightness -> Brightness (0-100) payload.hue -> Hue (0-360) payload.sat -> Saturation (0-100)	On -> {"type":"light","payload":{"power":"on"/"off"}} Brightness -> {"type":"light","payload":{"brightness":0-100}} Hue/Saturation -> {"type":"light","payload":{"hue":0-360,"sat":0-100}}	OK
light	power, brightness	LightBulb	On, Brightness	payload.power -> On (true/false) payload.brightness -> Brightness (0-100)	On -> {"type":"light","payload":{"power":"on"/"off"}} Brightness -> {"type":"light","payload":{"brightness":0-100}}	OK
light	power	LightBulb	On	payload.power -> On (true/false)	On -> {"type":"light","payload":{"power":"on"/"off"}}	OK
thermostat	current, target	Thermostat	CurrentTemperature, TargetTemperature, CurrentHeatingCoolingState, TargetHeatingCoolingState	payload.current -> CurrentTemperature (°C) payload.target -> TargetTemperature (°C) CurrentHeatingCoolingState -> 1 (heat, fest) TargetHeatingCoolingState -> 3 (auto, fest)	TargetTemperature -> {"type":"thermostat","payload":{"target":temp}} Hinweis: Mode ist immer "auto", keine Mode-Änderung über HomeKit	OK
relay	power	Outlet	On, OutletInUse	payload.power -> On (true/false) payload.power -> OutletInUse (true/false)	On -> {"type":"relay","payload":{"power":"on"/"off"}}	OK
contact	contact	ContactSensor	ContactSensorState	payload.contact -> ContactSensorState (0=detected, 1=not detected)	N/A (read-only sensor)	OK
temp_humidity	temperature, humidity	TemperatureSensor + HumiditySensor	CurrentTemperature, CurrentRelativeHumidity	payload.temperature -> CurrentTemperature (°C) payload.humidity -> CurrentRelativeHumidity (%)	N/A (read-only sensors)	REVIEW
cover	position, tilt	WindowCovering	CurrentPosition, TargetPosition, CurrentHorizontalTiltAngle, TargetHorizontalTiltAngle	payload.position -> CurrentPosition (0-100) payload.tilt -> CurrentHorizontalTiltAngle (-90 to 90)	TargetPosition -> {"type":"cover","payload":{"position":0-100}} TargetHorizontalTiltAngle -> {"type":"cover","payload":{"tilt":-90 to 90}}	TODO
switch	power	Switch	On	payload.power -> On (true/false)	On -> {"type":"switch","payload":{"power":"on"/"off"}}	OK

Offene Punkte und Kommentare

Hinweise zur Implementierung

• State-Updates: Alle State-Änderungen von MQTT/API werden auf entsprechende HomeKit-Characteristics gemappt und via set_value() aktualisiert
• Set-Befehle: HomeKit-Charakteristik-Änderungen werden in HTTP POST-Requests an /devices/{id}/set umgewandelt
• Read-only Sensors: Sensoren (contact, temp_humidity) unterstützen nur State-Updates, keine Set-Befehle
• Bidirektionales Mapping: Änderungen müssen in beide Richtungen synchronisiert werden (HomeKit ↔ Abstraction Layer)