🔁Ereignis-Debugger

Was passiert zwischen dem Tippen auf eine Kachel und dem Klacken des Relais? Und wie erfährt die Home-App, dass es geklappt hat? Wähle ein Szenario und gehe Schritt für Schritt durch – Adressen, Skripte und Werte werden aus dem Szenario berechnet.

🐞Hinweg und Rückweg

Schaltsteckdose im Musterhaus (Kanal 3), in HomeKit als „Outlet“. Adresse: HmIP-RF.000A1BE9A00001:3, Kanaltyp SWITCH_VIRTUAL_RECEIVER, Service-Klasse HomeMaticSwitchAccessory.

Schritt 1 / 11 · Tasten ← →

BefehlHome-App / Steuerzentrale → HAP-Instanz (Bridge)

1. Tippen in der Home-App

Die Home-App (oder die Steuerzentrale, wenn du unterwegs bist) schickt einen Schreibbefehl für die Characteristic On an die Bridge. Die Bridge ist die HAP-Instanz 0 des Addons und lauscht auf Port 9877 der CCU. Die Sitzung ist nach dem Koppeln verschlüsselt.

Beleg: HAP-NodeJS: HAPServer.ts (Route /characteristics), Verschlüsselung in util/hapCrypto.ts

(belegt in HAP-NodeJS)

Was über die Leitung geht

PUT /characteristics HTTP/1.1
Host: ccu.example.org:9877

{"characteristics":[{"aid":2,"iid":10,"value":true}]}

Bisheriger Weg

Quellen:Quelltext lib/services/ (71 Service-Klassen)Quelltext lib/HomeMaticCCU.js Quelltext lib/HomeMaticRegaRequest.js Quelltext lib/HomeMaticRPC.js Quelltext lib/HomeMaticAddress.js homebridge/HAP-NodeJS (Bibliothek, auf der da…VisualHomematic – Grundlagen-App dieser Samml…

🧠Drei Dinge, die der Debugger zeigt

💡 Schreiben per Skript, nicht per setValue

Befehle gehen als HomeMatic-Skript an die Logikschicht (dom.GetObject(…).State(…), HTTP-POST an Port 8181). Die XML-RPC-Verbindung dient dem Addon vor allem für die Rückrichtung.

✅ Rückmeldung ohne Abfragen

Weil sich das Addon mit init() als Ereignisempfänger anmeldet, schickt die Zentrale jede Änderung von selbst. Deshalb stimmt die Kachel auch, wenn jemand am Gerät selbst schaltet (Szenario „Am Gerät geschaltet“).

⚠️ Wo „Keine Antwort“ entsteht

Antwortet die Bridge auf dem HAP-Port nicht – Dienst gestoppt, Port in der Firewall zu, Bridge im Netz nicht auffindbar –, scheitert schon Schritt 1. Kommt nur die Rückmeldung nicht an, schaltet das Gerät zwar, die Kachel zeigt aber einen alten Zustand.

🚀Was beim Start des Dienstes passiert

Die Reihenfolge erklärt, warum die Rückmeldungen funktionieren – und warum jede Instanz einen eigenen Port belegt.

HAP-Instanzen3CUxD ist installiert

1
Startskript
Beim Hochfahren der CCU ruft /usr/local/etc/config/rc.d/hap-homematic start zuerst postinstall.sh auf. Fehlt der Dienst noch, wird er per npm i hap-homematic nachgeladen – deshalb braucht die erste Installation Internet.
addon_installer/rc.d/hap-homematic, addon_installer/etc/postinstall.sh
2
Einstellungen laden
config.json aus /usr/local/etc/config/addons/hap-homematic wird gelesen. Ist die Datei kein gültiges JSON, wird sie als config_<Zeit>.backup weggesichert und mit leerer Konfiguration gestartet.
lib/Server.js (loadSettings)
3
Config-WebUI startenPort 9874
Die Konfigurationsoberfläche lauscht – mit HTTPS, wenn die Einstellung gesetzt ist und /etc/config/server.pem existiert.
lib/configurationsrv/index.js
4
Schnittstellen erfragen
Per ReGa-Skript (Port 8181) fragt das Addon die Schnittstellen der Zentrale ab (root.Interfaces()): Name, Typ und URL – z. B. BidCos-RF, HmIP-RF, VirtualDevices.
lib/HomeMaticCCU.js (_fetchInterfaces)
5
Ereignisserver startenPort 9875
Ein XML-RPC-Server nimmt künftig die Ereignisse der Zentrale entgegen. Ist der Port belegt, bricht der Start mit „Sorry the local port 9875 on your system is in use“ ab.
lib/HomeMaticRPC.js (initServer)
6
init() an jeder Schnittstelle
Bei jeder benutzten Schnittstelle meldet sich das Addon als Ereignisempfänger an – Kennung HAP_<Schnittstelle>.. Ein Watchdog (Standard 300 s) meldet sich neu an, wenn so lange nichts mehr kam.
lib/HomeMaticRPC.js (connect, ccuWatchDog)
7
HAP-Instanz 0 veröffentlichenPort 9877
Bridge anlegen, zugeordnete Geräte, Variablen, Programme und Spezialgeräte laden, mit Kennung, Kopplungscode und Port veröffentlichen und per mDNS im Netz bekannt machen.
lib/Server.js (powerUpBridges, loadInstance)
8
HAP-Instanz 1 veröffentlichenPort 9878
Bridge anlegen, zugeordnete Geräte, Variablen, Programme und Spezialgeräte laden, mit Kennung, Kopplungscode und Port veröffentlichen und per mDNS im Netz bekannt machen.
lib/Server.js (powerUpBridges, loadInstance)
9
HAP-Instanz 2 veröffentlichenPort 9879
Bridge anlegen, zugeordnete Geräte, Variablen, Programme und Spezialgeräte laden, mit Kennung, Kopplungscode und Port veröffentlichen und per mDNS im Netz bekannt machen.
lib/Server.js (powerUpBridges, loadInstance)

Quellen:Quelltext addon_installer/ (Installer, rc.d-S…Quelltext lib/Server.js Quelltext lib/configurationsrv/ (Config-WebUI)Quelltext lib/HomeMaticCCU.js Quelltext lib/HomeMaticRPC.js

🔑Koppeln und Verschlüsselung – was HAP-NodeJS dabei tut

Das Addon implementiert das HomeKit Accessory Protocol nicht selbst, sondern nutzt die Bibliothek HAP-NodeJS. Aus deren Quelltext (nicht aus der Addon-Dokumentation) stammen diese Punkte:

Die Bridge kündigt sich per mDNS mit dem Diensttyp _hap._tcp an; der TXT-Eintrag enthält u. a. Kennung, Modell und ob sie schon gekoppelt ist.
Koppeln läuft über /pair-setup mit dem 8-stelligen Code (SRP-Verfahren), spätere Verbindungen über /pair-verify. Danach ist die Sitzung mit ChaCha20-Poly1305 verschlüsselt.
Lesen und Schreiben geschieht über /accessories und /characteristics; Änderungen kommen als EVENT/1.0-Nachricht zurück.
Der QR-Code in der Instanzliste enthält eine Setup-URI der Form X-HM://…, berechnet aus Code, Kategorie und Setup-ID.
HAP-NodeJS ist laut eigener Beschreibung keine von Apple zertifizierte Umsetzung.

Quellen:homebridge/HAP-NodeJS (Bibliothek, auf der da…HAP-NodeJS v0.11.1: src/lib/Accessory.ts Quelltext lib/Server.js