MQTT Adressen I/O – Anbindung an Node-RED und Home Assistant

Diese Seite beschreibt Schritt für Schritt, wie Fremdsysteme wie Node-RED und Home Assistant über den Funktionsbaustein MQTT Adressen I/O mit der uni-PRO Steuerung verbunden werden. Der Baustein sendet die Werte der Variablen (Adressen) als MQTT Nachrichten an einen MQTT Broker und übernimmt umgekehrt Werte, die von Fremdsystemen an den Broker gesendet werden.

Wichtig: Für diese Funktion muss die Steuerung eine Image Version 3.034 oder höher haben.

MQTT Grundlagen

MQTT ist ein einfaches Nachrichtenprotokoll für die Gebäude- und Geräteautomatisierung. Alle Teilnehmer verbinden sich mit einem zentralen Server, dem Broker:

• Topic: Jede Nachricht wird unter einem Namen, dem Topic, veröffentlicht, z.B. "uniPRO/100/10/1". Topics sind wie Pfade mit "/" gegliedert.
• Payload: Der Inhalt der Nachricht, hier der Wert der Variable, z.B. "21.5".
• Publish / Subscribe: Ein Teilnehmer veröffentlicht (publish) Nachrichten, andere Teilnehmer abonnieren (subscribe) Topics und erhalten die Nachrichten automatisch.
• Wildcards: Beim Abonnieren kann "+" für eine Ebene und "#" für alle folgenden Ebenen verwendet werden. "uniPRO/#" empfängt also alle Nachrichten des Bausteins.
• Retain: Der Broker merkt sich die letzte Nachricht eines Topics und liefert sie an neue Abonnenten sofort aus. Der Parameter "Retain" des Bausteins ist standardmäßig aktiv, damit Fremdsysteme nach einem Neustart sofort alle Werte kennen.

Aufbau der MQTT Nachrichten des Bausteins

Das Topic wird aus dem Parameter "Topic Präfix" (Standard "uniPRO") und der Adresse Hauptgruppe/Mittelgruppe/Untergruppe gebildet:

Es werden nur Adressen der im Parameter "Filter Hauptgruppe" eingestellten Hauptgruppen gesendet und empfangen.

Baustein konfigurieren

1. Funktionsbaustein "MQTT Adressen I/O" im Programm einfügen.
2. Server Typ:
   • Intern: Der in der Steuerung integrierte MQTT Broker wird verwendet. Es ist keine weitere Einstellung nötig. Fremdsysteme verbinden sich dann mit der IP Adresse der Steuerung, Port 1883, ohne Benutzer/Passwort.
   • Extern: Ein externer Broker (z.B. Mosquitto) wird verwendet. Server, Port und optional Benutzer/Passwort und TLS angeben.
3. Filter Hauptgruppe: Hauptgruppen der zu übertragenden Variablen angeben, mehrere durch Semikolon getrennt, z.B. "100;101".
4. "Beim Start aktualisieren" und "Retain" aktiviert lassen, damit Fremdsysteme immer aktuelle Werte haben.

Alle Parameter im Detail: Hilfe MQTT Adressen I/O. Zur Kontrolle der Nachrichten kann im Studio die MQTT Diagnose verwendet werden (Menü Diagnose).

Node-RED

Node-RED ist ein grafisches Werkzeug, mit dem Abläufe (Flows) per Drag & Drop aus Bausteinen (Nodes) zusammengesetzt werden. Es läuft z.B. auf einem Raspberry Pi, einem Server oder in Docker. Die Installation ist hier beschrieben: nodered.org/docs/getting-started. Nach der Installation wird der Editor im Browser unter "http://<IP-Adresse>:1880" geöffnet.

Die MQTT Nodes

Die MQTT Nodes sind fester Bestandteil von Node-RED und müssen nicht nachinstalliert werden. Sie befinden sich in der Palette links in der Kategorie "Netzwerk" (network):

• mqtt in: Abonniert ein Topic und gibt jede empfangene Nachricht als Nachricht (msg.payload) an die nachfolgenden Nodes weiter. Damit werden Werte von uni-PRO empfangen.
• mqtt out: Veröffentlicht die eingehende msg.payload unter einem Topic. Damit werden Werte an uni-PRO gesendet.

Sollten zusätzliche Nodes benötigt werden (z.B. Dashboards), können diese über Menü (☰) → "Palette verwalten" installiert werden.

Broker Verbindung anlegen

Einen "mqtt in" Node in den Flow ziehen und per Doppelklick öffnen. Neben "Server" über das Stift-Symbol eine neue mqtt-broker Konfiguration anlegen:

• Server: IP Adresse des Brokers. Beim internen Broker die IP Adresse der Steuerung angeben.
• Port: 1883 (Standard).
• Security: Benutzername/Passwort nur nötig, wenn der Broker eine Anmeldung verlangt. Der interne Broker der Steuerung benötigt keine Anmeldung.

Die Konfiguration muss nur einmal angelegt werden und kann dann in allen MQTT Nodes ausgewählt werden.

Werte empfangen (mqtt in)

• Topic: "uniPRO/#" empfängt alle Variablen des Bausteins. Eine einzelne Variable wird mit dem vollen Topic abonniert, z.B. "uniPRO/100/10/1".
• QoS: 2 (Standard) kann beibehalten werden.
• Output: "auto-detect" kann beibehalten werden, der Wert kommt dann als Text in msg.payload an, das Topic in msg.topic.

Werte senden (mqtt out)

• Topic: Volles Topic der Variable, z.B. "uniPRO/100/10/1". Bleibt das Feld leer, wird msg.topic der eingehenden Nachricht verwendet.
• Der zu sendende Wert wird als msg.payload übergeben, z.B. "21.5" oder bei Bitvariablen "1"/"0", "on"/"off" oder "true"/"false".

Beispiel Flow

1. Einen "mqtt in" Node (Topic "uniPRO/#") mit einem "debug" Node verbinden.
2. Einen "inject" Node (Payload z.B. Zahl 21.5) mit einem "mqtt out" Node (Topic "uniPRO/100/10/1") verbinden.
3. Rechts oben auf "Deploy" (übernehmen) klicken. Unter den MQTT Nodes muss "connected" (verbunden) erscheinen.
4. Empfangene Werte erscheinen in der Debug-Seitenleiste (Käfer-Symbol rechts). Ein Klick auf den inject Node sendet den Wert an uni-PRO.

Weitere Beispiele: Node-RED Cookbook MQTT, Dokumentation: nodered.org/docs.

Home Assistant

Home Assistant ist eine Open-Source Software für die Hausautomation. Für die Anbindung wird die MQTT Integration von Home Assistant verwendet.

MQTT Broker

Home Assistant und der uni-PRO Baustein müssen denselben Broker verwenden. Zwei Möglichkeiten:

• Interner Broker der Steuerung: Im Baustein "Server Typ" = "Intern" wählen. In Home Assistant wird als Broker die IP Adresse der Steuerung angegeben, Port 1883, ohne Benutzer/Passwort.
• Mosquitto Add-on: Läuft der Broker in Home Assistant (Add-on "Mosquitto broker"), im Baustein "Server Typ" = "Extern" wählen und IP Adresse von Home Assistant, Port 1883 sowie die im Add-on angelegten Zugangsdaten eintragen.

MQTT Integration einrichten

In Home Assistant: Einstellungen → Geräte & Dienste → Integration hinzufügen, nach "MQTT" suchen und die Verbindungsdaten des Brokers eingeben:

Automatische Einbindung (Auto Discovery)

Wird im Baustein der Parameter "Home Assistant Auto Discovery" aktiviert, sendet der Baustein für jede Variable eine Konfigurationsnachricht an Home Assistant. Die Variablen erscheinen dann automatisch als Entitäten vom Typ "number" (Zahl), der Name der Entität ist der Kommentar der Adresse:

Wichtig: Bei aktiviertem Auto Discovery muss der Parameter "Topic Präfix" auf dem Standardwert "uniPRO" bleiben, da die automatisch erzeugte Konfiguration diese Topics verwendet. Zurzeit werden nur Entitäten vom Typ "number" erzeugt; alle Werte werden dabei als Zahl übertragen.

Manuelle Einbindung (configuration.yaml)

Alternativ (oder zusätzlich, z.B. für Schalter) können Entitäten manuell in der Datei configuration.yaml angelegt werden. Beispiel für einen Sensor und einen Schalter:

mqtt:
  sensor:
    - name: "Wohnzimmer Temperatur"
      state_topic: "uniPRO/100/10/1"
      unit_of_measurement: "°C"
  switch:
    - name: "Licht Wohnzimmer"
      state_topic: "uniPRO/101/1/1"
      command_topic: "uniPRO/101/1/1"
      payload_on: "1"
      payload_off: "0"

payload_on/payload_off müssen zum Parameter "Typ Bitvariable" des Bausteins passen (z.B. "on"/"off" statt "1"/"0"). Nach Änderungen an der configuration.yaml muss Home Assistant neu gestartet werden. Details: Home Assistant MQTT Dokumentation.

Testen

Unter Einstellungen → Geräte & Dienste → MQTT → Konfigurieren bietet Home Assistant ein Testwerkzeug: Mit "Auf ein Topic lauschen" und dem Topic "uniPRO/#" werden alle Nachrichten des Bausteins angezeigt. Über "Ein Paket veröffentlichen" kann ein Wert testweise an eine Adresse gesendet werden (Topic z.B. "uniPRO/100/10/1", Payload "21.5").

Tipps zur Fehlersuche

• Der Ausgang "VB" des Bausteins muss 1 sein (mit MQTT Broker verbunden).
• Im Studio zeigt die MQTT Diagnose alle gesendeten und empfangenen Nachrichten des Brokers an.
• In Node-RED mit einem "mqtt in" Node und Topic "#" bzw. in Home Assistant mit "Auf ein Topic lauschen" prüfen, ob Nachrichten ankommen.
• Prüfen ob Port 1883 erreichbar ist (Firewall, Netzwerk).
• Die Hauptgruppe der Adresse muss im Parameter "Filter Hauptgruppe" enthalten sein.
• Für Senden und Empfangen wird empfohlen, zwei Bausteine mit unterschiedlichen Hauptgruppen zu verwenden (Parameter "Modus").

Hinweis: Node-RED, Home Assistant und Mosquitto sind Produkte von Drittanbietern. Für Installation, Betrieb und Absicherung dieser Software ist der Anwender selbst verantwortlich; die verlinkten Dokumentationen können sich ändern.