Node-RED Worldmap : suivre des appareils GPS via MQTT

Le nœud Node-RED Worldmap transforme en quelques minutes un flux de messages GPS MQTT en marqueurs mobiles sur une carte interactive. Dans ce tutoriel, vous allez simuler trois véhicules, convertir leurs positions JSON en marqueurs Worldmap avec cap et couleurs, signaler les appareils qui cessent d'émettre et tracer des parcours. À la fin, vous disposerez d'un suivi en direct fonctionnel que vous pourrez brancher sur du vrai matériel GPS.

Comment fonctionne le nœud Node-RED Worldmap

Le paquet node-red-contrib-web-worldmap ajoute un nœud worldmap qui sert une carte basée sur Leaflet à l'adresse http://<node-red-host>:1880/worldmap. Chaque message envoyé au nœud décrit un objet :

• msg.payload.name est l'identifiant unique. Envoyer une nouvelle position avec le même nom déplace le marqueur existant.
• msg.payload.lat et msg.payload.lon donnent la position en degrés décimaux.
• Des propriétés optionnelles contrôlent l'apparence et le comportement.

Comme toute propriété supplémentaire se retrouve dans la popup, vous pouvez transmettre des valeurs de capteurs, des noms de conducteurs ou des niveaux de batterie sans configuration supplémentaire. Les commandes passent par le même nœud : un message avec msg.payload.command, par exemple { "lat": 41.01, "lon": 28.97, "zoom": 12 }, déplace et zoome la carte.

Installer le nœud Worldmap

Dans l'éditeur, ouvrez Manage palette → Install et recherchez node-red-contrib-web-worldmap. Ou installez-le en ligne de commande :

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

La carte télécharge ses tuiles depuis des serveurs de tuiles en ligne : le navigateur qui l'affiche doit donc avoir accès à Internet. Si vous débutez avec Node-RED et MQTT, le tutoriel Node-RED MQTT couvre d'abord l'installation et la configuration du broker.

Simuler des appareils GPS via MQTT

Chaque véhicule publie une position JSON sur son propre topic : connectmq/demo/a7f3k2/fleet/<vehicle>/gps. Placer l'identifiant du véhicule dans le topic, et pas seulement dans le payload, permet aux abonnés de choisir un véhicule précis ou d'utiliser un wildcard + pour tous. Ce script fait tourner trois véhicules en boucle autour d'un centre-ville et publie sur broker.connectmq.com, le serveur MQTT public gratuit. Remplacez a7f3k2 par votre propre chaîne aléatoire ; les positions publiées sur le serveur public sont visibles par tous, n'y envoyez donc que des données simulées.

# 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()

Le QoS 0 est un choix raisonnable pour des positions fréquentes : si une mise à jour se perd, la suivante arrive quelques secondes plus tard. Utilisez le QoS 1 pour les événements à ne pas manquer, comme les alarmes de géorepérage. Le guide sur le suivi de véhicules avec MQTT approfondit la conception des topics et des payloads pour les flottes, et le tutoriel traceur GPS ESP32 montre le côté appareil avec du vrai matériel.

Construire le flow Node-RED Worldmap

Étape 1 : s'abonner à tous les véhicules

Ajoutez un nœud mqtt in avec une configuration broker pointant vers broker.connectmq.com:1883 et un client ID unique. Réglez le topic sur connectmq/demo/a7f3k2/fleet/+/gps et la sortie sur « a parsed JSON object ».

Étape 2 : convertir les payloads MQTT en marqueurs

Ajoutez un nœud function entre le nœud mqtt in et un nœud worldmap :

// 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;

Déployez, puis ouvrez http://localhost:1880/worldmap. Trois marqueurs apparaissent et se déplacent toutes les trois secondes. Cliquez sur l'un d'eux pour voir la vitesse et l'heure de dernière réception dans la popup. Si un véhicule cesse de publier, son marqueur disparaît au bout de deux minutes grâce à ttl.

Étape 3 : centrer la carte au démarrage

Ajoutez un nœud inject réglé sur inject once after 1 second avec le payload JSON {"command": {"lat": 41.0082, "lon": 28.9784, "zoom": 12}} et reliez-le au même nœud worldmap. Notez que les commandes s'appliquent à leur arrivée : un navigateur qui se connecte plus tard démarre sur la vue par défaut, sauf si vous renvoyez aussi la commande à la connexion. Le nœud worldmap in émet un événement de connexion que vous pouvez utiliser pour cela.

Étape 4 : tracer les parcours

Le paquet inclut aussi un nœud worldmap tracks. Placez-le entre votre nœud function et le nœud worldmap et définissez le nombre de points à conserver, par exemple 50. Il ajoute une ligne derrière chaque marqueur en mouvement, ce qui rend les itinéraires et les boucles évidents au premier coup d'œil.

Gérer les appareils muets et hors ligne

Supprimer les marqueurs avec ttl est simple, mais on préfère souvent garder un marqueur en signalant que sa position est ancienne. Deux approches fonctionnent bien :

1. Colorer selon l'ancienneté. Conservez le dernier message de chaque véhicule dans le contexte du flow, lancez un inject toutes les 30 secondes et renvoyez chaque véhicule avec iconColor: "grey" si son horodatage dépasse un seuil.
2. Utiliser le Last Will and Testament. Chaque appareil définit un message de will retenu, par exemple offline, sur .../fleet/<vehicle>/status. Si sa connexion tombe, le broker publie ce will et un second nœud mqtt in met à jour le marqueur. Grâce au statut retenu, un Node-RED fraîchement démarré sait immédiatement quels véhicules sont hors ligne.

Combiner les deux donne aux opérateurs une image claire : les marqueurs verts en mouvement sont sains, les gris sont en retard et ceux marqués hors ligne ont perdu leur connexion. Router ces messages de statut est un bon travail pour le nœud switch de Node-RED.

Intégrer la carte dans Dashboard 2.0

La Worldmap a sa propre page, mais vous pouvez aussi l'afficher dans un tableau de bord. Dans Dashboard 2.0, ajoutez un widget ui-template dont le template contient une iframe pointant vers /worldmap, dimensionnée au groupe. La carte reste ainsi à côté des jauges et des alertes sur un même écran. Le tutoriel Dashboard 2.0 explique les groupes et la mise en page.

Check-list de dépannage

1. Aucun marqueur. Vérifiez l'arrivée des messages avec un nœud debug ; contrôlez que name, lat et lon existent et sont des nombres, pas des chaînes.
2. Les marqueurs sautent dans le golfe de Guinée. C'est la position 0,0, une sortie typique d'un GPS « sans fix ». La fonction ci-dessus la filtre.
3. Tous les véhicules partagent un seul marqueur. Chaque message a le même name. Dérivez-le du topic ou d'un identifiant d'appareil.
4. La carte reste grise. Le navigateur n'atteint pas le serveur de tuiles ; vérifiez l'accès Internet ou les réglages de proxy.
5. Les icônes ne pivotent pas. Seules les icônes directionnelles tiennent compte de bearing ; passez à une icône de véhicule comme car.
6. Les positions sont en retard sur la réalité. Vérifiez l'intervalle de publication de l'appareil et les réglages de keep-alive, et évitez de mettre en file d'anciennes positions en QoS 2 pour des cartes en direct.

Passer le suivi GPS en production

Dans bien des contextes, les données de localisation sont des données personnelles : elles ne doivent jamais transiter par un serveur public en production. Migrez appareils et Node-RED vers un broker privé avec TLS sur le port 8883 et des identifiants par appareil. Avec ConnectMQ, le portail génère un nom d'utilisateur, un mot de passe et un client ID par broker, et les échecs de connexion répétés depuis une IP entraînent son blocage, ce qui aide contre la devinette d'identifiants sur les appareils de terrain. Les appareils en connexion cellulaire profitent d'un broker MQTT managé doté d'un endpoint public stable, puisqu'ils ne font que des connexions sortantes. Si vous voulez d'abord comparer les options d'hébergement, lisez ce que fait un broker MQTT et en quoi les brokers diffèrent en matière d'authentification et de limites.

Suivez vos appareils sur ConnectMQ

Inscrivez-vous sur app.connectmq.com et commencez avec l'offre gratuite Serverless, sans carte bancaire. Créez un broker, flashez les identifiants dans vos traceurs, pointez le nœud de configuration Node-RED vers le port 8883 avec TLS, et votre Worldmap tourne sur un flux privé et chiffré. L'explorateur de topics en direct de ConnectMQ permet de vérifier rapidement que le topic GPS de chaque véhicule se met à jour.

Questions fréquentes

Quelle URL utilise la Worldmap de Node-RED ?

Par défaut, la carte est servie à l'adresse http://<node-red-host>:1880/worldmap. Le chemin peut être modifié dans les réglages du nœud worldmap.

Comment déplacer un marqueur au lieu d'en créer un nouveau ?

Envoyez un nouveau message avec le même name. Le nœud worldmap traite name comme l'identifiant du marqueur et met à jour sa position et ses propriétés.

Comment retirer un véhicule de la carte ?

Envoyez un message avec le name du véhicule et deleted: true, ou définissez ttl pour que les marqueurs disparaissent automatiquement quand les mises à jour cessent.

La Worldmap peut-elle afficher d'autres données que la position GPS ?

Oui. Toute propriété supplémentaire du payload, comme la vitesse, la batterie ou la température, apparaît dans la popup du marqueur, et la propriété layer permet de regrouper les marqueurs par type.