Node-RED MQTT: conectar, assinar e publicar

Node-RED e MQTT formam uma dupla natural: o MQTT move mensagens entre dispositivos, e o Node-RED permite ligar essas mensagens a dashboards, bancos de dados, alertas e APIs sem escrever uma aplicação completa. O Node-RED já vem com dois nós MQTT — mqtt in e mqtt out — além de um nó de configuração do broker compartilhado. Este tutorial cobre os três e termina com um fluxo que você pode importar.

Rodar o Node-RED

Se você ainda não tem o Node-RED, as opções mais rápidas são npm ou 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

Abra http://localhost:1880 no navegador. O Node-RED é só o lado cliente — você ainda precisa de um broker. Para desenvolvimento local, rode o Mosquitto no Docker ao lado dele; para um teste rápido, o broker público da HiveMQ funciona sem nenhuma configuração.

Configurar o nó do broker MQTT

Arraste um nó mqtt in para o canvas, dê um duplo clique nele e clique no ícone de lápis ao lado de Server para criar uma configuração de broker. Todos os nós MQTT que usam o mesmo nó de configuração compartilham uma única conexão.

A mensagem Will na aba Messages é o Last Will do MQTT — veja Last Will and Testament. Um rótulo verde connected abaixo de cada nó MQTT depois do deploy significa que o broker aceitou a conexão. Não sabe qual porta o seu broker usa? Confira portas MQTT explicadas.

Assinar com o nó mqtt in

Defina em Topic o tópico a assinar — curingas são permitidos, então testmqtt/nodered-demo/+/telemetry recebe a telemetria de todos os cômodos. Cada mensagem recebida se torna um msg do Node-RED com:

• msg.payload — o corpo da mensagem
• msg.topic — o tópico concreto em que ela chegou
• msg.qos e msg.retain — detalhes de entrega

Teste seus filtros de tópico com o testador de tópicos MQTT antes do deploy. A opção Output define o tipo de msg.payload:

• auto-detect (string or buffer) — texto vira string, dados binários continuam como Buffer.
• a parsed JSON object — o nó roda JSON.parse para você, então msg.payload.temp pode ser usado diretamente. JSON inválido gera um erro que você pode capturar com um nó catch.
• auto-detect (parsed JSON object, string or buffer) — interpreta o JSON quando possível e, se não der, usa string.

Se preferir, mantenha a saída padrão e adicione um nó json depois do mqtt in; ele converte uma string JSON em objeto e vice-versa.

Assinaturas dinâmicas

Definir o tipo de tópico do nó mqtt in como Dynamic subscription dá a ele uma entrada. Envie uma mensagem com msg.action igual a subscribe (e o tópico em msg.topic), unsubscribe, connect ou disconnect para controlá-lo em tempo de execução — útil quando a lista de dispositivos muda.

Publicar com o nó mqtt out

O nó mqtt out publica msg.payload. Se o payload for um objeto, ele é convertido automaticamente em uma string JSON. Seus campos funcionam como valores de fallback:

• Topic — deixe vazio para usar msg.topic. É assim que você publica em tópicos dinâmicos, como um tópico por dispositivo.
• QoS e Retain — deixe vazios para usar msg.qos e msg.retain da mensagem.

Um nó function é a forma mais simples de montar o tópico por mensagem:

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;

Status retido e mensagens de birth

O nó de configuração do broker pode publicar uma mensagem Birth ao conectar, uma mensagem Close antes de um disconnect limpo e uma mensagem Will se a conexão cair. Apontar as três para um mesmo tópico retido, como nodered/status com online e offline, dá a outros sistemas uma forma confiável de saber se a sua instância do Node-RED está no ar. Mensagens retidas são explicadas em mensagens retidas (retained) no MQTT.

Com o protocolo definido como MQTT V5, os nós exibem opções extras como expiração de mensagem, content type, user properties e as flags de assinatura No Local, Retain As Published e Retain Handling.

Fluxo de exemplo para importar

Este fluxo publica uma leitura de temperatura aleatória a cada 10 segundos em testmqtt/nodered-demo/room1/telemetry, assina todos os cômodos com interpretação de JSON ativada e registra as leituras acima de 24 °C na barra lateral de debug. Copie-o, abra o menu, escolha Import, cole e faça o 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": []
  }
]

Acompanhe as mesmas mensagens de fora do Node-RED para confirmar que elas realmente chegam ao broker:

Veja suas mensagens do Node-RED ao vivo

Solução de problemas

• Preso em connecting — porta ou configuração de TLS errada, ou o campo Server contém mqtt://. Informe apenas o nome do host.
• Conecta e desconecta em loop — outro cliente usa o mesmo client ID, muitas vezes uma segunda instância do Node-RED com um fluxo copiado. Limpe o campo.
• Nenhuma mensagem chega — o tópico da assinatura não corresponde ao tópico de publicação (maiúsculas e minúsculas importam), ou uma ACL no broker o bloqueia. Mais no guia de erros de conexão MQTT.

Vai tirar a lógica do Node-RED e passá-la para um script mais tarde? O gerador de código MQTT gera código cliente para as configurações do seu broker em Python, JavaScript e outras linguagens, e o cliente MQTT online é prático para inspecionar tópicos enquanto você monta os fluxos.

Perguntas frequentes