Mit Node-RED auf die HMIP Home Control Unit (HCU) zugreifen

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):

Copy to Clipboard

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):

Copy to Clipboard

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:

Copy to Clipboard

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.

Node Beschreibung
Inject Node ("Close Connection") Mit diesem Node kann ich die Websocket-Verbindung schließen. Dazu braucht als Parameter nur in "msg.close" gleich "true" angegeben zu werden.
Inject Node ("Open Connection") Mit diesem Node kann ich die Websocket-Verbindung wieder aufbauen. Dazu braucht als Parameter nur in "msg.url" als String die Serveradresse "wss://" angegeben zu werden.
Switch Node ("Event Types unterscheiden") Hier löse ich die Event-Types auf, die von der HCU übermittelt werden (wird später noch weiter ausgebaut).
Switch Node ("PLUGIN_STATE_RESPONS Message") Über diesen Node erstelle ich die JSON-Nachricht, die ich per Websocket an die HCU schicke. In dem folgenden Screenshot müssen die PluginID sowie die ClientID durch die eigenen Werte ersetzt werden.

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.