Le nœud JSON de Node-RED convertit des chaînes JSON en objets JavaScript et inversement, et c'est lui qui détermine si msg.payload.temp fonctionne ou renvoie undefined. Ce guide vous montre comment le JSON arrive via MQTT, quand laisser le nœud mqtt in l'analyser pour vous, quand utiliser plutôt le nœud JSON, comment valider les payloads avec un schéma et comment corriger les erreurs d'analyse courantes.
Pourquoi les payloads MQTT doivent être analysés
MQTT lui-même ignore tout du JSON. Un broker transporte chaque payload sous forme d'octets bruts, que ces octets représentent un nombre, une ligne CSV, un message Protobuf ou un document JSON. Lorsqu'un capteur de température publie {"temp": 22.4, "hum": 41}, l'abonné reçoit 26 octets et doit décider de leur signification.
Node-RED vous offre deux endroits pour prendre cette décision : l'option Output du nœud mqtt in et le nœud JSON séparé. Tous deux utilisent le même analyseur en interne. La différence tient à l'endroit où la conversion a lieu et au degré de contrôle que vous conservez. Pour revoir comment les brokers acheminent ces octets, consultez ce que fait un broker MQTT.
Option 1 : laisser le nœud mqtt in analyser le JSON
Ouvrez n'importe quel nœud mqtt in et regardez la liste déroulante Output. Les versions actuelles de Node-RED proposent :
| Réglage Output | Ce que devient msg.payload |
Adapté à |
|---|---|---|
| auto-detect (parsed JSON object, string or buffer) | Objet si le JSON est valide, sinon chaîne, ou Buffer pour du binaire | Topics mixtes ou inconnus |
| a parsed JSON object | Toujours un objet ; un JSON invalide lève une erreur | Topics que vous maîtrisez et qui transportent toujours du JSON |
| a UTF-8 string | Chaîne | Texte brut, CSV, payloads que vous analysez vous-même |
| a Buffer | Buffer Node.js | Formats binaires comme Protobuf |
| a Base64 encoded string | Texte Base64 | Faire transiter du binaire par des systèmes texte uniquement |
Pour les topics où chaque éditeur envoie du JSON, « a parsed JSON object » est le choix le plus propre. Vous obtenez directement un objet et une erreur visible lorsqu'un équipement se comporte mal. L'auto-détection est pratique quand vous vous abonnez avec un wildcard large et que certains topics transportent des valeurs simples comme ON ou 21.5, mais les nœuds en aval doivent alors gérer l'un ou l'autre type.
L'auto-détection fonctionne en tentant d'analyser le payload : s'il s'agit de JSON valide, vous obtenez un objet, sinon une chaîne, ou un Buffer lorsque les octets ne forment pas un texte valide. C'est pratique, mais moins strict que l'option parsed JSON.
Option 2 : utiliser le nœud JSON de Node-RED
Le nœud JSON se place n'importe où dans un flow et convertit la propriété de votre choix. Son réglage Action propose trois modes :
- Convert between JSON String and Object : une chaîne devient un objet, un objet devient une chaîne. C'est le mode par défaut, pratique dans les deux sens.
- Always convert to JavaScript Object : les chaînes sont analysées ; les objets passent sans modification.
- Always convert to JSON String : les objets sont sérialisés ; les chaînes passent sans modification. Cochez Format JSON string pour une sortie indentée et lisible.
Vous pouvez aussi remplacer la Property payload par une autre, comme payload.data, lorsqu'un document JSON est imbriqué sous forme de chaîne dans un autre document. Ce cas se présente avec les passerelles qui enveloppent les messages des équipements.
Utilisez le nœud JSON plutôt que le réglage du nœud mqtt in lorsque :
- Vous vous abonnez une seule fois avec un wildcard, mais seules certaines branches transportent du JSON. Aiguillez d'abord avec un nœud switch Node-RED, puis analysez uniquement la branche JSON.
- Vous avez besoin d'une validation par schéma (voir ci-dessous).
- Le JSON est imbriqué dans une autre propriété.
- Vous recevez du JSON d'une autre source que MQTT, comme une requête HTTP ou un fichier.
Essayez sur le broker public
Le serveur MQTT public gratuit broker.connectmq.com permet de tester rapidement chaque réglage sans rien installer ; il est réservé aux tests et aux prototypes, pas aux données de production. Publiez un payload valide et un payload invalide depuis un terminal, en remplaçant b52e par votre propre chaîne aléatoire :
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-json-b52e \
-t "connectmq/demo/b52e/room1/env" -m '{"temp": 22.4, "hum": 41}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-json-b52e \
-t "connectmq/demo/b52e/room1/env" -m '{temp: 22.4}'
Importez ensuite ce flow. Il s'abonne en chaîne UTF-8 et analyse avec un nœud JSON, ce qui vous permet de voir à la fois le chemin de réussite et le chemin d'erreur.
[
{"id":"tab1","type":"tab","label":"JSON demo"},
{"id":"brk","type":"mqtt-broker","name":"ConnectMQ public","broker":"broker.connectmq.com","port":"1883","clientid":"nr-json-b52e","autoConnect":true,"usetls":false,"protocolVersion":"4","keepalive":"60","cleansession":true},
{"id":"in","type":"mqtt in","z":"tab1","name":"env","topic":"connectmq/demo/b52e/+/env","qos":"0","datatype":"utf8","broker":"brk","x":110,"y":100,"wires":[["json"]]},
{"id":"json","type":"json","z":"tab1","name":"parse","property":"payload","action":"obj","pretty":false,"x":270,"y":100,"wires":[["ok"]]},
{"id":"ok","type":"debug","z":"tab1","name":"parsed","active":true,"complete":"payload","x":430,"y":100,"wires":[]},
{"id":"catch","type":"catch","z":"tab1","name":"","scope":["json"],"uncaught":false,"x":110,"y":180,"wires":[["bad"]]},
{"id":"bad","type":"debug","z":"tab1","name":"parse errors","active":true,"complete":"true","x":290,"y":180,"wires":[]}
]
Le premier message apparaît dans la sortie debug « parsed » sous forme d'objet dépliable. Le second déclenche le nœud Catch, et le message complet, y compris msg.error.message, apparaît sous « parse errors ». En production, reliez cette sortie catch à un compteur ou à un topic d'alerte plutôt qu'à un nœud debug, pour savoir quand une mise à jour de firmware commence à envoyer du JSON cassé.
Valider les payloads avec JSON Schema
Un JSON valide n'est pas forcément un JSON correct. Un équipement peut envoyer "temp": "22.4" sous forme de chaîne, ou omettre un champ après une mise à jour de firmware. Le nœud JSON peut vérifier les payloads par rapport à un JSON Schema : définissez msg.schema avec un objet schéma avant le nœud, et les messages invalides lèvent une erreur avec les détails de validation dans msg.schemaError.
Définissez le schéma avec un nœud Change ou une petite fonction :
msg.schema = {
type: "object",
required: ["temp", "hum"],
properties: {
temp: { type: "number", minimum: -40, maximum: 125 },
hum: { type: "number", minimum: 0, maximum: 100 }
},
additionalProperties: true
};
return msg;
Placez-la avant le nœud JSON et conservez le nœud Catch de la démo. Les messages qui échouent à la validation partent sur le chemin d'erreur avec une raison lisible, ce qui est bien plus simple à déboguer que de traquer des valeurs NaN dans un tableau de bord. Notez que le schéma est vérifié côté objet : il fonctionne donc aussi bien lors de l'analyse d'une chaîne que lorsque le payload est déjà un objet.
Republier du JSON sur MQTT
Le nœud mqtt out sérialise automatiquement les objets : si msg.payload est un objet, il est envoyé sous forme de chaîne JSON. Dans la plupart des flows, vous n'avez pas besoin d'un nœud JSON avant de publier. Ajoutez-en un avec Always convert to JSON String uniquement si vous devez sérialiser une propriété précise ou souhaitez une sortie formatée pour des lecteurs humains.
Un point subtil : si vous publiez directement un nombre comme 21.5, le nœud envoie le texte 21.5. Les abonnés en auto-détection y verront du JSON valide et obtiendront un nombre, tandis que les abonnés réglés en UTF-8 verront une chaîne. Choisissez une convention par topic et documentez-la.
Dépanner les erreurs JSON dans Node-RED
| Symptôme | Cause probable | Solution |
|---|---|---|
Unexpected token o in JSON at position 1 |
Le payload est déjà un objet et il est analysé une seconde fois | Supprimez le nœud JSON superflu ou réglez la sortie de mqtt in en chaîne |
msg.payload.temp vaut undefined |
Le payload est encore une chaîne | Réglez mqtt in en parsed JSON ou ajoutez un nœud JSON |
Unexpected token } in JSON |
Virgule finale ou clés sans guillemets dans le firmware | Corrigez l'éditeur ; JSON exige des clés entre guillemets et aucune virgule finale |
| Le debug affiche un Buffer | Sortie réglée sur Buffer, ou payload binaire en auto-détection | Utilisez la sortie chaîne UTF-8 ou parsed JSON |
| Les nombres arrivent sous forme de chaînes | L'éditeur met les valeurs entre guillemets | Validez avec un schéma et corrigez le firmware, ou convertissez avec un nœud Change |
| Caractères étranges en début de payload | Marque d'ordre des octets UTF-8 ajoutée par certains outils | Supprimez-la avec un nœud function ou corrigez l'éditeur |
La plupart de ces erreurs viennent d'une double analyse ou d'une absence d'analyse. Ajoutez un nœud debug réglé sur « complete msg object » juste après mqtt in ; la barre latérale indique si payload est une chaîne, un objet ou un Buffer.
Check-list des bonnes pratiques
- Choisissez un seul point d'analyse par flow, soit le nœud mqtt in, soit un nœud JSON, jamais les deux.
- Utilisez « a parsed JSON object » pour les topics que vous maîtrisez, et l'auto-détection uniquement pour les wildcards mixtes.
- Validez les payloads critiques avec un schéma et faites passer les échecs par un nœud Catch.
- Gardez des payloads petits et plats autant que possible ; les enveloppes imbriquées compliquent la vie de chaque consommateur.
- Placez l'identité de l'équipement dans le topic, pas seulement dans le payload. Notre guide du nœud function Node-RED montre comment découper le topic en champs.
- Documentez le format du payload de chaque topic à côté de votre plan de nommage des topics.
Pour une prise en main complète, le tutoriel Node-RED MQTT couvre la configuration du broker, les tableaux de bord et les alertes dans un seul flow. Le guide officiel working with messages sur nodered.org détaille la structure des messages et le nœud JSON.
Passez vos flows JSON sur ConnectMQ
Le broker public est partagé et lisible par tous : les vraies données de vos équipements ont leur place sur un broker privé. ConnectMQ est un broker MQTT managé avec TLS sur le port 8883 et un explorateur de topics dans le portail, où vous pouvez inspecter le JSON exact publié par chaque équipement avant qu'il n'atteigne Node-RED. Inscrivez-vous sur app.connectmq.com pour l'offre gratuite Serverless, sans carte bancaire, puis collez les identifiants générés dans votre nœud broker et activez TLS. L'offre gratuite accepte des messages jusqu'à 256 Ko, ce qui suffit largement pour une télémétrie JSON classique.
Questions fréquentes
Ai-je besoin d'un nœud JSON après le nœud mqtt in ?
Non, si la sortie du nœud mqtt in est réglée sur « a parsed JSON object » ou sur l'auto-détection et que le payload est du JSON valide. Ajouter en plus un nœud JSON peut provoquer des erreurs de double analyse.
Comment convertir un objet en chaîne JSON dans Node-RED ?
Utilisez le nœud JSON avec l'action « Always convert to JSON String », éventuellement avec Format JSON string pour une sortie lisible. Le nœud mqtt out sérialise lui aussi automatiquement les objets.
Le nœud JSON peut-il valider les types de données ?
Oui. Définissez msg.schema avec un JSON Schema avant le nœud ; les messages non conformes lèvent une erreur que vous pouvez traiter avec un nœud Catch, avec les détails dans msg.schemaError.
Pourquoi l'auto-détection me donne-t-elle parfois un nombre au lieu d'un objet ?
Un payload comme 42 ou true est du JSON valide, donc l'auto-détection le convertit en nombre ou en booléen. Si vous attendez toujours un objet, vérifiez le type dans un nœud Switch ou utilisez un schéma.
