Node-RED y MQTT: conectar, suscribirse y publicar

Node-RED y MQTT forman una pareja natural: MQTT mueve mensajes entre dispositivos, y Node-RED te permite conectar esos mensajes con dashboards, bases de datos, alertas y APIs sin escribir una aplicación completa. Node-RED trae de serie dos nodos MQTT — mqtt in y mqtt out — más un nodo de configuración del broker compartido. Este tutorial cubre los tres y termina con un flow que puedes importar.

Ejecutar Node-RED

Si todavía no tienes Node-RED, las opciones más rápidas son npm o Docker:

# with Node.js installed
npm install -g --unsafe-perm node-red
node-red

# or with Docker
docker run -it -p 1880:1880 -v node_red_data:/data --name nodered nodered/node-red

Abre http://localhost:1880 en tu navegador. Node-RED es solo la parte cliente — sigues necesitando un broker. Para desarrollo local, ejecuta Mosquitto en Docker a su lado; para una prueba rápida, el broker público de HiveMQ funciona sin configurar nada.

Configurar el nodo del broker MQTT

Arrastra un nodo mqtt in al lienzo, haz doble clic en él y pulsa el icono del lápiz junto a Server para crear una configuración de broker. Todos los nodos MQTT que usan el mismo nodo de configuración comparten una única conexión.

El mensaje Will de la pestaña Messages es el Last Will de MQTT — consulta Last Will and Testament. Una etiqueta verde connected bajo cada nodo MQTT tras hacer deploy significa que el broker aceptó la conexión. ¿No sabes qué puerto usa tu broker? Consulta los puertos MQTT explicados.

Suscribirse con el nodo mqtt in

Define en Topic el topic al que suscribirte — se permiten comodines, así que testmqtt/nodered-demo/+/telemetry recibe la telemetría de todas las habitaciones. Cada mensaje entrante se convierte en un msg de Node-RED con:

• msg.payload — el cuerpo del mensaje
• msg.topic — el topic concreto por el que llegó
• msg.qos y msg.retain — detalles de entrega

Prueba tus filtros de topic con el probador de topics MQTT antes de hacer deploy. La opción Output decide el tipo de msg.payload:

• auto-detect (string or buffer) — el texto se convierte en string y los datos binarios siguen siendo un Buffer.
• a parsed JSON object — el nodo ejecuta JSON.parse por ti, así que msg.payload.temp se puede usar directamente. Un JSON no válido produce un error que puedes capturar con un nodo catch.
• auto-detect (parsed JSON object, string or buffer) — parsea JSON cuando puede y, si no, recurre a un string.

Si lo prefieres, deja la salida por defecto y añade un nodo json después de mqtt in; convierte un string JSON en un objeto y viceversa.

Suscripciones dinámicas

Si pones el tipo de topic del nodo mqtt in en Dynamic subscription, el nodo obtiene una entrada. Envíale un mensaje con msg.action igual a subscribe (y el topic en msg.topic), unsubscribe, connect o disconnect para controlarlo en tiempo de ejecución — útil cuando la lista de dispositivos cambia.

Publicar con el nodo mqtt out

El nodo mqtt out publica msg.payload. Si el payload es un objeto, se convierte automáticamente en un string JSON. Sus campos funcionan como valores de reserva:

• Topic — déjalo vacío para usar msg.topic. Así es como se publica en topics dinámicos, como un topic por dispositivo.
• QoS y Retain — déjalos vacíos para tomar msg.qos y msg.retain del mensaje.

Un nodo function es la forma más sencilla de construir el topic para cada mensaje:

const room = msg.payload.room || 'unknown';
msg.topic = 'testmqtt/nodered-demo/' + room + '/telemetry';
msg.payload = { temp: msg.payload.temp, ts: Date.now() };
msg.qos = 1;
return msg;

Estado retenido y mensajes de nacimiento

El nodo de configuración del broker puede publicar un mensaje Birth al conectarse, un mensaje Close antes de una desconexión limpia y un mensaje Will si la conexión se cae. Si apuntas los tres a un mismo topic retenido, como nodered/status con online y offline, otros sistemas tendrán una forma fiable de saber si tu instancia de Node-RED está en marcha. Los mensajes retenidos se explican en mensajes retenidos de MQTT.

Con el protocolo en MQTT V5, los nodos exponen opciones adicionales como la caducidad de mensajes, el content type, las propiedades de usuario y los flags de suscripción No Local, Retain As Published y Retain Handling.

Flow de ejemplo para importar

Este flow publica una lectura de temperatura aleatoria cada 10 segundos en testmqtt/nodered-demo/room1/telemetry, se suscribe a todas las habitaciones con el parseo de JSON activado y registra en la barra lateral de depuración las lecturas por encima de 24 °C. Cópialo, abre el menú, elige Import, pégalo y haz deploy.

[
  {
    "id": "b1a1c0de00000001",
    "type": "mqtt-broker",
    "name": "HiveMQ public",
    "broker": "broker.hivemq.com",
    "port": "1883",
    "clientid": "",
    "autoConnect": true,
    "usetls": false,
    "protocolVersion": "4",
    "keepalive": "60",
    "cleansession": true
  },
  {
    "id": "b1a1c0de00000002",
    "type": "inject",
    "name": "every 10 s",
    "props": [{ "p": "payload" }],
    "repeat": "10",
    "once": true,
    "onceDelay": "1",
    "payload": "",
    "payloadType": "date",
    "x": 130,
    "y": 80,
    "wires": [["b1a1c0de00000003"]]
  },
  {
    "id": "b1a1c0de00000003",
    "type": "function",
    "name": "build reading",
    "func": "msg.topic = 'testmqtt/nodered-demo/' + 'room1' + '/telemetry';\nmsg.payload = { temp: +(18 + Math.random() * 8).toFixed(1), ts: msg.payload };\nreturn msg;",
    "outputs": 1,
    "x": 320,
    "y": 80,
    "wires": [["b1a1c0de00000004"]]
  },
  {
    "id": "b1a1c0de00000004",
    "type": "mqtt out",
    "name": "publish",
    "topic": "",
    "qos": "1",
    "retain": "false",
    "broker": "b1a1c0de00000001",
    "x": 510,
    "y": 80,
    "wires": []
  },
  {
    "id": "b1a1c0de00000005",
    "type": "mqtt in",
    "name": "subscribe",
    "topic": "testmqtt/nodered-demo/+/telemetry",
    "qos": "1",
    "datatype": "json",
    "broker": "b1a1c0de00000001",
    "nl": false,
    "rap": true,
    "rh": 0,
    "inputs": 0,
    "x": 140,
    "y": 160,
    "wires": [["b1a1c0de00000006"]]
  },
  {
    "id": "b1a1c0de00000006",
    "type": "switch",
    "name": "temp > 24",
    "property": "payload.temp",
    "propertyType": "msg",
    "rules": [{ "t": "gt", "v": "24", "vt": "num" }],
    "checkall": "true",
    "outputs": 1,
    "x": 330,
    "y": 160,
    "wires": [["b1a1c0de00000007"]]
  },
  {
    "id": "b1a1c0de00000007",
    "type": "debug",
    "name": "too warm",
    "active": true,
    "tosidebar": true,
    "complete": "true",
    "x": 510,
    "y": 160,
    "wires": []
  }
]

Observa los mismos mensajes desde fuera de Node-RED para confirmar que llegan de verdad al broker:

Mira tus mensajes de Node-RED en directo

Solución de problemas

• Se queda en connecting — puerto o ajuste de TLS incorrectos, o el campo Server contiene mqtt://. Introduce solo el nombre de host.
• Se conecta y se desconecta en bucle — otro cliente usa el mismo client ID, a menudo una segunda instancia de Node-RED con un flow copiado. Vacía el campo.
• No llegan mensajes — el topic de suscripción no coincide con el de publicación (las mayúsculas importan), o una ACL del broker lo deniega. Más información en la guía de errores de conexión MQTT.

¿Vas a sacar más adelante la lógica de Node-RED a un script? El generador de código MQTT genera código cliente para la configuración de tu broker en Python, JavaScript y más, y el cliente MQTT online es práctico para curiosear en los topics mientras construyes flows.

Preguntas frecuentes