Node-RED MQTT: verbinden, subscriben und publishen

Node-RED und MQTT sind ein natürliches Paar: MQTT bewegt Nachrichten zwischen Geräten, und mit Node-RED verdrahtest du diese Nachrichten mit Dashboards, Datenbanken, Alerts und APIs, ohne eine komplette Anwendung zu schreiben. Node-RED bringt von Haus aus zwei MQTT-Nodes mit – mqtt in und mqtt out – plus einen gemeinsam genutzten Broker-Config-Node. Dieses Tutorial behandelt alle drei und endet mit einem Flow, den du importieren kannst.

Node-RED starten

Wenn du Node-RED noch nicht hast, geht es am schnellsten mit npm oder Docker:

# with Node.js installed
npm install -g --unsafe-perm node-red
node-red

# or with Docker
docker run -it -p 1880:1880 -v node_red_data:/data --name nodered nodered/node-red

Öffne http://localhost:1880 im Browser. Node-RED ist nur die Client-Seite – einen Broker brauchst du trotzdem. Für die lokale Entwicklung betreibst du Mosquitto in Docker daneben; für einen schnellen Test funktioniert der öffentliche HiveMQ-Broker ganz ohne Setup.

Den MQTT-Broker-Node konfigurieren

Zieh einen mqtt in-Node auf die Arbeitsfläche, doppelklicke ihn und klicke auf das Stiftsymbol neben Server, um eine Broker-Konfiguration anzulegen. Alle MQTT-Nodes, die denselben Config-Node nutzen, teilen sich eine Verbindung.

Die Will-Nachricht im Tab Messages ist der Last Will von MQTT – siehe Last Will and Testament. Ein grünes connected unter jedem MQTT-Node nach dem Deploy bedeutet, dass der Broker die Verbindung akzeptiert hat. Nicht sicher, welchen Port dein Broker nutzt? Sieh unter MQTT-Ports erklärt nach.

Subscriben mit dem mqtt-in-Node

Trage unter Topic ein, was abonniert werden soll – Wildcards sind erlaubt, sodass testmqtt/nodered-demo/+/telemetry die Telemetrie aller Räume empfängt. Jede eingehende Nachricht wird zu einer Node-RED-msg mit:

• msg.payload – dem Inhalt der Nachricht
• msg.topic – dem konkreten Topic, auf dem sie ankam
• msg.qos und msg.retain – Details zur Zustellung

Teste deine Topic-Filter vor dem Deploy mit dem MQTT-Topic-Matcher. Die Option Output bestimmt den Typ von msg.payload:

• auto-detect (string or buffer) – Text wird zum String, Binärdaten bleiben ein Buffer.
• a parsed JSON object – der Node führt JSON.parse für dich aus, sodass msg.payload.temp direkt nutzbar ist. Ungültiges JSON erzeugt einen Fehler, den du mit einem catch-Node abfangen kannst.
• auto-detect (parsed JSON object, string or buffer) – parst JSON, wenn möglich, und fällt sonst auf einen String zurück.

Wenn du magst, behältst du die Standardausgabe und hängst einen json-Node hinter mqtt in; er wandelt einen JSON-String in ein Objekt um und zurück.

Dynamische Subscriptions

Stellst du den Topic-Typ des mqtt-in-Nodes auf Dynamic subscription, bekommt er einen Eingang. Schick ihm eine Nachricht mit msg.action auf subscribe (und dem Topic in msg.topic), unsubscribe, connect oder disconnect, um ihn zur Laufzeit zu steuern – praktisch, wenn sich die Liste der Geräte ändert.

Publishen mit dem mqtt-out-Node

Der mqtt-out-Node publisht msg.payload. Ist die Payload ein Objekt, wird sie automatisch in einen JSON-String umgewandelt. Seine Felder dienen als Fallback:

• Topic – leer lassen, um msg.topic zu verwenden. So publishst du auf dynamische Topics, etwa ein Topic pro Gerät.
• QoS und Retain – leer lassen, um msg.qos und msg.retain aus der Nachricht zu übernehmen.

Ein Function-Node ist der einfachste Weg, das Topic pro Nachricht zu bauen:

const room = msg.payload.room || 'unknown';
msg.topic = 'testmqtt/nodered-demo/' + room + '/telemetry';
msg.payload = { temp: msg.payload.temp, ts: Date.now() };
msg.qos = 1;
return msg;

Retained Status und Birth Messages

Der Broker-Config-Node kann beim Verbinden eine Birth-Nachricht publishen, vor einem sauberen Disconnect eine Close-Nachricht und eine Will-Nachricht, falls die Verbindung abreißt. Zeigen alle drei auf ein Retained Topic wie nodered/status mit online und offline, können andere Systeme zuverlässig erkennen, ob deine Node-RED-Instanz läuft. Retained Messages werden unter MQTT Retained Messages erklärt.

Mit dem Protokoll MQTT V5 bieten die Nodes zusätzliche Optionen wie Message Expiry, Content Type, User Properties und die Subscription-Flags No Local, Retain As Published und Retain Handling.

Beispiel-Flow zum Importieren

Dieser Flow publisht alle 10 Sekunden einen zufälligen Temperaturwert auf testmqtt/nodered-demo/room1/telemetry, abonniert alle Räume mit aktiviertem JSON-Parsing und gibt Werte über 24 °C in der Debug-Seitenleiste aus. Kopiere ihn, öffne das Menü, wähle Import, füge ihn ein und deploye.

[
  {
    "id": "b1a1c0de00000001",
    "type": "mqtt-broker",
    "name": "HiveMQ public",
    "broker": "broker.hivemq.com",
    "port": "1883",
    "clientid": "",
    "autoConnect": true,
    "usetls": false,
    "protocolVersion": "4",
    "keepalive": "60",
    "cleansession": true
  },
  {
    "id": "b1a1c0de00000002",
    "type": "inject",
    "name": "every 10 s",
    "props": [{ "p": "payload" }],
    "repeat": "10",
    "once": true,
    "onceDelay": "1",
    "payload": "",
    "payloadType": "date",
    "x": 130,
    "y": 80,
    "wires": [["b1a1c0de00000003"]]
  },
  {
    "id": "b1a1c0de00000003",
    "type": "function",
    "name": "build reading",
    "func": "msg.topic = 'testmqtt/nodered-demo/' + 'room1' + '/telemetry';\nmsg.payload = { temp: +(18 + Math.random() * 8).toFixed(1), ts: msg.payload };\nreturn msg;",
    "outputs": 1,
    "x": 320,
    "y": 80,
    "wires": [["b1a1c0de00000004"]]
  },
  {
    "id": "b1a1c0de00000004",
    "type": "mqtt out",
    "name": "publish",
    "topic": "",
    "qos": "1",
    "retain": "false",
    "broker": "b1a1c0de00000001",
    "x": 510,
    "y": 80,
    "wires": []
  },
  {
    "id": "b1a1c0de00000005",
    "type": "mqtt in",
    "name": "subscribe",
    "topic": "testmqtt/nodered-demo/+/telemetry",
    "qos": "1",
    "datatype": "json",
    "broker": "b1a1c0de00000001",
    "nl": false,
    "rap": true,
    "rh": 0,
    "inputs": 0,
    "x": 140,
    "y": 160,
    "wires": [["b1a1c0de00000006"]]
  },
  {
    "id": "b1a1c0de00000006",
    "type": "switch",
    "name": "temp > 24",
    "property": "payload.temp",
    "propertyType": "msg",
    "rules": [{ "t": "gt", "v": "24", "vt": "num" }],
    "checkall": "true",
    "outputs": 1,
    "x": 330,
    "y": 160,
    "wires": [["b1a1c0de00000007"]]
  },
  {
    "id": "b1a1c0de00000007",
    "type": "debug",
    "name": "too warm",
    "active": true,
    "tosidebar": true,
    "complete": "true",
    "x": 510,
    "y": 160,
    "wires": []
  }
]

Verfolge dieselben Nachrichten außerhalb von Node-RED, um zu bestätigen, dass sie wirklich beim Broker ankommen:

Deine Node-RED-Nachrichten live ansehen

Fehlerbehebung

• Hängt bei „connecting“ – falscher Port oder falsche TLS-Einstellung, oder im Feld Server steht mqtt://. Trag nur den Hostnamen ein.
• Verbindet sich und trennt sich in einer Schleife – ein anderer Client nutzt dieselbe Client-ID, oft eine zweite Node-RED-Instanz mit kopiertem Flow. Leere das Feld.
• Es kommen keine Nachrichten an – das Subscription-Topic passt nicht zum Publish-Topic (Groß-/Kleinschreibung zählt), oder eine ACL auf dem Broker verweigert es. Mehr dazu im Leitfaden zu MQTT-Verbindungsfehlern.

Willst du Logik später aus Node-RED in ein Skript auslagern? Der MQTT-Code-Generator erzeugt Client-Code für deine eigenen Broker-Einstellungen in Python, JavaScript und mehr, und der Online-MQTT-Client ist praktisch, um beim Bauen von Flows Topics zu untersuchen.

Häufig gestellte Fragen