Modul Message Hub

info

Das Modul Message Hub steht ab NeuroomNet Version 2026.3 zur Verfügung.

Das Modul Message Hub bindet Geräte und Systeme an, die JSON-Nachrichten über WebSocket austauschen. Es ist ein generischer Provider: Statt für jedes Gerät einen eigenen Dienst zu benötigen, beschreibt man das Nachrichtenformat in NeuroomNet selbst.

Einleitung

Viele Geräte und Systeme senden und empfangen Nachrichten als JSON-Objekte über eine WebSocket-Verbindung. NeuroomNet kann damit auf zwei Arten arbeiten:

• Ereignisse: Eine eingehende Nachricht, die einem definierten Muster entspricht, löst ein NeuroomNet-Ereignis aus. Das Ereignis kann in Skriptblöcken als Auslöser verwendet werden, und die Werte aus der Nachricht stehen als Parameter zur Verfügung.
• Kommandos: Ein NeuroomNet-Kommando erzeugt eine JSON-Nachricht und sendet sie über die Verbindung. Die Werte, die im Skriptblock übergeben werden, werden in das Objekt eingesetzt.

Anders als bei MQTT beschreibt das Message Hub nicht nur einzelne Topics, sondern das gesamte Nachrichtenformat. Die Beschreibung legt man in einem gemeinsamen Protokoll ab, das mehrere Komponenten nutzen können.

Gemeinsames Protokoll

Ein Protokoll enthält die Ereignisse und Kommandos, die für ein bestimmtes Nachrichtenformat gelten. Alle Komponenten, die dasselbe Protokoll verwenden, teilen seine Ereignisse und Kommandos. Eine Änderung am Protokoll wirkt daher auf alle diese Komponenten.

Das Protokoll wird im Formular der Komponente über das Feld „Identifier“ ausgewählt. Mit „New“ wird ein neues Protokoll angelegt. Ereignisse und Kommandos eines Protokolls werden im Formular einer Komponente bearbeitet, die dieses Protokoll verwendet.

Im Reiter „Protocols“ sind alle gemeinsamen Protokolle aufgelistet. Dort ist sichtbar, wie viele Ereignisse und Kommandos ein Protokoll hat und welche Komponenten es verwenden.

• Umbenennen: Über das Stift-Symbol neben dem Namen.
• Kopieren: Der Button „Copy“ legt eine Kopie des Protokolls an. Die Kopie behält die Bezeichner der Ereignisse und Kommandos. Skripte funktionieren deshalb weiter, wenn eine Komponente auf die Kopie umgestellt wird.
• Löschen: Ein Protokoll kann nur gelöscht werden, wenn keine Komponente es mehr verwendet. Die Komponenten müssen vorher auf ein anderes Protokoll umgestellt werden.

Antwort auf Anwendungs-Ping

Mit der Option „Answer application ping“ im Bereich „Shared Protocol“ beantwortet der Dienst Anwendungs-Pings selbst. Die Einstellung gehört zum gemeinsamen Protokoll und gilt daher für alle Komponenten, die dieses Protokoll verwenden. Derzeit unterstützt NeuroomNet nur das Format JSON.

Die Option hat drei Felder, die vorbelegt sind:

• Key: Pfad des Schlüssels, der die Anfrage kennzeichnet. Punkte trennen verschachtelte Ebenen, zum Beispiel header.command. Vorbelegung: Command.
• Request: Der Wert, den der Schlüssel in einer Anfrage haben muss. Vorbelegung: Ping.
• Answer: Der Wert, den der Dienst in der Antwort am Schlüssel setzt. Vorbelegung: Pong.

Trifft eine eingehende Nachricht auf Key und Request (exakter Vergleich), antwortet der Dienst nur dem Absender. Die Antwort ist eine Kopie der Nachricht, am Key steht der Answer-Wert, und zusätzlich wird ein Feld ServerTime mit der Serverzeit im ISO-Format in UTC ergänzt:

Anfrage:  {"Command":"Ping","id":17}
Antwort:  {"Command":"Pong","id":17,"ServerTime":"2026-10-17T09:15:00.000Z"}

Ein Ping löst weder ein Ereignis noch eine Variable aus und wird nicht protokolliert. Alle anderen Nachrichten werden ganz normal verarbeitet.

Komponente anlegen

Mit „New Component“ wird eine neue Komponente angelegt. Im Bereich „Properties“ werden der Display Name und die Description eingetragen. Die Abbildung zeigt eine gespeicherte Komponente mit ihrem Protokoll und den Ereignissen.

Im Bereich „Connection Settings“ legt man die Verbindung fest:

• Transport: Entweder „WebSocket Client“ oder „WebSocket Server“.
• WebSocket Client: NeuroomNet verbindet sich mit dem Gerät. Die URL hat die Form wss://host:port/path. Mit „Ignore certificate errors“ werden Fehler beim Zertifikat ignoriert.- WebSocket Server: Das Gerät verbindet sich mit NeuroomNet. Der Path unterscheidet die Komponenten, weil alle Server-Komponenten denselben Port teilen. Das Formular zeigt die Adresse, unter der die Clients verbinden, sowohl verschlüsselt als auch unverschlüsselt.
• Subprotocol (optional): Ein WebSocket-Subprotokoll, falls das Gerät eines verlangt.
• Watch connection (ping/pong): Überwacht die Verbindung mit WebSocket-Ping- und Pong-Nachrichten auf Transportebene. Die Option ist beim Anlegen vorausgewählt. Bleibt bis zum nächsten Ping ein Pong aus, wird die Verbindung getrennt und neu aufgebaut. Der Abstand ist serverseitig konfigurierbar (siehe Administration). Das ist unabhängig von den Anwendungs-Pings oben.
• Report every message (MessageReceived): Löst für jede eingehende Nachricht das generische Ereignis MessageReceived aus. Das ist aufwendig und sollte nur bei Bedarf aktiviert werden.

hinweis

Die Adresse im Server-Modus hängt vom Präfix ab, das der Administrator serverseitig konfiguriert. Die Anzeige im Formular berücksichtigt das bereits.

Ereignisse (Reiter „Events“)

Der Reiter „Events“ definiert, welche eingehenden Nachrichten ein NeuroomNet-Ereignis auslösen. Das Eingabeformular links legt ein Ereignis an. Die Tabelle rechts listet die vorhandenen Ereignisse mit der Anzahl ihrer Parameter.

Die Felder im Einzelnen:

• NeuroomNet Event Name: Name des Ereignisses in NeuroomNet. Er erscheint später im Skripteditor als Auslöser.
• Description: Optionale Beschreibung.
• Example Message (JSON): Ein Beispiel für eine Nachricht, die dieses Ereignis auslösen soll. Mit „Validate“ wird das Beispiel geprüft. Danach erscheint die Liste der Felder als Parameter.
• Accept when key: Die Bedingung. Das Ereignis wird nur ausgelöst, wenn der Schlüssel den angegebenen Wert hat. Der Wert kann als Text, Number, Boolean oder Null angegeben werden. Mehrere Bedingungen werden mit UND verknüpft.
• Only if the message matches the structure of the example: Das Ereignis greift nur, wenn die Nachricht dieselbe Struktur hat wie das Beispiel (oberste Ebene).
• Single values as parameters / Complete message as one parameter: Entweder wird jedes Feld als eigener Parameter übergeben, oder die gesamte Nachricht wird als ein Objekt übergeben.
• In use: Legt fest, welche Felder als Parameter übernommen werden. Für jedes Feld wählt man den Parametertyp, zum Beispiel Integer für eine Zahl.

Mit „Add“ wird das Ereignis übernommen. Ein bestehendes Ereignis wird über die Tabelle ausgewählt und mit „Update“ geändert. „Cancel“ verwirft die Eingaben.

Üblich sind mehrere Ereignisse, die dasselbe Feld mit unterschiedlichen Werten prüfen. Die Übersicht oben zeigt die Ereignisse LampOn und LampOff für das Feld power.

Beispiel: Beispielnachricht validieren

Die Beispielnachricht bestimmt die Parameter. Im folgenden Beispiel hat das Gerät eine Statusmeldung mit den Feldern type, device, power und level. Nach dem Validieren werden die Felder als Parameter vorgeschlagen. Das Feld type ist hier für alle Nachrichten gleich und wird daher aus den Parametern entfernt.

Der Hinweis unter dem Formular zeigt, was noch fehlt, zum Beispiel den Schlüssel für die Bedingung.

Kommandos (Reiter „Commands“)

Der Reiter „Commands“ definiert, welche Nachrichten NeuroomNet senden kann. Die Bedienung entspricht den Ereignissen, mit folgendem Unterschied:

• NeuroomNet Command Name: Name des Kommandos im Skripteditor.
• Example Message (JSON): Die Nachricht, die gesendet wird. Die Felder werden als Parameter angeboten, die beim Aufruf im Skriptblock gesetzt werden.
• Set key ... to value: Ein fester Wert, der immer in die Nachricht geschrieben wird. Das Feld verschwindet dann aus den Parametern. Mit dieser Option lässt sich zum Beispiel ein Typ festlegen, der bei jedem Kommando gleich ist.

Die Abbildung zeigt das Kommando TurnOn. Der Schlüssel type ist fest auf command gesetzt. Die Parameter device, power und level können beim Aufruf im Skriptblock belegt werden.

Variablen und Status

Eine Komponente stellt die Variablen LastMessage (letzter Nachrichteninhalt) und LastMessage.Time (Zeitpunkt des Empfangs) bereit.

Beispiel: Komponente Lampe Foyer

Das Beispiel zeigt eine Komponente, die sich per WebSocket-Server mit einer Lampe verbindet:

1. Protokoll Lampensteuerung anlegen (über „New“ im Feld Identifier).
2. Ereignisse LampOn (Bedingung power = on) und LampOff (Bedingung power = off) mit jeweils einer Beispielnachricht anlegen.
3. Kommando TurnOn mit fest gesetztem Typ command anlegen.
4. Komponente als WebSocket Server mit dem Path lampe/foyer speichern. Das Gerät verbindet sich dann mit der angezeigten Adresse.

Die Übersicht oben zeigt das fertige Ergebnis.

Tipps

Ein Protokoll pro Gerätetyp

Geräte desselben Typs verwenden dasselbe Nachrichtenformat. Ein gemeinsames Protokoll für diese Geräte vermeidet doppelte Pflege. Jede Komponente bekommt nur ihren eigenen Display Name und Path.

Ereignisse aus dem Beispiel prüfen

Vor dem Speichern lohnt sich ein Blick auf die Parameterliste nach dem Validieren. Felder, die nicht als Parameter übernommen werden, stehen im Formular ausgegraut zur Verfügung und lassen sich mit dem Häkchen wieder aktivieren.

Administration

Die Konfiguration des Dienstes erfolgt serverseitig im Abschnitt webSocket:

• serverPort: Port des WebSocket-Servers.
• serverPathPrefix: Präfix der Pfade, Standard /msg/.
• keepAliveInterval: Abstand der Ping-Nachrichten in Millisekunden, Standard 25000. Im Client-Modus deaktiviert 0 die Überwachung.
• reconnectInterval: Wartezeit bis zum erneuten Verbindungsaufbau in Millisekunden, Standard 5000.
• caFile: Zusätzliche Wurzelzertifikate für den Client-Modus.

Bei Fragen zur Serverkonfiguration wenden Sie sich an den NeuroomNet Support.