111 lines
8.8 KiB
Markdown
111 lines
8.8 KiB
Markdown
<!--
|
|
Copilot-Aufgabe: HomeKit-Accessory-Mapping-Tabelle aus bestehender Implementierung ableiten
|
|
|
|
Ziel:
|
|
Erstelle eine Mapping-Tabelle, die beschreibt, wie unsere abstrakten Gerätetypen
|
|
(type/Features aus devices.yaml, apps/abstraction und apps/api) auf HomeKit-Accessories
|
|
und Characteristics (HAP-Python) abgebildet werden sollen.
|
|
|
|
Die Tabelle soll:
|
|
- sich an der bestehenden Implementierung und Konfiguration orientieren:
|
|
- devices.yaml (Typen, Features)
|
|
- apps/abstraction (Capabilities, Payload-Strukturen, Topics)
|
|
- apps/api (DTOs, /devices-Response, /devices/{id}/set, /realtime-Events)
|
|
- für jeden bekannten Gerätetyp (z.B. light, thermostat, outlet, contact, temp_humidity, cover, switch)
|
|
festhalten:
|
|
- Abstract Type (type)
|
|
- Relevante Features (Features-Flags, z.B. power, brightness, color_hsb, target, current, contact, humidity)
|
|
- HomeKit Service (z.B. LightBulb, Thermostat, Outlet, ContactSensor, TemperatureSensor, HumiditySensor, WindowCovering)
|
|
- HomeKit Characteristics (z.B. On, Brightness, Hue, Saturation, CurrentTemperature, TargetTemperature, ContactSensorState, CurrentPosition, TargetPosition)
|
|
- State-Mapping (abstraktes payload → HomeKit-Characteristics)
|
|
- Set-Mapping (HomeKit-Characteristics → HTTP POST /devices/{id}/set Payload)
|
|
- Status (OK / REVIEW / TODO)
|
|
|
|
Vorgehen für Copilot:
|
|
1. Analysiere die bestehenden Typen und Features:
|
|
- devices.yaml → "type" und "features" pro Gerät
|
|
- apps/abstraction → Capabilities, State-/Set-Modelle (z.B. light@1.2.0, thermostat, contact, temp_humidity)
|
|
- apps/api:
|
|
- Response-Modell von GET /devices (device_id, type, name, features)
|
|
- Struktur von GET /devices/{id}/state (payload-Felder je Typ)
|
|
- Struktur der Events in /realtime (payload-Felder je Typ)
|
|
- Body von POST /devices/{id}/set (type, payload)
|
|
|
|
2. Lege aufgrund dieser Analyse alle aktuell verwendeten abstrakten Typen an, z.B.:
|
|
- light (mit power, brightness, color_hsb)
|
|
- thermostat (mit current, target, mode)
|
|
- outlet
|
|
- contact
|
|
- temp_humidity
|
|
- ggf. cover, switch, etc., falls vorhanden
|
|
|
|
3. Erstelle eine Tabelle in Markdown mit folgenden Spalten:
|
|
|
|
| Abstract Type | Features (aus devices.yaml) | HomeKit Service | HomeKit Characteristics | State-Mapping (payload → HK) | Set-Mapping (HK → payload) | Status |
|
|
|---------------|-----------------------------|-----------------|-------------------------|------------------------------|----------------------------|--------|
|
|
|
|
Beispiele für Inhalte:
|
|
- Abstract Type: `light`
|
|
- Features: `power, brightness, color_hsb`
|
|
- HomeKit Service: `LightBulb`
|
|
- HomeKit Characteristics: `On, Brightness, Hue, Saturation`
|
|
- State-Mapping: `payload.power -> On; payload.brightness -> Brightness; payload.hue -> Hue; payload.sat -> Saturation`
|
|
- Set-Mapping: `On -> {"type":"light","payload":{"power":"on"/"off"}} ...`
|
|
- Status: `OK` wenn Mapping klar, `REVIEW` wenn du unsicher bist, `TODO` wenn Informationen fehlen
|
|
|
|
4. Nutze vorhandene Informationen aus dem Code:
|
|
- Wenn ein Gerätetyp in apps/abstraction bereits ein klares State-/Set-Modell hat, übernimm das in State-/Set-Mapping.
|
|
- Wenn bestimmte Features noch nicht im Code genutzt werden, markiere die entsprechenden Mapping-Zeilen mit Status=TODO.
|
|
- Falls unklar ist, welcher HomeKit-Service für einen Typ am besten passt, mache einen Vorschlag und setze Status=REVIEW.
|
|
|
|
5. Markiere explizit, wo man später noch eingreifen muss:
|
|
- In der Spalte "Status" mit `REVIEW` oder `TODO`.
|
|
- Optional zusätzliche kurze Kommentare unter der Tabelle wie:
|
|
- `<!-- TODO: RGBW-Unterstützung prüfen -->`
|
|
- `<!-- 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)`<br>`payload.brightness -> Brightness (0-100)`<br>`payload.hue -> Hue (0-360)`<br>`payload.sat -> Saturation (0-100)` | `On -> {"type":"light","payload":{"power":"on"/"off"}}`<br>`Brightness -> {"type":"light","payload":{"brightness":0-100}}`<br>`Hue/Saturation -> {"type":"light","payload":{"hue":0-360,"sat":0-100}}` | OK |
|
|
| `light` | `power, brightness` | `LightBulb` | `On, Brightness` | `payload.power -> On (true/false)`<br>`payload.brightness -> Brightness (0-100)` | `On -> {"type":"light","payload":{"power":"on"/"off"}}`<br>`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)`<br>`payload.target -> TargetTemperature (°C)`<br>`CurrentHeatingCoolingState -> 1 (heat, fest)`<br>`TargetHeatingCoolingState -> 3 (auto, fest)` | `TargetTemperature -> {"type":"thermostat","payload":{"target":temp}}`<br>**Hinweis:** Mode ist immer "auto", keine Mode-Änderung über HomeKit | OK |
|
|
| `relay` | `power` | `Outlet` | `On, OutletInUse` | `payload.power -> On (true/false)`<br>`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)`<br>`payload.humidity -> CurrentRelativeHumidity (%)` | N/A (read-only sensors) | REVIEW |
|
|
| `cover` | `position, tilt` | `WindowCovering` | `CurrentPosition, TargetPosition, CurrentHorizontalTiltAngle, TargetHorizontalTiltAngle` | `payload.position -> CurrentPosition (0-100)`<br>`payload.tilt -> CurrentHorizontalTiltAngle (-90 to 90)` | `TargetPosition -> {"type":"cover","payload":{"position":0-100}}`<br>`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
|
|
|
|
<!-- OK: thermostat - Verwendet nur Mode "auto" (TargetHeatingCoolingState=3, CurrentHeatingCoolingState=1). Keine Mode-Änderung über HomeKit möglich. -->
|
|
|
|
<!-- REVIEW: temp_humidity - Soll als ein kombiniertes Accessory oder zwei separate Accessories (TemperatureSensor + HumiditySensor) abgebildet werden? HAP-Python erlaubt beides -->
|
|
|
|
<!-- TODO: cover - Position/Tilt-Mapping validieren. Sind die Wertebereiche korrekt? Gibt es zusätzliche Features wie PositionState (opening/closing/stopped)? -->
|
|
|
|
<!-- TODO: RGBW-Unterstützung - Prüfen, ob separate ColorTemperature-Characteristic für Warmweiß/Kaltweiß benötigt wird -->
|
|
|
|
<!-- TODO: Prüfen, ob weitere Gerätetypen in devices.yaml existieren (z.B. motion, door, lock, fan, etc.) und diese ergänzen -->
|
|
|
|
## 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) |