homekit bridge initial
This commit is contained in:
553
HOMEKIT_BRIDGE_API_ANALYSIS.md
Normal file
553
HOMEKIT_BRIDGE_API_ANALYSIS.md
Normal file
@@ -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**
|
||||
Reference in New Issue
Block a user