HCU Archive - Smart home Ratgeber

Die Home Control Unit (HCU) in Node-RED integrieren – Teil 3

Dieter — Sat, 31 Oct 2026 14:17:16 +0000

HCU

Im dritten Teil dieser Serie betrachte ich die von der HCU übermittelten Änderungen von Device-Informationen. Diese sollen zum einen zur Aktualisierung der gespeicherten HCU-Daten und zum anderen zur Ausgabe von Gerätänderungen verwendet werden. Um alles zu verstehen, ist es wichtig, mindestens den vorigen Beitrag der Serie zu lesen, da auch dieser darauf aufbaut. Das wesentliche Dokument für alle folgenden Schritte ist auch die Homematic IP Connect API Dokumentation.

HMIP System Events

Wenn eine Plug-in-Message vom Typ „HMIP_SYSTEM_EVENT” ankommt – den unterscheide ich ab sofort auch im Switch-Node –, dann wurde auf der HCU irgendein Ereignis ausgelöst, welches die Änderung eines oder mehrerer Daten verursacht hat. Mehrere Änderungen ergeben sich beispielsweise, wenn ein Taster gedrückt wird und anschließend das Licht angeht oder auf eine bestimmte Helligkeit automatisch gedimmt wird. Die Änderungen befinden sich unter „body.eventTransaction.events” und zwar genau in der Reihenfolge, in der sie auch ausgeführt wurden.

Um ein Array von Objekten unter „body.eventTransaction.events” besser weiterverarbeiten zu können, teile ich dieses vorab mit einem Split-Node in seine Einzelteile auf. Der Split-Node macht aus einem Array eine Liste, d. h., jedes Objekt wird nun sequenziell weitergegeben.

Die Eigenschaften des Split-Nodes sind wie folgt:

Für jedes Objekt in der Liste gibt es einen "pushEventType", der die Art des Ereignisse für das Objekt angibt, sowie das device, auf das sich das Event bezieht.

Folgenden Typen (pushEventType) sind anfangs interessant:

pushEventType	Beschreibung
DEVICE_CHANGED	Mit diesem Type wird signalisiert, dass sich in einer Deice (einem Gerät) eine Änderung ergeben hat. I.d.R. sind das die für mich interessantesten Nachrichten.
DEVICE_CHANNEL_EVENT	Dieser Type ist nicht dokumentiert. Wenn er auftaucht, dann wurde ein Taster gedrückt (z.B. auf einem 6-Fach Taster). Das zugeörige Objekt liefert die deviceId, den ChannelIndex sowie den channelEventType mit z.B. "KEY_PRESS_SHORT"
DEVICE_ADDED	Ein Gerät wurde hinzugefügt (ist interessant, um es im Zwischenspeicher zu ergänzen)
DEVICE_REMOVED	Ein Gerät wurde gelöscht (ist interessant, um es im Zwischenspeicher zu löschen)

In diesem Beispiel werde ich nur die Nachricht DEVICE_CHANGED verarbeiten. Nach dem gleichen Prinzip können auch alle anderen Nachrichten verarbeitet werden, um beispielsweise Geräte zu löschen oder hinzuzufügen.

DEVICE_CHANGED-Nachricht verarbeiten

Wenn die Nachricht (pushEventType) des Array-Eintrags den Typ „DEVICE_CHANGED” besitzt, weiß ich, dass es Änderungen an einem Gerät gab (z. B. wurde die Temperatur geändert). Mit diesen Daten kann ich anschließend die in der Flow-Variable „f_systemresponse” zwischengespeicherten HCU-Informationen aktualisieren, sodass ich in dieser Variablen immer die aktuellen Gerätedaten habe.

Das heißt, ich prüfe in einem Switch-Node, ob der pushEventType dem Wert „DEVICE_CHANGED” entspricht. Wenn ja, dann speichere ich den Device-Teil des Objekts mit einem Change-Node in der payload.msg. (Ich ergänze hier auch noch ein Topic, das ich später für einen Join-Node verwenden kann.)

Anschließend tausche ich in einem Funktionsknoten das alte Gerätsobjekt, das sich in „f_systemresponse” befindet, gegen das neue Gerätsobjekt aus. Im Function-Node „Device Änderungen” verwende ich folgenden Code:

Copy to Clipboard

Weitere Typen sind in Kapitel 6.9 zu finden.

Bei meinen Versuchen habe ich festgestellt, dass im ersten Array-Element fast immer der Typ „DEVICE_CHANGED” steht. Das kann ich allerdings nicht garantieren. Daher baue ich in meinen Flow einen Split-Knoten ein, der das gesamte Array aufspaltet und die einzelnen Elemente zur Analyse der Events weiterschickt.

Änderungen eines Devices extrahieren

Mit einer DEVICE_CHANGED-Nachricht wird eine Änderung an einem Gerät angezeigt. Um diese sichtbar zu machen, verwende ich eine Funktion, die alle Änderungen, die in den Daten eines Geräts stattgefunden haben, in einem Array protokolliert und um wichtige Daten wie die Seriennummer, das Label und die ID ergänzt. Zusätzlich füge ich hier ein payload.topic hinzu, welches ich später für einen Join-Node benötige. Der Function-Node wird „Differenzen ermitteln” genannt und beinhaltet folgenden Code:

Copy to Clipboard

// Neues Device-Objekt aus dem Eingang lesen
const newObj = msg.payload;

// Wichtige Basiswerte aus dem neuen Objekt übernehmen
const deviceId = newObj.id;
const label = newObj.label;

// Seriennummer bestimmen:
// - bei externen Plugins: pluginDeviceId
// - sonst: id
const serialNr = newObj.type === "PLUGIN_EXTERNAL"
    ? newObj.pluginDeviceId
    : newObj.id;

// Altes Device-Objekt aus dem gespeicherten Systemzustand holen
const oldObj = flow.get("f_systemresponse")?.body?.body?.devices?.[deviceId];

// Rekursive Differenzfunktion:
// Vergleicht zwei Objekte und sammelt alle Unterschiede in einem Array
function diff(a, b, path = "") {
    const changes = [];

// Hilfsfunktion: Prüft, ob ein Wert ein normales Objekt ist
    // Arrays zählen hier nicht als Objekt
    const isObject = v => v && typeof v === "object" && !Array.isArray(v);

// Alle Schlüssel aus altem und neuem Objekt zusammennehmen
    const keys = new Set([
        ...Object.keys(a || {}),
        ...Object.keys(b || {})
    ]);

// Jeden Schlüssel einzeln vergleichen
    for (const key of keys) {
        // Vollständigen Pfad für die Änderung aufbauen
        const currentPath = path ? `${path}.${key}` : key;

// Wert im alten und neuen Objekt lesen
        const oldValue = a ? a[key] : undefined;
        const newValue = b ? b[key] : undefined;

// Wenn beide Werte Objekte sind, rekursiv weiter vergleichen
        if (isObject(oldValue) && isObject(newValue)) {
            changes.push(...diff(oldValue, newValue, currentPath));
        } else if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
            // Sonst Unterschiede direkt als Änderung speichern
            changes.push({
                path: currentPath,
                oldValue: oldValue,
                newValue: newValue
            });
        }
    }

return changes;
}

// Ergebnisobjekt 
msg.payload = {
    deviceId: deviceId,
    label: label,
    serialNr: serialNr,
    changes: diff(oldObj, newObj)
};

// Topic für den weiteren Flow setzen
msg.topic = "changes";

return msg;

Geräteänderungen automatisch anzeigen

Nun sind alle Voraussetzungen vorhanden, um bei einem Ereignis automatisch Geräteänderungen anzuzeigen. Zur Spezifikation der Geräte, die ich anzeigen möchte, verwende ich einen Funktionsknoten („Device-Liste“), in dem ich die Seriennummern der gewünschten Geräte sowie das jeweilige Feld angebe, bei dessen Änderungen ich informiert werden möchte. Das Ganze ist als Array aufgebaut und enthält zusätzlich eine payload.topic-Angabe, die ich im folgenden Join-Node verwenden werde.

Copy to Clipboard

Da ich jetzt alle Änderungen eines Geräts kenne (wie im vorigen Kapitel beschrieben), muss ich nur in den Änderungen nach der jeweiligen Seriennummer und dem gewünschten Feld suchen. Bei Übereinstimmung prüfe ich, ob sich dort eine Werteänderung ergeben hat. Wenn ja, gebe ich das als Ergebnis aus.

Da ein Function-Node nur einen Input hat und ich keine Flow-Variable nutzen möchte, füge ich den Input aus dem Function-Node, der mir die Änderungen ermittelt hat, sowie den Function-Node mit den zu überwachenden Devices mit einem Join-Node zusammen. Das ist möglich, da ich verschiedene payload.topic-Werte verwendet habe. So entsteht ein Objekt mit den beiden Topics „changes” und „search”, in denen alle Daten gemeinsam stehen. Der Node wird wie folgt konfiguriert.

Das Ergebnis des Join-Nodes wird dann in einen Function-Node geleitet ("Werteänderung finden"), der die beschriebene Suche durchführt und eine Ausgabe erzeugt, wenn es zu einem gesuchten Device eine Änderungen bei der gesuchten Eigenschaft gegeben hat.

Copy to Clipboard

// Aktuelles Device und Suchliste aus dem eingehenden Payload lesen
const device = msg.payload?.changes;
const searchList = msg.payload?.search;

// Nur weiterarbeiten, wenn alle benötigten Daten vorhanden sind
if (!device || !Array.isArray(device.changes) || !Array.isArray(searchList)) {
    return null;
}

// In der Suchliste den ersten Eintrag finden, dessen Seriennummer
// im aktuellen device.serialNr enthalten ist und der einen Feldnamen hat
const search = searchList.find(s =>
    s?.serialNr &&
    s?.fieldname &&
    String(device.serialNr || "").includes(String(s.serialNr).trim())
);

// Kein passender Such-Eintrag für dieses Device gefunden
if (!search) {
    return null;
}

// Den gesuchten Feldnamen normalisieren
const fieldname = String(search.fieldname).trim();

// In den Änderungen des Devices die erste echte Änderung für dieses Feld suchen
// Beispiel: "functionalChannels.1.presenceDetected" endet auf ".presenceDetected"
const change = device.changes.find(c =>
    String(c?.path || "").endsWith("." + fieldname) &&
    c.oldValue !== c.newValue
);

// Keine relevante Änderung gefunden
if (!change) {
    return null;
}

// Ergebnis für die weitere Verarbeitung im Flow aufbereiten
msg.topic = "changed";
msg.payload = {
    serialNr: search.serialNr,
    fieldname,
    label: device.label || null,
    oldValue: change.oldValue,
    newValue: change.newValue,
    path: change.path
};

return msg;

Das Ergebnis im Debug-Fenster wäre bei der Erkennung einer Bewegung beispielsweise wie folgt:

serialNr: "000C1BE9916CE3:1"

fieldname: "presenceDetected"

label: "Praesenzsmelder:1"

oldValue: false

newValue: true

path: "functionalChannels.1.presenceDetected"

Anschließend sollte noch der Funktionsknoten „Device Änderung” aufgerufen werden, damit der Status im Speicher wieder aktuell ist.

Der resultierende Node-Red-Flow sieht mit allen Ergänzungen jetzt wie folgt aus:

Natürlich kann noch ganz viel optimiert werden. Auf dieser Basis können nun weitere Ergänzungen wie z.B. das Steuern eines Devices gebaut werden. Wer weitere Verbesserungen und Informationen hat, kann diese gerne hier posten.

Der Beitrag Die Home Control Unit (HCU) in Node-RED integrieren – Teil 3 erschien zuerst auf Smart home Ratgeber.

Neue Node-RED-Library für die Homematic HCU

Dieter — Sun, 27 Sep 2026 16:44:05 +0000

HCU

In den letzten Monaten habe ich mich intensiver mit der neuen Homematic IP Home Control Unit (HCU) und den Möglichkeiten zur Integration in Node-RED beschäftigt.

Da ich keine passende Lösung gefunden habe, habe ich mit KI-Unterstützung die Node-RED-Palette node-red-contrib-homematic-hcu entwickelt.

Die Palette ermöglicht den direkten Zugriff auf die Homematic HCU über die offizielle Connect API – ganz ohne Cloud. Gerätezustände können ausgelesen, Ereignisse in Echtzeit empfangen und Aktoren direkt aus Node-RED gesteuert werden. Ziel war es, die Anbindung der HCU so einfach wie möglich zu gestalten und gleichzeitig die Flexibilität von Node-RED vollständig nutzen zu können.

Aktuell unterstützt die Palette unter anderem:

• Aufbau der Verbindung zur Homematic HCU
• Authentifizierung über die Connect API
• Empfang von Geräteereignissen per WebSocket
• Auslesen von Geräte- und Featurewerten
• Schalten und Steuern von Homematic-IP-Geräten
• Erstellen von Benutzermeldungen auf der HCU

Die Installation erfolgt wie gewohnt über den Node-RED Palette Manager oder per npm.

Ich stelle die Palette mit den Nodes frei zur Verfügung, da ich wahrscheinlich nicht der Einzige bin, der Node-RED als zentrales System nutzt. Anregungen, Verbesserungsvorschläge, Fehlermeldungen,etc. können auch über Github eingestellt werden. Da das Ganze ein Hobbyprojekt ist, bitte ich um Nachsicht, wenn ich nicht sofort antworte.

Weitere Informationen wie z.B. die Dokumentation findet ihr hier:

Node-Red Palette
GitHub Repository

Fragen und Anregungen können auch als Kommentare zu diesem Blog übermittelt werden.

Der Beitrag Neue Node-RED-Library für die Homematic HCU erschien zuerst auf Smart home Ratgeber.

Die Home Control Unit (HCU) in Node-RED integrieren – Teil 2

Dieter — Mon, 27 Jul 2026 17:42:40 +0000

HCU

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

Besonderheiten bei PLUGIN_EXTERNAL

Wenn der "type" eines devices "PLUGIN_EXTERNAL" ist dann ergeben sich ein paar Besonderheiten. Bei diesem Typ ist das Gerät nicht direkt in der HCU angelernt sondern wird durch ein anderes Plugin bereitgestellt (z.B. das CCU3 Plugin). Folgende Änderungen ergeben sich dann:

Die Seriennummer des Gerätes steht unter "pluginDeviceId", unter "id" steht eine eindeutige von der HCU vergebene Nummer mit mehreren von Bindestrichen getrennten HEX-Werten.
Für CCU3 Geräte hat die pluginDeviceId das folgendes Format: "00196BE98B20B2:1" (letzten 14 Stellen der SGTIN gefolgt von einem Doppelpunkt mit der Kanalnummer). Geräte, die direkt an der HCU angelernt wurden besitzen das Format "3014F711A00046F219898621" (entspricht der SGTIN mit insgesamt 24 Stellen).
Der Typ des Device steht nicht mehr unter "type" sondern unter "pluginDeviceType"

Die Suche nach der Seriennummer

Durch die Nutzung der CCU3 habe ich mich an die Notation der Seriennummern mit der Kanalnummer gewöhnt. Weil viele Geräte vorerst weiter auf der CCU laufen, möchte ich gerne diese Seriennummer-Notation für externe CCU3-Geräte bei der Suche nach Geräten beibehalten.

Da die Seriennummern von „PLUGIN_EXTERNAL“-Typen an anderer Stelle stehen als die Seriennummern von Geräten, die direkt an der HCU angelernt wurden, muss ich dies bei allen zukünftigen Funktionen berücksichtigen.

Will man diese Vorgehenswiese nicht verwenden kann auch einfach die id eines Gerätes verwendet werden, so dass man sich die Vergleiche mit dem Typ spart.

Ich gebe neben der Seriennummer auch ein Label-Feld zurück, damit die Geräte beim Debuggen schneller identifiziert werden können.

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

PluginMessageType	Beschreibung
PLUGIN_STATE_RQUEST	Wenn eine solche Nachricht ankommt, möchte die HCU eine Statusinformation des Plug-ins bzw. ein Lebenszeichen erhalten. Die Antwort darauf ist immer eine Nachricht an die HCU mit dem Payload-Typ PLUGIN_STATE_RESPONSE.
HMIP_SYSTEM_RESPONSE	Diese Nachricht beinhaltet den Status eines oder mehrerer Datenobjekte bzw. aller Daten in der HCU. Der Status wird erst dann gesendet, wenn zuvor ein HMIP_SYSTEM_REQUEST gesendet wurde.
HMIP_SYSTEM_EVENT	In dieser Nachricht befindet sich ein Update des HMIP-Systems. Wichtig ist, dass nicht immer der gesamte Status übertragen wird, sondern nur die geänderten Teile.

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:

Copy to Clipboard

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.

Copy to Clipboard

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.

Copy to Clipboard

const input = msg.payload || {};
const searchSerialNr = String(input.serialNr ?? "").trim();
const fieldname = String(input.fieldname ?? "").trim();

// Prüfen, ob die benötigten Eingabewerte vorhanden sind
if (!searchSerialNr) {
    msg.payload = {
        error: "serialNr ist leer oder fehlt",
        input: input
    };
    return msg;
}

if (!fieldname) {
    msg.payload = {
        error: "fieldname ist leer oder fehlt",
        input: input
    };
    return msg;
}

// flow-Variable mit den HCU-Daten laden
const systemResponse = flow.get("f_systemresponse");

// Nur den Bereich mit den Devices verwenden
const devices = systemResponse?.body?.body?.devices || {};

let foundDevice = null;
let foundValue = null;

// Alle Devices durchsuchen
for (const device of Object.values(devices)) {
    const type = String(device?.type ?? "").trim();
    const deviceId = String(device?.id ?? "").trim();
    const pluginDeviceId = String(device?.pluginDeviceId ?? "").trim();

let isMatch = false;

// Für PLUGIN_EXTERNAL wird links gegen pluginDeviceId verglichen
    if (type === "PLUGIN_EXTERNAL") {
        isMatch = pluginDeviceId === searchSerialNr;
    }
    // Für alle anderen Geräte wird rechts gegen device.id verglichen
    else {
        isMatch = deviceId === searchSerialNr;
    }

// Wenn das passende Device gefunden wurde, Schleife beenden
    if (isMatch) {
        foundDevice = device;
        break;
    }
}

// Im gefundenen Device unter functionalChannels nach dem gewünschten Feld suchen
if (foundDevice?.functionalChannels) {
    for (const channel of Object.values(foundDevice.functionalChannels)) {
        if (channel && Object.prototype.hasOwnProperty.call(channel, fieldname)) {
            foundValue = channel[fieldname];
            break;
        }
    }
}

// Ergebnis in msg.payload zurückgeben
msg.payload = {
    serialNr: searchSerialNr,
    fieldname: fieldname,
    foundDeviceName: foundDevice?.label || null,
    deviceId: foundDevice?.id || null,
    pluginDeviceId: foundDevice?.pluginDeviceId || null,
    value: foundValue
};

return msg;

Anschließend sieht das Ergebnis wie folgt aus:

serialNr: "0009149920ACD"

fieldname: "presenceDetected"

foundDeviceName: "BWM-Test-Flur:1"

value: false

Ausblick

Im nächsten Beitrag werde ich zeigen, wie die zwischengespeicherten HCU-Daten aktualisiert werden. Auf dieser Grundlage wird es dann auch möglich sein, sich Statusänderungen von Geräten automatisch ausgeben zu lassen.

Der Beitrag Die Home Control Unit (HCU) in Node-RED integrieren – Teil 2 erschien zuerst auf Smart home Ratgeber.

Die Home Control Unit (HCU) in Node-RED integrieren – Teil 1

Dieter — Sun, 17 May 2026 18:33:21 +0000

HCU

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:

Aktiviere den Entwicklermodus und gebe sofort die Websockets frei (Häkchen setzen)
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

Erscheint hier der Fehler "Could not generate response. SSL Error: Self signed certificate", dann braucht man nur die angebotene Option "Disable SSL Verification" zu bestätigen und schon funktioniert es.

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

Wenn es bei einem der beiden Request-Aufrufe zu dem Fehler "Invalid Request" kommt, dann kann das daran liegen, dass der Aktivierungsschlüssel abgelaufen ist. Dann generiert einfach einen Neuen, tauscht diesen in den body-Bereich aus und für die Requests erneut durch.

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.

Für die Angabe von Serveradressen gibt es zwei Möglichkeiten.

eQ3 verwendet https://hcu1-XXX.local:9001 oder wss://hcu1-XXXX.local:9001, wobei das XXXX durch die letzten 4 Zeichen der Seriennummer ersetzt werden.
Alternativ kann man https://192.177.156.43:9001 oder wss://192.177.156.43:9001 verwenden (d.h. man adressiert die HCU über die IP-Adresse und den Port)

Ich habe in Node-Red immer die zweite Variante verwendet, da ich mit der Namensauflösung erheblich Schwierigkeiten hatte. Diese Variante funktioniert auch für alle vorherigen Schritte.

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.

Der Beitrag Die Home Control Unit (HCU) in Node-RED integrieren – Teil 1 erschien zuerst auf Smart home Ratgeber.