Node-RED MQTT Tutorial: Flows, Dashboards und Automatisierung

Dieses Node-RED MQTT Tutorial zeigt Ihnen, wie Sie Node-RED mit einem Broker verbinden, Nachrichten empfangen und veröffentlichen, rohes JSON in ein Live-Dashboard verwandeln und Alarme auslösen, wenn Werte einen Schwellenwert überschreiten. Sie beginnen auf dem kostenlosen öffentlichen Broker unter broker.connectmq.com mit einem importierbaren Flow und stellen denselben Flow dann durch Ändern eines einzigen Konfigurations-Nodes auf einen privaten, TLS-verschlüsselten Broker um. Alles hier funktioniert auf einem Laptop, einem Raspberry Pi oder in einem Docker-Container.

Warum Node-RED und MQTT zusammenpassen

Node-RED ist ein Werkzeug für flussbasierte Programmierung: Sie verbinden Nodes in einem Browser-Editor miteinander, und jede Nachricht wandert als JavaScript-Objekt namens msg entlang der Verbindungen. MQTT ist ein Publish/Subscribe-Protokoll, bei dem Clients über einen Broker anhand von Topics Nachrichten austauschen. Beide teilen dasselbe Denkmodell. Ein mqtt in-Node ist ein Subscriber, der Nachrichten in einen Flow einspeist, und ein mqtt out-Node ist ein Publisher, der alles sendet, was bei ihm ankommt.

Das macht Node-RED zu einer natürlichen Verbindungsschicht rund um ein MQTT-System. Typische Aufgaben sind:

• Übersetzen zwischen Geräten, die unterschiedliche Payload-Formate sprechen.
• Schnelle Bediener-Dashboards ohne Frontend-Projekt bauen.
• Schwellenwerte überwachen und Benachrichtigungen per E-Mail oder Chat senden.
• Telemetrie in eine Zeitreihendatenbank schreiben.
• Protokolle wie Modbus, OPC UA oder HTTP in MQTT-Topics überführen.

Wenn Sie Ihr Wissen zu Brokern, Topics und Wildcards zuerst auffrischen möchten, lesen Sie was ein MQTT Broker leistet. Der Rest dieses Leitfadens setzt voraus, dass Sie wissen, dass + auf eine Topic-Ebene passt und # auf alles unterhalb einer Ebene.

Node-RED installieren

Wählen Sie die Installationsart, die zu Ihrem Rechner passt. Jede aktuelle Node-RED-4.x-Version enthält die MQTT-Nodes; bis zum Dashboard-Schritt brauchen Sie für dieses Tutorial keine zusätzlichen Pakete.

# Option 1: npm (erfordert Node.js 18 oder neuer)
sudo npm install -g --unsafe-perm node-red
node-red

# Option 2: Docker
docker run -d --name nodered -p 1880:1880 -v node_red_data:/data nodered/node-red:4.0

# Option 3: Raspberry Pi OS / Debian, offizielles Installationsskript
bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-node-red)

Öffnen Sie http://localhost:1880 (oder die Adresse des Pi) im Browser. Zu Diensteinrichtung, Upgrades und Windows-Besonderheiten siehe unsere Schritt-für-Schritt-Anleitung zum Installieren von Node-RED, und wenn Sie Container bevorzugen, behandelt Node-RED in Docker betreiben Volumes und Restart-Policies. Die offizielle Node-RED-Dokumentation ist die Referenz für jeden Core-Node.

Schritt 1: Den MQTT-Broker-Node konfigurieren

Jeder MQTT-Node in Node-RED verweist auf einen gemeinsamen Konfigurations-Node vom Typ mqtt-broker. Konfigurieren Sie ihn einmal und verwenden Sie ihn in allen Flows wieder; Node-RED hält dann eine einzige Verbindung zum Broker, was bei Brokern wichtig ist, die die Verbindungen pro Konto begrenzen.

Ziehen Sie einen mqtt in-Node auf die Arbeitsfläche, doppelklicken Sie ihn und klicken Sie auf den Stift neben Server, um einen neuen Broker hinzuzufügen:

Legen Sie auf dem Reiter Messages eine Birth-Nachricht fest (connectmq/demo/nr-7f3a/status, Payload online, retained, QoS 1) und eine Will-Nachricht auf demselben Topic mit offline. Andere Clients sehen nun, ob Ihre Node-RED-Instanz läuft.

Warum die Client ID selbst eintragen? Lassen Sie sie leer, erzeugt Node-RED eine, was auf dem öffentlichen MQTT-Broker für Tests in Ordnung ist. Auf einem produktiven Broker, der Client IDs an Zugangsdaten bindet, müssen Sie genau die ausgegebene ID eintragen. Zwei Node-RED-Instanzen (etwa Ihr Laptop und Ihr Pi) mit derselben Client ID trennen sich immer wieder gegenseitig.

Schritt 2: Einen funktionierenden Flow importieren

Am schnellsten lernen Sie, indem Sie einen vollständigen Flow importieren und auseinandernehmen. Öffnen Sie im Editor das Menü, wählen Sie Import, fügen Sie das folgende JSON ein und klicken Sie auf Import. Ersetzen Sie vorher jedes nr-7f3a durch Ihr eigenes zufälliges Suffix, damit Sie sich keine Topics mit anderen Lesern dieses Node-RED MQTT Tutorials teilen.

[
  { "id": "tab_mqtt", "type": "tab", "label": "MQTT tutorial" },
  {
    "id": "cmq_broker", "type": "mqtt-broker", "name": "ConnectMQ public",
    "broker": "broker.connectmq.com", "port": "1883", "clientid": "nodered-7f3a",
    "autoConnect": true, "usetls": false, "protocolVersion": "5", "keepalive": "60",
    "cleansession": true, "autoUnsubscribe": true,
    "birthTopic": "connectmq/demo/nr-7f3a/status", "birthQos": "1", "birthRetain": "true", "birthPayload": "online", "birthMsg": {},
    "closeTopic": "connectmq/demo/nr-7f3a/status", "closeQos": "1", "closeRetain": "true", "closePayload": "offline", "closeMsg": {},
    "willTopic": "connectmq/demo/nr-7f3a/status", "willQos": "1", "willRetain": "true", "willPayload": "offline", "willMsg": {},
    "userProps": "", "sessionExpiry": ""
  },
  {
    "id": "inj_tick", "type": "inject", "z": "tab_mqtt", "name": "every 5 s",
    "props": [{ "p": "payload" }], "repeat": "5", "crontab": "", "once": true, "onceDelay": "1",
    "topic": "", "payload": "", "payloadType": "date", "x": 120, "y": 80, "wires": [["fn_sim"]]
  },
  {
    "id": "fn_sim", "type": "function", "z": "tab_mqtt", "name": "simulate sensor",
    "func": "const base = 25 + 6 * Math.sin(Date.now() / 60000);\nmsg.payload = {\n  temperature: Math.round((base + Math.random()) * 10) / 10,\n  humidity: Math.round(40 + Math.random() * 10),\n  ts: Date.now()\n};\nreturn msg;",
    "outputs": 1, "x": 310, "y": 80, "wires": [["out_tel"]]
  },
  {
    "id": "out_tel", "type": "mqtt out", "z": "tab_mqtt", "name": "publish telemetry",
    "topic": "connectmq/demo/nr-7f3a/line1/sensor1/telemetry", "qos": "0", "retain": "false",
    "broker": "cmq_broker", "x": 530, "y": 80, "wires": []
  },
  {
    "id": "in_tel", "type": "mqtt in", "z": "tab_mqtt", "name": "all sensors",
    "topic": "connectmq/demo/nr-7f3a/+/+/telemetry", "qos": "1", "datatype": "auto-detect",
    "broker": "cmq_broker", "nl": false, "rap": true, "rh": 0, "inputs": 0,
    "x": 130, "y": 180, "wires": [["fn_alert", "dbg_tel"]]
  },
  {
    "id": "fn_alert", "type": "function", "z": "tab_mqtt", "name": "alert on crossing 30 C",
    "func": "const t = Number(msg.payload.temperature);\nif (Number.isNaN(t)) return null;\nconst key = msg.topic;\nconst wasHigh = context.get(key) || false;\nconst isHigh = t > 30;\ncontext.set(key, isHigh);\nif (isHigh === wasHigh) return null;\nmsg.topic = msg.topic.replace(/telemetry$/, 'alert');\nmsg.payload = { level: isHigh ? 'high' : 'normal', temperature: t, ts: Date.now() };\nreturn msg;",
    "outputs": 1, "x": 360, "y": 180, "wires": [["out_alert", "dbg_alert"]]
  },
  {
    "id": "out_alert", "type": "mqtt out", "z": "tab_mqtt", "name": "publish alert",
    "topic": "", "qos": "1", "retain": "true", "broker": "cmq_broker", "x": 590, "y": 160, "wires": []
  },
  {
    "id": "dbg_tel", "type": "debug", "z": "tab_mqtt", "name": "telemetry", "active": true,
    "tosidebar": true, "console": false, "complete": "payload", "x": 340, "y": 240, "wires": []
  },
  {
    "id": "dbg_alert", "type": "debug", "z": "tab_mqtt", "name": "alerts", "active": true,
    "tosidebar": true, "console": false, "complete": "true", "x": 580, "y": 220, "wires": []
  }
]

Klicken Sie auf Deploy. Innerhalb weniger Sekunden wird die kleine Statusanzeige unter jedem MQTT-Node grün mit dem Wort „connected“, und die Debug-Seitenleiste zeigt Telemetrieobjekte an. Prüfen Sie in einem Terminal, dass die Nachrichten wirklich über den Broker laufen:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-cli-7f3a -v -t "connectmq/demo/nr-7f3a/#"

Sie sollten zuerst die Retained-Nachricht status sehen, dann alle fünf Sekunden eine Telemetrienachricht und, sobald die simulierte Temperatur die 30 überschreitet, einen Alarm.

Schritt 3: Die Nodes mqtt in und mqtt out verstehen

Der importierte Flow nutzt jeden MQTT-Node auf eine bestimmte Weise, und diese Einstellungen werden Sie am häufigsten ändern.

Der mqtt-in-Node

• Topic akzeptiert Wildcards. connectmq/demo/nr-7f3a/+/+/telemetry empfängt die Telemetrie aller Sensoren auf allen Linien unter Ihrem Präfix, und msg.topic verrät Ihnen, wer sie gesendet hat.
• Output auf auto-detect gesetzt parst JSON-Payloads in Objekte, belässt reinen Text als String und gibt Binärdaten als Buffer weiter. Wenn ein Gerät manchmal fehlerhaftes JSON sendet, wählen Sie stattdessen a String und parsen Sie selbst mit einem JSON-Node, damit Sie Fehler abfangen können.
• QoS ist die maximale QoS, die Sie empfangen möchten. Der Broker liefert mit dem niedrigeren Wert aus Publisher- und Subscriber-QoS.
• Dynamisches Abonnement: Stellen Sie den Node so ein, dass er Eingaben akzeptiert, und senden Sie ihm msg.action = "subscribe" mit msg.topic. So kann ein Flow Topics folgen, die erst zur Laufzeit bekannt sind; der Leitfaden zu dynamischen MQTT-Abonnements in Node-RED enthält ein vollständiges Beispiel.

Der mqtt-out-Node

• Ist das Feld Topic des Nodes leer, veröffentlicht er auf msg.topic. Der Alarmzweig verlässt sich darauf: Der Function-Node schreibt das Topic von .../telemetry auf .../alert um.
• Ist das Feld Topic ausgefüllt, überschreibt es msg.topic. Ein häufiger Anfängerfehler ist, beides zu setzen und sich zu wundern, warum Nachrichten auf dem falschen Topic landen.
• Objekte in msg.payload werden automatisch als JSON serialisiert. Zahlen und Booleans werden zu Strings.
• Retain auf Alarm- und Zustands-Topics bedeutet, dass jeder später abonnierende Client sofort den neuesten Wert sieht. Lassen Sie es bei hochfrequenter Telemetrie aus.

Für tiefergehende JSON-Verarbeitung, einschließlich der Umwandlung von Strings in Objekte und zurück, siehe den Node-RED-JSON-Node. Um Logik wie die Alarmfunktion zu schreiben, lesen Sie den Node-RED-Function-Node, der Context-Speicher, mehrere Ausgänge und Fehlerbehandlung behandelt.

Schritt 4: Ein Node-RED-MQTT-Dashboard bauen

Rohe Debug-Ausgaben kann man keinem Bediener vorlegen. Dashboard 2.0 ist das aktuelle, aktiv gepflegte Dashboard für Node-RED. Installieren Sie es über Manage palette mit der Suche nach @flowfuse/node-red-dashboard oder über die Kommandozeile:

cd ~/.node-red
npm install @flowfuse/node-red-dashboard
# Node-RED danach neu starten

Erweitern Sie dann Ihren Flow:

1. Fügen Sie nach dem mqtt-in-Node all sensors einen function-Node mit dem folgenden Code hinzu. Er teilt jedes Telemetrieobjekt in diagrammfreundliche Nachrichten auf.
2. Verbinden Sie seinen ersten Ausgang mit einem ui-gauge (Bereich 0 bis 50, Beschriftung „Temperature“) und zusätzlich mit einem ui-chart (Typ Linie, X-Achse Zeit).
3. Verbinden Sie den zweiten Ausgang mit einem zweiten ui-gauge für die Luftfeuchtigkeit.
4. Wenn Sie das erste Widget hinzufügen, fordert Node-RED Sie auf, eine Seite und eine Gruppe anzulegen; übernehmen Sie die Standardwerte.
5. Deployen Sie und öffnen Sie http://localhost:1880/dashboard.

// Telemetrie in eine Nachricht pro Metrik für Gauges und Charts aufteilen
const sensor = msg.topic.split("/").slice(-2, -1)[0]; // z. B. "sensor1"
const p = msg.payload;
if (typeof p !== "object" || p === null) return null;

return [
  { topic: `${sensor} temperature`, payload: Number(p.temperature) },
  { topic: `${sensor} humidity`, payload: Number(p.humidity) }
];

Stellen Sie diesen Function-Node auf dem Reiter Setup auf zwei Ausgänge ein. Da der Sensorname in msg.topic steht, zeichnet ein einziges Diagramm automatisch eine Linie pro Sensor, wenn Sie weitere Geräte hinzufügen.

Um ein Gerät aus dem Dashboard zu steuern, fügen Sie einen ui-switch hinzu, dessen Ein- und Aus-Payloads ON und OFF sind, und verbinden Sie ihn mit einem mqtt out-Node mit einem Topic wie connectmq/demo/nr-7f3a/line1/fan1/set, QoS 1. Bewährt hat sich, den angezeigten Zustand des Schalters aus dem eigenen Zustands-Topic des Geräts zu speisen statt aus dem Klick, damit das Dashboard nie einen Zustand zeigt, den die Hardware nicht erreicht hat. Layouts, Themes und mehrseitige Dashboards behandelt unser Leitfaden zu Node-RED Dashboard 2.0, und die langfristige Speicherung der Historie ist Thema von Node-RED mit InfluxDB.

Schritt 5: Alarme und Automatisierung

Die Funktion alert on crossing 30 C im importierten Flow ist bewusst als Flankendetektor geschrieben. Sie speichert den vorherigen Zustand pro Topic im Node-Context und gibt nur dann eine Nachricht aus, wenn sich der Zustand ändert. Ohne das würde ein Sensor, der bei 31 Grad verharrt, alle fünf Sekunden einen Alarm auslösen und Ihr Postfach fluten.

Vom Alarm-Topic aus können Sie auf jeden Benachrichtigungskanal verteilen:

• E-Mail mit dem Node node-red-node-email; siehe E-Mail-Alarme aus Node-RED senden.
• Telegram für sofortige Benachrichtigungen aufs Smartphone mit einem Bot; siehe Node-RED-Telegram-Alarme.
• Ein weiteres MQTT-Topic, das von einer Sirene, einer Signalsäule oder einem anderen System konsumiert wird.

Da der Alarm selbst als Retained-Nachricht zurück an MQTT veröffentlicht wird, ist Node-RED nicht der einzige Abnehmer. Jedes Dashboard, jede mobile App und jedes Skript, das +/alert abonniert hat, sieht dasselbe Ereignis. So bleibt Ihre Automatisierungslogik an einem Ort, und Ihre Benachrichtigungskanäle bleiben entkoppelt.

Für größere Installationen bewährt sich ein Unified Namespace (UNS): eine hierarchische Topic-Struktur nach der ISA-95-Anlagenhierarchie wie site/area/line/cell/device/metric, konkret etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur. Damit deckt ein einziges Wildcard-Abonnement in Node-RED eine ganze Linie oder das ganze Werk ab, und MES, SCADA und Dashboards finden dieselben Daten am selben Ort. Wie Sie den UNS aufbauen, beschreibt MQTT, Sparkplug B und der Unified Namespace.

Schritt 6: Wechsel zu einem privaten Broker mit TLS

Der öffentliche Broker ist geteilt und für jeden lesbar, also nur für Tests gedacht. Für echte Flows verwenden Sie einen eigenen Broker mit Verschlüsselung und Zugangsdaten. Sie können selbst einen betreiben, aber ein verwalteter MQTT-Broker streicht Patches, Zertifikate und Verfügbarkeit von Ihrer To-do-Liste. Bei ConnectMQ registrieren Sie sich, wählen einen Plan, erstellen einen Broker und kopieren den generierten Benutzernamen, das Passwort und die Client ID aus dem Portal.

Öffnen Sie den Konfigurations-Node ConnectMQ public und ändern Sie ihn:

Der Broker nutzt ein öffentlich vertrauenswürdiges Let's-Encrypt-Zertifikat, daher validiert Node-RED es mit seinem integrierten CA-Speicher, und Sie laden keine CA-Datei hoch. Zugangsdaten werden in der verschlüsselten Credentials-Datei von Node-RED gespeichert, nicht im Flow-JSON, weshalb exportierte Flows nie Passwörter enthalten. Setzen Sie in settings.js ein credentialSecret, damit diese Datei lesbar bleibt, wenn Sie Node-RED auf einen anderen Rechner umziehen.

Details wie Client-Zertifikate, eigene CAs und häufige Handshake-Fehler finden Sie in Node-RED MQTT über TLS. Sichern Sie außerdem den Editor selbst ab: Ein offen erreichbarer Node-RED-Editor ohne Login ist praktisch Remote Code Execution auf Ihrem Server. Node-RED absichern erklärt adminAuth, HTTPS und die Netzwerkexposition.

Fehlerbehebung im Node-RED MQTT Tutorial

Wenn ein Node dauerhaft „disconnected“ oder „connecting“ anzeigt, gehen Sie diese Checkliste durch:

1. Tippfehler im Hostnamen oder Protokollpräfix. Das Feld Server erwartet broker.connectmq.com, nicht mqtt://broker.connectmq.com.
2. Falscher Port für TLS. Port 1883 ist unverschlüsseltes TCP, 8883 erfordert die Option Use TLS. Eine Vermischung führt zu stillen Timeouts.
3. Doppelte Client ID. Eine andere Node-RED-Instanz, ein Testskript oder MQTT Explorer mit derselben ID wirft die Verbindung alle paar Sekunden hinaus.
4. Falsche Zugangsdaten oder abweichende Client ID. Das Node-Log zeigt „Connection refused: Not authorized“. Kopieren Sie alle drei Werte erneut aus dem Portal.
5. Ausgehende Ports blockiert. Führen Sie nc -vz broker.connectmq.com 8883 auf dem Node-RED-Host aus. Docker-Container brauchen eventuell auch korrekte DNS-Einstellungen.
6. Nachrichten kommen an, sehen aber falsch aus. Prüfen Sie die Output-Einstellung des mqtt-in-Nodes; ein Buffer in der Debug-Seitenleiste bedeutet, dass der Node auf binär steht.
7. Raten- oder Größenlimits. Halten Sie auf dem öffentlichen Broker jeden Client unter 10 Nachrichten pro Sekunde und 64 KB pro Nachricht; Inject-Nodes mit sehr kurzen Intervallen stoßen schnell daran.

Für die Diagnose jedes dieser Punkte anhand der Logs führt unser eigener Leitfaden Node-RED MQTT verbindet sich nicht durch die genauen Fehlermeldungen.

Wie es mit Node-RED weitergeht

Sobald Ihnen die Grundlagen vertraut sind, erweitern diese Leitfäden dieselbe Broker-Verbindung zu echten Projekten:

• Industriedaten: SPS-Register mit Node-RED und Modbus auslesen oder Birth- und Datennachrichten mit Node-RED und Sparkplug B dekodieren.
• Sauberes Topic-Design: unordentliche Geräte-Topics mit Node-RED MQTT Topic Mapping neu strukturieren.
• Wiederverwendbare Logik: wiederkehrende Nodes in Node-RED-Subflows bündeln.
• Produktionskennzahlen: ein OEE-Dashboard in Node-RED bauen.

Betreiben Sie Ihre Node-RED-Flows mit ConnectMQ

Node-RED übernimmt die Logik; der Broker transportiert jede Nachricht zwischen Ihren Flows, Geräten und Dashboards. Der kostenlose Serverless-Plan von ConnectMQ benötigt keine Kreditkarte und bietet Ihnen einen privaten Broker mit TLS auf Port 8883, MQTT 5, bis zu 25 Verbindungen und einen MQTT-Client im Browser, um Topics während der Entwicklung zu inspizieren. Wenn Ihre Flows wachsen, ergänzt der kostenpflichtige Serverless-Plan Shared Subscriptions zur Lastverteilung über mehrere Node-RED-Instanzen, und Dedicated-Pläne bieten Ihnen einen isolierten Cluster. Erstellen Sie Ihren kostenlosen Broker unter app.connectmq.com, fügen Sie die Zugangsdaten in Ihren Broker-Node ein und deployen Sie. Um die Hosting-Optionen genauer abzuwägen, lesen Sie unseren Leitfaden zum Betrieb eines MQTT-Brokers in der Cloud, oder beginnen Sie direkt mit Tests auf dem öffentlichen MQTT-Broker.

Häufig gestellte Fragen

Enthält Node-RED einen MQTT Broker?

Nein. Node-RED bringt nur MQTT-Client-Nodes mit. Sie verbinden sie mit einem externen Broker, etwa einem verwalteten MQTT-Broker oder einer selbst betriebenen Mosquitto-Instanz; Broker-Nodes aus der Community gibt es zwar, sie werden für den Produktivbetrieb aber nicht empfohlen.

Wie viele Verbindungen nutzt Node-RED für MQTT?

Eine pro mqtt-broker-Konfigurations-Node, unabhängig davon, wie viele mqtt-in- und mqtt-out-Nodes ihn teilen. Verwenden Sie einen einzigen Konfigurations-Node wieder, um innerhalb der Verbindungslimits zu bleiben.

Warum gibt mein mqtt-in-Node einen String statt eines Objekts aus?

Die Output-Einstellung steht vermutlich auf a String, oder der Payload ist kein gültiges JSON. Wechseln Sie auf auto-detect oder a parsed JSON object, oder fügen Sie einen JSON-Node hinzu, um ihn explizit zu parsen.

Kann Node-RED MQTT-5-Funktionen nutzen?

Ja. Stellen Sie im Broker-Node das Protokoll auf MQTT V5, um Funktionen wie User Properties, Message Expiry, Response Topics und Session Expiry aus den mqtt-in- und mqtt-out-Nodes zu nutzen.

Ist es sicher, den öffentlichen Broker mit Node-RED zu verwenden?

Für Lernzwecke und Demos ist das in Ordnung, aber jeder kann öffentliche Topics lesen. Verwenden Sie eindeutige Topic-Präfixe, senden Sie keine sensiblen Daten und wechseln Sie zu einem privaten Broker mit TLS, bevor Sie echte Anlagen anbinden.