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

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.

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

Datenstruktur verstehen

Device Eigenschaften

Plugin Messages auswerten

PluginMessageType

Zwischenspeicherung der HCU-Daten

Status eines Device abfragen

Ausblick

Hinterlasse einen Kommentar Antwort abbrechen