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)

npm install -g homebridge-gira-client

Lokal installieren

npm install homebridge-gira-client

Konfiguration

Grundkonfiguration

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

Erweiterte Konfiguration

{
  "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:

{
  "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

npm run build

Watch Mode

npm run watch

Linting

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.