MQTT Connector – Funktionsbeschreibung

Der MQTT Connector (HP.MQTTConnector) ist eine App von Herborner Pumpen für die FLECS-Plattform. Sie verbindet Ihre Steuerung – eine SPS oder ein Leitsystem – über MQTT mit den übrigen Herborner-Apps auf dem Gerät: Die App bringt einen eigenen MQTT-Broker mit, veröffentlicht dort die Werte der Pumpen als Topics und übernimmt die Werte, die die Steuerung schreibt. Sie ist das Gegenstück zum Modbus Connector für Anlagen, die MQTT statt Modbus TCP verwenden.

Die Apps im Zusammenspiel

Alle Apps laufen auf demselben FLECS-Gerät und tauschen ihre Daten ausschließlich über den Datenbus aus. Der MQTT Connector ist die einzige App mit einer MQTT-Schnittstelle zur Steuerung.

Steuerung (SPS)              HP.MQTTConnector                     Datenbus
┌─────────────┐ publiziert ┌────────────────────┐ Messwerte ┌──────────────────┐
│             │ ─────────► │ Command-Topics     │ ────────► │ HP.AiCore        │
│             │ abonniert  │ (Broker + App)     │ Kennwerte │                  │
│             │ ◄───────── │ State-Topics       │ ◄──────── │                  │
└─────────────┘            └────────────────────┘           ├──────────────────┤
                                                            │ HP.CloudLink     │ ◄──► Herborner-Cloud
                                                            └──────────────────┘

Datenfluss

1. Die Steuerung publiziert die Messwerte einer Pumpe – Volumenstrom, Drücke, Drehzahl, Leistung, Motorwerte, Umrichter-Status – auf die Command-Topics der Pumpe.
2. Der MQTT Connector prüft jeden Wert auf Datentyp und die zulässigen Grenzen (Min/Max) und gibt gültige Werte auf den Datenbus. Ungültige Werte werden verworfen und auf dem Fehler-Topic gemeldet.
3. HP.AiCore berechnet aus den Messwerten die Kennwerte der Pumpe und gibt sie auf den Datenbus.
4. Der MQTT Connector veröffentlicht Mess- und Kennwerte auf den State-Topics, die die Steuerung abonniert.
5. HP.CloudLink überträgt Mess- und Kennwerte in die Herborner-Cloud.

Nach einem Neustart fordert der MQTT Connector die Konfigurationen und die aktuellen Kennwerte bei den anderen Apps neu an, damit die State-Topics wieder gefüllt sind.

Pumpen und Entities

Pumpen haben einen festen Satz an Datenpunkten. Jeder Datenpunkt hat ein State-Topic, beschreibbare Datenpunkte zusätzlich ein Command-Topic. Die vollständige Liste mit Topics, Datentypen und Grenzwerten steht in der Standard-Konfiguration.

Die Topics einer Pumpe beginnen mit HP/pump/<Seriennummer>, z. B. HP/pump/AB-2400654-010-01:

Alle Schreib-Topics einer Pumpe liegen unter HP/pump/<Seriennummer>/set. Ein Datenpunkt mit dem Namen set erhält deshalb kein Topic.

Pfad über die Nummer: Auf Wunsch schaltet Herborner Pumpen zusätzlich oder statt der Seriennummer die Nummer des Geräts als Pfad ein (number_paths), etwa HP/pump/1/flow_rate. Beide Pfade tragen dieselben Werte und nehmen Befehle an. Die Seriennummer bleibt gleich, wenn Geräte in der Cloud umnummeriert werden; die Nummer nicht. Haben zwei Geräte vorübergehend dieselbe Nummer, behält das erste den Pfad über die Nummer; die Weboberfläche meldet den Konflikt in der Zeile Topics. Befehle über die Seriennummer erreichen immer genau ihr Gerät. Taugt eine Seriennummer nicht als Topic-Ebene (etwa mit /), erhält das Gerät keinen Pfad über sie; die Weboberfläche meldet das in der Zeile Topics.

Beschreibbar sind die Messwerte: Volumenstrom, Drücke (Druckseite, Saugseite, Vorfilter), Drehzahl, Wellenleistung, Motorstrom und -spannung, Betriebsstunden, Energieverbrauch, Umrichter-Statuswort und -Fehlercode, Füllstand Windkessel, Vorfilter gereinigt und Verschmutzungsgrad Vorfilter. Nur lesbar sind die Kennwerte von HP.AiCore – berechneter Volumenstrom¹, Differenzdruck, Wirkungsgrad, Pumpen-Statuswort, Vorfilterzustand¹ – sowie Name und Seriennummer der Pumpe.

¹ Nur, wenn das zugehörige Analysemodul für die Pumpe freigeschaltet ist; sonst bleibt das Topic leer.

Entities sind frei definierte Objekte ohne Pumpe, etwa Messstellen oder Behälter, mit eigenen Datenpunkten. Ihre Topics beginnen mit HP/entity/<UUID>, mit eingeschaltetem Pfad über die Nummer auch HP/entity/<Nr.>; Command-Topics gibt es nur für beschreibbare Datenpunkte.

Pumpen und Entities legt Herborner Pumpen in der Cloud an; HP.CloudLink überträgt ihre Konfiguration auf das Gerät, der MQTT Connector speichert sie lokal. Neu angelegte Pumpen, Entities und Datenpunkte erhalten ihre Topics sofort, ohne Neustart.

Verhalten der MQTT-Schnittstelle

• Erreichbarkeit: Port 1883 des Geräts, MQTT 3.1.1 und 5.0. Ist TLS eingeschaltet, nimmt das Gerät Verbindungen nur noch verschlüsselt auf Port 8883 an; Port 1883 bleibt dann der App selbst vorbehalten. Das Gerät weist sich mit einem selbst erzeugten Zertifikat aus, dem die Steuerung einmal vertraut, siehe Sicherheit.
• Anmeldung: Der Broker nimmt nur angemeldete Clients an, siehe Zugriff.
• State-Topics werden bei jeder Änderung veröffentlicht, nach jedem Verbindungsaufbau und spätestens alle 30 Sekunden vollständig – retained und mit QoS 0. Eine Steuerung, die sich neu verbindet, erhält deshalb sofort alle aktuellen Werte. Ist der Broker ausgelastet, erhält sie den neuesten Wert, keine Zwischenstände.
• Werte ohne Messung werden nicht veröffentlicht; im JSON-Objekt stehen sie als null.
• Formate: scalar (ein Topic je Wert, die Nutzlast ist der Wert als Text: 12.5, 1450, true), json (ein Topic je Pumpe) oder beides (Standard). Steuerungen ohne JSON-Parser verwenden die Einzelwerte.
• Zustand der App: HP/status steht auf online, solange die App mit dem Broker verbunden ist, sonst auf offline – auch bei einem Absturz (Last Will).
• Schreibbefehle abonniert die App mit QoS 1. Wahrheitswerte werden als true/false oder 1/0 angenommen. Ein JSON-Befehl mit mehreren Werten übernimmt alle gültigen Werte, auch wenn einzelne abgelehnt werden; jeder abgelehnte wird einzeln gemeldet.
• Abgelehnte Befehle erscheinen als JSON auf HP/error, z. B. {"topic": "HP/pump/AB-2400654-010-01/set/flow_rate", "reason": "out_of_range", "key": "flow_rate"}. Gründe: unknown_topic, invalid_payload, unknown_key, not_writable, out_of_range, retained, response_topic_denied.
• Antworten (MQTT 5): Setzt die Steuerung ein Response Topic unter HP/response/, etwa HP/response/plc, antwortet die App dort mit den übernommenen und abgelehnten Werten und der Correlation Data der Anfrage. Jedes andere Response Topic wird mit response_topic_denied abgelehnt; der Befehl selbst wird trotzdem ausgeführt.
• Befehle nicht retained senden: Ein retainter Befehl würde nach jedem Neustart des Brokers erneut ausgeführt. Die App verwirft ihn, meldet ihn und löscht ihn auf dem Broker.

Zugriff

Lesen dürfen alle Benutzer alle Topics unter HP/. Was ein Benutzer schreiben darf, legt seine Liste write fest; jeder Benutzer muss sie haben:

Mehrere Einträge lassen sich kombinieren. Durchgesetzt werden die Rechte vom Broker: Einen Befehl ohne Recht verwirft er, bevor er die App erreicht. Die Weboberfläche zeigt unter Telemetry je Datenpunkt in der Spalte write access, wer ihn schreiben darf (nur mit dem eigenen Broker; an einem fremden Broker gelten dessen Rechte), und meldet in der Zeile Users Einträge, die auf kein vorhandenes Gerät zeigen.

Standardmäßig gibt es zwei Benutzer:

Die Passwörter stehen nur als Hash in der Konfiguration (Format von mosquitto_passwd) und können so über eThemis gesetzt werden; ein geändertes Passwort gilt sofort. Alternativ werden sie als Umgebungsvariablen der App beim Einrichten auf dem Gerät gesetzt: MQTT_PASSWORD_PLC, MQTT_PASSWORD_MONITOR. Die App überträgt deren Hash in die Konfiguration; eine gesetzte Variable hat Vorrang vor einem Hash aus der Cloud und gilt nach dem nächsten Start der App. Ein Benutzer ohne Passwort kann sich nicht anmelden; die Weboberfläche zeigt ihn unter Users als gesperrt. Gelb wird die Zeile erst, wenn sich kein schreibender Benutzer anmelden kann. Weitere Benutzer kann Herborner Pumpen in der Konfiguration anlegen. Wie Sie ein sicheres Passwort wählen und setzen, steht unter Sicherheit.

Inbetriebnahme und Implementierung

Inbetriebnahme mit einem MQTT-Tool

Für die erste Prüfung genügt ein MQTT-Client auf einem Rechner im selben Netz, etwa MQTT Explorer oder mosquitto_sub/mosquitto_pub.

1. Verbindung prüfen: mit Benutzer plc und Passwort an <IP-Adresse>:1883 verbinden und HP/status abonnieren. Erwartet: online. Wird die Verbindung abgelehnt, ist das Passwort nicht gesetzt oder falsch.

2. Werte prüfen: HP/pump/# abonnieren. Unter HP/pump/<Seriennummer>/… erscheinen sofort die Werte jeder Pumpe. Erscheinen keine Pumpen-Topics, sind keine Pumpen konfiguriert – Herborner Pumpen muss sie in der Cloud anlegen, und HP.CloudLink muss auf dem Gerät laufen.

3. Schreiben prüfen: einen bekannten Wert schreiben und auf dem State-Topic beobachten:

   mosquitto_pub -h <IP-Adresse> -u plc -P <Passwort> -t HP/pump/<Seriennummer>/set/flow_rate -m 12.5
   mosquitto_sub -h <IP-Adresse> -u plc -P <Passwort> -t HP/pump/<Seriennummer>/flow_rate -t HP/error -v
   

   Die Weboberfläche zeigt unter Telemetry in der Zeile flow_rate den neuen Wert.

Implementierung in der Steuerung

• Beim Verbindungsaufbau HP/status abonnieren. Steht dort offline, eine Störung „MQTT Connector liefert keine Daten“ melden und die Werte als ungültig behandeln.
• State-Topics abonnieren, die die Steuerung braucht, oder HP/pump/<Seriennummer> für alle Werte einer Pumpe in einer Nachricht. Durch retained stehen die Werte direkt nach dem Abonnieren bereit. Nur die eigenen Geräte abonnieren, nicht HP/#: Sind beide Pfade eingeschaltet, käme dort jeder Wert doppelt an.
• Messwerte schreiben auf die Command-Topics, mit QoS 1 und ohne Retain-Flag.
• HP/error abonnieren, um abgelehnte Werte zu erkennen, etwa außerhalb von Min/Max.
• Neustart erkennen: Wechselt HP/status von offline auf online, hat die App neu gestartet; die Werte kommen danach vollständig neu.

Ablauf in Pseudocode:

beim Verbindungsaufbau:
    verbinde(benutzer="plc", passwort=…)
    pumpe = "HP/pump/AB-2400654-010-01"
    abonniere("HP/status", "HP/error", pumpe + "/#")

bei Nachricht:
    "HP/status"            -> daten_gültig = (payload == "online")
    "HP/error"             -> Störung melden (reason, key)
    pumpe + "/set…"        -> ignorieren (eigene Schreibbefehle)
    pumpe + "/<wert>"      -> wert übernehmen

zyklisch (z. B. 1 s):
    publiziere(pumpe + "/set/flow_rate", volumenstrom, qos=1, retain=false)

Einstellungen

Die Einstellungen von Broker, Client und Topics – Port, Topic-Basis, Format, Intervalle, Benutzer – sind mit ihren Standardwerten in der Standard-Konfiguration beschrieben. Herborner Pumpen kann sie über die Cloud anpassen; HP.CloudLink übergibt die Änderung an den MQTT Connector, und die aktuelle Konfiguration wird zurück in die Cloud gemeldet. Einzelne Werte lassen sich außerdem über Umgebungsvariablen der App setzen; sie werden dabei dauerhaft übernommen.

• Mehrere Geräte in einer Anlage: Jedes Gerät hat seinen eigenen Broker; die Topics stören sich nicht. Nur wenn die Broker mehrerer Geräte in einen zentralen Broker gespiegelt werden (Bridge), braucht jedes Gerät eine eigene Topic-Basis, etwa HP/halle2.
• Fremder Broker: Statt des eigenen Brokers kann sich die App mit einem vorhandenen Broker der Anlage verbinden. Die Zugangsdaten der App liegen dann in der Datei data/mosquitto/credentials.json auf dem Gerät.
• Alte Topics: Ändern sich die Topic-Basis oder der Name eines Topics, bleiben die alten retainten Werte auf dem Broker stehen. Entfernen lassen sie sich mit einer leeren retainten Nachricht (mosquitto_pub … -t <altes/topic> -r -n).

Weboberfläche

Die Weboberfläche der App zeigt:

• Telemetry: je Pumpe bzw. Entity eine Tabelle mit einer Zeile je Wert: aktueller Wert und Einheit, das State-Topic, auf dem die App ihn veröffentlicht, das Command-Topic, auf dem ein Client ihn schreiben kann (nur beschreibbare Werte). Mit dem JSON-Format steht zuoberst die Zeile all values (JSON) mit der vollständigen Nachricht. Geänderte Zeilen sind etwa 20 Sekunden lang hervorgehoben, gleich ob der Wert von der Pumpe oder aus einem Befehl kam. Dazu der Zustand der App (Verbindung zum Broker, Broker-Prozess, verbundene Clients, anmeldbare Benutzer, TLS mit Ablaufdatum, kopierbarem Fingerabdruck und Download des Zertifikats, Anzahl Topics),
• Logs: die letzten Protokolleinträge, auch die des eigenen Brokers (Start, An- und Abmeldungen, Fehler; mit Mosquitto: gekennzeichnet, die Client-ID der App gekürzt),
• Statistics: Nachrichten, Befehle, Verbindungsabbrüche und abgelehnte Befehle,
• Jobs: Wartungsaufträge, die Herborner Pumpen über die Cloud anstößt, etwa die Installation, Aktualisierung oder den Neustart einer anderen App auf dem Gerät. Der MQTT Connector kann sich selbst nicht aktualisieren oder neu starten.

Ereignisse und Protokolle der App gelangen über HP.CloudLink auch in die Herborner-Cloud.

Sicherheit

Der Broker verlangt Benutzername und Passwort; jeder Benutzer darf nur die Geräte schreiben, die seine Schreibrechte erlauben. Ohne TLS werden Passwörter und Werte jedoch unverschlüsselt übertragen. Mit TLS erzeugt die App Schlüssel und Zertifikat selbst und erneuert sie; der Schlüssel verlässt das Gerät nie. Lässt sich TLS nicht einrichten, arbeitet der Broker mit der bisherigen Einstellung weiter und die Weboberfläche zeigt den Fehler. Die Apps auf dem Gerät tauschen Konfigurationen und Befehle nur noch signiert aus; Nachrichten anderer Absender verwirft die App. Die Weboberfläche arbeitet ohne Anmeldung. Betreiben Sie das Gerät nur in einem vertrauenswürdigen Netz und sichern Sie den Zugang zu Port 1883 und zur Weboberfläche über Firewall oder Netzwerksegmentierung ab.

Wie die einzelnen Sicherheitsebenen wirken und wie Sie sie einrichten, beschreibt die Seite Sicherheit.

Lizenzen

Für die Nutzung gelten die Lizenz und die Lizenzbedingungen (EULA). Der MQTT-Broker Eclipse Mosquitto wird unverändert als eigener Prozess ausgeliefert. Die enthaltene Drittanbieter-Software ist unter Drittanbieter-Lizenzen aufgeführt.