Modul MQTT Administration

Einleitung

MQTT (Message Queuing Telemetry Transport) ist ein leichtgewichtiges Nachrichtenprotokoll, das ursprünglich für ressourcenschwache Geräte und unzuverlässige Netzwerke entwickelt wurde und heute weit verbreitet in der Gebäudeautomation, IoT-Installationen und industriellen Anwendungen ist.

Das Grundprinzip: Ein zentraler Broker vermittelt Nachrichten zwischen Teilnehmern. Sender (Publisher) schicken Nachrichten an einen Topic (Themenpfad, z. B. gebaeude/etage1/licht/raum3/status). Empfänger (Subscriber) abonnieren Topics – entweder exakt oder mit Wildcards (+ für genau eine Ebene, # für alle verbleibenden Ebenen). Der Broker stellt sicher, dass jede Nachricht alle passenden Abonnenten erreicht.

NeuroomNet verbindet sich als Client mit einem bestehenden MQTT-Broker und kann damit:

• Nachrichten an Topics schicken, um Geräte zu steuern (Aktionen)
• Topics abonnieren, um auf eingehende Nachrichten zu reagieren (Ereignisse)

Besonderheit: Serverweite Broker-Verbindung

Im Gegensatz zu Providern wie SNMP, PJLink oder Netzwerk-Komponenten, bei denen jede Komponente ihre eigene direkte Verbindung zu einem Gerät hat, verwendet MQTT eine einzige serverweite Verbindung zum Broker. Diese Verbindung wird beim Start des MQTT-Dienstes aufgebaut und bleibt für alle Komponenten gemeinsam bestehen.

Die Verbindungsparameter (URL, Zugangsdaten, TLS usw.) werden nicht in der Admin-UI konfiguriert, sondern serverseitig in config.mqtt.json (Abschnitt mqtt.broker:). Einzelne MQTT-Komponenten in der Admin-UI definieren nur, welche Topics abonniert werden und welche Nachrichten sie veröffentlichen – nicht wie die Verbindung aufgebaut wird.

Anmerkung: Die Konfiguration der Broker-Verbindung erfordert Zugriff auf die Server-Konfiguration und ist Aufgabe des Systemadministrators. Kontaktieren Sie bei Bedarf den NeuroomNet Support.

Modul MQTT Administration

Das Modul MQTT Administration zeigt links eine Liste aller angelegten MQTT-Komponenten. Mit dem Button „Add MQTT Component" oben links wird eine neue Komponente angelegt. Über das Suchfeld lässt sich die Liste nach Name, ID, Topic oder Beschreibung filtern.

Wählt man eine Komponente aus der Liste oder legt eine neue an, erscheint rechts das Bearbeitungsformular. Über die Buttons „Speichern" und „Abbrechen" werden Änderungen gespeichert bzw. verworfen. Mit „Löschen" kann eine Komponente entfernt werden.

Felder einer Komponente

• Display Name: Anzeigename der Komponente in NeuroomNet (beliebiger Freitext, sollte eindeutig sein)
• Description: Optionale Freitextbeschreibung der Komponente

MQTT-Ereignisse (Subscribe Events)

Der Abschnitt „MQTT Events" definiert, auf welche eingehenden MQTT-Nachrichten diese Komponente reagiert. Jedes Ereignis entspricht einem NeuroomNet-Ereignis, das in Skriptblöcken als Auslöser verwendet werden kann.

Über das Eingabeformular oberhalb der Tabelle werden Ereignisse hinzugefügt. Die Felder im Einzelnen:

• Event Name: Interner Name des Ereignisses in NeuroomNet (z. B. DeviceOnline). Dieser Name erscheint später im Skripteditor als Auslöser.

• Topic: Das MQTT-Topic, das abonniert wird (z. B. home/device/+/status). Wildcards sind erlaubt:

  • + ersetzt genau eine Topic-Ebene (z. B. home/device/+/status passt auf home/device/abc/status und home/device/xyz/status)
  • # ersetzt alle verbleibenden Ebenen und muss am Ende stehen (z. B. home/device/# passt auf alle Topics unterhalb von home/device/)

  Wildcards können mit einem benutzerdefinierten Namen versehen werden, indem ein Doppelpunkt und der gewünschte Name direkt angefügt werden: +:Name oder #:Name. Dieser Name erscheint dann im Skripteditor als Bezeichner des zugehörigen Parameters statt des automatisch generierten Namens (Level 1, Level 2 … bzw. Subtopics).

  Topic	Parametername im Skripteditor
  home/device/+/status	Level 3 (automatisch, Position 3)
  home/device/+:raum/status	raum
  home/device/#	Subtopics (automatisch)
  home/device/#:pfad	pfad

  Die Benennung hat keinen Einfluss auf das MQTT-Abonnement — gegenüber dem Broker wirkt +:raum identisch wie +.

• Payload (exact match): Optionaler Filter auf den Nachrichteninhalt. Ist dieses Feld gefüllt, löst das Ereignis nur aus, wenn der empfangene Payload exakt mit diesem Wert übereinstimmt. Bleibt es leer, löst jede Nachricht an diesem Topic das Ereignis aus – und der empfangene Payload wird als Parameter an den Skriptblock übergeben.

• Offline: Ist dieses Häkchen gesetzt, wird die Komponente in NeuroomNet auf Offline gesetzt, sobald dieses Ereignis eintrifft (z. B. für eine LWT-Nachricht oder eine Status-Meldung, die das Gerät als nicht erreichbar meldet).

• Fail: Ist dieses Häkchen gesetzt, wird der Status der Komponente auf Fehler gesetzt, wenn dieses Ereignis eintrifft.

Bestehende Ereignisse können über die Stift- und Papierkorb-Buttons in der Tabelle bearbeitet bzw. gelöscht werden.

MQTT-Aktionen (Publish Commands)

Der Abschnitt „MQTT Actions" definiert, welche Nachrichten diese Komponente veröffentlichen kann. Jede Aktion entspricht einer NeuroomNet-Aktion, die in Skriptblöcken ausgeführt werden kann.

Über das Eingabeformular oberhalb der Tabelle werden Aktionen hinzugefügt. Die Felder im Einzelnen:

• Command Name: Interner Name der Aktion in NeuroomNet (z. B. TurnOn). Dieser Name erscheint später im Skripteditor als ausführbare Aktion.

• Topic: Das MQTT-Topic, an das die Nachricht veröffentlicht wird (z. B. home/lights/1/set). Wildcards sind erlaubt und verwandeln die Aktion in einen dynamischen Publish:

  • Jede Wildcard-Position (+ oder #) wird zu einem Pflichtparameter der Aktion.
  • Beim Aufruf der Aktion im Skriptblock muss der Aufrufer den konkreten Wert für jede Wildcard-Position übergeben; dieser wird dann in das Topic eingesetzt.
  • Benannte Wildcards (+:Name, #:Name) funktionieren wie bei Ereignissen und steuern den Parameternamen im Skripteditor.

  Beispiel: Topic home/+:raum/licht/set erzeugt einen Pflichtparameter raum. Die Aktion wird dann z. B. mit raum = "wohnzimmer" aufgerufen und veröffentlicht an home/wohnzimmer/licht/set.

• Default Payload: Optionaler fester Inhalt der Nachricht (z. B. ON). Ist dieses Feld gefüllt, hat die Aktion keinen Payload-Parameter – der konfigurierte Wert wird immer verwendet. Bleibt das Feld leer, erhält die Aktion einen optionalen Payload-Parameter, der beim Aufruf im Skriptblock übergeben werden kann.

• Quality of Service (QoS): MQTT-Übertragungsgarantie, einer der drei Werte:

  • 0 – „Höchstens einmal": Die Nachricht wird einmal gesendet, ohne Bestätigung (schnellste Option, kein Retry)
  • 1 – „Mindestens einmal": Der Broker bestätigt den Empfang; Duplikate sind möglich
  • 2 – „Genau einmal": Vier-Wege-Handshake sichert exakt einmalige Zustellung (langsamste, sicherste Option)

• Retain: Ist dieses Häkchen gesetzt, speichert der Broker die letzte Nachricht an diesem Topic und sendet sie sofort an jeden neuen Subscriber. Sinnvoll für Statusnachrichten, die auch nach dem Verbindungsaufbau noch bekannt sein sollen.

Bestehende Aktionen können über die Stift- und Papierkorb-Buttons in der Tabelle bearbeitet bzw. gelöscht werden.

Status von MQTT-Komponenten

Der Status einer MQTT-Komponente hängt von der serverweiten Broker-Verbindung ab:

• Online (grün): Die Verbindung zum MQTT-Broker ist aktiv.
• Offline (rot): Die Verbindung zum Broker ist unterbrochen. Dies betrifft alle MQTT-Komponenten gleichzeitig, da sie sich die Verbindung teilen.

Zusätzlich kann der Status einer einzelnen Komponente durch eingehende Ereignisse beeinflusst werden (siehe Felder Offline und Fail im Abschnitt MQTT-Ereignisse).

Im Gegensatz zu TCP/IP-Geräten sagt der grüne Status also nicht aus, ob ein einzelnes Gerät erreichbar ist – sondern nur, ob NeuroomNet mit dem Broker verbunden ist.

Broker-Konfiguration (Administrator)

Die Verbindungsparameter zum MQTT-Broker werden serverseitig in config.mqtt.json im Abschnitt mqtt.broker konfiguriert. Die wichtigsten Felder:

Feld	Bedeutung
url	Broker-URL, z. B. mqtt://192.168.1.10:1883 oder mqtts://broker.example.com:8883
clientId	Optionale Client-ID (wird sonst automatisch vergeben)
username / password	Zugangsdaten für einen gesicherten Broker
keepalive	Keepalive-Intervall in Sekunden (Standard: 60)
tls.caFile	Pfad zu einem Root-CA-Zertifikat (bei selbst signierten Broker-Zertifikaten)
tls.rejectUnauthorized	false deaktiviert die Zertifikatsprüfung (nur für Entwicklung/Tests)
onConnect	Nachricht, die beim Verbindungsaufbau veröffentlicht wird (Birth Message)
lastWill	Last Will and Testament – wird vom Broker veröffentlicht, wenn NeuroomNet die Verbindung unerwartet verliert

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

Tipps

MQTT-Komponenten sinnvoll benennen

Da alle MQTT-Komponenten dieselbe Broker-Verbindung nutzen, empfiehlt es sich, Komponenten nach dem Gerät oder der Funktion zu benennen, die sie repräsentieren – z. B. Beleuchtung Foyer, Klimaanlage Büro 2.12 oder Präsentationssystem Saal A. So bleibt die Zuordnung in Skriptblöcken eindeutig.

Payload-Filter gezielt einsetzen

Wenn ein Gerät verschiedene Zustände auf demselben Topic meldet (z. B. online, offline, error), können für denselben Topic mehrere Ereignisse mit unterschiedlichen Payload-Filtern angelegt werden. Jeder Zustand wird dann als eigenständiges NeuroomNet-Ereignis behandelt.

Beispiel: Topic gebaeude/geraet/1/status mit drei Ereignissen:

• Payload online → Ereignis GeraetOnline
• Payload offline → Ereignis GeraetOffline (mit Flag Offline aktiv)
• Payload leer → Ereignis GeraetStatusEmpfangen (empfängt den Payload als Parameter)

Benannte Wildcards für sprechende Parameternamen

Wenn ein Topic mehrere Wildcard-Positionen enthält oder die automatischen Namen (Level 1, Level 2, Subtopics) im Skripteditor unpraktisch sind, lohnt sich der Einsatz benannter Wildcards.

Beispiel Ereignis: Topic gebaeude/+:etage/raum/+:raum/temperatur liefert im Skripteditor die Parameter etage und raum statt Level 2 und Level 4.

Beispiel Aktion: Topic geraete/+:geraeteId/befehl erzeugt einen Pflichtparameter geraeteId, der beim Aufruf mit der konkreten Geräte-ID belegt wird.

Die Syntax hat keinen Einfluss auf das eigentliche MQTT-Protokoll.

Benutzerdefinierte Komponententypen und Aliase

Wenn mehrere MQTT-Komponenten vom gleichen Typ sind (z. B. mehrere gleichartige Leuchten), können benutzerdefinierte Komponententypen mit Aktions-Aliasen angelegt werden. So lassen sich sprechende Namen wie „Licht einschalten" verwenden statt des allgemeinen Aktionsnamens.

Siehe Modul Setup / Reiter Komponententypen für eine Erklärung hierzu.