Utility

MQTT Debug

Der Node ist eine Abwandlung des MQTT-In-Nodes von Node-RED. Er abonniert Topics bei einem MQTT-Broker (Version 3.1, 3.1.1 oder 5.0), gibt jede empfangene Nachricht am ersten Ausgang weiter und hält zusätzlich die letzten Nachrichten in einem Historien-Puffer. Per Knopfdruck am Node oder in einem festen Intervall gibt er diesen Puffer am zweiten Ausgang aus. Für Broker hinter einem HTTP-Proxy wertet er die Proxy-Umgebungsvariablen aus.

• MQTT
• Debugging
• Wiedergabe

Node-Typ

mqtt-debug-in (Konfigurationsnode: mqtt-debug-broker)

Paket

@htag/node-red-contrib-hypertegrity-utility

Eingänge / Ausgänge

0 (1 bei dynamischen Topics) / 2

Abhängigkeit

MQTT-Broker; Bibliotheken mqtt, is-utf8, https-proxy-agent

Wofür Sie den Node verwenden

Beim Aufbau eines Flows ist es mühsam, auf die nächste Sensornachricht zu warten, um eine Änderung zu testen. Der MQTT-Debug-Node merkt sich die zuletzt empfangenen Nachrichten und spielt sie auf Wunsch erneut aus. So testen Sie nachgelagerte Nodes mit echten Daten, ohne den Sensor erneut senden zu lassen.

Typische Einsatzfälle sind:

• Flows mit echten Nachrichten entwickeln: Die letzte TTN-Uplink-Nachricht wird per Knopfdruck erneut an den Device-Info-Node oder den NGSI-LD Builder gegeben.
• Nachrichten in Proxy-Umgebungen empfangen: In Netzen mit vorgeschaltetem HTTP-Proxy verbindet sich der Node über die Umgebungsvariablen all_proxy, mqtt_proxy oder (im Legacy-Modus) http_proxy.
• Eingangsdaten beobachten: Ein Intervall gibt regelmäßig die letzten bis zu zehn Nachrichten mit Empfangszeit aus, etwa für ein Monitoring-Dashboard.

So funktioniert der Node

1

Verbinden

Der Konfigurationsnode MQTT-Broker baut die Verbindung auf, optional mit TLS, Zugangsdaten, Birth-, Close- und Will-Nachricht und bei Bedarf über einen HTTP-Proxy.

→

2

Abonnieren

Der Node abonniert das konfigurierte Topic oder, im dynamischen Modus, Topics aus eingehenden Steuernachrichten.

→

3

Dekodieren und senden

Jede Nachricht wird gemäß Ausgabeformat dekodiert (Auto-Erkennung, String, Buffer, JSON, Base64) und am ersten Ausgang gesendet.

→

4

Puffern und wiedergeben

Eine Kopie landet im Historien-Puffer. Der Knopf am Node oder der Intervall-Timer senden den Puffer als Debug-Nachricht am zweiten Ausgang.

Ergebnis: Ausgang 1 liefert den normalen MQTT-Nachrichtenstrom, Ausgang 2 auf Anforderung die letzten empfangenen Nachrichten.

Der Node ist ereignisbasiert: Er wird durch eingehende MQTT-Nachrichten ausgelöst. Der Historien-Puffer arbeitet nach dem FIFO-Prinzip mit einer konfigurierbaren Größe von 1 bis 10 Nachrichten. Mit aktiver Persistenz wird er im globalen Kontext unter mqtt_history_<Node-ID> abgelegt und übersteht Deploys; beim Löschen des Nodes wird er entfernt.

Konfiguration

Der Node verwendet einen Konfigurationsnode MQTT-Broker (mqtt-debug-broker), der von mehreren MQTT-Debug-Nodes gemeinsam genutzt werden kann. Die Beschriftungen entsprechen weitgehend dem MQTT-In-Node von Node-RED.

MQTT Debug (Node)

Feld	Typ	Standard	Bedeutung
Name	Text	leer	Anzeigename; ohne Namen wird das Topic angezeigt.
Server	Konfigurationsnode	–	Auswahl des MQTT-Broker-Konfigurationsnodes (Pflichtfeld).
Aktion	Auswahl	Einzelnes Topic abonnieren	topic: festes Topic. dynamic: Der Node erhält einen Eingang und abonniert Topics per Steuernachricht (siehe Eingang).
Topic	Text	leer	Abonniertes Topic; Platzhalter + und # sind erlaubt. Pflichtfeld bei einzelnem Topic.
QoS	Auswahl 0/1/2	2	Dienstgüte des Abonnements.
Flags: No Local	Kontrollkästchen	inaktiv	Nur MQTT 5: eigene Veröffentlichungen nicht empfangen.
Flags: Retain as Published	Kontrollkästchen	aktiv	Nur MQTT 5: Retain-Kennzeichen der ursprünglichen Veröffentlichung beibehalten.
Retain Handling	Auswahl 0/1/2	0	Nur MQTT 5: 0 erhaltene Nachrichten beim Abonnieren senden, 1 nur bei neuem Abonnement, 2 nie.
Ausgabe	Auswahl	automatisch erkennen (String oder Buffer)	Dekodierung des Payloads: auto-detect (UTF-8-Text, JSON wird geparst, sonst Buffer), auto (String, veraltet), buffer, utf8 (String), json (geparstes Objekt, Fehler bei ungültigem JSON) oder base64. Bei MQTT 5 steuert ein gesetzter contentType die Auto-Erkennung.
Debug: Wiederholende Debug-Ausgabe aktivieren	Kontrollkästchen	inaktiv	Startet den Intervall-Timer, der den Puffer am zweiten Ausgang ausgibt. Der Knopf am Node funktioniert unabhängig davon.
Intervall (s)	Zahl	10	Abstand der zeitgesteuerten Ausgabe; mindestens 1 s.
Max. Wiederholungen	Zahl	0	Anzahl der zeitgesteuerten Ausgaben, danach stoppt der Timer. 0 bedeutet unbegrenzt.
Historien-Puffer	Zahl 1–10	1	Anzahl der gespeicherten Nachrichten.
Persistenz: Historie über Deploys hinweg speichern	Kontrollkästchen	aktiv	Legt den Puffer im globalen Kontext ab.

MQTT-Broker (Konfigurationsnode), Registerkarte Verbindung

Feld	Typ	Standard	Bedeutung
Name	Text	leer	Anzeigename; sonst <Client-ID>@<Server>:<Port>.
Server	Text	leer	Hostname oder IP des Brokers. Enthält der Wert ://, wird er als vollständige URL verwendet und der Port ignoriert. IPv6-Adressen werden erkannt. Leer bedeutet localhost.
Port	Zahl	1883	Port des Brokers.
Automatisch verbinden	Kontrollkästchen	aktiv	Verbindet beim Deploy, sobald der erste Node den Broker nutzt. Sonst nur über die Aktion connect.
TLS	Kontrollkästchen	inaktiv	Nutzt mqtts:// und blendet die TLS-Konfiguration ein.
TLS Configuration	Konfigurationsnode	–	Standard-TLS-Konfigurationsnode von Node-RED (Zertifikate, Prüfung des Serverzertifikats).
Protokoll	Auswahl	MQTT V3.1.1	3 MQTT 3.1, 4 MQTT 3.1.1, 5 MQTT 5.0. Blendet die MQTT-5-Felder ein.
Client-ID	Text	leer	Leer: automatisch nodered<Zufall>. Pflicht, wenn Clean Session deaktiviert ist.
Keep Alive	Zahl	60	Keep-Alive-Intervall in Sekunden.
Clean Session / Clean Start	Kontrollkästchen	aktiv	Sitzung beim Verbinden verwerfen. Bei MQTT 5 heißt das Feld Clean Start.
Beim Schließen abmelden	Kontrollkästchen	aktiv	Nur bei nicht sauberer Sitzung sichtbar: Abonnements beim Schließen beim Broker abmelden.
Sitzungsablauf (s)	Zahl	0	Nur MQTT 5: Session Expiry Interval.
Benutzereigenschaften	JSON	leer	Nur MQTT 5: User Properties für die Verbindung.

MQTT-Broker, Registerkarte Sicherheit

Feld	Typ	Standard	Bedeutung
Username	Text (Credential)	leer	Benutzername für den Broker; wird verschlüsselt in flows_cred.json gespeichert.
Passwort	Passwort (Credential)	leer	Passwort für den Broker; wird verschlüsselt gespeichert.

MQTT-Broker, Registerkarte Nachrichten

Für Birth Message (beim Verbinden), Close Message (beim geordneten Trennen) und Will Message (vom Broker gesendet, wenn die Verbindung abbricht) gibt es je einen aufklappbaren Abschnitt mit denselben Feldern.

Feld	Typ	Standard	Bedeutung
Topic	Text	leer	Topic der Nachricht; leer bedeutet keine Nachricht. Platzhalter sind nicht erlaubt.
Retain	Auswahl	false	Retain-Kennzeichen.
Payload	Text	leer	Inhalt der Nachricht.
QoS	Auswahl 0/1/2	0	Dienstgüte.
Content Type, User Properties, Response Topic, Correlation Data, Ablauf	Typed Input	Keine	Nur MQTT 5: zusätzliche Eigenschaften der Nachricht; gespeichert in birthMsg, closeMsg beziehungsweise willMsg.
Verzögerung (s)	Zahl	leer	Nur Will Message bei MQTT 5: Will Delay Interval.

Die Prüfung des Serverzertifikats und Client-Zertifikate konfigurieren Sie über die TLS-Konfiguration.

Eingang

Im Modus Einzelnes Topic abonnieren hat der Node keinen Eingang; er wird durch Nachrichten des Brokers ausgelöst. Im Modus Dynamische Topics abonnieren erhält er einen Eingang für Steuernachrichten:

Eigenschaft	Typ	Bedeutung
msg.action	Text	Pflicht: connect, disconnect, subscribe, unsubscribe oder getSubscriptions. Andere Werte lösen den Fehler „Aktion ungültig“ aus.
msg.broker	Objekt	Bei connect: optionale Verbindungsoptionen (zum Beispiel broker, port, username, password, will). Mit force: true wird eine bestehende Verbindung zuvor getrennt.
msg.topic	Text, Objekt oder Array	Bei subscribe/unsubscribe: ein Topic, ein Objekt {"topic": "…", "qos": 2} oder ein Array davon. Objekte dürfen zusätzlich rh, rap, nl (MQTT 5) und datatype enthalten. Bei unsubscribe meldet msg.topic = true alle dynamischen Abonnements ab.
msg.subscriptions	Array	Wird nach subscribe/unsubscribe in die Steuernachricht geschrieben, enthält die aktuellen dynamischen Abonnements. Die Nachricht wird nicht gesendet.

Bei getSubscriptions sendet der Node die Steuernachricht am ersten Ausgang mit msg.topic = "subscriptions" und der Liste der Abonnements in msg.payload.

Ausgang

Ausgang 1: MQTT-Nachricht

Jede empfangene Nachricht wird sofort weitergegeben.

{
  "topic": "v3/beispielstadt@ttn/devices/eui-70b3d57ed0000001/up",
  "payload": {"end_device_ids": {"device_id": "eui-70b3d57ed0000001"}, "received_at": "2026-10-01T08:15:00.000Z"},
  "qos": 0,
  "retain": false
}

Feld	Bedeutung
topic	Topic der empfangenen Nachricht.
payload	Dekodierter Inhalt gemäß Ausgabeformat.
qos, retain	Dienstgüte und Retain-Kennzeichen des Pakets.
_topic	Nur bei Brokern localhost oder 127.0.0.1: Kopie des Topics.
responseTopic, correlationData, contentType, messageExpiryInterval, payloadFormatIndicator, reasonString, userProperties	Nur MQTT 5, nur wenn im Paket vorhanden.

Ausgang 2: Debug-Ausgabe

Wird nur bei Wiedergabe gesendet, per Knopf am Node oder durch den Intervall-Timer. Die neueste Nachricht steht an erster Stelle.

{
  "payload": {
    "debug": [
      {
        "topic": "v3/beispielstadt@ttn/devices/eui-70b3d57ed0000001/up",
        "payload": {"end_device_ids": {"device_id": "eui-70b3d57ed0000001"}},
        "qos": 0,
        "retain": false,
        "_observedAt": "2026-10-01T08:15:00.000Z",
        "replayedAt": "2026-10-01T09:00:00.000Z"
      }
    ],
    "count": 1,
    "manual": true
  }
}

Feld	Bedeutung
payload.debug	Array der gepufferten Nachrichten mit topic, payload (Kopie), qos, retain und _observedAt (Empfangszeit).
payload.debug[].replayedAt	Nur bei manueller Wiedergabe: Zeitpunkt der Wiedergabe je Eintrag.
payload.count	Anzahl der Einträge.
payload.manual	true bei Wiedergabe per Knopf.
payload.replayedAt	Nur bei zeitgesteuerter Wiedergabe: Zeitpunkt der Ausgabe.

Der Knopf am Node ruft den Admin-Endpunkt POST /mqtt-debug/<Node-ID>/replay auf. Ohne gepufferte Nachrichten meldet er „No history available“.

Beispiel-Flow

Das Paket bringt einen Beispiel-Flow mit. Sie importieren ihn in Node-RED über Menü → Importieren → Beispiele → @htag/node-red-contrib-hypertegrity-utility → mqtt-debug. Alternativ laden Sie die Datei mqtt-debug.json herunter und importieren sie über Menü → Importieren. Server und Topic sind im Beispiel leer und werden nach dem Import eingetragen.

Schritt 1

MQTT Debug

Der Node abonniert ein Topic beim konfigurierten Broker und puffert die letzte Nachricht mit Persistenz.

Schritt 2

Debug: Mqtt Message

Ein Debug-Node am ersten Ausgang zeigt jede empfangene Nachricht.

Schritt 3

Debug: Debug Message

Ein Debug-Node am zweiten Ausgang zeigt den Puffer, sobald Sie den Knopf am Node drücken.

Beispiel-Flow als JSON anzeigen

[
  {"id": "tab1", "type": "tab", "label": "mqtt debug", "disabled": false, "info": ""},
  {"id": "mq1", "type": "mqtt-debug-in", "z": "tab1", "name": "", "debugEnable": false, "debugInterval": 10, "debugBuffer": 1, "debugLimit": 0, "debugPersist": true,
    "topic": "", "qos": "2", "datatype": "auto-detect", "nl": false, "rap": true, "rh": 0, "inputs": 0,
    "x": 160, "y": 160, "wires": [["dbg1"], ["dbg2"]]},
  {"id": "dbg1", "type": "debug", "z": "tab1", "name": "Mqtt Message", "active": true, "tosidebar": true, "complete": "payload", "targetType": "msg", "x": 340, "y": 140, "wires": []},
  {"id": "dbg2", "type": "debug", "z": "tab1", "name": "Debug Message", "active": true, "tosidebar": true, "complete": "payload", "targetType": "msg", "x": 340, "y": 180, "wires": []}
]

Status und Fehler

Anzeige	Bedeutung
Roter Ring „Nicht verbunden“	Keine Verbindung zum Broker (auch nach Deploy, bis die Verbindung steht).
Gelber Ring „Verbinde...“	Verbindungsaufbau oder Wiederverbindung läuft.
Grüner Punkt „Verbunden“	Verbindung zum Broker besteht.
Fehler „Ungültiges JSON“ / „Ungültiger JSON-String“	Ausgabeformat JSON, aber der Payload ist kein gültiges JSON beziehungsweise kein UTF-8-Text. Die Nachricht wird verworfen.
Fehler „Fehler bei Debug-Erfassung: …“	Die Nachricht konnte nicht in den Puffer kopiert werden.
Fehler „Standard-Sendefehler: …“	Das Senden am ersten Ausgang ist fehlgeschlagen.
Fehler „Aktion ungültig“ / „Aktion ungültig: Ungültiges Abonnement“ / „Ungültiges Topic“	Fehlerhafte Steuernachricht im dynamischen Modus.
Fehler „Broker nicht definiert“ / „Missing configuration“	Kein Topic und kein dynamischer Modus beziehungsweise kein Konfigurationsnode ausgewählt.
Warnung „Nicht-saubere Sitzung angefordert, aber keine Client-ID konfiguriert“	Clean Session wurde automatisch aktiviert.
Warnung „Ungültiges Topic“	Das konfigurierte Topic ist kein gültiges Abonnement-Topic; der Node bleibt inaktiv.
Protokoll „Proxy wird verwendet: …“	Für die Broker-URL wurde ein Proxy aus den Umgebungsvariablen ermittelt.

Hinweise

• Proxy-Unterstützung: Der Node ermittelt anhand der Broker-URL einen Proxy aus den Umgebungsvariablen und tunnelt die Verbindung per HTTP CONNECT. Im Standardmodus („strict“) werden für eine URL mqtt:// beziehungsweise mqtts:// die Variablen mqtt_proxy beziehungsweise mqtts_proxy, npm_config_mqtt_proxy, npm_config_proxy und all_proxy geprüft (Groß- und Kleinschreibung); no_proxy schließt Hosts aus, * deaktiviert den Proxy. Mit NR_PROXY_MODE=legacy werden stattdessen http_proxy/HTTP_PROXY und no_proxy/NO_PROXY nach einfacher Teilstring-Prüfung ausgewertet. Fehlt bei der Proxy-Adresse das Schema, wird das Schema der Broker-URL vorangestellt.
• Persistenter Puffer: Mit aktiver Persistenz wird der Puffer bei jeder Nachricht in den globalen Kontext geschrieben. Für ein Überleben von Neustarts muss ein persistenter Kontextspeicher in settings.js konfiguriert sein. Bei zehn großen Nachrichten kann der Kontext entsprechend wachsen.
• Datenschutz: Der Puffer speichert vollständige Nachrichteninhalte, bei Persistenz auch auf der Festplatte des Node-RED-Servers. Enthalten die MQTT-Nachrichten personenbezogene Daten (etwa Standorte oder Kennungen einzelner Personen), löschen Sie den Puffer nach der Entwicklung, deaktivieren Sie die Persistenz oder verwenden Sie Testdaten. Zugangsdaten zum Broker liegen verschlüsselt in flows_cred.json.
• Lizenz: Der Node basiert auf dem MQTT-Node der Node-RED-Kernnodes (Apache-2.0, JS Foundation) mit Änderungen der HYPERTEGRITY AG; der Proxy-Helfer stammt aus proxy-from-env (MIT).

Weiterführende Themen

Referenzen