In der ersten Folge dieser Serie habe ich gezeigt, wie man aus Node-Red direkt auf die HCU zugreift und ein Objekt mit allen HMIP-Daten abfragt. In diesem Teil der Serie erkläre ich die Datenstruktur, mit der sich der Status von Geräten abfragen lässt. Das wesentliche Dokument für alle folgenden Schritte ist dabei die Homematic IP Connect API Dokumentation.

Datenstruktur verstehen

Mithilfe des debug93-Nodes aus dem letzten Beitrag wurde die gesamte Datenstruktur der HCU ausgegeben. Bevor weitere Funktionen ergänzt werden, ist es wichtig, die Grundstruktur zu verstehen. Ich fokussiere mich hier nur auf die Geräte und deren besondere Attribute (Gruppen oder Clients werden nicht betrachtet). HMIP-Geräte werden als Devices bezeichnet.

Die Datenwerte eines Geräts werden in der HCU als Features bezeichnet (z. B. Temperatur), die einen Wert beinhalten können. Jedes Device besitzt einen „Type”, der genau angibt, welche Features obligatorisch oder optional zu einem Device-Objekt gehören.

Die Struktur des HCU-Datenobjektes mit den relevanten Daten zum Auslesen und Verarbeiten von Geräten ist in der folgenden Grafik dargestellt (blaue Kästchen sind Objekte, weiße Kästchen sind Attribute):

Bei Änderungen schickt die HCU nur die geänderten Objekte. Der Gedanke dahinter ist, dass die Kommunikation deutlich schneller funktioniert, wenn nur die Änderungen übermittelt werden. Die Datenstruktur mit den Änderungen ist leicht anders und wird in folgender Grafik dargestellt (blaue Kästchen sind Objekte, weiße Kästchen Attribute):

Device Eigenschaften

Jedes Gerät besitzt das Attribut „type“, das angibt, welche „Features“ es unterstützt. Mit den Features sind in der Regel die Daten der Sensorwerte, der Zustand eines Schalters etc. gemeint.

Die möglichen Features ergeben sich aus den Beschreibungen in Kapitel 6.6.5 der Connect-API-Dokumentation.

Für den HMIP-Bewegungsmelder (HMIP-SMI) vom Typ „OCCUPANCY_SENSOR” sind dies beispielsweise die Features:

• presenceDetected (true oder false)
• unreach (true oder false, gehört zum Feature Maintenance)
• lowbat (true oder false, gehört zum Feature Maintenance)
• sabotage (true oder false, gehört zum Feature Maintenance)

Diese stehen in einem zweidimensionalen Array im Objektbereich "Functional Channels".

Plugin Messages auswerten

Wenn eine Nachricht von der HCU an Node-Red übermittelt wird, dann wird auch immer der Typ der Nachricht (PluginMessageType) übertragen. Dieser steht unter payload.type. Im Folgenden sind zunächst nur die folgenden Werte interessant (weitere Typen sind in Kapitel 6.4 der API erläutert):

Zwischenspeicherung der HCU-Daten

eQ3 empfiehlt, den gesamten Status aller Objekte (Devices, Gruppen etc.) auf der HCU nur einmal nach Aufbau der Verbindung abzuholen und in einem Cache zwischenzuspeichern. Gibt es Änderungen an den Daten, schickt die HCU nur die geänderten Objekte. Dahinter steckt der Gedanke, dass die Kommunikation deutlich schneller funktioniert, wenn nur Änderungen übermittelt werden. Daher empfiehlt eQ3 auch, die initialen HCU-Daten zwischenzuspeichern und bei jedem Update den geänderten Teil zu ersetzen. Damit sind im Speicher immer alle Daten der HCU auf dem aktuellen Stand verfügbar.

Um die Daten nach dem Aufbau der Websocket-Verbindung abfragen zu können, nutze ich einen Input-Node, der zwei Sekunden nach dem Start eine HMIP_SYSTE_REQUEST-Nachricht in der folgenden Form verschickt:

Ich realisiere dies einfach durch Abfrage des PluginMessageType.  Hat dieser den Wert "HMIP_SYSTEM_RESPONSE", dann speichere ich den payload Wert in meiner Node-Red Flow-Variablen "f_systemresponse". Ich ergänze dies in meinem Flow am Ende des Beitrag1 Mit Node-RED auf die HMIP Home Control Unit (HCU) zugreifen Teil 1

Status eines Device abfragen

Auf Basis der in den vorigen Abschnitten beschriebenen Grundlagen kann nun die Statusabfrage eines Geräts erfolgen. Ich möchte beispielsweise für einen Bewegungsmelder abfragen, ob er eine Bewegung erkannt hat oder nicht. Dazu verwende ich einen Input-Node, in dem ich die Seriennummer angebe sowie das Feature „presenceDetected”, welches zu diesem Gerätetyp bereitgestellt wird.

Anschließend verwende ich die Daten in einem Function-Node. Nach diversen Prüfungen führt dieser die Suche nach der normierten Seriennummer durch, holt sich das passende Device-Objekt aus dem HCU-Objekt und extrahiert das Feature bzw. den Wert des Attributs.

Ausblick

Nach der Einführung der neuen HMIP-Zentrale HCU (Home Control Unit) hat eQ-3 eine API veröffentlicht, mit der man eigene Plugins erstellen und auf die HMIP-Daten zugreifen kann. Im Herbst 2025 wurde angekündigt, dass die auch von mir genutzte CCU3 vom eQ-3 nicht weiterentwickelt, sondern in dem freien Modell OpenCCU (ehemals Raspberrymatic) durch die Community weitergepflegt werden soll.

Ich habe auf der CCU3 viel programmiert und mit Node-RED auf die CCU3-Geräte zugegriffen. Jetzt will ich prüfen, wie gut man die HCU in Node-RED einbinden kann, um langfristig von der CCU auf die HCU zu wechseln.

Im ersten Schritt möchte ich eine Verbindung zwischen Node-RED und der HCU aufbauen und erste Daten von HMIP-Geräten empfangen. Ich nehme vorweg, das Ganze funktioniert einfacher als erwartet. In den folgenden Kapiteln beschreibe ich dazu detailliert die Vorgehensweise. Das wesenliche Dokument für alle folgenden Schritte ist dabei die Homematic IP Connect API Dokumentation.

HCU Entwicklermodus freischalten

Damit die HCU API-Zugriffe akzeptiert, muss der Entwickler-Modus aktiviert werden. In diesem Modus kann man eigene Plugins direkt auf der HCU laden. Oder man kann mit Plugins auf anderen Systemen (z. B. Node-RED) über eine Websocket-Verbindung kommunizieren.

Die Vorgehensweise zur Freischaltung ist gut in der API-Dokumentation beschrieben, so dass ich nur auf folgendes hinweise:

1. Aktiviere den Entwicklermodus und gebe sofort die Websockets frei (Häkchen setzen)
2. Warte mit der Erstellung des Aktivierungsschlüssels bis zum nächsten Schritt!

Authentication Token vereinbaren

Jedes Plugin braucht für die Kommunikation eine eindeutige ID.  eQ-3 empfiehlt zur Namensfindung die "Reverse Domain Name Notation". Ich habe diesen Namen für die folgenden Tests benutzt:

de.spike.grass.plugin.example1

Damit die Kommunikation zwischen der HCU und einem anderen Gerät sicher, aber einfach ist, brauche ich außerdem ein Token. Dieser Authentication Token ist wie ein Passwort. Zur Erstellung des Tokens muss man mit der HCU über API-Requests kommunizieren.

Ich empfehle das Tool Postman zu verwenden, da es einfach zu bedienen ist.

Ich verweise hier auch auf die Anleitung in Kapitel 2.4 (Step 2) und ergänze noch ein paar Hinweise::

• Wähle in Postman die Methode "POST" aus. Trage dahinter als Adresse https://hcu1-XXXX.local:6969/hmip/auth/requestConnectApiAuthToken ein (Setze anstelle von hcu1-XXXX den lokalen Netzwerknamen ein)
• Ergänze unter dem Tab "Headers" das Feld "VERSION" mit dem Wert "12"
• Gehe nun zuerst zurück in den Entwicklermodus der HCU und generiere einen Aktivierungsschlüssel (dieser ist nur kurzzeitig gültig)
• Kopiere in den Tab "body" den body-example Code aus Kapitel 2.4 Step 2
• Tausche den Aktivierungsschlüssel gegen den soeben generierten Schlüssel aus
• Tausche die plugin_id gegen die von dir gewählte ID aus (siehe oben)

Drücke auf Send und man sollte ein solches Feedback erhalten (Wert für spätere Verwendung speichern):

Nun muss der Erhalt dieses Schlüssels noch bestätigt werden. Gehe dazu wie folgt in Postman vor:

• Drücke oben in der Tabzeile auf "New Request"
• Ergänze unter dem Tab "Headers" das Feld "VERSION" mit dem Wert "12"
• Wähle in Postman die Methode "POST" aus. Trage dahinter als Adresse https://hcu1-XXXX.local:6969/hmip/auth/confirmConnectApiAuthToken (Setze anstelle von hcu1-XXXX den lokalen Netzwerknamen ein)
• Kopiere in den Tab "body" den body-example Code aus Kapitel 2.4 Step 3
• Tausche den Aktivierungsschlüssel gegen den eben generierten aus
• Tausche den authToken gegen den im vorigen Schritt erhaltenen authToken aus.

Drücke auf Send und du solltest eine client_id in der folgenden Form erhalten (Wert für spätere Verwendung speichern):

Websocket Verbindung testen

Nun kann getestet werden, ob eine Websocket-Verbindung zur HCU mit den gerade erzeugten Daten aufgebaut werden kann. Ich empfehle hierzu auch wieder das Tool Postman zu verwenden.

Hier gibt es allerdings mit der freien und unregistrierten Version eine Einschränkung: In dieser Version kann man keine Self-Signed-Socket Verbindungen aufbauen, die wir aber für die Kommunikation mit der HCU benötigen.

Man löst das Ganze, indem man sich einen (kostenlosen) Postman-Account erstellt und sich dann mit dem Account in der App anmeldet. Anschließend ist die Kommunikation mit den Self- Signed- Zertifikaten möglich.

Folgende Schritte sind anschließend in Postman durchzuführen:

• In der Adressleiste wird folgende Adresse eingetragen: wss://hcu1-XXXX.local:9001 (Setze anstelle von hcu1-XXXX den lokalen Netzwerknamen ein)
• Auf das Plus-Zeichen links oben im Workspace drücken und "Websocket" auswählen.
• Unter Headers wird ein neuer Key "authtoken" mit dem eben generierten Wert eingetragen.
• Unter Headers wird ein weiterer neuer Key "plugin-id" mit der generierten Plugin-ID eingetragen.

Nach Betätigen von Connect sollte die Meldung "connected to .local:9001" erscheinen.

Und in der HCU im Plugins Menü sollte die Verbindung ebenfalls auftauchen!

Mit Node-RED HCU-Daten abfragen

Jetzt kann eine Websocket Verbindung zur HCU aus Node-RED aufgebaut werden. Die Sockets-Nodes in Node-RED unterstützen allerdings keine Self-Signed Zertifikate. Stattdessen verwende ich die Palette node-red-contrib-dynamic-websocket, die ich in Node-RED installiert habe. Darin befindet sich ein Websocket-Node, der viel mehr Möglichkeiten als die Standard-Nodes bietet.

In Node-RED wird nun der Dynamic-Websocket-Node eingefügt und in den Eigenschaften folgende Daten eingetragen:

• Default-Url "wss://"
• "Allow Self Signed Certificates"-Häkchen setzen

Unter Custom Headers wird anschließend folgender JSON-Eintrag ergänzt:

Im Code wird die eigene Plugin-ID sowie das eigene Authentication Token eingetragen. Mit der Zeile "hmip-system-events":"true" wird die HCU so eingestellt, dass alle Änderungen an HMIP-Zuständen (Basisstation, Geräte, Gruppen, etc.=) sofort an Node-Red übermittelt werden (siehe auch API-Dokumentation).

Alle Websocket-Nachrichten können durch einen Debug-Node am ersten Ausgang des Websocket-Nodes im Debug-Fenster ausgegeben werden. Nach dem deployen des Flows sollte das Ergebnis wie folgt aussehen. In den Objekten sind bereits alle Informationen zu den HMIP-Geräte enthalten.

Weitere Funktionen ergänzen

Ich erweitere den Flow jetzt noch um Funktionen, die bei den weiteren Tests hilfreich sind. Hierzu gehört auch, dass die HCU zwischenzeitlich abfragt, ob mein Plugin einsatzbnereit ist. Hierzu sendet die HCU an Node-Red unter payload.type einen "PLUGIN_STATE_REQUEST". Sobald ich diesen erhalte schicke ich eine PLUGIN_STATE_RESPOND Message zurück. Die Nodes, die ich ergänze sind in folgender Tabelle aufgeführt.

Der Flow sieht anschließend wie folgt aus und bietet jetzt eine solide Basis für die Kommunikation mit der HCU.

Im nächsten Beitrag werde ich mir die Nachrichtenformate der HCU näher anschauen und entscheiden, wie ich diese am besten auswerte. Anregungen und Ergänzungen sind herzlich willkommen.