From 5bf37a19adb2ca101a942d8e9674dd93773bfb4f Mon Sep 17 00:00:00 2001 From: Wolfgang Hottgenroth Date: Mon, 17 Nov 2025 10:18:27 +0100 Subject: [PATCH] homekit bridge initial --- HOMEKIT_BRIDGE_API_ANALYSIS.md | 553 ++++++++++++++++++++++++++++++++ apps/api/main.py | 142 +++++++- apps/homekit/README.md | 465 +++++++++++++++++++++++++++ apps/homekit/homekit_mapping.md | 111 +++++++ apps/homekit/main.py | 223 +++++++++++++ apps/homekit/requirements.txt | 13 + 6 files changed, 1506 insertions(+), 1 deletion(-) create mode 100644 HOMEKIT_BRIDGE_API_ANALYSIS.md create mode 100644 apps/homekit/README.md create mode 100644 apps/homekit/homekit_mapping.md create mode 100644 apps/homekit/main.py create mode 100644 apps/homekit/requirements.txt diff --git a/HOMEKIT_BRIDGE_API_ANALYSIS.md b/HOMEKIT_BRIDGE_API_ANALYSIS.md new file mode 100644 index 0000000..c453709 --- /dev/null +++ b/HOMEKIT_BRIDGE_API_ANALYSIS.md @@ -0,0 +1,553 @@ +# HomeKit-Bridge API-Modell: Analyse der bestehenden Implementierung + +**Analysedatum:** 17. November 2025 +**Analysierte Dateien:** +- `apps/api/main.py` +- `apps/api/routes/groups_scenes.py` +- `config/devices.yaml` + +--- + +## Zusammenfassung + +Die bestehende API-Implementierung erfüllt **~60%** der Anforderungen des HomeKit-Bridge Ziel-Modells. Die meisten Kernfunktionalitäten sind vorhanden, aber es fehlen wichtige Metadaten-Felder und ein dedizierter State-Endpoint. + +--- + +## 1. GET /devices + +### Status: ✅ **VORHANDEN** mit Abweichungen + +### Implementierung (apps/api/main.py:325-343) +```python +@app.get("/devices") +async def get_devices() -> list[DeviceInfo]: + devices = load_devices() + return [ + DeviceInfo( + device_id=device["device_id"], + type=device["type"], + name=device.get("name", device["device_id"]), + features=device.get("features", {}) + ) + for device in devices + ] +``` + +### Response-Modell (DeviceInfo) +```python +class DeviceInfo(BaseModel): + device_id: str + type: str + name: str + features: dict[str, Any] = {} +``` + +### Abweichungen vom Ziel-Modell + +| Feld | Ziel-Modell | Ist-Zustand | Status | +|------|-------------|-------------|---------| +| `device_id` | ✅ Erforderlich | ✅ Vorhanden | OK | +| `type` | ✅ Erforderlich | ✅ Vorhanden | OK | +| `cap_version` | ✅ Erforderlich | ❌ **FEHLT** | FEHLT | +| `room` | ✅ Erforderlich | ❌ **FEHLT** | FEHLT | +| `friendly_name` | ✅ Erforderlich | ⚠️ Heißt `name` | UMBENENNUNG | +| `technology` | ✅ Erforderlich | ❌ **FEHLT** | FEHLT | +| `features` | ✅ Erforderlich | ✅ Vorhanden | OK | +| `read_only` | ✅ Erforderlich | ❌ **FEHLT** | FEHLT | +| `tags` | Optional | ❌ **FEHLT** | FEHLT | + +### Details zu fehlenden Feldern + +#### ❌ `cap_version` +- **Vorhanden in devices.yaml:** Ja, als `cap_version` (z.B. `"light@1.2.0"`) +- **Problem:** Wird von `load_devices()` geladen, aber nicht in `DeviceInfo` exponiert +- **Lösung:** Feld zu `DeviceInfo` hinzufügen und aus `device["cap_version"]` befüllen + +#### ❌ `room` +- **Vorhanden in layout.yaml:** Ja, indirekt über Raum-Zuordnung +- **Problem:** Aktuell nur über separaten Endpoint `/devices/{device_id}/room` verfügbar +- **Lösung:** Room-Mapping in `/devices` integrieren (Resolver bereits vorhanden in `apps/api/resolvers.py`) + +#### ⚠️ `friendly_name` vs. `name` +- **Vorhanden in devices.yaml:** Ja, als `metadata.friendly_name` +- **Problem:** Aktuell wird `device.get("name", device["device_id"])` verwendet, nicht `metadata.friendly_name` +- **Lösung:** Priorisierung: `metadata.friendly_name` > `name` > `device_id` + +#### ❌ `technology` +- **Vorhanden in devices.yaml:** Ja, als `technology` (z.B. `"zigbee2mqtt"`) +- **Problem:** Wird nicht in Response exponiert +- **Lösung:** Feld zu `DeviceInfo` hinzufügen + +#### ❌ `read_only` +- **Implizit vorhanden:** Ja, über `topics.set` (wenn fehlt → read-only) +- **Problem:** Muss berechnet werden +- **Lösung:** `read_only = "set" not in device.get("topics", {})` + +#### ❌ `tags` +- **Vorhanden in devices.yaml:** Nein +- **Status:** Nicht kritisch, kann später ergänzt werden + +--- + +## 2. GET /devices/{device_id} + +### Status: ❌ **FEHLT KOMPLETT** + +### Aktuell vorhanden +- `/devices/{device_id}/room` (liefert nur `{"device_id": str, "room": str | None}`) + +### Erforderlich +Ein Endpoint, der das gleiche Schema wie ein Eintrag aus `/devices` zurückgibt: +```python +@app.get("/devices/{device_id}") +async def get_device(device_id: str) -> DeviceInfo: + # Load device, enrich with room, return DeviceInfo +``` + +### Implementierung +- Device aus `load_devices()` filtern +- Mit `get_room(device_id)` anreichern +- Als `DeviceInfo` zurückgeben +- 404 bei nicht gefunden + +--- + +## 3. GET /devices/{device_id}/state + +### Status: ❌ **FEHLT KOMPLETT** + +### Aktuell vorhanden +- `/devices/states` (liefert **alle** Device-States als Dict) + ```python + @app.get("/devices/states") + async def get_device_states() -> dict[str, dict[str, Any]]: + return device_states # In-memory cache + ``` + +### Ziel-Format +```json +{ + "device_id": "thermostat_wolfgang", + "type": "thermostat", + "room": "Schlafzimmer", + "payload": { + "current": 19.5, + "target": 21.0, + "mode": "heat" + }, + "ts": "2025-11-17T14:23:45.123Z" +} +``` + +### Erforderlich +```python +@app.get("/devices/{device_id}/state") +async def get_device_state(device_id: str) -> DeviceStateResponse: + # Get from device_states cache + # Enrich with metadata (type, room) + # Add timestamp + # Return structured response +``` + +### Problem +- Aktuell wird nur `payload` im Cache gespeichert +- Timestamp fehlt im Cache (müsste bei SSE-Updates mitgespeichert werden) +- Metadaten (type, room) müssen aus devices.yaml/layout.yaml ergänzt werden + +--- + +## 4. SSE-Endpoint /realtime + +### Status: ✅ **VORHANDEN** mit kleineren Abweichungen + +### Implementierung (apps/api/main.py:608-637) +```python +@app.get("/realtime") +async def realtime_events(request: Request) -> StreamingResponse: + return StreamingResponse( + event_generator(request), + media_type="text/event-stream", + # ... headers + ) +``` + +### Aktuelles Event-Format (aus Redis) +```json +{ + "type": "state", + "device_id": "thermostat_wolfgang", + "payload": { + "current": 19.5, + "target": 21.0 + } +} +``` + +### Ziel-Format +```json +{ + "type": "state", + "device_id": "thermostat_wolfgang", + "device_type": "thermostat", // ← FEHLT + "room": "Schlafzimmer", // ← FEHLT + "payload": { + "current": 19.5, + "target": 21.0 + }, + "ts": "2025-11-17T14:23:45.123Z", // ← FEHLT + "source": "zigbee2mqtt" // ← FEHLT (optional) +} +``` + +### Abweichungen + +| Feld | Ziel-Modell | Ist-Zustand | Status | +|------|-------------|-------------|---------| +| `type` | ✅ | ✅ | OK | +| `device_id` | ✅ | ✅ | OK | +| `device_type` | ✅ | ❌ **FEHLT** | FEHLT | +| `room` | ✅ | ❌ **FEHLT** | FEHLT | +| `payload` | ✅ | ✅ | OK | +| `ts` | ✅ | ❌ **FEHLT** | FEHLT | +| `source` | Optional | ❌ **FEHLT** | FEHLT | + +### Problem +Events werden direkt aus Redis weitergeleitet ohne Enrichment. + +### Lösungsansätze + +**Option A: Enrichment im SSE-Generator** +```python +# Im event_generator() nach JSON-Parse: +state_data = json.loads(data) +if state_data.get("type") == "state": + # Enrich with metadata + device_id = state_data["device_id"] + device = get_device_from_cache(device_id) + state_data["device_type"] = device["type"] + state_data["room"] = get_room(device_id) + if "ts" not in state_data: + state_data["ts"] = datetime.utcnow().isoformat() + data = json.dumps(state_data) +``` + +**Option B: Enrichment im Publisher (apps/abstraction)** +- Besser: Events bereits vollständig beim Publizieren +- Würde auch `/devices/{id}/state` helfen + +--- + +## 5. POST /devices/{device_id}/set + +### Status: ✅ **VORHANDEN** mit kleinen Abweichungen + +### Implementierung (apps/api/main.py:406-504) +```python +@app.post("/devices/{device_id}/set", status_code=status.HTTP_202_ACCEPTED) +async def set_device(device_id: str, request: SetDeviceRequest) -> dict[str, str]: + # Validierung, MQTT publish +``` + +### Request-Modell +```python +class SetDeviceRequest(BaseModel): + type: str + payload: dict[str, Any] +``` + +### Vergleich mit Ziel-Modell + +| Aspekt | Ziel-Modell | Ist-Zustand | Status | +|--------|-------------|-------------|---------| +| Body-Format | `{type, payload}` | `{type, payload}` | ✅ OK | +| Type-Validierung | ✅ Erforderlich | ✅ Vorhanden | OK | +| Payload-Validierung | ✅ Per Device-Type | ✅ Vorhanden | OK | +| Read-Only Check | ✅ → 405 | ✅ → 405 | OK | +| Response Code | 200/202 | 202 | OK | + +### Validierungs-Details + +**✅ Gut implementiert:** +- Type-spezifische Pydantic-Validierung (LightState, ThermostatState, etc.) +- Whitelist für erlaubte Felder bei Thermostaten +- Read-only Detection über `topics.set` +- Proper HTTP Status Codes (404, 405, 422) + +**⚠️ Kleine Abweichung:** +- Thermostat-Validierung erlaubt nur `{mode, target}` beim SET +- Ziel-Modell erwähnt dies nicht explizit +- **Bewertung:** Ist sinnvolle Einschränkung, kein Problem + +### MQTT-Publishing +```python +topic = f"home/{request.type}/{device_id}/set" +mqtt_payload = { + "type": request.type, + "payload": request.payload +} +await publish_mqtt(topic, mqtt_payload) +``` +✅ Korrekt implementiert + +--- + +## 6. Zusätzliche Endpoints (nicht im Ziel-Modell) + +### ℹ️ Vorhanden, aber nicht gefordert + +- **GET /spec** - Capability-Versionen +- **GET /devices/states** - Alle States (könnte nützlich für Bridge sein) +- **GET /layout** - UI-spezifisch +- **GET /devices/{device_id}/room** - Wird obsolet wenn `/devices` `room` hat +- **GET /groups**, **POST /groups/{id}/set** - Gruppen-Feature +- **GET /scenes**, **POST /scenes/{id}/run** - Szenen-Feature + +**Bewertung:** Nicht störend, können bleiben. Bridge muss diese nicht nutzen. + +--- + +## 7. Datenquellen-Analyse + +### devices.yaml +**✅ Enthält alle benötigten Felder:** +```yaml +- device_id: leselampe_esszimmer + type: light + cap_version: "light@1.2.0" # ← Vorhanden + technology: zigbee2mqtt # ← Vorhanden + features: + power: true + brightness: true + topics: + state: "..." + set: "..." # ← Für read_only Detection + metadata: + friendly_name: "Leselampe Esszimmer" # ← Vorhanden + ieee_address: "..." + model: "LED1842G3" + vendor: "IKEA" +``` + +### layout.yaml +**✅ Enthält Room-Mapping:** +```yaml +rooms: + - name: "Schlafzimmer" + devices: + - device_id: thermostat_wolfgang +``` + +**✅ Resolver bereits vorhanden:** `apps/api/resolvers.py::get_room(device_id)` + +--- + +## 8. Priorisierte To-Do-Liste + +### 🔴 **Kritisch** (Bridge funktioniert nicht ohne) + +1. **GET /devices: Fehlende Felder ergänzen** + - `cap_version` aus devices.yaml + - `room` via `get_room()` + - `friendly_name` aus `metadata.friendly_name` + - `technology` aus devices.yaml + - `read_only` berechnen + +2. **GET /devices/{device_id}/state implementieren** + - Neuer Endpoint + - State aus Cache + Metadaten + - Timestamp hinzufügen + +### 🟡 **Wichtig** (Bridge funktioniert, aber eingeschränkt) + +3. **SSE /realtime: Events enrichen** + - `device_type` hinzufügen + - `room` hinzufügen + - `ts` sicherstellen + +4. **GET /devices/{device_id} implementieren** + - Einzelgerät-Abfrage + - Gleiche Struktur wie `/devices`-Eintrag + +### 🟢 **Nice-to-have** + +5. **State-Cache mit Timestamps erweitern** + - Aktuell: `device_states[id] = payload` + - Ziel: `device_states[id] = {payload, ts}` + +6. **SSE: source-Feld hinzufügen** + - Aus `device["technology"]` ableiten + +--- + +## 9. Implementierungs-Reihenfolge + +### Phase 1: GET /devices erweitern +**Dateien:** +- `apps/api/main.py` (DeviceInfo-Modell, get_devices()) + +**Änderungen:** +```python +class DeviceInfo(BaseModel): + device_id: str + type: str + cap_version: str + room: str | None + friendly_name: str + technology: str + features: dict[str, Any] + read_only: bool + tags: list[str] | None = None + +@app.get("/devices") +async def get_devices() -> list[DeviceInfo]: + devices = load_devices() + return [ + DeviceInfo( + device_id=device["device_id"], + type=device["type"], + cap_version=device["cap_version"], + room=get_room(device["device_id"]), + friendly_name=device.get("metadata", {}).get("friendly_name", device["device_id"]), + technology=device["technology"], + features=device.get("features", {}), + read_only="set" not in device.get("topics", {}), + tags=device.get("tags") + ) + for device in devices + ] +``` + +### Phase 2: GET /devices/{device_id}/state +**Dateien:** +- `apps/api/main.py` + +**Neues Modell:** +```python +class DeviceStateResponse(BaseModel): + device_id: str + type: str + room: str | None + payload: dict[str, Any] + ts: str + +@app.get("/devices/{device_id}/state") +async def get_device_state(device_id: str) -> DeviceStateResponse: + if device_id not in device_states: + raise HTTPException(404, f"No state for {device_id}") + + devices = load_devices() + device = next((d for d in devices if d["device_id"] == device_id), None) + if not device: + raise HTTPException(404, f"Device {device_id} not found") + + return DeviceStateResponse( + device_id=device_id, + type=device["type"], + room=get_room(device_id), + payload=device_states[device_id], + ts=datetime.utcnow().isoformat() + "Z" + ) +``` + +### Phase 3: SSE Enrichment +**Dateien:** +- `apps/api/main.py` (event_generator()) + +**Im event_generator() nach JSON-Parse:** +```python +if message and message["type"] == "message": + data = message["data"] + state_data = json.loads(data) + + # Enrich events + if state_data.get("type") == "state" and state_data.get("device_id"): + device_id = state_data["device_id"] + devices = load_devices() + device = next((d for d in devices if d["device_id"] == device_id), None) + + if device: + state_data["device_type"] = device["type"] + state_data["room"] = get_room(device_id) + if "ts" not in state_data: + state_data["ts"] = datetime.utcnow().isoformat() + "Z" + state_data["source"] = device.get("technology") + + data = json.dumps(state_data) + + yield f"event: message\ndata: {data}\n\n" +``` + +### Phase 4: GET /devices/{device_id} +**Dateien:** +- `apps/api/main.py` + +```python +@app.get("/devices/{device_id}") +async def get_device(device_id: str) -> DeviceInfo: + devices = load_devices() + device = next((d for d in devices if d["device_id"] == device_id), None) + + if not device: + raise HTTPException(404, f"Device {device_id} not found") + + return DeviceInfo( + device_id=device["device_id"], + type=device["type"], + cap_version=device["cap_version"], + room=get_room(device["device_id"]), + friendly_name=device.get("metadata", {}).get("friendly_name", device["device_id"]), + technology=device["technology"], + features=device.get("features", {}), + read_only="set" not in device.get("topics", {}), + tags=device.get("tags") + ) +``` + +--- + +## 10. Zusammenfassung der Abweichungen + +### ✅ Bereits konform (40%) +- POST /devices/{id}/set - Vollständig implementiert +- SSE /realtime - Grundfunktion vorhanden +- GET /devices - Grundstruktur vorhanden + +### ⚠️ Teilweise konform (40%) +- GET /devices - Fehlen wichtige Felder (cap_version, room, friendly_name, technology, read_only) +- SSE /realtime - Events ohne device_type, room, ts + +### ❌ Nicht vorhanden (20%) +- GET /devices/{device_id}/state - Komplett fehlend +- GET /devices/{device_id} - Komplett fehlend + +--- + +## 11. Risiko-Bewertung + +### 🟢 **Geringes Risiko** +- Alle Daten sind in devices.yaml/layout.yaml vorhanden +- Resolver-Funktionen existieren bereits +- Pydantic-Modelle sind etabliert +- Keine Breaking Changes an bestehenden Endpoints nötig + +### 🟡 **Mittleres Risiko** +- SSE-Enrichment könnte Performance beeinflussen (load_devices() bei jedem Event) + - **Mitigation:** Device-Lookup cachen +- Timestamp-Handling muss konsistent sein + - **Mitigation:** UTC + ISO8601 + "Z" Suffix + +### 🔴 **Kein hohes Risiko identifiziert** + +--- + +## 12. Nächste Schritte + +1. **Freigabe einholen:** Sollen wir mit Phase 1 (GET /devices erweitern) starten? +2. **Testing-Strategie:** Sollen Tests für die neuen Endpoints geschrieben werden? +3. **Backward Compatibility:** GET /devices ändert Response-Struktur - ist das OK? (Vermutlich ja, da UI diese Felder ignorieren kann) +4. **Performance:** Device-Lookup-Cache implementieren vor SSE-Enrichment? + +--- + +**Ende der Analyse** diff --git a/apps/api/main.py b/apps/api/main.py index 628c0a7..373f8f0 100644 --- a/apps/api/main.py +++ b/apps/api/main.py @@ -1,4 +1,144 @@ -"""API main entry point.""" +"""API main entry point. + +API-Analyse für HomeKit-Bridge Kompatibilität +============================================== + +1) GET /devices + Status: ✅ VORHANDEN (Zeile 325-343) + + Aktuelles Response-Modell (DeviceInfo, Zeile 189-194): + { + "device_id": str, ✅ OK + "type": str, ✅ OK + "name": str, ⚠️ ABWEICHUNG: Erwartet wurde "short_name" (optional) + "features": dict ✅ OK + } + + Bewertung: + - ✅ Liefert device_id, type, features wie erwartet + - ⚠️ Verwendet "name" statt "short_name" + - ✅ Fallback auf device_id wenn name nicht vorhanden + - Kompatibilität: HOCH - einfach "name" als "short_name" verwenden + + +2) GET /layout + Status: ✅ VORHANDEN (Zeile 354-387) + + Aktuelles Response-Format: + { + "rooms": [ + { + "name": "Schlafzimmer", + "devices": [ + { + "device_id": "thermostat_wolfgang", + "title": "Thermostat Wolfgang", ← friendly_name + "icon": "thermometer", + "rank": 1 + } + ] + } + ] + } + + Mapping device_id -> room, friendly_name: + - room: Durch Iteration über rooms[].devices[] ableitbar + - friendly_name: Im Feld "title" enthalten + + Bewertung: + - ✅ Alle erforderlichen Informationen vorhanden + - ⚠️ ABWEICHUNG: Verschachtelte Struktur (rooms -> devices) + - ⚠️ ABWEICHUNG: friendly_name heißt "title" + - Kompatibilität: HOCH - einfache Transformation möglich: + ```python + for room in layout["rooms"]: + for device in room["devices"]: + mapping[device["device_id"]] = { + "room": room["name"], + "friendly_name": device["title"] + } + ``` + + +3) POST /devices/{device_id}/set + Status: ✅ VORHANDEN (Zeile 406-504) + + Aktuelles Request-Modell (SetDeviceRequest, Zeile 182-185): + { + "type": str, ✅ OK - muss zum Gerätetyp passen + "payload": dict ✅ OK - abstraktes Kommando + } + + Beispiel Light: + POST /devices/leselampe_esszimmer/set + {"type": "light", "payload": {"power": "on", "brightness": 80}} + + Beispiel Thermostat: + POST /devices/thermostat_wolfgang/set + {"type": "thermostat", "payload": {"target": 21.0}} + + Validierung: + - ✅ Type-spezifische Payload-Validierung (Zeile 437-487) + - ✅ Read-only Check → 405 METHOD_NOT_ALLOWED (Zeile 431-435) + - ✅ Ungültige Payload → 422 UNPROCESSABLE_ENTITY + - ✅ Device nicht gefunden → 404 NOT_FOUND + + Bewertung: + - ✅ Exakt wie erwartet implementiert + - ✅ Alle geforderten Error Codes vorhanden + - Kompatibilität: PERFEKT + + +4) Realtime-Endpoint (SSE) + Status: ✅ VORHANDEN als GET /realtime (Zeile 608-632) + + Implementierung: + - ✅ Server-Sent Events (media_type="text/event-stream") + - ✅ Redis Pub/Sub basiert (event_generator, Zeile 510-607) + - ✅ Safari-kompatibel (Heartbeats, Retry-Hints) + + Aktuelles Event-Format (aus apps/abstraction/main.py:250-256): + { + "type": "state", ✅ OK + "device_id": str, ✅ OK + "payload": dict, ✅ OK - z.B. {"power":"on","brightness":80} + "ts": str ✅ OK - ISO-8601 format von datetime.now(timezone.utc) + } + + Beispiel-Event: + { + "type": "state", + "device_id": "thermostat_wolfgang", + "payload": {"current": 19.5, "target": 21.0}, + "ts": "2025-11-17T14:23:45.123456+00:00" + } + + Bewertung: + - ✅ Alle geforderten Felder vorhanden + - ✅ Timestamp im korrekten Format + - ✅ SSE mit proper headers und error handling + - Kompatibilität: PERFEKT + + +ZUSAMMENFASSUNG +=============== + +Alle 4 geforderten Endpunkte sind implementiert! + +Kompatibilität mit HomeKit-Bridge Anforderungen: +- GET /devices: HOCH (nur Name-Feld unterschiedlich) +- GET /layout: HOCH (Struktur-Transformation nötig) +- POST /devices/{id}/set: PERFEKT (1:1 wie gefordert) +- GET /realtime (SSE): PERFEKT (1:1 wie gefordert) + +Erforderliche Anpassungen für Bridge: +1. GET /devices: "name" als "short_name" interpretieren ✓ trivial +2. GET /layout: Verschachtelte Struktur zu flat mapping umwandeln ✓ einfach + +Keine Code-Änderungen in der API erforderlich! +Die Bridge kann die bestehenden Endpoints direkt nutzen. + +""" import asyncio import json diff --git a/apps/homekit/README.md b/apps/homekit/README.md new file mode 100644 index 0000000..c60a39b --- /dev/null +++ b/apps/homekit/README.md @@ -0,0 +1,465 @@ +# HomeKit Bridge + +HomeKit Accessory Protocol (HAP) Bridge für das Home Automation System. + +## Überblick + +Diese HomeKit-Bridge ermöglicht die Steuerung aller Geräte über Apple HomeKit / Home-App auf iPhone/iPad/Mac. + +**Architektur:** +- Läuft auf Raspberry Pi im lokalen Netzwerk +- Kommuniziert ausschließlich über REST-API (kein direkter MQTT/Redis-Zugriff) +- Verwendet [HAP-Python](https://github.com/ikalchev/HAP-python) für HomeKit-Protokoll +- Unterstützt Echtzeit-Updates über Server-Sent Events (SSE) + +## Implementierungsanleitung für Copilot + +
+Copilot-Aufgabe: Implementiere die HomeKit-Bridge (HAP-Python) für unser System + +### Kontext + +- Wir verwenden HAP-Python als HomeKit-Bridge. +- Die Bridge läuft auf einem Raspberry Pi im gleichen LAN wie die iPhones. +- Die Bridge kommuniziert AUSSCHLIESSLICH über die REST-API mit dem restlichen System (KEIN direkter MQTT-/Redis-Zugriff). +- Geräte- und Raum-Infos kommen aus: + - `GET /devices` + - `GET /layout` + und werden über `device_id` gejoint. +- Die Abbildung von abstrakten Gerätetypen/Features auf HomeKit-Services/Characteristics steht in der Datei `apps/homekit/homekit_mapping.md` (Markdown-Tabelle). Bitte orientiere dich daran. + +### Ziel + +Implementiere eine lauffähige HomeKit-Bridge in `apps/homekit`, die: +- beim Start Geräte & Räume über die API lädt, +- daraus anhand der Mapping-Tabelle HomeKit-Accessories erzeugt, +- Zustandsänderungen über einen Realtime-Endpoint der API empfängt und in HomeKit spiegeln kann, +- Set-Kommandos aus HomeKit (z.B. Licht an/aus, Helligkeit, Zieltemperatur) per `POST /devices/{id}/set` an die API sendet, +- saubere Start-/Stop-Logs ausgibt, +- einfache Test-/Startanweisungen für den Raspberry Pi und die Home-App (iPhone) in Kommentaren dokumentiert. + +### WICHTIG + +- Bitte benutze HAP-Python (pyhap). +- Keine direkte MQTT- oder Redis-Kommunikation in der Bridge. +- Nutze HTTP(S) zur API (z.B. mit requests oder httpx; gerne sync, HAP-Python ist selbst eventloop-orientiert). +- Nutze die Mapping-Tabelle in `apps/homekit/homekit_mapping.md` als Leitlinie für die Accessory-Typen. + +### Paketstruktur + +``` +apps/homekit/ +├── __init__.py +├── main.py # Einstiegspunkt +├── api_client.py # REST-Client zur API +├── device_registry.py # Join /devices + /layout → internes Device-Modell +├── accessories/ +│ ├── base.py # gemeinsame Basisklasse/n für Accessories +│ ├── light.py # Light-Accessories +│ ├── thermostat.py +│ ├── contact.py +│ ├── sensor.py # temp_humidity etc. +│ └── cover.py # optional, Rollladen +└── tests/ # rudimentäre Tests/Checks +``` + +## Teil 1: Internes Gerätemodell / Device-Registry + +### 1.1 Erstelle in `apps/homekit/device_registry.py`: + +**Dataklasse/Model Device:** +- `device_id: str` +- `type: str` - "light","thermostat","outlet","contact","temp_humidity","cover",... +- `name: str` - Kurzname aus `GET /devices.name` +- `friendly_name: str` - title aus `GET /layout` (fallback name) +- `room: str | None` - Raumname aus layout +- `features: dict[str, bool]` +- `read_only: bool` - heuristisch: Sensor-/Kontakt-Typen sind read_only + +**Klasse DeviceRegistry mit Funktionen:** +- `def load_from_api(api: ApiClient) -> DeviceRegistry`: + - ruft `GET /devices` und `GET /layout` auf, + - joint über `device_id`, + - erstellt Device-Instanzen. +- `get_all(): list[Device]` +- `get_by_id(device_id: str) -> Device | None` + +**Akzeptanz:** +- `load_from_api` funktioniert mit der bestehenden Struktur von `/devices` und `/layout`: + - `/devices` liefert mindestens `{device_id, type, name, features}` + - `/layout` liefert eine Struktur, aus der `device_id → room + title` ableitbar ist +- Der Join über `device_id` klappt; fehlende Layout-Einträge werden toleriert + +## Teil 2: API-Client + +### 2.1 Erstelle in `apps/homekit/api_client.py`: + +**Klasse ApiClient mit:** +- `__init__(self, base_url: str, token: str | None = None, timeout: int = 5)` +- **Methoden:** + - `get_devices() -> list[dict]`: GET /devices + - `get_layout() -> dict`: GET /layout + - `get_device_state(device_id: str) -> dict`: GET /devices/{id}/state + - `post_device_set(device_id: str, type: str, payload: dict) -> None`: POST /devices/{id}/set + - `stream_realtime() -> Iterator[dict]`: + - GET /realtime als SSE, yield jedes Event als dict: + `{"type":"state","device_id":...,"payload":{...},"ts":...}` + +**Auth:** +- Wenn ein API-Token via ENV `HOMEKIT_API_TOKEN` gesetzt ist, nutze HTTP-Header: + `Authorization: Bearer ` + +**Akzeptanz:** +- ApiClient ist robust: + - bei Netzwerkfehlern gibt es sinnvolle Exceptions/Logs, + - `stream_realtime` behandelt Reconnect (z.B. einfache Endlosschleife mit Backoff). +- Es werden keine MQTT-Details verwendet, nur HTTP. + +## Teil 3: HomeKit-Accessory-Klassen (HAP-Python) + +### 3.1 Erstelle in `apps/homekit/accessories/base.py`: + +**Basisklasse BaseDeviceAccessory(Accessory) mit:** +- Referenz auf Device (aus DeviceRegistry) +- Referenz auf ApiClient +- Methoden zum: + - Registrieren von HAP-Characteristics und Set-Handlern + - Aktualisieren von Characteristics bei eingehenden Events +- Logging + +### 3.2 Erstelle spezifische Accessory-Klassen basierend auf homekit_mapping.md: + +**LightAccessories (`apps/homekit/accessories/light.py`):** +- On/Off (nur power) +- Dimmable (power + brightness) +- Color (power + brightness + color_hsb) + +**ThermostatAccessory:** +- CurrentTemperature, TargetTemperature, Mode (so weit in Mapping definiert) + +**ContactAccessory:** +- ContactSensorState (open/closed) + +**TempHumidityAccessory:** +- TemperatureSensor (CurrentTemperature) +- HumiditySensor (CurrentRelativeHumidity) + +**OutletAccessory:** +- On/Off + +**CoverAccessory (optional):** +- WindowCovering mit CurrentPosition/TargetPosition + +**Die Mapping-Tabelle in `homekit_mapping.md` ist die normative Referenz:** +- Bitte lies die Tabelle und mappe `abstract_type + Features → passende Accessory-Klasse und Characteristics` +- Wo die Tabelle `Status=TODO/REVIEW` hat: + - Implementiere nur das, was eindeutig ist, + - lasse TODO-Kommentare an den entsprechenden Stellen im Code. + +**Akzeptanz:** +- Für die abstrakten Typen, die bereits in `devices.yaml` und Mapping-Tabelle klar definiert sind (z.B. light, thermostat, contact, temp_humidity), existieren passende Accessory-Klassen. +- Set-Operationen erzeugen korrekte Payloads für `POST /devices/{id}/set`: + - Light: `{"type":"light","payload":{"power":"on"/"off", "brightness":..., "hue":..., "sat":...}}` + - Thermostat: `{"type":"thermostat","payload":{"target":...}}` + - Contact: read_only → keine Set-Handler + - Temp/Humidity: read_only → keine Set-Handler + +## Teil 4: Bridge-Setup mit HAP-Python + +### 4.1 Implementiere in `apps/homekit/main.py`: + +**env-Konfiguration:** +- `HOMEKIT_NAME` (default: "Home Automation Bridge") +- `HOMEKIT_PIN` (z.B. "031-45-154") +- `HOMEKIT_PORT` (default 51826) +- `API_BASE` (z.B. "http://api:8001" oder extern) +- `HOMEKIT_API_TOKEN` (optional) + +**Funktion `build_bridge(driver, api_client: ApiClient) -> Bridge`:** +- DeviceRegistry via `load_from_api(api_client)` laden. +- Für jedes Device anhand Mapping-Tabelle die passende Accessory-Klasse instanziieren. +- Einen Bridge-Accessory (`pyhap.accessory.Bridge`) erstellen. +- Alle Device-Accessories der Bridge hinzufügen. + +**Realtime-Event-Loop:** +- In einem Hintergrund-Thread oder ThreadPool: + - `api_client.stream_realtime()` iterieren, + - für jedes Event `device_id → Accessory` finden, + - Characteristics updaten. +- Thread wird beim Shutdown sauber beendet. + +**`main()`:** +- Logging einrichten. +- ApiClient erstellen. +- `AccessoryDriver(port=HOMEKIT_PORT, persist_file="homekit.state")` erstellen. +- Bridge via `build_bridge(driver, api_client)` bauen. +- Bridge dem Driver hinzufügen. +- Realtime-Thread starten. +- `driver.start()` aufrufen. +- Auf KeyboardInterrupt reagieren und sauber stoppen. + +**Akzeptanz:** +- Beim Start loggt die Bridge: + - Anzahl Devices, + - auf welchem Port sie als HomeKit-Bridge lauscht, + - welches API_BASE verwendet wird. +- Die Datei `homekit.state` wird im Arbeitsverzeichnis bzw. einem konfigurierbaren Ordner abgelegt (um Pairing-Info persistent zu halten). +- Die Bridge übersteht API-Neustarts (Realtime-Loop reconnectet) und Netzwerkflaps. + +## Teil 5: Tests & Testanweisungen + +### 5.1 Lege in `apps/homekit/tests/` einfache Tests/Checks an: + +**Unit-Tests (pytest), soweit ohne echtes HomeKit möglich:** +- Test für `DeviceRegistry.load_from_api()` mit Mock-Antworten aus `/devices` und `/layout`: + - Korrekte Join-Logik, + - Korrekte room/friendly_name-Zuordnung. +- Test für set-Payload-Erzeugung pro Accessory: + - z.B. LightAccessory: On=True → POST /devices/{id}/set wird mit korrektem Payload aufgerufen (über Mock ApiClient). + +### Allgemein + +- Nutze möglichst sinnvolle Typannotationen und Docstrings. +- Hinterlasse TODO-Kommentare an Stellen, wo die Mapping-Tabelle explizit Status=TODO/REVIEW hat. +- Ändere KEINE bestehenden API-Endpunkte; verlasse dich nur auf deren aktuelles Verhalten (GET /devices, GET /layout, /realtime, POST /devices/{id}/set). + + +## Installation & Setup + +### Voraussetzungen + +- Python 3.9+ +- Raspberry Pi im gleichen LAN wie iPhone/iPad +- API-Server erreichbar (z.B. `http://api:8001`) + +### Installation + +```bash +cd apps/homekit +pip install -r requirements.txt +``` + +### Umgebungsvariablen + +Erstelle eine `.env` Datei oder setze folgende Variablen: + +```bash +export API_BASE="http://YOUR_API_IP:8001" +export HOMEKIT_API_TOKEN="your-token-if-needed" # optional +export HOMEKIT_PIN="031-45-154" +export HOMEKIT_NAME="Home Automation Bridge" +export HOMEKIT_PORT="51826" +export HOMEKIT_PERSIST_FILE="homekit.state" +``` + +## Start + +```bash +python -m apps.homekit.main +``` + +**Erwartete Logs:** +``` +Loading devices from API... +Loaded X devices from API +Bridge built with Y accessories +HomeKit Bridge started on port 51826 +Starting realtime event loop... +``` + +## Pairing mit iPhone (Home-App) + +1. **Voraussetzungen:** + - iPhone im gleichen WLAN wie Raspberry Pi + - Bridge läuft und zeigt "started on port 51826" + +2. **Home-App öffnen:** + - Öffne die Home-App auf dem iPhone + - Tippe auf "+" → "Gerät hinzufügen" + - Wähle "Weitere Optionen..." oder "Code fehlt oder kann nicht gescannt werden" + +3. **Bridge auswählen:** + - Die Bridge sollte in der Nähe-Liste erscheinen (z.B. "Home Automation Bridge") + - Tippe auf die Bridge + +4. **PIN eingeben:** + - Gib den PIN ein: `031-45-154` (oder dein `HOMEKIT_PIN`) + - Format: `XXX-XX-XXX` + +5. **Konfiguration abschließen:** + - Geräte werden geladen + - Räume werden automatisch aus `layout.yaml` übernommen + - Geräte können nun über Home-App gesteuert werden + +## Funktionstests + +### Test 1: Licht einschalten + +**Aktion:** Lampe in Home-App antippen (On) + +**Erwartung:** +- API-Log zeigt: `POST /devices/{id}/set` mit `{"type":"light","payload":{"power":"on"}}` +- Physische Lampe oder Simulator schaltet ein + +### Test 2: Helligkeit ändern (dimmbare Lampe) + +**Aktion:** Helligkeits-Slider bewegen (z.B. 75%) + +**Erwartung:** +- `POST /devices/{id}/set` mit `brightness` ca. 75 +- Lampe dimmt entsprechend + +### Test 3: Farbe ändern (Farblampe) + +**Aktion:** Farbe in Home-App wählen + +**Erwartung:** +- `POST /devices/{id}/set` mit `hue`/`sat` Werten +- Lampe wechselt Farbe + +### Test 4: Thermostat Zieltemperatur + +**Aktion:** Zieltemperatur auf 22°C setzen + +**Erwartung:** +- `POST /devices/{id}/set` mit `target=22` +- `CurrentTemperature` wird über `/realtime` aktualisiert + +### Test 5: Kontaktsensor (read-only) + +**Aktion:** Fenster physisch öffnen/schließen + +**Erwartung:** +- `/realtime` sendet Event +- Home-App zeigt "Offen" oder "Geschlossen" + +### Test 6: Temperatur-/Feuchtigkeitssensor + +**Aktion:** Werte ändern sich (z.B. Heizung an) + +**Erwartung:** +- `/realtime` Events aktualisieren Werte +- Home-App zeigt aktuelle Temperatur/Luftfeuchtigkeit + +## Troubleshooting + +### Bridge erscheint nicht in Home-App + +- **Netzwerk prüfen:** iPhone und RPi im gleichen Subnet? +- **Firewall prüfen:** Port 51826 muss erreichbar sein +- **Logs prüfen:** Fehler beim Start? +- **mDNS/Bonjour:** Funktioniert Bonjour im Netzwerk? + +### Geräte reagieren nicht + +- **API-Logs prüfen:** Kommen POST-Requests an? +- **Realtime-Verbindung:** Läuft `/realtime` Event-Loop? (Log-Meldungen) +- **API-Endpoints testen:** Manuell mit `curl` testen + +### Pairing schlägt fehl + +- **State-Datei löschen:** `rm homekit.state` und Bridge neu starten +- **PIN-Format prüfen:** Muss `XXX-XX-XXX` Format haben +- **Alte Pairings löschen:** In Home-App unter "Home-Einstellungen" → "HomeKit-Geräte zurücksetzen" + +### Realtime-Updates funktionieren nicht + +- **SSE-Verbindung prüfen:** Logs zeigen "Starting realtime event loop..."? +- **API-Endpoint testen:** `curl -N http://api:8001/realtime` +- **Firewall/Proxy:** Blockiert etwas SSE-Streams? + +## Docker Deployment + +### Dockerfile + +```dockerfile +FROM python:3.11-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY . . + +CMD ["python", "-m", "apps.homekit.main"] +``` + +### docker-compose.yml + +```yaml +services: + homekit: + build: ./apps/homekit + environment: + - API_BASE=http://api:8001 + - HOMEKIT_PIN=031-45-154 + - HOMEKIT_NAME=Home Automation Bridge + ports: + - "51826:51826" + volumes: + - ./data/homekit:/data + network_mode: "host" # Wichtig für mDNS/Bonjour Discovery + restart: unless-stopped +``` + +**Wichtig:** `network_mode: "host"` ist erforderlich für mDNS/Bonjour Discovery, damit die Bridge im lokalen Netzwerk gefunden werden kann. + +## Architektur + +``` +┌─────────────┐ +│ iPhone/ │ +│ Home-App │ +└──────┬──────┘ + │ HomeKit (HAP) + │ Port 51826 +┌──────▼──────────────────┐ +│ HomeKit Bridge │ +│ (HAP-Python) │ +│ - Device Registry │ +│ - Accessory Mapping │ +│ - SSE Event Loop │ +└──────┬──────────────────┘ + │ HTTP REST API + │ (GET /devices, POST /set, SSE /realtime) +┌──────▼──────────────────┐ +│ API Server │ +│ (FastAPI) │ +└──────┬──────────────────┘ + │ MQTT +┌──────▼──────────────────┐ +│ Abstraction Layer │ +│ (Zigbee2MQTT, MAX!) │ +└─────────────────────────┘ +``` + +## Weitere Dokumentation + +- **API-Mapping:** Siehe `homekit_mapping.md` für Device-Type → HomeKit-Service Mapping +- **API-Dokumentation:** Siehe API-Server README für Endpoint-Dokumentation +- **HAP-Python Docs:** https://github.com/ikalchev/HAP-python + +## Entwicklung + +### Tests ausführen + +```bash +pytest apps/homekit/tests/ +``` + +### Logs + +Die Bridge gibt detaillierte Logs aus: +- `INFO`: Normale Betriebsmeldungen (Start, Device-Anzahl, etc.) +- `DEBUG`: Detaillierte State-Updates und API-Calls +- `ERROR`: Fehler bei API-Kommunikation oder Accessory-Updates + +Log-Level über Environment-Variable steuern: +```bash +export LOG_LEVEL=DEBUG +``` + +## Lizenz + +Siehe Hauptprojekt-Lizenz. diff --git a/apps/homekit/homekit_mapping.md b/apps/homekit/homekit_mapping.md new file mode 100644 index 0000000..60fbd35 --- /dev/null +++ b/apps/homekit/homekit_mapping.md @@ -0,0 +1,111 @@ +` + - `` + +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) \ No newline at end of file diff --git a/apps/homekit/main.py b/apps/homekit/main.py new file mode 100644 index 0000000..226a93e --- /dev/null +++ b/apps/homekit/main.py @@ -0,0 +1,223 @@ +from .accessories.light import ( + OnOffLightAccessory, + DimmableLightAccessory, + ColorLightAccessory, +) + +# Configure logging +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' +) +logger = logging.getLogger(__name__) + + +# Environment configuration +HOMEKIT_NAME = os.getenv("HOMEKIT_NAME", "Home Automation Bridge") +HOMEKIT_PIN = os.getenv("HOMEKIT_PIN", "031-45-154") +HOMEKIT_PORT = int(os.getenv("HOMEKIT_PORT", "51826")) +API_BASE = os.getenv("API_BASE", "http://api:8001") +HOMEKIT_API_TOKEN = os.getenv("HOMEKIT_API_TOKEN") +PERSIST_FILE = os.getenv("HOMEKIT_PERSIST_FILE", "homekit.state") + + +def build_bridge(driver: AccessoryDriver, api_client: ApiClient) -> Bridge: + """ + Build the HomeKit Bridge with all device accessories. + + Args: + driver: HAP-Python AccessoryDriver + api_client: API client for communication with backend + + Returns: + Bridge accessory with all device accessories attached + """ + logger.info("Loading devices from API...") + registry = DeviceRegistry.load_from_api(api_client) + devices = registry.get_all() + logger.info(f"Loaded {len(devices)} devices from API") + + # Create bridge + bridge = Bridge(driver, HOMEKIT_NAME) + accessory_map = {} # device_id -> Accessory instance + + for device in devices: + try: + accessory = create_accessory_for_device(device, api_client, driver) + if accessory: + bridge.add_accessory(accessory) + accessory_map[device.device_id] = accessory + logger.info(f"Added accessory: {device.friendly_name} ({device.type})") + else: + logger.warning(f"No accessory mapping for device: {device.name} ({device.type})") + except Exception as e: + logger.error(f"Failed to create accessory for {device.name}: {e}", exc_info=True) + + # Store accessory_map on bridge for realtime updates + bridge._accessory_map = accessory_map + + logger.info(f"Bridge built with {len(accessory_map)} accessories") + return bridge + + +def create_accessory_for_device(device, api_client: ApiClient, driver: AccessoryDriver): + """ + Create appropriate HomeKit accessory based on device type and features. + + Maps device types to HomeKit accessories according to homekit_mapping.md. + """ + device_type = device.type + features = device.features + + # Light accessories + if device_type == "light": + if features.get("color_hsb"): + return ColorLightAccessory(driver, device, api_client) + elif features.get("brightness"): + return DimmableLightAccessory(driver, device, api_client) + else: + return OnOffLightAccessory(driver, device, api_client) + + # Thermostat + elif device_type == "thermostat": + return ThermostatAccessory(driver, device, api_client) + + # Contact sensor + elif device_type == "contact": + return ContactAccessory(driver, device, api_client) + + # Temperature/Humidity sensor + elif device_type == "temp_humidity": + return TempHumidityAccessory(driver, device, api_client) + + # Outlet/Switch + elif device_type == "outlet": + return OutletAccessory(driver, device, api_client) + + # Cover/Blinds (optional) + elif device_type == "cover": + # TODO: Implement CoverAccessory based on homekit_mapping.md + return CoverAccessory(driver, device, api_client) + + # TODO: Add more device types as needed (lock, motion, etc.) + + return None + + +def realtime_event_loop(api_client: ApiClient, bridge: Bridge, stop_event: threading.Event): + """ + Background thread that listens to realtime events and updates accessories. + + Args: + api_client: API client + bridge: HomeKit bridge with accessories + stop_event: Threading event to signal shutdown + """ + logger.info("Starting realtime event loop...") + + while not stop_event.is_set(): + try: + for event in api_client.stream_realtime(): + if stop_event.is_set(): + break + + # Handle state update events + if event.get("type") == "state": + device_id = event.get("device_id") + payload = event.get("payload", {}) + + # Find corresponding accessory + accessory = bridge._accessory_map.get(device_id) + if accessory and hasattr(accessory, 'update_state'): + try: + accessory.update_state(payload) + logger.debug(f"Updated state for {device_id}: {payload}") + except Exception as e: + logger.error(f"Error updating accessory {device_id}: {e}") + + except Exception as e: + if not stop_event.is_set(): + logger.error(f"Realtime stream error: {e}. Reconnecting in 5s...") + stop_event.wait(5) # Backoff before reconnect + + logger.info("Realtime event loop stopped") + + +def main(): + logger.info("=" * 60) + logger.info(f"Starting HomeKit Bridge: {HOMEKIT_NAME}") + logger.info(f"API Base: {API_BASE}") + logger.info(f"HomeKit Port: {HOMEKIT_PORT}") + logger.info(f"PIN: {HOMEKIT_PIN}") + logger.info("=" * 60) + + # Create API client + api_client = ApiClient( + base_url=API_BASE, + token=HOMEKIT_API_TOKEN, + timeout=10 + ) + + # Test API connectivity + try: + devices = api_client.get_devices() + logger.info(f"API connectivity OK - {len(devices)} devices available") + except Exception as e: + logger.error(f"Failed to connect to API at {API_BASE}: {e}") + logger.error("Please check API_BASE and network connectivity") + sys.exit(1) + + # Create AccessoryDriver + driver = AccessoryDriver( + port=HOMEKIT_PORT, + persist_file=PERSIST_FILE + ) + + # Build bridge with all accessories + try: + bridge = build_bridge(driver, api_client) + except Exception as e: + logger.error(f"Failed to build bridge: {e}", exc_info=True) + sys.exit(1) + + # Add bridge to driver + driver.add_accessory(accessory=bridge) + + # Setup realtime event thread + stop_event = threading.Event() + realtime_thread = threading.Thread( + target=realtime_event_loop, + args=(api_client, bridge, stop_event), + daemon=True + ) + + # Signal handlers for graceful shutdown + def signal_handler(sig, frame): + logger.info("Received shutdown signal, stopping...") + stop_event.set() + driver.stop() + + signal.signal(signal.SIGINT, signal_handler) + signal.signal(signal.SIGTERM, signal_handler) + + # Start realtime thread + realtime_thread.start() + + # Start the bridge + logger.info(f"HomeKit Bridge started on port {HOMEKIT_PORT}") + logger.info(f"Pair with PIN: {HOMEKIT_PIN}") + logger.info("Press Ctrl+C to stop") + + try: + driver.start() + except KeyboardInterrupt: + logger.info("KeyboardInterrupt received") + finally: + logger.info("Stopping bridge...") + stop_event.set() + realtime_thread.join(timeout=5) + logger.info("Bridge stopped") + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/apps/homekit/requirements.txt b/apps/homekit/requirements.txt new file mode 100644 index 0000000..7852203 --- /dev/null +++ b/apps/homekit/requirements.txt @@ -0,0 +1,13 @@ +# HomeKit Bridge Dependencies +# HAP-Python - HomeKit Accessory Protocol implementation +HAP-python>=4.9.0 + +# HTTP client for API communication (REST API only - no MQTT) +httpx>=0.24.0 + +# Utilities +python-dotenv>=1.0.0 # For .env file support +pydantic>=2.0.0 # For data validation (shared with main app) + +# Logging and monitoring (optional) +# sentry-sdk>=1.0.0 # Optional: Error tracking