Tutorial de Node-RED y MQTT: flujos, dashboards y automatización

Este tutorial de Node-RED y MQTT te muestra cómo conectar Node-RED a un broker, recibir y publicar mensajes, convertir JSON en bruto en un dashboard en vivo y lanzar alertas cuando los valores superan un umbral. Empezarás en el servidor MQTT público gratuito broker.connectmq.com con un flujo importable y después pasarás ese mismo flujo a un broker privado cifrado con TLS cambiando un único nodo de configuración. Todo funciona en un portátil, una Raspberry Pi o un contenedor Docker.

Por qué Node-RED y MQTT encajan

Node-RED es una herramienta de programación basada en flujos: conectas nodos en un editor del navegador y cada mensaje viaja por los cables como un objeto JavaScript llamado msg. MQTT es un protocolo de publicación/suscripción en el que los clientes intercambian mensajes a través de un broker usando topics. Ambos comparten el mismo modelo mental. Un nodo mqtt in es un suscriptor que inyecta mensajes en un flujo, y un nodo mqtt out es un publicador que envía lo que le llega.

Eso convierte a Node-RED en una capa de unión natural alrededor de un sistema MQTT. Las tareas típicas incluyen:

• Traducir entre dispositivos que usan formatos de payload distintos.
• Construir dashboards rápidos para operarios sin un proyecto de front-end.
• Vigilar umbrales y enviar notificaciones por correo o chat.
• Escribir telemetría en una base de datos de series temporales.
• Hacer de puente entre protocolos como Modbus, OPC UA o HTTP y los topics MQTT.

Si antes necesitas repasar brokers, topics y comodines, lee qué hace un broker MQTT. El resto de esta guía da por sabido que + coincide con un nivel de topic y # con todo lo que hay por debajo de un nivel.

Instala Node-RED

Elige la instalación que mejor se adapte a tu máquina. Cualquier versión actual de Node-RED 4.x incluye los nodos MQTT; no necesitas paquetes adicionales para este tutorial hasta el paso del dashboard.

# Opción 1: npm (requiere Node.js 18 o superior)
sudo npm install -g --unsafe-perm node-red
node-red

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

# Opción 3: Raspberry Pi OS / Debian, script de instalación oficial
bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-node-red)

Abre http://localhost:1880 (o la dirección de la Pi) en un navegador. Para configurarlo como servicio, actualizarlo y los detalles de Windows, consulta nuestra guía paso a paso para instalar Node-RED, y si prefieres contenedores, ejecutar Node-RED en Docker trata los volúmenes y las políticas de reinicio. La documentación oficial de Node-RED es la referencia de todos los nodos principales.

Paso 1: configura el nodo del broker MQTT

Todos los nodos MQTT de Node-RED apuntan a un nodo de configuración compartido de tipo mqtt-broker. Configúralo una vez y reutilízalo en todos los flujos; Node-RED mantiene así una única conexión con el broker, algo importante en brokers que limitan las conexiones por cuenta.

Arrastra un nodo mqtt in al lienzo, haz doble clic en él y pulsa el lápiz junto a Server para añadir un broker nuevo:

En la pestaña Messages, configura un mensaje de nacimiento (connectmq/demo/nr-7f3a/status, payload online, retenido, QoS 1) y un mensaje de will en el mismo topic con offline. Así, otros clientes pueden ver si tu instancia de Node-RED está viva.

¿Por qué rellenar tú mismo el client ID? Si lo dejas vacío, Node-RED genera uno, lo cual está bien en un broker de pruebas. En un broker de producción que vincula los client IDs a las credenciales, debes introducir exactamente el ID que se te emitió. Dos instancias de Node-RED (por ejemplo, tu portátil y tu Pi) con el mismo client ID se desconectarán mutuamente una y otra vez.

Paso 2: importa un flujo funcional

La forma más rápida de aprender es importar un flujo completo y desmontarlo. En el editor, abre el menú, elige Import, pega el JSON siguiente y pulsa Import. Antes, cambia cada nr-7f3a por tu propio sufijo aleatorio para no compartir topics con otros lectores de este tutorial de Node-RED y 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": []
  }
]

Pulsa Deploy. En pocos segundos, el pequeño indicador de estado bajo cada nodo MQTT se pone verde con la palabra "connected", y la barra lateral de depuración empieza a mostrar objetos de telemetría. Comprueba desde un terminal que los mensajes pasan de verdad por el broker:

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

Deberías ver primero el mensaje retenido status, después un mensaje de telemetría cada cinco segundos y, cada vez que la temperatura simulada cruce los 30, una alerta.

Paso 3: entiende los nodos mqtt in y mqtt out

El flujo importado usa cada nodo MQTT de una forma concreta, y estos son los ajustes que más a menudo cambiarás.

El nodo mqtt in

• Topic acepta comodines. connectmq/demo/nr-7f3a/+/+/telemetry recibe la telemetría de todos los sensores de todas las líneas bajo tu prefijo, y msg.topic te dice cuál la envió.
• Output en auto-detect convierte los payloads JSON en objetos, deja el texto plano como cadena y pasa los datos binarios como Buffer. Si un dispositivo envía a veces JSON mal formado, elige a String y procésalo tú mismo con un nodo JSON para poder capturar los errores.
• QoS es la QoS máxima que quieres recibir. El broker entrega con la menor entre la QoS del publicador y la del suscriptor.
• Suscripción dinámica: configura el nodo para que acepte entradas y envíale msg.action = "subscribe" con msg.topic. Así un flujo puede seguir topics que solo se conocen en tiempo de ejecución; la guía de suscripciones MQTT dinámicas en Node-RED incluye un ejemplo completo.

El nodo mqtt out

• Si el campo Topic del nodo está vacío, publica en msg.topic. La rama de alertas se basa en esto: el nodo function reescribe el topic de .../telemetry a .../alert.
• Si el campo Topic está relleno, sustituye a msg.topic. Un error típico de principiante es configurar ambos y preguntarse por qué los mensajes acaban en el topic equivocado.
• Los objetos en msg.payload se serializan a JSON automáticamente. Los números y los booleanos se convierten en cadenas.
• Retain en los topics de alerta y de estado hace que cualquier cliente que se suscriba más tarde vea de inmediato el último valor. Déjalo desactivado para la telemetría de alta frecuencia.

Para un manejo más profundo de JSON, incluida la conversión de cadenas a objetos y viceversa, consulta el nodo JSON de Node-RED. Para escribir lógica como la función de alerta, lee el nodo function de Node-RED, que trata el almacenamiento en contexto, las salidas múltiples y la gestión de errores.

Paso 4: crea un dashboard de Node-RED con MQTT

La salida de depuración en bruto no es algo que puedas entregar a un operario. Dashboard 2.0 es el dashboard actual y mantenido activamente para Node-RED. Instálalo desde Manage palette buscando @flowfuse/node-red-dashboard, o desde la línea de comandos:

cd ~/.node-red
npm install @flowfuse/node-red-dashboard
# reinicia Node-RED después

Después amplía tu flujo:

1. Añade un nodo function después del nodo mqtt in all sensors con el código siguiente. Divide cada objeto de telemetría en mensajes aptos para gráficos.
2. Conecta su primera salida a un ui-gauge (rango de 0 a 50, etiqueta "Temperature") y también a un ui-chart (tipo línea, eje X temporal).
3. Conecta la segunda salida a un segundo ui-gauge para la humedad.
4. Al añadir el primer widget, Node-RED te pide crear una página y un grupo; acepta los valores por defecto.
5. Despliega y abre http://localhost:1880/dashboard.

// Divide la telemetría en un mensaje por métrica para indicadores y gráficos
const sensor = msg.topic.split("/").slice(-2, -1)[0]; // p. ej. "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) }
];

Configura este nodo function con dos salidas en su pestaña Setup. Usar el nombre del sensor en msg.topic hace que un único gráfico dibuje automáticamente una línea por sensor cuando añadas más dispositivos.

Para controlar un dispositivo desde el dashboard, añade un ui-switch cuyos payloads de encendido y apagado sean ON y OFF, y conéctalo a un nodo mqtt out con un topic como connectmq/demo/nr-7f3a/line1/fan1/set y QoS 1. La buena práctica es que el estado que muestra el interruptor proceda del topic de estado del propio dispositivo y no del clic, para que el dashboard nunca muestre un estado que el hardware no ha alcanzado. Los diseños, los temas y los dashboards de varias páginas se tratan en nuestra guía de Node-RED Dashboard 2.0, y la conservación de un histórico largo es el tema de Node-RED con InfluxDB.

Paso 5: alertas y automatización

La función alert on crossing 30 C del flujo importado está escrita a propósito como un detector de flancos. Guarda el estado anterior por topic en el contexto del nodo y solo emite un mensaje cuando el estado cambia. Sin eso, un sensor que se mantenga a 31 grados lanzaría una alerta cada cinco segundos e inundaría tu bandeja de entrada.

Desde el topic de alerta puedes distribuir a cualquier canal de notificación:

• Correo electrónico con el nodo node-red-node-email; consulta enviar alertas por correo desde Node-RED.
• Telegram para notificaciones instantáneas en el móvil con un bot; consulta alertas de Node-RED por Telegram.
• Otro topic MQTT que consuma una sirena, una baliza luminosa u otro sistema.

Como la propia alerta se publica de nuevo en MQTT como mensaje retenido, Node-RED no es el único consumidor. Cualquier dashboard, app móvil o script suscrito a +/alert ve el mismo evento, lo que mantiene tu lógica de automatización en un solo lugar y tus canales de notificación desacoplados.

Un patrón útil para instalaciones más grandes es una estructura jerárquica de topics como site/area/line/cell/device/metric, inspirada en ISA-95. Permite que una única suscripción con comodín en Node-RED abarque toda una línea o toda la planta, y es la base del enfoque Unified Namespace descrito en MQTT, Sparkplug B y el Unified Namespace.

Paso 6: pasa a un broker privado con TLS

El servidor público es compartido y cualquiera puede leerlo, así que solo sirve para pruebas. Para flujos reales, usa tu propio broker con cifrado y credenciales. Puedes operar uno tú mismo, pero un broker MQTT gestionado quita de tu lista de tareas los parches, los certificados y la disponibilidad. Con ConnectMQ, te registras, eliges un plan, creas un broker y copias del portal el nombre de usuario, la contraseña y el client ID generados.

Abre el nodo de configuración ConnectMQ public y cámbialo:

El broker usa un certificado de Let's Encrypt de confianza pública, así que Node-RED lo valida con su almacén de CA integrado y no tienes que subir ningún archivo de CA. Las credenciales se guardan en el archivo de credenciales cifrado de Node-RED, no en el JSON del flujo, y por eso los flujos exportados nunca contienen contraseñas. Define un credentialSecret en settings.js para que ese archivo siga siendo legible cuando traslades Node-RED a otra máquina.

Los detalles sobre certificados de cliente, CA personalizadas y errores habituales del handshake están en Node-RED MQTT sobre TLS. Protege también el propio editor: un editor de Node-RED expuesto sin inicio de sesión equivale a ejecución remota de código en tu servidor. Proteger Node-RED explica adminAuth, HTTPS y la exposición en red.

Resolución de problemas del tutorial de Node-RED y MQTT

Cuando un nodo muestra "disconnected" o "connecting" indefinidamente, repasa esta lista:

1. Errata en el nombre de host o prefijo de protocolo. El campo Server admite broker.connectmq.com, no mqtt://broker.connectmq.com.
2. Puerto incorrecto para TLS. El puerto 1883 es TCP sin cifrar; el 8883 requiere la casilla Use TLS. Mezclarlos provoca tiempos de espera agotados sin aviso.
3. Client ID duplicado. Otra instancia de Node-RED, un script de prueba o MQTT Explorer con el mismo ID expulsa la conexión cada pocos segundos.
4. Credenciales incorrectas o client ID que no coincide. El log del nodo muestra "Connection refused: Not authorized". Vuelve a copiar los tres valores del portal.
5. Puertos salientes bloqueados. Ejecuta nc -vz broker.connectmq.com 8883 desde el host de Node-RED. Los contenedores Docker también pueden necesitar una configuración DNS correcta.
6. Los mensajes llegan, pero se ven mal. Revisa el ajuste Output del mqtt in; un Buffer en la barra de depuración significa que el nodo está configurado en binario.
7. Límites de frecuencia o tamaño. En el broker público, mantén cada cliente por debajo de 10 mensajes por segundo y 64 KB por mensaje; los nodos inject con intervalos muy cortos los alcanzan enseguida.

Para un diagnóstico a nivel de log de cada uno de estos casos, nuestra guía específica Node-RED MQTT no se conecta repasa los mensajes de error exactos.

Próximos pasos con Node-RED

Cuando domines lo básico, estas guías amplían la misma conexión al broker a proyectos reales:

• Datos industriales: lee registros de PLC con Node-RED y Modbus o decodifica mensajes de nacimiento y de datos con Node-RED y Sparkplug B.
• Diseño limpio de topics: reestructura topics de dispositivos desordenados con el mapeo de topics MQTT en Node-RED.
• Lógica reutilizable: empaqueta nodos repetidos en subflujos de Node-RED.
• Métricas de producción: crea un dashboard de OEE en Node-RED.
• Visualización 3D: alimenta con los mismos topics un gemelo digital 3D de tu planta, sea en Monterrey o en Valencia.

Ejecuta tus flujos de Node-RED sobre ConnectMQ

Node-RED gestiona la lógica; el broker transporta cada mensaje entre tus flujos, dispositivos y dashboards. El plan Serverless gratuito de ConnectMQ no requiere tarjeta de crédito y te ofrece un broker privado con TLS en el puerto 8883, MQTT 5, hasta 25 conexiones y un cliente MQTT en el navegador para inspeccionar los topics mientras construyes. Cuando tus flujos crezcan, el Serverless de pago añade suscripciones compartidas para repartir la carga entre varias instancias de Node-RED, y los planes Dedicated te dan un clúster aislado. Crea tu broker gratuito en app.connectmq.com, pega las credenciales en tu nodo broker y despliega. Para valorar las opciones de alojamiento con más detalle, lee nuestra guía sobre cómo ejecutar un broker MQTT en la nube, o empieza a probar ya mismo en el servidor MQTT público gratuito.

Preguntas frecuentes

¿Node-RED incluye un broker MQTT?

No. Node-RED solo incluye nodos cliente MQTT. Los conectas a un broker externo, como un broker MQTT gestionado o una instancia de Mosquitto que operes tú; existen nodos de broker de la comunidad, pero no se recomiendan para producción.

¿Cuántas conexiones usa Node-RED para MQTT?

Una por cada nodo de configuración mqtt-broker, independientemente de cuántos nodos mqtt in y mqtt out lo compartan. Reutiliza un único nodo de configuración para no superar los límites de conexiones.

¿Por qué mi nodo mqtt in devuelve una cadena en lugar de un objeto?

Probablemente el ajuste Output está en a String, o el payload no es JSON válido. Cámbialo a auto-detect o a parsed JSON object, o añade un nodo JSON para procesarlo explícitamente.

¿Puede Node-RED usar las funciones de MQTT 5?

Sí. Configura el protocolo como MQTT V5 en el nodo broker para usar desde los nodos mqtt in y mqtt out funciones como las user properties, la caducidad de mensajes, los response topics y la caducidad de sesión.

¿Es seguro usar el broker público con Node-RED?

Está bien para aprender y para demos, pero cualquiera puede leer los topics públicos. Usa prefijos de topic únicos, no envíes datos sensibles y pasa a un broker privado con TLS antes de conectar equipos reales.