Node-RED Worldmap: GPS-Geräte über MQTT verfolgen

Der Node-RED-Worldmap-Node verwandelt einen Strom von MQTT-GPS-Nachrichten in wenigen Minuten in bewegte Marker auf einer interaktiven Karte. In diesem Tutorial simulieren Sie drei Fahrzeuge, wandeln ihre JSON-Positionen in Worldmap-Marker mit Kurs und Farben um, markieren Geräte, die nicht mehr melden, und zeichnen Spuren. Am Ende haben Sie einen funktionierenden Live-Tracker, den Sie auf echte GPS-Hardware umstellen können.

So funktioniert der Node-RED-Worldmap-Node

Das Paket node-red-contrib-web-worldmap fügt einen worldmap-Node hinzu, der unter http://<node-red-host>:1880/worldmap eine Leaflet-basierte Karte bereitstellt. Jede Nachricht, die Sie an den Node senden, beschreibt ein Objekt:

• msg.payload.name ist die eindeutige ID. Eine neue Position mit demselben Namen verschiebt den vorhandenen Marker.
• msg.payload.lat und msg.payload.lon sind die Position in Dezimalgrad.
• Optionale Eigenschaften steuern Aussehen und Verhalten.

Da jede zusätzliche Eigenschaft im Popup landet, können Sie Sensorwerte, Fahrernamen oder Akkustände ohne weitere Konfiguration mitgeben. Befehle nutzen denselben Node: Eine Nachricht mit msg.payload.command wie { "lat": 41.01, "lon": 28.97, "zoom": 12 } verschiebt und zoomt die Karte.

Den Worldmap-Node installieren

Öffnen Sie im Editor Manage palette → Install und suchen Sie nach node-red-contrib-web-worldmap. Oder installieren Sie ihn über die Kommandozeile:

cd ~/.node-red
npm install node-red-contrib-web-worldmap
# then restart Node-RED

Die Karte lädt Kacheln von Online-Tile-Servern; der Browser, in dem sie angezeigt wird, braucht also Internetzugang. Wenn Sie neu bei Node-RED und MQTT sind, behandelt das Node-RED-MQTT-Tutorial zunächst Installation und Broker-Konfiguration.

GPS-Geräte über MQTT simulieren

Jedes Fahrzeug publiziert eine JSON-Position auf sein eigenes Topic: connectmq/demo/a7f3k2/fleet/<vehicle>/gps. Steht die Fahrzeug-ID im Topic und nicht nur in der Payload, können Subscriber ein einzelnes Fahrzeug wählen oder mit der Wildcard + alle abonnieren. Dieses Skript bewegt drei Fahrzeuge in Schleifen um ein Stadtzentrum und publiziert an broker.connectmq.com, den kostenlosen Öffentlichen MQTT-Broker. Ersetzen Sie a7f3k2 durch Ihren eigenen Zufallsstring; Positionen auf dem öffentlichen MQTT-Broker sind für jeden sichtbar, verwenden Sie dort also nur simulierte Daten.

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

import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/a7f3k2/fleet"
CENTER_LAT, CENTER_LON = 41.0082, 28.9784

vehicles = {
    "van1": {"angle": 0.0, "radius": 0.020, "speed": 0.010},
    "van2": {"angle": 2.0, "radius": 0.030, "speed": 0.007},
    "truck1": {"angle": 4.0, "radius": 0.045, "speed": 0.005},
}

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

try:
    while True:
        for vid, v in vehicles.items():
            v["angle"] += v["speed"] * random.uniform(0.8, 1.2)
            lat = CENTER_LAT + v["radius"] * math.sin(v["angle"])
            lon = CENTER_LON + v["radius"] * 1.3 * math.cos(v["angle"])
            # Heading is tangent to the circle, in degrees clockwise from north
            dlat = math.cos(v["angle"])
            dlon = -1.3 * math.sin(v["angle"])
            heading = (math.degrees(math.atan2(dlon, dlat)) + 360) % 360
            payload = {
                "lat": round(lat, 6),
                "lon": round(lon, 6),
                "heading": round(heading),
                "speed": round(random.uniform(25, 55), 1),
                "ts": int(time.time() * 1000),
            }
            client.publish(f"{PREFIX}/{vid}/gps", json.dumps(payload), qos=0)
        time.sleep(3)
except KeyboardInterrupt:
    pass
finally:
    client.loop_stop()
    client.disconnect()

QoS 0 ist für häufige Positionsmeldungen eine vernünftige Wahl: Geht ein Update verloren, kommt das nächste wenige Sekunden später. Verwenden Sie QoS 1 für Ereignisse, die Sie nicht verpassen dürfen, etwa Geofence-Alarme. Der Leitfaden zur Fahrzeugortung mit MQTT vertieft Topic- und Payload-Design für Flotten, und das Tutorial zum ESP32-GPS-Tracker zeigt die Geräteseite mit echter Hardware.

Den Node-RED-Worldmap-Flow aufbauen

Schritt 1: Alle Fahrzeuge abonnieren

Fügen Sie einen mqtt in-Node mit einer Broker-Konfiguration für broker.connectmq.com:1883 und einer eindeutigen Client ID hinzu. Setzen Sie das Topic auf connectmq/demo/a7f3k2/fleet/+/gps und die Ausgabe auf „a parsed JSON object“.

Schritt 2: MQTT-Payloads auf Marker abbilden

Fügen Sie zwischen dem mqtt in-Node und einem worldmap-Node einen Function-Node ein:

// Function node "gps to worldmap marker"
const p = msg.payload;
const lat = Number(p.lat);
const lon = Number(p.lon);

// Reject missing or impossible coordinates (and the classic 0,0 "no fix")
if (!Number.isFinite(lat) || !Number.isFinite(lon) ||
    Math.abs(lat) > 90 || Math.abs(lon) > 180 || (lat === 0 && lon === 0)) {
    return null;
}

// connectmq/demo/a7f3k2/fleet/van1/gps -> van1
const id = msg.topic.split("/")[4];
const isTruck = id.startsWith("truck");
const speed = Number(p.speed) || 0;

msg.payload = {
    name: id,
    lat: lat,
    lon: lon,
    bearing: Number(p.heading) || 0,
    icon: isTruck ? "fa-truck" : "car",
    iconColor: speed > 50 ? "orange" : "green",
    layer: isTruck ? "Trucks" : "Vans",
    label: id,
    speed: speed + " km/h",
    lastSeen: new Date(p.ts || Date.now()).toLocaleTimeString(),
    ttl: 120
};
return msg;

Deployen Sie und öffnen Sie http://localhost:1880/worldmap. Drei Marker erscheinen und bewegen sich alle drei Sekunden. Klicken Sie auf einen, um Geschwindigkeit und Zeitpunkt der letzten Meldung im Popup zu sehen. Stellt ein Fahrzeug das Publizieren ein, verschwindet sein Marker dank ttl nach zwei Minuten.

Schritt 3: Die Karte beim Start zentrieren

Fügen Sie einen Inject-Node mit inject once after 1 second und der JSON-Payload {"command": {"lat": 41.0082, "lon": 28.9784, "zoom": 12}} hinzu und verbinden Sie ihn mit demselben worldmap-Node. Beachten Sie, dass Befehle beim Eintreffen angewendet werden; ein Browser, der sich später verbindet, startet in der Standardansicht, sofern Sie den Befehl nicht bei jeder Verbindung erneut senden. Der worldmap in-Node gibt dafür ein Connect-Ereignis aus.

Schritt 4: Spuren zeichnen

Das Paket enthält außerdem einen worldmap tracks-Node. Setzen Sie ihn zwischen Ihren Function-Node und den worldmap-Node und legen Sie fest, wie viele Punkte behalten werden sollen, zum Beispiel 50. Er zeichnet eine Linie hinter jeden bewegten Marker, wodurch Routen und Schleifen auf einen Blick sichtbar werden.

Umgang mit veralteten und Offline-Geräten

Marker per ttl zu entfernen ist einfach, oft möchten Sie einen Marker aber lieber behalten und zeigen, dass er veraltet ist. Zwei Muster bewähren sich:

1. Nach Alter einfärben. Halten Sie die letzte Nachricht pro Fahrzeug im Flow-Context, lassen Sie alle 30 Sekunden einen Inject laufen und senden Sie jedes Fahrzeug mit iconColor: "grey" erneut, wenn sein Zeitstempel älter als ein Schwellwert ist.
2. Last Will and Testament nutzen. Jedes Gerät setzt eine retained Will-Nachricht wie offline auf .../fleet/<vehicle>/status. Bricht die Verbindung ab, publiziert der Broker den Will, und ein zweiter mqtt in-Node aktualisiert den Marker. Durch den retained Status weiß ein frisch gestartetes Node-RED sofort, welche Fahrzeuge offline sind.

Beides zusammen gibt dem Bedienpersonal ein klares Bild: Grüne, bewegte Marker sind in Ordnung, graue sind verspätet, und als offline markierte haben ihre Verbindung verloren. Das Routing dieser Statusnachrichten ist eine gute Aufgabe für den Node-RED Switch-Node.

Die Karte in Dashboard 2.0 einbetten

Die Worldmap hat eine eigene Seite, Sie können sie aber auch in einem Dashboard anzeigen. Fügen Sie in Dashboard 2.0 ein ui-template-Widget hinzu, dessen Template einen iframe auf /worldmap enthält, passend zur Gruppengröße. So steht die Karte neben Anzeigen und Alarmen auf einem Bildschirm. Das Tutorial zu Dashboard 2.0 erklärt Gruppen und Layout.

Checkliste zur Fehlerbehebung

1. Keine Marker. Prüfen Sie mit einem Debug-Node, ob Nachrichten ankommen; kontrollieren Sie, dass name, lat und lon vorhanden und Zahlen statt Strings sind.
2. Marker springen in den Golf von Guinea. Das ist Position 0,0, eine typische Ausgabe bei „kein GPS-Fix“. Die Funktion oben filtert sie heraus.
3. Alle Fahrzeuge teilen sich einen Marker. Jede Nachricht hat denselben name. Leiten Sie ihn aus dem Topic oder einer Geräte-ID ab.
4. Karte ist einheitlich grau. Der Browser erreicht den Tile-Server nicht; prüfen Sie Internetzugang oder Proxy-Einstellungen.
5. Symbole drehen sich nicht. Nur richtungsabhängige Symbole beachten bearing; wechseln Sie zu einem Fahrzeugsymbol wie car.
6. Positionen hinken der Realität hinterher. Prüfen Sie Publish-Intervall und Keep-Alive des Geräts und vermeiden Sie bei Live-Karten, alte Positionen mit QoS 2 aufzustauen.

GPS-Tracking in die Produktion bringen

Standortdaten sind in vielen Zusammenhängen personenbezogene Daten im Sinne der DSGVO und dürfen in der Produktion daher niemals über einen öffentlichen Broker laufen. Ziehen Sie Geräte und Node-RED auf einen privaten Broker mit TLS auf Port 8883 und Zugangsdaten pro Gerät um. Bei ConnectMQ erzeugt das Portal pro Broker Benutzername, Passwort und Client ID, und wiederholte fehlgeschlagene Anmeldungen von einer IP führen zu deren Sperrung, was gegen das Erraten von Zugangsdaten auf Feldgeräten hilft. Geräte mit Mobilfunkanbindung profitieren von einem verwalteten MQTT-Broker mit stabilem öffentlichem Endpunkt, da sie ausschließlich ausgehend verbinden. Wenn Sie zuerst die Hosting-Optionen vergleichen möchten, lesen Sie, was ein MQTT-Broker leistet und wie sich Broker bei Authentifizierung und Limits unterscheiden.

Ihre Geräte auf ConnectMQ verfolgen

Registrieren Sie sich unter app.connectmq.com und starten Sie mit dem kostenlosen Serverless-Plan, ohne Kreditkarte. Legen Sie einen Broker an, spielen Sie die Zugangsdaten auf Ihre Tracker, richten Sie den Node-RED-Konfigurations-Node auf Port 8883 mit TLS aus, und Ihre Worldmap läuft auf einem privaten, verschlüsselten Datenstrom. Mit dem Live-Topic-Explorer von ConnectMQ prüfen Sie schnell, ob das GPS-Topic jedes Fahrzeugs aktualisiert wird.

Häufig gestellte Fragen

Unter welcher URL ist die Node-RED Worldmap erreichbar?

Standardmäßig wird die Karte unter http://<node-red-host>:1880/worldmap bereitgestellt. Der Pfad lässt sich in den Einstellungen des Worldmap-Nodes ändern.

Wie verschiebe ich einen Marker, statt einen neuen anzulegen?

Senden Sie eine neue Nachricht mit demselben name. Der Worldmap-Node behandelt name als ID des Markers und aktualisiert dessen Position und Eigenschaften.

Wie entferne ich ein Fahrzeug von der Karte?

Senden Sie eine Nachricht mit dem name des Fahrzeugs und deleted: true, oder setzen Sie ttl, damit Marker automatisch verschwinden, wenn keine Updates mehr kommen.

Kann die Worldmap andere Daten als die GPS-Position anzeigen?

Ja. Alle zusätzlichen Eigenschaften in der Payload, etwa Geschwindigkeit, Akkustand oder Temperatur, erscheinen im Popup des Markers, und mit der Eigenschaft layer gruppieren Sie Marker nach Typ.