Node-RED Dashboard 2.0 mit MQTT: Anzeigen, Diagramme und Bedienelemente

Node-RED Dashboard 2.0 verwandelt MQTT-Topics in eine Browser-Oberfläche mit Anzeigen, Diagrammen und Bedienelementen, ohne separates Frontend-Projekt. In diesem Tutorial bauen Sie eine Seite, die Live-Temperatur und -Luftfeuchte eines simulierten Geräts zeigt, beide in einem Liniendiagramm darstellt und einen Lüfter über einen Schalter steuert, der Befehle publiziert und den bestätigten Zustand des Geräts widerspiegelt. Alles läuft gegen einen kostenlosen Broker, Sie können also sofort mitmachen.

Was Node-RED Dashboard 2.0 ist

Dashboard 2.0 ist der Nachfolger des ursprünglichen Pakets node-red-dashboard, das inzwischen veraltet ist. Es wird als @flowfuse/node-red-dashboard veröffentlicht, basiert auf Vue und Vuetify und behält dieselbe Idee bei: Widget-Nodes in Ihrem Flow werden zu Elementen einer Webseite, die Node-RED unter /dashboard ausliefert.

Die Struktur ist eine Hierarchie von Config-Nodes:

Diese legen Sie selten von Hand an. Wenn Sie das erste Widget platzieren und "Add new ui-group" wählen, bietet der Editor an, Seite und Basis für Sie zu erstellen. Die offizielle Dokumentation zu Dashboard 2.0 listet jedes Widget und seine Optionen auf.

Dashboard 2.0 installieren

Öffnen Sie im Node-RED-Editor Menu → Manage palette → Install, suchen Sie nach @flowfuse/node-red-dashboard und installieren Sie es. Oder über die Kommandozeile in Ihrem Node-RED-Benutzerverzeichnis:

cd ~/.node-red
npm install @flowfuse/node-red-dashboard
# Node-RED anschließend neu starten, z. B.:
node-red-restart   # bei Installation per Raspberry-Pi-Installationsskript

Verwenden Sie ein aktuelles Node-RED-4.x-Release. Nach einem Neustart sehen Sie einen neuen Abschnitt "dashboard 2" in der Palette. Falls Sie Node-RED selbst noch einrichten, führt Sie das Node-RED-MQTT-Tutorial durch die Installation und Ihre erste Broker-Verbindung.

Ein Gerät simulieren, das Telemetrie publiziert

Damit es etwas anzuzeigen gibt, starten Sie ein kleines Python-Skript, das sich wie ein Raumcontroller verhält. Es publiziert alle zwei Sekunden JSON-Telemetrie, wartet auf Lüfterbefehle und publiziert den Lüfterzustand als retained message, sobald es einen Befehl umgesetzt hat. Es verbindet sich mit broker.connectmq.com, dem kostenlosen Öffentlichen MQTT-Broker, der anonyme Clients mit jeder eindeutigen, nicht leeren Client-ID akzeptiert.

Ersetzen Sie a7f3k2 durch eine eigene Zufallszeichenfolge. Der öffentliche MQTT-Broker ist für jeden lesbar und nur für Tests gedacht; halten Sie das Präfix also eindeutig und die Daten harmlos.

# pip install "paho-mqtt>=2.0"
import json
import random
import time
import uuid

import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/a7f3k2/room1"
fan_on = False


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)
    client.subscribe(f"{PREFIX}/fan/set", qos=1)


def on_message(client, userdata, msg):
    global fan_on
    command = msg.payload.decode().strip().upper()
    if command in ("ON", "OFF"):
        fan_on = command == "ON"
        # Bestätigten Zustand melden, retained, damit neue Dashboards ihn sofort sehen
        client.publish(f"{PREFIX}/fan/state", command, qos=1, retain=True)
        print("Fan is now", command)


client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=f"room-sim-{uuid.uuid4().hex[:8]}")
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_start()

temperature = 24.0
try:
    while True:
        drift = random.uniform(-0.3, 0.35) - (0.25 if fan_on else 0.0)
        temperature = max(15.0, min(35.0, temperature + drift))
        payload = {
            "temperature": round(temperature, 2),
            "humidity": round(random.uniform(40, 55), 1),
        }
        client.publish(f"{PREFIX}/telemetry", json.dumps(payload), qos=0)
        time.sleep(2)
except KeyboardInterrupt:
    pass
finally:
    client.loop_stop()
    client.disconnect()

Lassen Sie es laufen. Die Ausgabe können Sie mit mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-a7f3k2 -v -t 'connectmq/demo/a7f3k2/#' beobachten.

Den Flow für Node-RED Dashboard 2.0 bauen

Schritt 1: Telemetrie abonnieren

Fügen Sie einen mqtt in-Node hinzu. Legen Sie einen neuen mqtt-broker-Config-Node mit dem Server broker.connectmq.com, Port 1883 und einer eindeutigen Client-ID wie nr-dash-a7f3k2 an. Setzen Sie das Topic auf connectmq/demo/a7f3k2/room1/telemetry, QoS 1, und die Ausgabe auf a parsed JSON object.

Schritt 2: Die Payload für jedes Widget aufteilen

Gauges erwarten eine einzelne Zahl in msg.payload, während ein Diagramm mit mehreren Datenreihen eine Nachricht pro Reihe mit dem Reihennamen in msg.topic erwartet. Ein Function-Node mit drei Ausgängen erledigt beides:

// Function-Node "split telemetry" - Outputs auf 3 setzen
const t = Number(msg.payload.temperature);
const h = Number(msg.payload.humidity);

if (Number.isNaN(t) || Number.isNaN(h)) {
    node.warn("Unexpected payload: " + JSON.stringify(msg.payload));
    return null;
}

return [
    { payload: t },                       // Ausgang 1 -> Temperatur-Gauge
    { payload: h },                       // Ausgang 2 -> Luftfeuchte-Gauge
    [                                      // Ausgang 3 -> Diagramm, zwei Reihen
        { topic: "Temperature (C)", payload: t },
        { topic: "Humidity (%)", payload: h }
    ]
];

Ein Array innerhalb eines Ausgangsplatzes sendet mehrere Nachrichten nacheinander über diesen Port.

Schritt 3: Gauges hinzufügen

Platzieren Sie zwei ui-gauge-Nodes und verbinden Sie sie mit den Ausgängen 1 und 2. Klicken Sie im ersten auf den Stift neben Group, um eine neue Gruppe "Room 1" anzulegen, wodurch auch Seite und Basis entstehen. Nützliche Einstellungen:

• Typ: "Gauge 3/4" für die Temperatur, "Tile"- oder "Battery"-Stil für die Luftfeuchte, wenn Sie eine kompakte Ansicht bevorzugen.
• Bereich: 0 bis 40 für die Temperatur, 0 bis 100 für die Luftfeuchte.
• Segmente: grün ab 0, gelb ab 26, rot ab 30, sodass schon die Farbe die Lage verrät.
• Einheiten: °C und %.

Schritt 4: Ein Liniendiagramm hinzufügen

Verbinden Sie Ausgang 3 mit einem ui-chart-Node in derselben Gruppe. Wählen Sie den Typ "Line", belassen Sie Series auf msg.topic und X als Zeitstempel, sodass jeder Punkt beim Eintreffen gestempelt wird. Behalten Sie unter den Punktlimits die letzten 300 Punkte oder die letzte Stunde. Ohne Limit wächst ein lange laufendes Dashboard im Arbeitsspeicher immer weiter.

Diagrammdaten liegen in Dashboard 2.0 im Arbeitsspeicher von Node-RED, ein Neustart leert sie also. Der weiterführende Leitfaden zum Node-RED Diagramm-Verlauf zeigt, wie Sie sie persistieren und zurückspielen.

Schritt 5: Ein Bedienelement hinzufügen, das Befehle publiziert

Fügen Sie der Gruppe einen ui-switch mit der Beschriftung "Fan" hinzu. Setzen Sie seine On-Payload auf den String ON und die Off-Payload auf OFF. Verbinden Sie ihn mit einem mqtt out-Node mit dem Topic connectmq/demo/a7f3k2/room1/fan/set, QoS 1, Retain aus. Befehle sollten nicht retained sein: Ein retained ON würde dem Gerät bei jedem Reconnect erneut zugestellt, selbst Stunden später.

Schritt 6: Den echten Gerätezustand widerspiegeln

Ein Schalter, der nur zeigt, was der Nutzer angeklickt hat, kann lügen. Ist das Gerät offline, zeigt der Schalter "an", während der Lüfter aus ist. Beheben Sie das, indem Sie den bestätigten Zustand des Geräts in den Schalter zurückführen:

1. Fügen Sie einen zweiten mqtt in-Node auf connectmq/demo/a7f3k2/room1/fan/state hinzu, Ausgabe als UTF-8-String.
2. Verbinden Sie ihn mit dem Eingang desselben ui-switch.
3. Stellen Sie in den Schaltereinstellungen sicher, dass Eingangsnachrichten nicht an den Ausgang durchgereicht werden. Sonst würde jede Zustandsaktualisierung als neuer Befehl publiziert, und Sie erzeugen eine Schleife.

Weil der Simulator den Zustand retained publiziert, zeigt ein frisch geöffnetes Dashboard oder ein neu gestartetes Node-RED sofort die richtige Stellung.

Schritt 7: Deployen und die Seite öffnen

Klicken Sie auf Deploy und öffnen Sie http://localhost:1880/dashboard. Die Gauges bewegen sich alle zwei Sekunden, das Diagramm zeichnet zwei Linien, und wenn Sie den Lüfter einschalten, zeigt der Temperaturtrend einige Messwerte später nach unten.

Widget-Referenz für MQTT-Dashboards

Für größere Projekte lohnt sich ein Blick auf das Beispiel für ein OEE-Dashboard, das Kennzahlen berechnet, bevor sie die Widgets erreichen, und auf das Worldmap-Tutorial für Standortdaten. In der Industrie ordnen Sie Seiten und Gruppen sinnvollerweise nach der ISA-95-Hierarchie (Werk, Bereich, Linie, Zelle), die auch die Topic-Struktur Ihres Unified Namespace (UNS) bildet.

Häufige Probleme und Lösungen

1. Widgets aktualisieren sich nie. Prüfen Sie den Status des mqtt in-Nodes. Steht dort "connecting", wird die Client-ID möglicherweise von einem anderen Client verwendet; machen Sie sie eindeutig.
2. Die Gauge zeigt NaN oder bleibt bei null. Die Payload erreichte die Gauge als Objekt. Stellen Sie sicher, dass nur eine Zahl an die Gauge geht.
3. Das Diagramm zeichnet eine einzige zusammengeführte Linie. Jede Nachricht trägt dasselbe msg.topic. Setzen Sie pro Wert einen eigenen Reihennamen.
4. Der Schalter flackert oder Befehle wiederholen sich. Pass-through ist aktiv, während Zustandsnachrichten zurückgeführt werden. Deaktivieren Sie es.
5. Die Seite ist von überall erreichbar. Dashboard 2.0 hat standardmäßig keine Anmeldung. Stellen Sie Node-RED hinter eine Authentifizierung oder einen Reverse Proxy, bevor Sie es exponieren.
6. Das Dashboard funktioniert im LAN, aber nicht aus der Ferne. Port 1880 ist meist gesperrt; veröffentlichen Sie die Seite über einen Proxy mit HTTPS, statt den Port zu öffnen.

Von der Demo zur Produktion

Der öffentliche MQTT-Broker ist für dieses Tutorial ideal, doch seine Daten sind für jeden sichtbar, und er hat Ratenlimits pro Client. Für eine echte Installation richten Sie denselben mqtt-broker-Config-Node auf einen privaten Broker mit Zugangsdaten und TLS auf Port 8883 aus. Ein Cloud-MQTT-Broker ermöglicht es außerdem, dass Geräte in mehreren Gebäuden an einen Ort publizieren, den ein einziges Node-RED-Dashboard lesen kann. Wenn Sie zum ersten Mal Zertifikate konfigurieren, erklärt der Leitfaden zu Node-RED, MQTT und TLS das Schritt für Schritt.

Mit ConnectMQ erhalten Sie den generierten Benutzernamen, das Passwort und die Client-ID aus dem Portal, und die einzige Änderung im Flow betrifft den Config-Node. Jedes Widget, jede Function und jedes Topic dieses Tutorials bleibt gleich, sobald Sie das Demo-Präfix entfernen. Mit einem verwalteten MQTT-Broker entfällt zudem die Notwendigkeit, Mosquitto auf derselben Maschine wie Ihr Dashboard zu betreiben und zu patchen.

Betreiben Sie Ihr Node-RED-Dashboard mit ConnectMQ

Erstellen Sie ein kostenloses Konto unter app.connectmq.com, wählen Sie den Plan Serverless (Free), ohne Kreditkarte, und erstellen Sie einen Broker. Fügen Sie die Zugangsdaten in Ihren Node-RED-Config-Node ein, wechseln Sie auf Port 8883 mit TLS, und Ihre Dashboard-2.0-Seite liest private, verschlüsselte Daten. Der MQTT-Client im Browser im ConnectMQ-Portal ist praktisch, um beim Gestalten der Seite Testbefehle an das Lüfter-Topic zu senden.

Häufig gestellte Fragen

Was ist der Unterschied zwischen Node-RED Dashboard und Dashboard 2.0?

Das ursprüngliche node-red-dashboard ist veraltet und basiert auf AngularJS. Dashboard 2.0, @flowfuse/node-red-dashboard, ist der gepflegte Nachfolger auf Basis von Vue, mit einer vertraut wirkenden Struktur aus Seiten, Gruppen und Widgets.

Unter welcher URL ist Node-RED Dashboard 2.0 erreichbar?

Standardmäßig wird das Dashboard unter http://<node-red-host>:1880/dashboard ausgeliefert. Den Pfad können Sie im Config-Node ui-base ändern.

Kann Dashboard 2.0 MQTT-Befehle senden?

Ja. Verbinden Sie einen ui-switch, ui-button oder ui-slider mit einem mqtt out-Node. Führen Sie den bestätigten Zustand des Geräts in das Widget zurück, damit die Oberfläche die Realität zeigt und nicht nur den letzten Klick.

Warum ist mein Diagramm nach einem Neustart von Node-RED leer?

Diagrammdaten werden im Arbeitsspeicher gehalten. Persistieren Sie Messwerte im Context-Speicher oder in einer Datenbank und spielen Sie sie beim Start zurück, um den Verlauf über Neustarts hinweg zu behalten.