Tutoriel Node-RED MQTT : flows, tableaux de bord et automatisation

Ce tutoriel Node-RED MQTT vous montre comment connecter Node-RED à un broker, recevoir et publier des messages, transformer du JSON brut en tableau de bord en direct et déclencher des alertes lorsque des valeurs franchissent un seuil. Vous commencerez sur le serveur MQTT public gratuit broker.connectmq.com avec un flow importable, puis basculerez ce même flow vers un broker privé chiffré par TLS en modifiant un seul nœud de configuration. Tout ce qui suit fonctionne sur un ordinateur portable, un Raspberry Pi ou un conteneur Docker.

Pourquoi Node-RED et MQTT vont si bien ensemble

Node-RED est un outil de programmation par flux : vous reliez des nœuds dans un éditeur web, et chaque message circule le long des fils sous la forme d'un objet JavaScript appelé msg. MQTT est un protocole publish/subscribe dans lequel les clients échangent des messages via un broker à l'aide de topics. Les deux partagent le même modèle mental. Un nœud mqtt in est un abonné qui injecte des messages dans un flow, et un nœud mqtt out est un éditeur qui envoie tout ce qui lui parvient.

Node-RED est donc une couche de liaison naturelle autour d'un système MQTT. Ses usages typiques :

• Traduire entre des équipements qui utilisent des formats de payload différents.
• Construire rapidement des tableaux de bord opérateur sans projet front-end.
• Surveiller des seuils et envoyer des notifications par e-mail ou messagerie.
• Écrire la télémétrie dans une base de données de séries temporelles.
• Relier des protocoles comme Modbus, OPC UA ou HTTP à des topics MQTT.

Si vous avez d'abord besoin de réviser les notions de broker, de topics et de wildcards, lisez ce que fait un broker MQTT. La suite de ce guide suppose que vous savez que + correspond à un niveau de topic et # à tout ce qui se trouve sous un niveau.

Installer Node-RED

Choisissez l'installation qui convient à votre machine. Toute version actuelle de Node-RED 4.x inclut les nœuds MQTT ; vous n'avez besoin d'aucun paquet supplémentaire pour ce tutoriel jusqu'à l'étape du tableau de bord.

# Option 1 : npm (nécessite Node.js 18 ou plus récent)
sudo npm install -g --unsafe-perm node-red
node-red

# Option 2 : Docker
docker run -d --name nodered -p 1880:1880 -v node_red_data:/data nodered/node-red:4.0

# Option 3 : Raspberry Pi OS / Debian, script d'installation officiel
bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-node-red)

Ouvrez http://localhost:1880 (ou l'adresse du Pi) dans un navigateur. Pour la configuration en tant que service, les mises à jour et les spécificités de Windows, consultez notre guide pas à pas pour installer Node-RED, et si vous préférez les conteneurs, exécuter Node-RED dans Docker couvre les volumes et les politiques de redémarrage. La documentation officielle de Node-RED est la référence pour chaque nœud de base.

Étape 1 : configurer le nœud broker MQTT

Chaque nœud MQTT de Node-RED pointe vers un nœud de configuration partagé de type mqtt-broker. Configurez-le une fois et réutilisez-le dans tous les flows ; Node-RED maintient alors une seule connexion au broker, ce qui compte sur les brokers qui limitent le nombre de connexions par compte.

Faites glisser un nœud mqtt in sur le canevas, double-cliquez dessus, puis cliquez sur le crayon à côté de Server pour ajouter un nouveau broker :

Dans l'onglet Messages, définissez un message de naissance (connectmq/demo/nr-7f3a/status, payload online, retenu, QoS 1) et un message Last Will sur le même topic avec offline. Les autres clients peuvent alors savoir si votre instance Node-RED est en vie.

Pourquoi renseigner vous-même le client ID ? Si vous le laissez vide, Node-RED en génère un, ce qui convient sur un broker de test. Sur un broker de production qui lie les client ID aux identifiants, vous devez saisir exactement l'ID qui vous a été attribué. Deux instances Node-RED (par exemple votre portable et votre Pi) ayant le même client ID se déconnecteront mutuellement en boucle.

Étape 2 : importer un flow fonctionnel

Le moyen le plus rapide d'apprendre est d'importer un flow complet et de le décortiquer. Dans l'éditeur, ouvrez le menu, choisissez Import, collez le JSON ci-dessous et cliquez sur Import. Remplacez d'abord chaque nr-7f3a par votre propre suffixe aléatoire pour ne pas partager vos topics avec d'autres lecteurs de ce tutoriel Node-RED MQTT.

[
  { "id": "tab_mqtt", "type": "tab", "label": "MQTT tutorial" },
  {
    "id": "cmq_broker", "type": "mqtt-broker", "name": "ConnectMQ public",
    "broker": "broker.connectmq.com", "port": "1883", "clientid": "nodered-7f3a",
    "autoConnect": true, "usetls": false, "protocolVersion": "5", "keepalive": "60",
    "cleansession": true, "autoUnsubscribe": true,
    "birthTopic": "connectmq/demo/nr-7f3a/status", "birthQos": "1", "birthRetain": "true", "birthPayload": "online", "birthMsg": {},
    "closeTopic": "connectmq/demo/nr-7f3a/status", "closeQos": "1", "closeRetain": "true", "closePayload": "offline", "closeMsg": {},
    "willTopic": "connectmq/demo/nr-7f3a/status", "willQos": "1", "willRetain": "true", "willPayload": "offline", "willMsg": {},
    "userProps": "", "sessionExpiry": ""
  },
  {
    "id": "inj_tick", "type": "inject", "z": "tab_mqtt", "name": "every 5 s",
    "props": [{ "p": "payload" }], "repeat": "5", "crontab": "", "once": true, "onceDelay": "1",
    "topic": "", "payload": "", "payloadType": "date", "x": 120, "y": 80, "wires": [["fn_sim"]]
  },
  {
    "id": "fn_sim", "type": "function", "z": "tab_mqtt", "name": "simulate sensor",
    "func": "const base = 25 + 6 * Math.sin(Date.now() / 60000);\nmsg.payload = {\n  temperature: Math.round((base + Math.random()) * 10) / 10,\n  humidity: Math.round(40 + Math.random() * 10),\n  ts: Date.now()\n};\nreturn msg;",
    "outputs": 1, "x": 310, "y": 80, "wires": [["out_tel"]]
  },
  {
    "id": "out_tel", "type": "mqtt out", "z": "tab_mqtt", "name": "publish telemetry",
    "topic": "connectmq/demo/nr-7f3a/line1/sensor1/telemetry", "qos": "0", "retain": "false",
    "broker": "cmq_broker", "x": 530, "y": 80, "wires": []
  },
  {
    "id": "in_tel", "type": "mqtt in", "z": "tab_mqtt", "name": "all sensors",
    "topic": "connectmq/demo/nr-7f3a/+/+/telemetry", "qos": "1", "datatype": "auto-detect",
    "broker": "cmq_broker", "nl": false, "rap": true, "rh": 0, "inputs": 0,
    "x": 130, "y": 180, "wires": [["fn_alert", "dbg_tel"]]
  },
  {
    "id": "fn_alert", "type": "function", "z": "tab_mqtt", "name": "alert on crossing 30 C",
    "func": "const t = Number(msg.payload.temperature);\nif (Number.isNaN(t)) return null;\nconst key = msg.topic;\nconst wasHigh = context.get(key) || false;\nconst isHigh = t > 30;\ncontext.set(key, isHigh);\nif (isHigh === wasHigh) return null;\nmsg.topic = msg.topic.replace(/telemetry$/, 'alert');\nmsg.payload = { level: isHigh ? 'high' : 'normal', temperature: t, ts: Date.now() };\nreturn msg;",
    "outputs": 1, "x": 360, "y": 180, "wires": [["out_alert", "dbg_alert"]]
  },
  {
    "id": "out_alert", "type": "mqtt out", "z": "tab_mqtt", "name": "publish alert",
    "topic": "", "qos": "1", "retain": "true", "broker": "cmq_broker", "x": 590, "y": 160, "wires": []
  },
  {
    "id": "dbg_tel", "type": "debug", "z": "tab_mqtt", "name": "telemetry", "active": true,
    "tosidebar": true, "console": false, "complete": "payload", "x": 340, "y": 240, "wires": []
  },
  {
    "id": "dbg_alert", "type": "debug", "z": "tab_mqtt", "name": "alerts", "active": true,
    "tosidebar": true, "console": false, "complete": "true", "x": 580, "y": 220, "wires": []
  }
]

Cliquez sur Deploy. En quelques secondes, le petit indicateur d'état sous chaque nœud MQTT passe au vert avec la mention « connected », et la barre latérale de débogage commence à afficher des objets de télémétrie. Vérifiez depuis un terminal que les messages passent réellement par le broker :

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-cli-7f3a -v -t "connectmq/demo/nr-7f3a/#"

Vous devriez voir d'abord le message status retenu, puis un message de télémétrie toutes les cinq secondes et, chaque fois que la température simulée franchit 30, une alerte.

Étape 3 : comprendre les nœuds mqtt in et mqtt out

Le flow importé utilise chaque nœud MQTT d'une manière précise, et ces réglages sont ceux que vous modifierez le plus souvent.

Le nœud mqtt in

• Topic accepte les wildcards. connectmq/demo/nr-7f3a/+/+/telemetry reçoit la télémétrie de chaque capteur de chaque ligne sous votre préfixe, et msg.topic vous indique lequel l'a envoyée.
• Output réglé sur auto-detect transforme les payloads JSON en objets, laisse le texte brut sous forme de chaîne et transmet les données binaires sous forme de Buffer. Si un équipement envoie parfois du JSON mal formé, choisissez plutôt a String et analysez-le vous-même avec un nœud JSON afin de pouvoir intercepter les erreurs.
• QoS est la QoS maximale que vous souhaitez recevoir. Le broker livre avec la plus faible des QoS de l'éditeur et de l'abonné.
• Abonnement dynamique : configurez le nœud pour qu'il accepte une entrée et envoyez-lui msg.action = "subscribe" avec msg.topic. Un même flow peut ainsi suivre des topics connus seulement à l'exécution ; le guide des abonnements MQTT dynamiques dans Node-RED en donne un exemple complet.

Le nœud mqtt out

• Si le champ Topic du nœud est vide, il publie sur msg.topic. La branche d'alerte s'appuie sur ce comportement : le nœud function réécrit le topic de .../telemetry en .../alert.
• Si le champ Topic est rempli, il prend le pas sur msg.topic. Un bug fréquent chez les débutants consiste à renseigner les deux et à se demander pourquoi les messages arrivent sur le mauvais topic.
• Les objets dans msg.payload sont automatiquement sérialisés en JSON. Les nombres et les booléens deviennent des chaînes.
• Retain sur les topics d'alerte et d'état garantit que tout client qui s'abonne plus tard voit immédiatement la dernière valeur. Laissez-le désactivé pour la télémétrie à haute fréquence.

Pour une gestion plus poussée du JSON, notamment la conversion de chaînes en objets et inversement, voir le nœud JSON de Node-RED. Pour écrire une logique comme la fonction d'alerte, lisez le nœud function de Node-RED, qui couvre le stockage de contexte, les sorties multiples et la gestion des erreurs.

Étape 4 : construire un tableau de bord Node-RED MQTT

Une sortie de débogage brute n'est pas quelque chose que l'on peut confier à un opérateur. Dashboard 2.0 est le tableau de bord actuel et activement maintenu de Node-RED. Installez-le depuis Manage palette en recherchant @flowfuse/node-red-dashboard, ou en ligne de commande :

cd ~/.node-red
npm install @flowfuse/node-red-dashboard
# redémarrez Node-RED ensuite

Complétez ensuite votre flow :

1. Ajoutez un nœud function après le nœud mqtt in all sensors avec le code ci-dessous. Il découpe chaque objet de télémétrie en messages adaptés aux graphiques.
2. Reliez sa première sortie à un ui-gauge (plage de 0 à 50, libellé « Temperature ») ainsi qu'à un ui-chart (type ligne, axe X temporel).
3. Reliez la seconde sortie à un second ui-gauge pour l'humidité.
4. Lorsque vous ajoutez le premier widget, Node-RED vous demande de créer une page et un groupe ; acceptez les valeurs par défaut.
5. Déployez et ouvrez http://localhost:1880/dashboard.

// Découpe la télémétrie en un message par métrique pour les jauges et les graphiques
const sensor = msg.topic.split("/").slice(-2, -1)[0]; // ex. "sensor1"
const p = msg.payload;
if (typeof p !== "object" || p === null) return null;

return [
  { topic: `${sensor} temperature`, payload: Number(p.temperature) },
  { topic: `${sensor} humidity`, payload: Number(p.humidity) }
];

Réglez ce nœud function sur deux sorties dans son onglet Setup. Utiliser le nom du capteur dans msg.topic permet à un même graphique de tracer automatiquement une ligne par capteur lorsque vous ajoutez des équipements.

Pour commander un équipement depuis le tableau de bord, ajoutez un ui-switch dont les payloads marche et arrêt valent ON et OFF, et reliez-le à un nœud mqtt out avec un topic comme connectmq/demo/nr-7f3a/line1/fan1/set, en QoS 1. La bonne pratique consiste à piloter l'état affiché de l'interrupteur à partir du topic d'état de l'équipement lui-même plutôt qu'à partir du clic, afin que le tableau de bord n'affiche jamais un état que le matériel n'a pas atteint. Mises en page, thèmes et tableaux de bord multipages sont traités dans notre guide Node-RED Dashboard 2.0, et la conservation d'un long historique fait l'objet de Node-RED avec InfluxDB.

Étape 5 : alertes et automatisation

La fonction alert on crossing 30 C du flow importé est volontairement écrite comme un détecteur de fronts. Elle stocke l'état précédent par topic dans le contexte du nœud et n'émet un message que lorsque l'état change. Sans cela, un capteur stable à 31 degrés déclencherait une alerte toutes les cinq secondes et inonderait votre boîte de réception.

À partir du topic d'alerte, vous pouvez diffuser vers n'importe quel canal de notification :

• E-mail avec le nœud node-red-node-email ; voir envoyer des alertes par e-mail depuis Node-RED.
• Telegram pour des notifications instantanées sur téléphone via un bot ; voir les alertes Telegram avec Node-RED.
• Un autre topic MQTT consommé par une sirène, une colonne lumineuse ou un autre système.

Comme l'alerte elle-même est republiée vers MQTT sous forme de retained message, Node-RED n'est pas le seul consommateur. Tout tableau de bord, application mobile ou script abonné à +/alert voit le même événement, ce qui garde votre logique d'automatisation en un seul endroit et vos canaux de notification découplés.

Un pattern utile pour les installations plus importantes est une structure de topics hiérarchique comme site/area/line/cell/device/metric, inspirée d'ISA-95. Elle permet à un seul abonnement wildcard dans Node-RED de couvrir une ligne entière ou tout le site, et constitue la base de l'approche Unified Namespace décrite dans MQTT, Sparkplug B et le Unified Namespace.

Étape 6 : passer à un broker privé avec TLS

Le serveur MQTT public gratuit est partagé et lisible par tous ; il est donc réservé aux tests. Pour de vrais flows, utilisez votre propre broker avec chiffrement et identifiants. Vous pouvez en exploiter un vous-même, mais un broker MQTT managé retire les correctifs, les certificats et la disponibilité de votre liste de tâches. Avec ConnectMQ, vous vous inscrivez, choisissez un plan, créez un broker et copiez depuis le portail le nom d'utilisateur, le mot de passe et le client ID générés.

Ouvrez le nœud de configuration ConnectMQ public et modifiez-le :

Le broker utilise un certificat Let's Encrypt publiquement reconnu ; Node-RED le valide donc avec son magasin de CA intégré, et vous n'avez aucun fichier CA à téléverser. Les identifiants sont stockés dans le fichier d'identifiants chiffré de Node-RED, et non dans le JSON du flow : c'est pourquoi les flows exportés ne contiennent jamais de mots de passe. Définissez un credentialSecret dans settings.js pour que ce fichier reste lisible si vous déplacez Node-RED sur une autre machine.

Les détails comme les certificats client, les CA personnalisées et les erreurs de poignée de main courantes se trouvent dans Node-RED MQTT sur TLS. Verrouillez aussi l'éditeur lui-même : un éditeur Node-RED exposé sans authentification équivaut à une exécution de code à distance sur votre serveur. Sécuriser Node-RED explique adminAuth, HTTPS et l'exposition réseau.

Dépannage du tutoriel Node-RED MQTT

Lorsqu'un nœud affiche « disconnected » ou reste indéfiniment sur « connecting », parcourez cette checklist :

1. Faute de frappe dans le nom d'hôte ou préfixe de protocole. Le champ Server attend broker.connectmq.com, et non mqtt://broker.connectmq.com.
2. Mauvais port pour TLS. Le port 1883 est du TCP en clair, le 8883 exige la case Use TLS. Les mélanger provoque des délais d'attente silencieux.
3. Client ID en double. Une autre instance Node-RED, un script de test ou MQTT Explorer utilisant le même ID fait tomber la connexion toutes les quelques secondes.
4. Identifiants incorrects ou client ID qui ne correspond pas. Le journal du nœud affiche « Connection refused: Not authorized ». Recopiez les trois valeurs depuis le portail.
5. Ports sortants bloqués. Exécutez nc -vz broker.connectmq.com 8883 depuis l'hôte Node-RED. Les conteneurs Docker peuvent aussi nécessiter des réglages DNS corrects.
6. Les messages arrivent mais semblent incorrects. Vérifiez le réglage Output du nœud mqtt in ; un Buffer dans la barre de débogage signifie que le nœud est réglé en binaire.
7. Limites de débit ou de taille. Sur le serveur MQTT public gratuit, restez sous 10 messages par seconde et 64 Ko par message pour chaque client ; des nœuds inject réglés sur des intervalles très courts atteignent vite ces limites.

Pour un diagnostic au niveau des journaux pour chacun de ces cas, notre guide dédié Node-RED MQTT ne se connecte pas passe en revue les messages d'erreur exacts.

Pour aller plus loin avec Node-RED

Une fois les bases maîtrisées, ces guides prolongent la même connexion au broker vers de vrais projets :

• Données industrielles : lisez des registres d'automates avec Node-RED et Modbus ou décodez les messages de naissance et de données avec Node-RED et Sparkplug B.
• Conception propre des topics : restructurez des topics d'équipements désordonnés avec le mapping de topics MQTT dans Node-RED.
• Logique réutilisable : regroupez les nœuds répétés dans des subflows Node-RED.
• Indicateurs de production : construisez un tableau de bord TRS dans Node-RED.

Faites tourner vos flows Node-RED sur ConnectMQ

Node-RED gère la logique ; le broker transporte chaque message entre vos flows, vos équipements et vos tableaux de bord. Le plan Serverless gratuit de ConnectMQ ne demande aucune carte bancaire et vous fournit un broker privé avec TLS sur le port 8883, MQTT 5, jusqu'à 25 connexions et un client MQTT dans le navigateur pour inspecter les topics pendant que vous construisez. Lorsque vos flows grandissent, le Serverless payant ajoute les abonnements partagés pour répartir la charge entre plusieurs instances Node-RED, et les plans Dedicated vous offrent un cluster isolé. Créez votre broker gratuit sur app.connectmq.com, collez les identifiants dans votre nœud broker et déployez. Pour examiner plus en détail les options d'hébergement, lisez notre guide pour exploiter un broker MQTT dans le cloud, ou commencez à tester immédiatement sur le serveur MQTT public gratuit.

Questions fréquentes

Node-RED inclut-il un broker MQTT ?

Non. Node-RED ne fournit que des nœuds clients MQTT. Vous les connectez à un broker externe, comme un broker MQTT managé ou une instance Mosquitto que vous exploitez vous-même ; il existe des nœuds broker communautaires, mais ils ne sont pas recommandés en production.

Combien de connexions Node-RED utilise-t-il pour MQTT ?

Une par nœud de configuration mqtt-broker, quel que soit le nombre de nœuds mqtt in et mqtt out qui le partagent. Réutilisez un seul nœud de configuration pour rester dans les limites de connexions.

Pourquoi mon nœud mqtt in renvoie-t-il une chaîne au lieu d'un objet ?

Le réglage Output est probablement sur a String, ou le payload n'est pas du JSON valide. Passez à auto-detect ou a parsed JSON object, ou ajoutez un nœud JSON pour l'analyser explicitement.

Node-RED peut-il utiliser les fonctionnalités de MQTT 5 ?

Oui. Réglez le protocole sur MQTT V5 dans le nœud broker pour utiliser depuis les nœuds mqtt in et mqtt out des fonctionnalités comme les user properties, l'expiration des messages, les topics de réponse et l'expiration des sessions.

Est-il sûr d'utiliser le serveur MQTT public gratuit avec Node-RED ?

C'est adapté pour apprendre et faire des démos, mais n'importe qui peut lire les topics publics. Utilisez des préfixes de topic uniques, n'envoyez aucune donnée sensible et passez à un broker privé avec TLS avant de connecter de vrais équipements.