Tutorial Node-RED MQTT: Fluxos, Dashboards e Automação

Este tutorial Node-RED MQTT mostra como conectar o Node-RED a um broker, receber e publicar mensagens, transformar JSON bruto em um dashboard ao vivo e disparar alertas quando os valores ultrapassam um limite. Você vai começar no servidor MQTT público gratuito em broker.connectmq.com com um fluxo importável e depois migrar o mesmo fluxo para um broker privado criptografado com TLS alterando um único nó de configuração. Tudo aqui funciona em um notebook, em um Raspberry Pi ou em um contêiner Docker.

Por Que Node-RED e MQTT Combinam

O Node-RED é uma ferramenta de programação baseada em fluxos: você liga nós em um editor no navegador, e cada mensagem percorre os fios como um objeto JavaScript chamado msg. O MQTT é um protocolo publish/subscribe em que os clientes trocam mensagens por meio de um broker usando topics. Os dois compartilham o mesmo modelo mental. Um nó mqtt in é um subscriber que injeta mensagens em um fluxo, e um nó mqtt out é um publisher que envia tudo o que chega até ele.

Isso faz do Node-RED uma camada de integração natural em torno de um sistema MQTT. As tarefas típicas incluem:

• Traduzir entre dispositivos que falam formatos de payload diferentes.
• Construir dashboards rápidos para operadores sem um projeto de front-end.
• Monitorar limites e enviar notificações por e-mail ou chat.
• Gravar telemetria em um banco de dados de séries temporais.
• Fazer a ponte de protocolos como Modbus, OPC UA ou HTTP para topics MQTT.

Se precisar relembrar brokers, topics e wildcards primeiro, leia o que um broker MQTT faz. O restante deste guia pressupõe que você sabe que + corresponde a um nível de topic e # corresponde a tudo abaixo de um nível.

Instale o Node-RED

Escolha a instalação que melhor se adapta à sua máquina. Qualquer versão atual do Node-RED 4.x inclui os nós MQTT; você não precisa de pacotes extras para este tutorial até a etapa do dashboard.

# Opção 1: npm (requer Node.js 18 ou mais recente)
sudo npm install -g --unsafe-perm node-red
node-red

# Opção 2: Docker
docker run -d --name nodered -p 1880:1880 -v node_red_data:/data nodered/node-red:4.0

# Opção 3: Raspberry Pi OS / Debian, script de instalação oficial
bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-node-red)

Abra http://localhost:1880 (ou o endereço do Pi) em um navegador. Para configurar o serviço, fazer atualizações e ver detalhes específicos do Windows, confira nosso guia passo a passo de instalação do Node-RED e, se você prefere contêineres, rodando o Node-RED no Docker aborda volumes e políticas de reinício. A documentação oficial do Node-RED é a referência para todos os nós principais.

Passo 1: Configure o Nó do Broker MQTT

Todo nó MQTT no Node-RED aponta para um nó de configuração compartilhado do tipo mqtt-broker. Configure-o uma vez e reutilize-o em todos os fluxos; assim o Node-RED mantém uma única conexão com o broker, o que importa em brokers que limitam as conexões por conta.

Arraste um nó mqtt in para o canvas, dê um duplo clique nele e clique no lápis ao lado de Server para adicionar um novo broker:

Na aba Messages, defina uma birth message (connectmq/demo/nr-7f3a/status, payload online, retida, QoS 1) e uma will message no mesmo topic com offline. Agora outros clientes conseguem ver se a sua instância do Node-RED está viva.

Por que preencher o client ID você mesmo? Se deixá-lo vazio, o Node-RED gera um, o que não tem problema em um broker de testes. Em um broker de produção que vincula client IDs às credenciais, você precisa informar exatamente o ID que recebeu. Duas instâncias do Node-RED (por exemplo, a do seu notebook e a do seu Pi) com o mesmo client ID vão se desconectar repetidamente.

Passo 2: Importe um Fluxo Funcional

A forma mais rápida de aprender é importar um fluxo completo e desmontá-lo. No editor, abra o menu, escolha Import, cole o JSON abaixo e clique em Import. Antes, troque cada nr-7f3a pelo seu próprio sufixo aleatório para não compartilhar topics com outros leitores deste tutorial Node-RED 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": []
  }
]

Clique em Deploy. Em poucos segundos, o pequeno indicador de status embaixo de cada nó MQTT fica verde com a palavra "connected", e a barra lateral de debug começa a mostrar objetos de telemetria. Confirme a partir de um terminal que as mensagens realmente passam pelo broker:

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

Você deve ver primeiro a mensagem status retida, depois uma mensagem de telemetria a cada cinco segundos e, sempre que a temperatura simulada ultrapassar 30, um alerta.

Passo 3: Entenda os Nós mqtt in e mqtt out

O fluxo importado usa cada nó MQTT de uma forma específica, e estas são as configurações que você mais vai alterar.

O nó mqtt in

• Topic aceita wildcards. connectmq/demo/nr-7f3a/+/+/telemetry recebe a telemetria de todos os sensores de todas as linhas sob o seu prefixo, e msg.topic informa qual deles enviou.
• Output configurado como auto-detect converte payloads JSON em objetos, mantém texto simples como string e repassa dados binários como Buffer. Se um dispositivo às vezes envia JSON malformado, escolha a String e faça o parse você mesmo com um nó JSON, para poder capturar os erros.
• QoS é o QoS máximo que você quer receber. O broker entrega com o menor entre o QoS do publisher e o do subscriber.
• Assinatura dinâmica: configure o nó para aceitar entrada e envie a ele msg.action = "subscribe" com msg.topic. Isso permite que um fluxo acompanhe topics que só são conhecidos em tempo de execução; o guia de assinaturas MQTT dinâmicas no Node-RED traz um exemplo completo.

O nó mqtt out

• Se o campo Topic do nó estiver vazio, ele publica em msg.topic. O ramo de alertas depende disso: o nó function reescreve o topic de .../telemetry para .../alert.
• Se o campo Topic estiver preenchido, ele sobrepõe msg.topic. Um bug frequente de iniciantes é preencher os dois e não entender por que as mensagens caem no topic errado.
• Objetos em msg.payload são serializados para JSON automaticamente. Números e booleanos viram strings.
• Retain em topics de alerta e de estado faz com que qualquer cliente que assine depois veja o valor mais recente imediatamente. Deixe desligado para telemetria de alta frequência.

Para um tratamento de JSON mais aprofundado, incluindo a conversão de strings em objetos e vice-versa, veja o nó JSON do Node-RED. Para escrever lógica como a função de alerta, leia o nó function do Node-RED, que aborda armazenamento em context, múltiplas saídas e tratamento de erros.

Passo 4: Construa um Dashboard Node-RED com MQTT

Uma saída de debug bruta não é algo que se entrega a um operador. O Dashboard 2.0 é o dashboard atual e ativamente mantido do Node-RED. Instale-o em Manage palette, pesquisando por @flowfuse/node-red-dashboard, ou pela linha de comando:

cd ~/.node-red
npm install @flowfuse/node-red-dashboard
# reinicie o Node-RED em seguida

Depois, amplie o seu fluxo:

1. Adicione um nó function depois do nó mqtt in all sensors com o código abaixo. Ele divide cada objeto de telemetria em mensagens adequadas para gráficos.
2. Ligue a primeira saída a um ui-gauge (faixa de 0 a 50, rótulo "Temperature") e também a um ui-chart (tipo linha, eixo X de tempo).
3. Ligue a segunda saída a um segundo ui-gauge para a umidade.
4. Ao adicionar o primeiro widget, o Node-RED pede para você criar uma página e um grupo; aceite os padrões.
5. Faça o deploy e abra http://localhost:1880/dashboard.

// Divide a telemetria em uma mensagem por métrica para gauges e gráficos
const sensor = msg.topic.split("/").slice(-2, -1)[0]; // por exemplo "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) }
];

Configure esse nó function com duas saídas na aba Setup. Usar o nome do sensor em msg.topic faz com que um único gráfico desenhe automaticamente uma linha por sensor quando você adicionar mais dispositivos.

Para controlar um dispositivo a partir do dashboard, adicione um ui-switch cujos payloads de ligado e desligado sejam ON e OFF e ligue-o a um nó mqtt out com um topic como connectmq/demo/nr-7f3a/line1/fan1/set, QoS 1. A boa prática é alimentar o estado exibido pelo switch a partir do topic de estado do próprio dispositivo, e não do clique, para que o dashboard nunca mostre um estado que o hardware não atingiu. Layouts, temas e dashboards de várias páginas são abordados no nosso guia do Node-RED Dashboard 2.0, e manter um histórico longo é o tema de Node-RED com InfluxDB.

Passo 5: Alertas e Automação

A função alert on crossing 30 C do fluxo importado foi escrita deliberadamente como um detector de borda. Ela armazena o estado anterior por topic no context do nó e só emite uma mensagem quando o estado muda. Sem isso, um sensor parado em 31 graus dispararia um alerta a cada cinco segundos e lotaria a sua caixa de entrada.

A partir do topic de alerta, você pode distribuir para qualquer canal de notificação:

• E-mail com o nó node-red-node-email; veja enviando alertas por e-mail a partir do Node-RED.
• Telegram para notificações instantâneas no celular com um bot; veja alertas do Node-RED no Telegram.
• Outro topic MQTT consumido por uma sirene, uma torre de sinalização ou outro sistema.

Como o próprio alerta é publicado de volta no MQTT como mensagem retida, o Node-RED não é o único consumidor. Qualquer dashboard, app móvel ou script que assine +/alert vê o mesmo evento, o que mantém a sua lógica de automação em um só lugar e os canais de notificação desacoplados.

Um padrão útil para instalações maiores, como uma planta em Joinville ou uma estação de saneamento, é uma estrutura de topics hierárquica como site/area/line/cell/device/metric, inspirada na ISA-95. Ela permite que uma única assinatura com wildcard no Node-RED cubra uma linha inteira ou o site inteiro, e é a base da abordagem de Unified Namespace descrita em MQTT, Sparkplug B e o Unified Namespace.

Passo 6: Migre para um Broker Privado com TLS

O servidor MQTT público é compartilhado e pode ser lido por qualquer pessoa, então serve apenas para testes. Para fluxos reais, use o seu próprio broker com criptografia e credenciais. Você pode operar um por conta própria, mas um broker MQTT gerenciado tira patches, certificados e disponibilidade da sua lista de tarefas. Com a ConnectMQ, você se cadastra, escolhe um plano, cria um broker e copia do portal o nome de usuário, a senha e o client ID gerados.

Abra o nó de configuração ConnectMQ public e altere-o:

O broker usa um certificado Let's Encrypt publicamente confiável, então o Node-RED o valida com o seu repositório de CAs integrado e você não precisa enviar nenhum arquivo de CA. As credenciais ficam armazenadas no arquivo de credenciais criptografado do Node-RED, e não no JSON do fluxo, e é por isso que fluxos exportados nunca contêm senhas. Defina um credentialSecret em settings.js para que esse arquivo continue legível depois de mover o Node-RED para outra máquina.

Detalhes como certificados de cliente, CAs personalizadas e erros comuns de handshake estão em Node-RED MQTT sobre TLS. Proteja também o próprio editor: um editor do Node-RED exposto sem login equivale, na prática, a execução remota de código no seu servidor. Protegendo o Node-RED explica adminAuth, HTTPS e exposição de rede.

Solução de Problemas do Tutorial Node-RED MQTT

Quando um nó mostra "disconnected" ou "connecting" indefinidamente, percorra este checklist:

1. Erro de digitação no hostname ou prefixo de protocolo. O campo Server recebe broker.connectmq.com, não mqtt://broker.connectmq.com.
2. Porta errada para TLS. A porta 1883 é TCP simples; a 8883 exige a caixa Use TLS marcada. Misturá-las causa timeouts silenciosos.
3. Client ID duplicado. Outra instância do Node-RED, um script de teste ou o MQTT Explorer usando o mesmo ID derruba a conexão a cada poucos segundos.
4. Credenciais erradas ou client ID que não corresponde. O log do nó mostra "Connection refused: Not authorized". Copie de novo os três valores do portal.
5. Portas de saída bloqueadas. Rode nc -vz broker.connectmq.com 8883 a partir do host do Node-RED. Contêineres Docker também podem precisar de configurações de DNS corretas.
6. As mensagens chegam, mas com aparência errada. Verifique a configuração Output do mqtt in; um Buffer na barra lateral de debug significa que o nó está configurado para binário.
7. Limites de taxa ou de tamanho. No servidor MQTT público, mantenha cada cliente abaixo de 10 mensagens por segundo e 64 KB por mensagem; nós inject configurados com intervalos muito curtos atingem isso rapidamente.

Para diagnosticar cada um desses casos no nível dos logs, nosso guia dedicado Node-RED MQTT não conecta percorre as mensagens de erro exatas.

Próximos Passos com o Node-RED

Quando o básico já estiver familiar, estes guias levam a mesma conexão com o broker para projetos reais:

• Dados industriais: leia registradores de CLP com Node-RED e Modbus ou decodifique mensagens de nascimento e de dados com Node-RED e Sparkplug B.
• Projeto de topics limpo: reestruture topics de dispositivos bagunçados com o mapeamento de topics MQTT no Node-RED.
• Lógica reutilizável: empacote nós repetidos em subflows do Node-RED.
• Métricas de produção: construa um dashboard de OEE no Node-RED.

Rode Seus Fluxos Node-RED na ConnectMQ

O Node-RED cuida da lógica; o broker transporta cada mensagem entre seus fluxos, dispositivos e dashboards. O plano Serverless (Free) da ConnectMQ não exige cartão de crédito e oferece um broker privado com TLS na porta 8883, MQTT 5, até 25 conexões e um cliente MQTT no navegador para inspecionar topics enquanto você constrói. Quando seus fluxos crescerem, o Serverless (Paid) adiciona assinaturas compartilhadas para balancear a carga entre várias instâncias do Node-RED, e os planos Dedicated oferecem um cluster isolado. Crie seu broker gratuito em app.connectmq.com, cole as credenciais no seu nó de broker e faça o deploy. Para avaliar as opções de hospedagem com mais profundidade, leia nosso guia sobre como operar um broker MQTT na nuvem, ou comece a testar agora mesmo, com dados de teste, no servidor MQTT público (gratuito).

Perguntas frequentes

O Node-RED inclui um broker MQTT?

Não. O Node-RED traz apenas nós cliente MQTT. Você os conecta a um broker externo, como um broker MQTT gerenciado ou uma instância do Mosquitto operada por você; existem nós de broker da comunidade, mas eles não são recomendados para produção.

Quantas conexões o Node-RED usa para MQTT?

Uma por nó de configuração mqtt-broker, não importa quantos nós mqtt in e mqtt out o compartilhem. Reutilize um único nó de configuração para ficar dentro dos limites de conexão.

Por que meu nó mqtt in gera uma string em vez de um objeto?

A configuração Output provavelmente está em a String, ou o payload não é um JSON válido. Mude para auto-detect ou a parsed JSON object, ou adicione um nó JSON para fazer o parse explicitamente.

O Node-RED pode usar recursos do MQTT 5?

Sim. Defina o protocolo como MQTT V5 no nó do broker para usar, a partir dos nós mqtt in e mqtt out, recursos como user properties, expiração de mensagens, response topics e expiração de sessão.

É seguro usar o servidor MQTT público com o Node-RED?

É adequado para aprendizado e demonstrações, mas qualquer pessoa pode ler os topics públicos. Use prefixos de topic únicos, não envie dados sensíveis e migre para um broker privado com TLS antes de conectar equipamentos reais.