🩺Fehlersuche

Typische Störungen mit Prüfschritten zum Abhaken. Jeder Schritt ist markiert: stammt er aus dem Wiki des Projekts, aus einem einzelnen Issue, aus dem Quelltext – oder ist es allgemeines HomeKit- und Netzwissen, das im Projekt selbst nicht dokumentiert ist.

🌳Entscheidungsbaum für „Keine Antwort“

HomeKit zeigt „Keine Antwort“
│
├─ Öffnet sich http://ccu.example.org:9874/ ?
│   ├─ nein ─> Dienst läuft nicht ─> Neustart, dann Log und *.crash lesen
│   └─ ja
│       ├─ Sind ALLE Bridges betroffen?
│       │   ├─ ja ──> Netz: gleiche IP wie beim Koppeln? gleiches Netzsegment? mDNS?
│       │   └─ nein > Firewall: hat die betroffene Instanz ihren Port (9877 + n) frei?
│       └─ Schaltet das Gerät, aber die Kachel bleibt alt?
│           └─ Rückweg: Ereignisserver 9875, Watchdog, Log im Debug-Modus

Eigene Zusammenfassung dieser App aus den unten belegten Prüfschritten.

🧯Symptome und Prüfschritte

8 von 8 Themen

Wiki des ProjektsIssue im Repository (Einzelfall)Quelltextallgemeines HomeKit-/Netzwissen

Läuft der Dienst überhaupt? Konfigurationsseite auf Port 9874 öffnen; antwortet sie nicht, Dienst neu starten.Wiki des Projekts
```
/usr/local/etc/config/rc.d/hap-homematic restart
```
Firewall der Zentrale: Jede HAP-Instanz braucht ihren eigenen Port ab 9877. Kam eine Instanz dazu, fehlt oft genau deren Port.Wiki des Projekts
Hat sich die IP-Adresse der Zentrale geändert? Die Bridges werden per mDNS angekündigt; im gemeldeten Fall half erst das Entfernen und erneute Hinzufügen der Instanz in HomeKit.Issue im Repository (Einzelfall)
Steuerzentrale neu starten – in einem Issue löste der Neustart des Apple TV das Problem; in einem anderen half nach einem Wechsel der Steuerzentrale der Neustart der HAP-Instanz.Issue im Repository (Einzelfall)
iPhone und Zentrale im selben Netzsegment? mDNS überschreitet keine Router- oder VLAN-Grenze. Zwischen getrennten Netzen braucht es einen mDNS-Reflector und freigegebene HAP-Ports.allgemeines HomeKit-/Netzwissen

Quellen:Wiki – Troubleshooting Issue #230 – „Keine Antwort“ für alle Geräte Issue #667 – startet nach Update nicht mehr Issue #686 – ciao als mDNS-Advertiser RFC 6762 – Multicast DNS Home Assistant: HomeKit Bridge (Dokumentation)

Helfer: Dateien einer Instanz im Ordner „persist“

Wert user der Instanz aus der config.json eintragen:

Kennung: 123456E99E0C

persist/AccessoryInfo.123456E99E0C.json

persist/IdentifierCache.123456E99E0C.json

Das Wiki nennt die zweite Datei verkürzt „Identifier.…json“; HAP-NodeJS legt sie als IdentifierCache.…json an. Das Löschen entkoppelt die Bridge – sie muss danach neu zu HomeKit hinzugefügt werden.

Quellen:Wiki – Troubleshooting homebridge/HAP-NodeJS (Bibliothek, auf der da…

📜Protokoll und Debug-Modus

Protokoll

Der Dienst schreibt nach /var/log/hap-homematic.log (per SSH oder CUxD lesbar). Über „Log herunterladen“ kommt die Datei auch aus der Konfigurationsseite.

tail -f /var/log/hap-homematic.log

Quellen:Wiki – Troubleshooting

Debug-Modus

Unter „Internes“ auf Debug einschalten – der Menüpunkt heißt danach „Debug ausschalten“. Debug erzeugt sehr viel Ausgabe, deshalb wieder abschalten. Ein Neustart des Dienstes beendet den Debug-Modus und leert das Protokoll.

Quellen:Wiki – Troubleshooting

Debug beim nächsten Start

Liegt beim Start eine Datei .hapdebug im temporären Ordner, schaltet der Dienst Debug ein und löscht die Datei.

touch /tmp/.hapdebug

Quellen:Quelltext index.js (Kommandozeile)

Absturzprotokoll

Bei einer unbehandelten Ausnahme schreibt der Dienst <Zeitstempel>.crash in den Konfigurationsordner und beendet sich.

Quellen:Quelltext index.js (Kommandozeile)

🌐mDNS über Netzgrenzen (VLAN, Gäste-WLAN)

Dieser Abschnitt ist allgemeines Netz- und HomeKit-Wissen. Im Wiki und in den Issues des Projekts gibt es dazu keinen eigenen Eintrag.

Die Bridges kündigen sich per mDNS an. mDNS arbeitet mit Multicast im lokalen Netzsegment (IPv4 224.0.0.251, IPv6 ff02::fb, UDP-Port 5353) – Router leiten diese Pakete nicht weiter. Steht die Zentrale in einem eigenen VLAN, sehen iPhone und Steuerzentrale die Bridges deshalb nicht.

Zwei Dinge sind dann nötig:

ein mDNS-Reflector bzw. -Repeater auf dem Router (z. B. Avahi im Reflector-Modus), der die Ankündigungen zwischen den Netzen spiegelt,
Firewall-Regeln, die den Steuergeräten den Zugriff auf die HAP-Ports der Zentrale (9877 und folgende) erlauben.

VLAN 10 „Wohnen“            Router            VLAN 20 „Smart Home“
iPhone 192.0.2.50   <─ mDNS-Reflector ─>   CCU 198.51.100.10
Apple TV 192.0.2.60  ── TCP 9877…n  ─────>   Bridges

💡 Aus den Issues des Projekts

Belegt ist dort nur der verwandte Fall: Nach einem Wechsel der IP-Adresse der Zentrale waren alle Geräte ohne Antwort; der Autor verwies auf die Ankündigung per mDNS, geholfen hat das erneute Hinzufügen der Instanz.

Quellen:RFC 6762 – Multicast DNS Home Assistant: HomeKit Bridge (Dokumentation)Issue #230 – „Keine Antwort“ für alle Geräte homebridge/HAP-NodeJS (Bibliothek, auf der da…