homebridge-gira-client/README.md

Homebridge Plugin für Gira Homeserver 4 mit automatischer Geräteerkennung über IoT REST API

# Homebridge Gira Client Plugin

Ein vollständiges Homebridge Plugin für die Integration des Gira Homeserver 4 in Apple HomeKit über die Gira IoT REST API.

## Features

- **Gira IoT REST API Integration**: Automatische Verbindung und Authentifizierung mit dem Gira Homeserver 4
- **Automatische Geräteerkennung**: Alle kompatiblen Geräte werden automatisch erkannt und in HomeKit integriert
- **Gebäudestruktur-Unterstützung**: Erkennt und nutzt die Gira Gebäudehierarchie (Gebäude → Stockwerke → Räume)
- **Umfassende Geräteunterstützung**:
  - Schalter und Dimmer
  - Jalousien und Rollläden
  - Temperatur- und Feuchtigkeitssensoren
  - Heizungssteuerung/Thermostate
  - Szenen und weitere Sensoren
- **Statusaktualisierungen**: Regelmäßige Abfrage der Gerätestatus über REST API
- **Robuste Verbindung**: Automatische Wiederverbindung bei Verbindungsabbrüchen
- **Umfangreiche Konfiguration**: Detaillierte Filteroptionen für Räume und Gerätetypen
- **Debug-Modus**: Erweiterte Logging-Funktionen für Troubleshooting

## Voraussetzungen

Bevor Sie das Plugin verwenden können:

1. **Gira Homeserver 4** mit Firmware 4.10 oder höher
2. **Gira IoT REST API Lizenz** und Aktivierung:
   - Lizenz "IoT REST API" im Gira Project Assistant unter "System" → "Lizenzen"
   - Aktivierung unter "Einstellungen" → "IoT REST API"
3. **Homebridge** Installation 
4. **Netzwerkzugang** zum Homeserver (Port 80 oder 443)
5. **Gültige Anmeldedaten** für den Homeserver

## Installation

### Über Homebridge UI

1. Öffnen Sie die Homebridge Web UI
2. Navigieren Sie zu "Plugins"
3. Suchen Sie nach "homebridge-gira-client"
4. Klicken Sie auf "Install"

### Über npm (empfohlen)

```bash
npm install -g homebridge-gira-client
```

### Lokal installieren

```bash
npm install homebridge-gira-client
```

## Konfiguration

### Grundkonfiguration

```json
{
  "platforms": [
    {
      "platform": "GiraHomeserver",
      "name": "Gira Homeserver",
      "host": "192.168.1.100",
      "username": "ihr-benutzername",
      "password": "ihr-passwort"
    }
  ]
}
```

### Erweiterte Konfiguration

```json
{
  "platforms": [
    {
      "platform": "GiraHomeserver",
      "name": "Gira Homeserver",
      "host": "192.168.1.100",
      "port": 80,
      "username": "ihr-benutzername",
      "password": "ihr-passwort",
      "pollingInterval": 30000,
      "debugMode": false,
      "buildingStructure": {
        "useLocationHierarchy": true,
        "groupByFloor": true,
        "groupByBuilding": false,
        "customRoomMappings": {
          "Hauptgebäude_EG_Wohnzimmer": "Wohnzimmer",
          "Hauptgebäude_OG_Schlafzimmer": "Schlafzimmer"
        }
      },
      "deviceFilters": {
        "includeRooms": ["Wohnzimmer", "Schlafzimmer", "Küche"],
        "excludeRooms": ["Keller", "Technikraum"],
        "includeTypes": ["switching", "dimming", "blinds"],
        "excludeTypes": ["scene"],
        "includeTrades": ["Beleuchtung", "Beschattung"],
        "excludeTrades": ["Heizung"]
      }
    }
  ]
}
```

## Konfigurationsoptionen

### Pflichtfelder

| Option | Typ | Beschreibung |
|--------|-----|--------------|
| `platform` | string | Muss "GiraHomeserver" sein |
| `name` | string | Name der Plattform in HomeKit |
| `host` | string | IP-Adresse oder Hostname des Gira Homeserver 4 |
| `username` | string | Benutzername für die Authentifizierung |
| `password` | string | Passwort für die Authentifizierung |

### Optionale Felder

| Option | Typ | Standard | Beschreibung |
|--------|-----|----------|--------------|
| `port` | number | 80 | Port-Nummer des Homeservers (80 für HTTP, 443 für HTTPS) |
| `pollingInterval` | number | 30000 | Intervall für Statusabfragen in ms |
| `debugMode` | boolean | false | Aktiviert erweiterte Debug-Logs |

### Gebäudestruktur

| Option | Typ | Standard | Beschreibung |
|--------|-----|----------|--------------|
| `buildingStructure.useLocationHierarchy` | boolean | false | Raumnamen in Gerätenamen einbeziehen |
| `buildingStructure.groupByFloor` | boolean | false | Stockwerk-Information in Gerätenamen |
| `buildingStructure.groupByBuilding` | boolean | false | Gebäude-Information in Gerätenamen |
| `buildingStructure.customRoomMappings` | object | {} | Individuelle Raum-Namens-Zuordnungen |

### Gerätefilter

| Option | Typ | Beschreibung |
|--------|-----|--------------|
| `deviceFilters.includeRooms` | string[] | Nur Geräte aus diesen Räumen einbeziehen |
| `deviceFilters.excludeRooms` | string[] | Geräte aus diesen Räumen ausschließen |
| `deviceFilters.includeTypes` | string[] | Nur diese Gerätetypen einbeziehen |
| `deviceFilters.excludeTypes` | string[] | Diese Gerätetypen ausschließen |
| `deviceFilters.includeTrades` | string[] | Nur Geräte aus diesen Gewerken einbeziehen |
| `deviceFilters.excludeTrades` | string[] | Geräte aus diesen Gewerken ausschließen |

## Unterstützte Gerätetypen

| Gira Gerätetyp | HomeKit Service | Unterstützte Eigenschaften |
|----------------|----------------|----------------------------|
| Schalter (`switching`) | Switch | Ein/Aus |
| Dimmer (`dimming`) | Lightbulb | Ein/Aus, Helligkeit |
| Jalousie (`blinds`) | WindowCovering | Position, Bewegungsstatus |
| Temperatursensor (`temperature`) | TemperatureSensor | Aktuelle Temperatur |
| Feuchtigkeitssensor (`humidity`) | HumiditySensor | Aktuelle Luftfeuchtigkeit |
| Heizung (`heating`) | Thermostat | Temperatur, Heiz-/Kühlmodus |
| Sensor (`sensor`) | Verschiedene | Je nach Sensortyp |

## Troubleshooting

### Verbindungsprobleme

1. **Überprüfen Sie die Netzwerkverbindung**: Stellen Sie sicher, dass der Homebridge-Server den Gira Homeserver erreichen kann
2. **Firewall-Einstellungen**: Überprüfen Sie, ob der Port (Standard: 80) nicht blockiert ist
3. **Anmeldedaten**: Stellen Sie sicher, dass Benutzername und Passwort korrekt sind

### Debug-Modus aktivieren

Setzen Sie `debugMode: true` in der Konfiguration, um detaillierte Logs zu erhalten:

```json
{
  "debugMode": true
}
```

### Häufige Probleme

#### "Unexpected server response: 404"
- **REST API nicht aktiviert**: Die Gira IoT REST API muss am Homeserver aktiviert werden
  - Gehen Sie ins Gira Project Assistant (GPA)
  - Unter "System" → "Lizenzen" prüfen Sie ob "IoT REST API" lizenziert ist
  - Unter "Einstellungen" → "IoT REST API" aktivieren Sie diese
- Versuchen Sie Port 80 (HTTP) statt 443 (HTTPS)
- Prüfen Sie die Firmware-Version des Homeservers (mind. 4.10 erforderlich)
- Testen Sie manuell: `http://IP-ADRESSE/api/v2/` im Browser

#### "SSL/TLS Fehler (wrong version number)"
- Verwenden Sie Port 80 für HTTP statt 443 für HTTPS
- Viele Gira Homeserver verwenden HTTP für die REST API
- Stellen Sie den Port in der Konfiguration auf 80

#### "Connection timeout"
- Überprüfen Sie die Netzwerkverbindung zum Homeserver
- Versuchen Sie sowohl Port 80 (HTTP) als auch Port 443 (HTTPS)
- Überprüfen Sie die Firewall-Einstellungen

#### "Authentication failed"
- Überprüfen Sie Benutzername und Passwort
- Stellen Sie sicher, dass der Benutzer die erforderlichen Berechtigungen hat
- Prüfen Sie, ob der Benutzer für die IoT API freigegeben ist

#### "Certificate errors"
- Verwenden Sie HTTP (Port 80) um SSL-Probleme zu vermeiden
- Falls HTTPS erforderlich: Das Plugin ignoriert SSL-Zertifikatsfehler automatisch

## Entwicklung

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

### Linting

```bash
npm run lint
```

## Changelog

### Version 1.2.0
- **Umfassende Geräteerkennung**: Erweiterte Suche nach allen verfügbaren Gerätetypen im System
- **Multi-Source Discovery**: Nutzt verschiedene API-Endpunkte und Konfigurationsvarianten
- **Vollständige Erfassung**: Standardmäßig werden ALLE Geräte inkludiert (keine Filterung)
- **Verbesserte Diagnose**: Automatischer Export von Analyse-Dateien für alle gefundenen Geräte
- **Erweiterte Logs**: Detaillierte Informationen über jeden Erkennungsschritt
- **Alle Funktionstypen**: Unterstützung für sämtliche in der Gira-Konfiguration verfügbare Gerätetypen

### Version 1.1.0
- **Updated API Implementation**: Complete alignment with Gira IoT REST API v2 specification
- **Enhanced Authentication**: Proper Basic Auth for client registration as per API docs
- **HTTPS Enforcement**: Uses HTTPS by default as required by API specification
- **Extended Function Support**: Added support for all function types from API documentation including:
  - Colored Light and Tunable White functions
  - Audio and Sonos control
  - Camera and IP Link functions
  - All status and value transmitter types
- **Improved Error Handling**: Better error messages with API error codes
- **API Compliance**: Exact endpoint usage and parameter formats as documented

### Version 1.0.3
- **Vollständige Geräteerkennung**: Alle Gira Geräte werden automatisch abgerufen und eingebunden
- **Intelligente Typerkennung**: Erweiterte Erkennung aller Gira Funktionstypen 
- **Generische Mappings**: Unbekannte Gerätetypen werden automatisch als passende HomeKit-Geräte eingebunden
- **Gebäudestruktur-Support**: Vollständige Unterstützung für Gira Gebäudehierarchie
- **Erweiterte Filter**: Flexible Ein-/Ausschlussmöglichkeiten nach Räumen, Typen und Gewerken

### Version 1.0.2
- HTTP/HTTPS Fallback-Logik für bessere Verbindungskompatibilität
- Erweiterte Diagnose-Funktionen
- Mehrere API-Pfad Tests

### Version 1.0.0
- Initiale Veröffentlichung
- Gira IoT REST API Integration
- Grundlegende Gerätetyp-Unterstützung
- Automatische Geräteerkennung
- Regelmäßige Statusaktualisierungen
- Robuste Fehlerbehandlung und Wiederverbindung

## Beispiel-Konfiguration für Ihr Smart Home

Basierend auf Ihrer Gebäudestruktur siehe `example-config.json`:

### **Was das Plugin automatisch macht:**

🏠 **Alle Räume werden erkannt:**
- ✅ Erdgeschoss: Küche, Wohnzimmer, Arbeitszimmer, Bad EG, Esszimmer, etc.
- ✅ Obergeschoss: Schlafzimmer, Martin, Henri, Bäder, Ankleide
- ✅ Dachgeschoss: Gästezimmer
- ✅ Außenanlage: Beleuchtung, Garage, Freisitz
- ✅ Keller: Sauna

⚡ **Alle Gerätetypen werden automatisch integriert:**
- 💡 Beleuchtung (Schalter, Dimmer, RGB)
- 🏠 Jalousien und Rollläden
- 🌡️ Heizung und Thermostate
- 📡 Sensoren (Temperatur, Feuchtigkeit)
- 🎬 Szenen
- 🔊 Audio-Systeme
- 🚨 Sicherheitstechnik (nach Bedarf)

📱 **Intelligente HomeKit-Namen:**
- "Küche Licht" statt nur "Licht"
- "Martin Jalousie" statt nur "Jalousie"
- "EG Treppenhaus Bewegungsmelder"

Das Plugin erkennt automatisch **alle verfügbaren Geräte** aus Ihrer umfangreichen Gira-Installation und organisiert sie sinnvoll in HomeKit!

## Lizenz

MIT License - siehe LICENSE Datei für Details.

## Support

Bei Problemen oder Fragen:

1. Aktivieren Sie den Debug-Modus und überprüfen Sie die Logs
2. Erstellen Sie ein Issue auf GitHub mit:
   - Homebridge Version
   - Plugin Version
   - Gira Homeserver Version
   - Relevante Log-Ausgaben
   - Konfiguration (ohne Passwörter!)

## Credits

Entwickelt für die Integration von Gira Homeserver 4 Systemen in Apple HomeKit über Homebridge.

---

**Hinweis**: Dieses Plugin ist nicht offiziell von Gira entwickelt oder unterstützt. Es handelt sich um ein Community-Projekt.