# 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

<details>
<summary>Copilot-Aufgabe: Implementiere die HomeKit-Bridge (HAP-Python) für unser System</summary>

### 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 <token>`

**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.