Der Node-RED JSON-Node wandelt zwischen JSON-Strings und JavaScript-Objekten um, und er entscheidet darüber, ob msg.payload.temp funktioniert oder undefined liefert. Dieser Leitfaden zeigt, wie JSON über MQTT ankommt, wann Sie das Parsen dem mqtt in-Node überlassen, wann Sie stattdessen den JSON-Node verwenden, wie Sie Payloads mit einem Schema validieren und wie Sie die häufigsten Parse-Fehler beheben.
Warum MQTT-Payloads geparst werden müssen
MQTT selbst kennt kein JSON. Ein Broker transportiert jeden Payload als rohe Bytes, egal ob diese Bytes eine Zahl, eine CSV-Zeile, eine Protobuf-Nachricht oder ein JSON-Dokument sind. Publiziert ein Temperatursensor {"temp": 22.4, "hum": 41}, erhält der Abonnent 26 Bytes und muss entscheiden, was sie bedeuten.
Node-RED bietet zwei Stellen für diese Entscheidung: die Option Output am mqtt in-Node und den separaten JSON-Node. Beide nutzen darunter denselben Parser. Der Unterschied liegt darin, wo die Umwandlung passiert und wie viel Kontrolle Sie behalten. Zur Auffrischung, wie Broker diese Bytes weiterleiten, lesen Sie, was ein MQTT-Broker macht.
Option 1: JSON vom mqtt in-Node parsen lassen
Öffnen Sie einen beliebigen mqtt in-Node und sehen Sie sich das Dropdown Output an. Aktuelle Node-RED-Versionen bieten:
| Output-Einstellung | Was aus msg.payload wird |
Geeignet für |
|---|---|---|
| auto-detect (parsed JSON object, string or buffer) | Objekt bei gültigem JSON, sonst String, bei Binärdaten Buffer | Gemischte oder unbekannte Topics |
| a parsed JSON object | Immer ein Objekt; ungültiges JSON löst einen Fehler aus | Eigene Topics, die immer JSON tragen |
| a UTF-8 string | String | Klartext, CSV, Payloads, die Sie selbst parsen |
| a Buffer | Node.js-Buffer | Binärformate wie Protobuf |
| a Base64 encoded string | Base64-Text | Binärdaten durch reine Textsysteme schleusen |
Für Topics, auf denen jeder Publisher JSON sendet, ist "a parsed JSON object" die sauberste Wahl. Sie erhalten direkt ein Objekt und einen sichtbaren Fehler, wenn ein Gerät sich falsch verhält. Auto-detect ist bequem, wenn Sie mit einer breiten Wildcard abonnieren und manche Topics einfache Werte wie ON oder 21.5 tragen, bedeutet aber, dass nachgelagerte Nodes mit beiden Typen umgehen müssen.
Auto-detect versucht, den Payload zu parsen: Ist er gültiges JSON, erhalten Sie ein Objekt, sonst einen String, oder einen Buffer, wenn die Bytes kein gültiger Text sind. Das ist bequem, aber weniger streng als die Option für geparstes JSON.
Option 2: Den Node-RED JSON-Node verwenden
Der JSON-Node kann an beliebiger Stelle im Flow stehen und wandelt die gewählte Property um. Die Einstellung Action hat drei Modi:
- Convert between JSON String and Object: Ein String wird zum Objekt, ein Objekt zum String. Das ist der Standard und in beide Richtungen praktisch.
- Always convert to JavaScript Object: Strings werden geparst, Objekte unverändert durchgereicht.
- Always convert to JSON String: Objekte werden serialisiert, Strings unverändert durchgereicht. Aktivieren Sie Format JSON string für eine eingerückte, gut lesbare Ausgabe.
Sie können die Property auch von payload auf etwas anderes ändern, etwa payload.data, wenn ein JSON-Dokument als String in einem anderen Dokument verschachtelt ist. Dieses Muster taucht bei Gateways auf, die Gerätenachrichten in einen Umschlag (Envelope) verpacken.
Verwenden Sie den JSON-Node statt der mqtt in-Einstellung, wenn:
- Sie einmal mit einer Wildcard abonnieren, aber nur einige Zweige JSON tragen. Routen Sie zuerst mit einem Node-RED Switch-Node und parsen Sie dann nur den JSON-Zweig.
- Sie eine Schema-Validierung brauchen (siehe unten).
- Das JSON in einer anderen Property verschachtelt ist.
- Sie JSON nicht aus MQTT erhalten, sondern zum Beispiel aus einer HTTP-Anfrage oder einer Datei.
Ausprobieren auf dem öffentlichen Broker
Der öffentliche MQTT-Broker unter broker.connectmq.com ist ein schneller Weg, jede Einstellung ohne Installation auszuprobieren. Publizieren Sie aus einem Terminal einen gültigen und einen ungültigen Payload und ersetzen Sie b52e durch eine eigene Zufallszeichenfolge:
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-json-b52e \
-t "connectmq/demo/b52e/room1/env" -m '{"temp": 22.4, "hum": 41}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-json-b52e \
-t "connectmq/demo/b52e/room1/env" -m '{temp: 22.4}'
Importieren Sie dann diesen Flow. Er abonniert als UTF-8-String und parst mit einem JSON-Node, sodass Sie sowohl den Erfolgs- als auch den Fehlerpfad sehen.
[
{"id":"tab1","type":"tab","label":"JSON demo"},
{"id":"brk","type":"mqtt-broker","name":"ConnectMQ public","broker":"broker.connectmq.com","port":"1883","clientid":"nr-json-b52e","autoConnect":true,"usetls":false,"protocolVersion":"4","keepalive":"60","cleansession":true},
{"id":"in","type":"mqtt in","z":"tab1","name":"env","topic":"connectmq/demo/b52e/+/env","qos":"0","datatype":"utf8","broker":"brk","x":110,"y":100,"wires":[["json"]]},
{"id":"json","type":"json","z":"tab1","name":"parse","property":"payload","action":"obj","pretty":false,"x":270,"y":100,"wires":[["ok"]]},
{"id":"ok","type":"debug","z":"tab1","name":"parsed","active":true,"complete":"payload","x":430,"y":100,"wires":[]},
{"id":"catch","type":"catch","z":"tab1","name":"","scope":["json"],"uncaught":false,"x":110,"y":180,"wires":[["bad"]]},
{"id":"bad","type":"debug","z":"tab1","name":"parse errors","active":true,"complete":"true","x":290,"y":180,"wires":[]}
]
Die erste Nachricht erscheint in der Debug-Ausgabe "parsed" als aufklappbares Objekt. Die zweite löst den Catch-Node aus, und die vollständige Nachricht einschließlich msg.error.message erscheint unter "parse errors". Verbinden Sie in der Produktion diesen Catch-Ausgang mit einem Zähler oder einem Alarm-Topic statt mit einem Debug-Node, damit Sie merken, wenn ein Firmware-Update anfängt, fehlerhaftes JSON zu senden.
Payloads mit JSON Schema validieren
Gültiges JSON ist nicht dasselbe wie korrektes JSON. Ein Gerät sendet vielleicht "temp": "22.4" als String oder lässt nach einer Firmware-Änderung ein Feld weg. Der JSON-Node kann Payloads gegen ein JSON Schema prüfen: Setzen Sie vor dem Node msg.schema auf ein Schema-Objekt, und ungültige Nachrichten lösen einen Fehler aus, dessen Validierungsdetails in msg.schemaError stehen.
Setzen Sie das Schema mit einem Change-Node oder einer kleinen Funktion:
msg.schema = {
type: "object",
required: ["temp", "hum"],
properties: {
temp: { type: "number", minimum: -40, maximum: 125 },
hum: { type: "number", minimum: 0, maximum: 100 }
},
additionalProperties: true
};
return msg;
Platzieren Sie dies vor dem JSON-Node und behalten Sie den Catch-Node aus der Demo. Nachrichten, die die Validierung nicht bestehen, landen mit einer lesbaren Begründung im Fehlerpfad, was das Debugging deutlich erleichtert, statt NaN-Werten durch ein Dashboard hinterherzujagen. Das Schema wird auf der Objektseite geprüft; es funktioniert also sowohl beim Parsen eines Strings als auch dann, wenn der Payload bereits ein Objekt ist.
JSON zurück an MQTT publizieren
Der mqtt out-Node serialisiert Objekte automatisch: Ist msg.payload ein Objekt, wird es als JSON-String gesendet. In den meisten Flows brauchen Sie vor dem Publizieren keinen JSON-Node. Fügen Sie einen mit Always convert to JSON String nur hinzu, wenn eine bestimmte Property serialisiert werden soll oder Sie eine formatierte Ausgabe für Menschen möchten.
Ein subtiler Punkt: Publizieren Sie eine Zahl wie 21.5 direkt, sendet der Node den Text 21.5. Abonnenten mit auto-detect sehen das als gültiges JSON und erhalten eine Zahl, Abonnenten mit UTF-8 dagegen einen String. Legen Sie pro Topic eine Konvention fest und dokumentieren Sie sie.
JSON-Fehler in Node-RED beheben
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
Unexpected token o in JSON at position 1 |
Payload ist bereits ein Objekt und wird erneut geparst | Zusätzlichen JSON-Node entfernen oder mqtt in-Output auf String stellen |
msg.payload.temp ist undefined |
Payload ist noch ein String | mqtt in auf geparstes JSON stellen oder einen JSON-Node hinzufügen |
Unexpected token } in JSON |
Abschließendes Komma oder Schlüssel ohne Anführungszeichen aus der Firmware | Publisher korrigieren; JSON verlangt Schlüssel in Anführungszeichen und keine abschließenden Kommas |
| Debug zeigt einen Buffer | Output auf Buffer gestellt oder Binär-Payload mit auto-detect | UTF-8-String oder geparstes JSON als Output verwenden |
| Zahlen kommen als Strings an | Publisher setzt Werte in Anführungszeichen | Mit Schema validieren und Firmware korrigieren oder mit einem Change-Node umwandeln |
| Seltsame Zeichen am Anfang | UTF-8-Byte-Order-Mark mancher Tools | Mit einem Function-Node entfernen oder Publisher korrigieren |
Die meisten dieser Fehler entstehen durch doppeltes oder fehlendes Parsen. Fügen Sie direkt nach mqtt in einen Debug-Node mit "complete msg object" ein; die Seitenleiste zeigt, ob payload ein String, ein Objekt oder ein Buffer ist.
Checkliste mit Best Practices
- Wählen Sie pro Flow genau eine Parse-Stelle, entweder den mqtt in-Node oder einen JSON-Node, niemals beide.
- Verwenden Sie "a parsed JSON object" für eigene Topics und auto-detect nur für gemischte Wildcards.
- Validieren Sie kritische Payloads mit einem Schema und leiten Sie Fehler über einen Catch-Node.
- Halten Sie Payloads möglichst klein und flach; verschachtelte Umschläge erschweren jedem Konsumenten die Arbeit.
- Legen Sie die Geräteidentität ins Topic, nicht nur in den Payload. Unser Leitfaden zum Node-RED Function-Node zeigt, wie Sie das Topic in Felder zerlegen. In der Industrie folgt das Topic dabei idealerweise der ISA-95-Hierarchie eines Unified Namespace (UNS), etwa
acme/werk-stuttgart/montage/linie-1/temperatur. - Dokumentieren Sie das Payload-Format jedes Topics zusammen mit Ihrem Plan für die Topic-Benennung.
Für einen vollständigen Einstieg behandelt das Node-RED-MQTT-Tutorial Broker-Konfiguration, Dashboards und Alarme in einem Flow. Der offizielle Leitfaden zum Arbeiten mit Nachrichten auf nodered.org erklärt Nachrichtenstruktur und JSON-Node noch ausführlicher.
Ihre JSON-Flows zu ConnectMQ umziehen
Der öffentliche Broker ist geteilt und für jeden lesbar, echte Gerätedaten gehören daher auf einen privaten Broker. ConnectMQ ist ein vollständig verwalteter MQTT-Broker mit TLS auf Port 8883 und einem Topic-Explorer im Portal, in dem Sie das exakte JSON jedes Geräts prüfen können, bevor es Node-RED erreicht. Registrieren Sie sich unter app.connectmq.com für den kostenlosen Serverless-Plan, ohne Kreditkarte, fügen Sie dann die generierten Zugangsdaten in Ihren Broker-Node ein und aktivieren Sie TLS. Der kostenlose Plan unterstützt Nachrichten bis 256 KB, was für typische JSON-Telemetrie mehr als genug ist.
Häufig gestellte Fragen
Brauche ich nach dem mqtt in-Node einen JSON-Node?
Nein, wenn der Output des mqtt in-Nodes auf "a parsed JSON object" oder auto-detect steht und der Payload gültiges JSON ist. Ein zusätzlicher JSON-Node kann dann Fehler durch doppeltes Parsen verursachen.
Wie wandle ich in Node-RED ein Objekt in einen JSON-String um?
Verwenden Sie den JSON-Node mit der Aktion "Always convert to JSON String", optional mit Format JSON string für eine lesbare Ausgabe. Auch der mqtt out-Node serialisiert Objekte automatisch.
Kann der JSON-Node Datentypen validieren?
Ja. Setzen Sie vor dem Node msg.schema auf ein JSON Schema; Nachrichten, die nicht passen, lösen einen Fehler aus, den Sie mit einem Catch-Node behandeln können, mit Details in msg.schemaError.
Warum liefert auto-detect manchmal eine Zahl statt eines Objekts?
Ein Payload wie 42 oder true ist gültiges JSON, daher parst auto-detect ihn in eine Zahl oder einen Boolean. Erwarten Sie immer ein Objekt, prüfen Sie den Typ in einem Switch-Node oder verwenden Sie ein Schema.
