El nodo JSON de Node-RED convierte entre cadenas JSON y objetos JavaScript, y es la pieza que decide si msg.payload.temp funciona o devuelve undefined. Esta guía muestra cómo llega el JSON por MQTT, cuándo dejar que el nodo mqtt in lo analice por ti, cuándo usar el nodo JSON en su lugar, cómo validar payloads con un esquema y cómo corregir los errores de análisis más comunes.
Por qué hay que analizar los payloads MQTT
MQTT en sí no sabe nada de JSON. Un broker transporta cada payload como bytes en bruto, ya sean un número, una línea CSV, un mensaje Protobuf o un documento JSON. Cuando un sensor de temperatura publica {"temp": 22.4, "hum": 41}, el suscriptor recibe 26 bytes y tiene que decidir qué significan.
Node-RED te ofrece dos lugares para tomar esa decisión: la opción Output del nodo mqtt in y el nodo JSON independiente. Ambos usan el mismo analizador por debajo. La diferencia está en dónde ocurre la conversión y cuánto control conservas. Si quieres repasar cómo enrutan los brokers esos bytes, consulta qué hace un broker MQTT.
Opción 1: deja que el nodo mqtt in analice el JSON
Abre cualquier nodo mqtt in y fíjate en el desplegable Output. Las versiones actuales de Node-RED ofrecen:
| Ajuste de Output | En qué se convierte msg.payload |
Adecuado para |
|---|---|---|
| auto-detect (parsed JSON object, string or buffer) | Objeto si es JSON válido; si no, cadena, o Buffer para binario | Topics mixtos o desconocidos |
| a parsed JSON object | Siempre un objeto; el JSON no válido genera un error | Topics que controlas y que siempre llevan JSON |
| a UTF-8 string | Cadena | Texto plano, CSV, payloads que analizas tú mismo |
| a Buffer | Buffer de Node.js | Formatos binarios como Protobuf |
| a Base64 encoded string | Texto Base64 | Pasar binario a través de sistemas que solo admiten texto |
Para topics en los que todos los publicadores envían JSON, "a parsed JSON object" es la opción más limpia. Obtienes un objeto directamente y un error visible cuando un dispositivo se comporta mal. Auto-detect resulta cómodo cuando te suscribes con un comodín amplio y algunos topics llevan valores simples como ON o 21.5, pero implica que los nodos posteriores deben poder manejar cualquiera de los dos tipos.
Auto-detect funciona intentando analizar el payload: si es JSON válido obtienes un objeto; si no, una cadena, o un Buffer cuando los bytes no son texto válido. Es práctico, pero menos estricto que la opción de JSON analizado.
Opción 2: usa el nodo JSON de Node-RED
El nodo JSON puede colocarse en cualquier punto de un flujo y convierte la propiedad que elijas. Su ajuste Action tiene tres modos:
- Convert between JSON String and Object: una cadena se convierte en objeto y un objeto en cadena. Es el modo predeterminado y resulta útil en ambas direcciones.
- Always convert to JavaScript Object: las cadenas se analizan; los objetos pasan sin cambios.
- Always convert to JSON String: los objetos se serializan; las cadenas pasan sin cambios. Marca Format JSON string para obtener una salida con sangría y legible.
También puedes cambiar la Property de payload a otra, como payload.data, cuando un documento JSON va anidado como cadena dentro de otro documento. Ese patrón aparece con gateways que envuelven los mensajes de los dispositivos en un sobre.
Usa el nodo JSON en lugar del ajuste de mqtt in cuando:
- Te suscribes una vez con un comodín pero solo algunas ramas llevan JSON. Enruta primero con un nodo switch de Node-RED y analiza solo la rama JSON.
- Necesitas validación con esquema (se explica más abajo).
- El JSON va anidado dentro de otra propiedad.
- Recibes JSON de un origen distinto de MQTT, como una petición HTTP o un archivo.
Pruébalo en el servidor público
El servidor MQTT público gratuito en broker.connectmq.com es una forma rápida de probar cada ajuste sin instalar nada. Publica un payload válido y otro no válido desde una terminal, sustituyendo b52e por tu propia cadena aleatoria:
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}'
Después importa este flujo. Se suscribe como cadena UTF-8 y analiza con un nodo JSON, así que puedes ver tanto el camino de éxito como el de error.
[
{"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":[]}
]
El primer mensaje aparece en la salida de depuración "parsed" como un objeto desplegable. El segundo activa el nodo Catch, y el mensaje completo, incluido msg.error.message, aparece en "parse errors". En producción, conecta esa salida de catch a un contador o a un topic de alertas en lugar de a un nodo debug, para saber cuándo una actualización de firmware de un dispositivo empieza a enviar JSON defectuoso.
Valida payloads con JSON Schema
Un JSON válido no es lo mismo que un JSON correcto. Un dispositivo podría enviar "temp": "22.4" como cadena, o dejar de enviar un campo tras un cambio de firmware. El nodo JSON puede comprobar los payloads contra un JSON Schema: asigna a msg.schema un objeto de esquema antes del nodo, y los mensajes no válidos generan un error con los detalles de validación en msg.schemaError.
Define el esquema con un nodo Change o con una pequeña función:
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;
Colócalo antes del nodo JSON y conserva el nodo Catch de la demo. Los mensajes que no superan la validación van al camino de error con un motivo legible, lo que es mucho más fácil de depurar que perseguir valores NaN por un panel. Ten en cuenta que el esquema se comprueba sobre el objeto, así que funciona tanto al analizar una cadena como cuando el payload ya es un objeto.
Publicar JSON de vuelta en MQTT
El nodo mqtt out serializa los objetos automáticamente: si msg.payload es un objeto, se envía como cadena JSON. En la mayoría de los flujos no necesitas un nodo JSON antes de publicar. Añade uno con Always convert to JSON String solo cuando necesites serializar una propiedad concreta o quieras una salida formateada para lectores humanos.
Un detalle sutil: si publicas directamente un número como 21.5, el nodo envía el texto 21.5. Los suscriptores con auto-detect lo verán como JSON válido y te darán un número, mientras que los configurados en UTF-8 verán una cadena. Elige una convención por topic y documéntala.
Solución de errores JSON en Node-RED
| Síntoma | Causa probable | Solución |
|---|---|---|
Unexpected token o in JSON at position 1 |
El payload ya es un objeto y se vuelve a analizar | Elimina el nodo JSON sobrante o configura la salida de mqtt in como cadena |
msg.payload.temp es undefined |
El payload sigue siendo una cadena | Configura mqtt in como JSON analizado o añade un nodo JSON |
Unexpected token } in JSON |
Coma final o claves sin comillas en el firmware del dispositivo | Corrige el publicador; JSON exige claves entre comillas y sin comas finales |
| Debug muestra un Buffer | Output configurado como Buffer, o payload binario con auto-detect | Usa la salida de cadena UTF-8 o de JSON analizado |
| Los números llegan como cadenas | El publicador pone los valores entre comillas | Valida con un esquema y corrige el firmware, o convierte con un nodo Change |
| Caracteres extraños al principio | Marca de orden de bytes (BOM) UTF-8 de algunas herramientas | Elimínala con un nodo function o corrige el publicador |
La mayoría de estos errores vienen de analizar dos veces o de no analizar en absoluto. Añade un nodo debug configurado como "complete msg object" justo después de mqtt in; la barra lateral muestra si payload es una cadena, un objeto o un Buffer.
Lista de buenas prácticas
- Elige un único punto de análisis por flujo, o el nodo mqtt in o un nodo JSON, nunca ambos.
- Usa "a parsed JSON object" para los topics que controlas y auto-detect solo para comodines mixtos.
- Valida los payloads críticos con un esquema y enruta los fallos a través de un nodo Catch.
- Mantén los payloads pequeños y planos siempre que sea posible; los sobres anidados complican a todos los consumidores.
- Pon la identidad del dispositivo en el topic, no solo en el payload. Nuestra guía del nodo function de Node-RED muestra cómo dividir el topic en campos.
- Documenta el formato del payload de cada topic junto con tu plan de nomenclatura de topics.
Para un recorrido completo desde cero, el tutorial de Node-RED MQTT cubre la configuración del broker, los paneles y las alertas en un solo flujo. La guía oficial sobre cómo trabajar con mensajes en nodered.org explica con más profundidad la estructura de los mensajes y el nodo JSON.
Lleva tus flujos JSON a ConnectMQ
El broker público es compartido y cualquiera puede leerlo, así que los datos reales de tus dispositivos deben ir a un broker privado. ConnectMQ es un broker MQTT gestionado con TLS en el puerto 8883 y un explorador de topics en el portal donde puedes inspeccionar el JSON exacto que publica cada dispositivo antes de que llegue a Node-RED. Regístrate en app.connectmq.com para obtener el plan Serverless gratuito, sin tarjeta de crédito, y pega las credenciales generadas en tu nodo broker y activa TLS. El plan gratuito admite mensajes de hasta 256 KB, más que suficiente para la telemetría JSON habitual.
Preguntas frecuentes
¿Necesito un nodo JSON después del nodo mqtt in?
No, si la salida del nodo mqtt in está configurada como "a parsed JSON object" o auto-detect y el payload es JSON válido. Añadir además un nodo JSON puede provocar errores por doble análisis.
¿Cómo convierto un objeto en una cadena JSON en Node-RED?
Usa el nodo JSON con la acción "Always convert to JSON String", opcionalmente con Format JSON string para obtener una salida legible. El nodo mqtt out también serializa los objetos automáticamente.
¿Puede el nodo JSON validar tipos de datos?
Sí. Asigna a msg.schema un JSON Schema antes del nodo, y los mensajes que no coincidan generarán un error que puedes gestionar con un nodo Catch, con los detalles en msg.schemaError.
¿Por qué auto-detect a veces me da un número en lugar de un objeto?
Un payload como 42 o true es JSON válido, así que auto-detect lo convierte en un número o un booleano. Si siempre esperas un objeto, comprueba el tipo en un nodo Switch o usa un esquema.
