Node-RED Dashboard 2.0 com MQTT: gauges, gráficos e controles

O Node-RED Dashboard 2.0 transforma topics MQTT em uma interface no navegador, com gauges, gráficos e controles, sem um projeto de front-end separado. Neste tutorial você vai montar uma página que mostra temperatura e umidade ao vivo de um dispositivo simulado, plota as duas em um gráfico de linha e aciona um ventilador por meio de um switch que publica comandos e reflete o estado confirmado pelo dispositivo. Tudo roda em um broker gratuito, então você pode acompanhar agora mesmo.

O que é o Node-RED Dashboard 2.0

O Dashboard 2.0 é o sucessor do pacote original node-red-dashboard, que agora está descontinuado. Ele é publicado como @flowfuse/node-red-dashboard, é construído sobre Vue e Vuetify e mantém a mesma ideia: os nodes de widget do seu flow viram elementos de uma página web servida pelo Node-RED em /dashboard.

A estrutura é uma hierarquia de nodes de configuração:

Raramente você cria esses nodes à mão. Quando você coloca o primeiro widget e escolhe "Add new ui-group", o editor se oferece para criar a página e a base para você. A documentação oficial do Dashboard 2.0 lista todos os widgets e suas opções.

Instale o Dashboard 2.0

No editor do Node-RED, abra Menu → Manage palette → Install, pesquise @flowfuse/node-red-dashboard e instale. Ou, pela linha de comando, no diretório de usuário do Node-RED:

cd ~/.node-red
npm install @flowfuse/node-red-dashboard
# reinicie o Node-RED em seguida, por exemplo:
node-red-restart   # em uma instalação feita pelo script do Raspberry Pi

Use uma versão atual do Node-RED 4.x. Depois de reiniciar, você verá uma nova seção "dashboard 2" na paleta. Se você ainda está configurando o próprio Node-RED, o tutorial Node-RED MQTT mostra a instalação e a primeira conexão com um broker.

Simule um dispositivo que publica telemetria

Para ter algo a exibir, rode um pequeno script Python que se comporta como um controlador de sala. Ele publica telemetria em JSON a cada dois segundos, escuta comandos para o ventilador e publica o estado do ventilador como retained message depois de aplicar um comando. Ele se conecta a broker.connectmq.com, o servidor MQTT público gratuito, que aceita clientes anônimos com qualquer client ID único e não vazio.

Substitua a7f3k2 por uma string aleatória sua. O servidor público pode ser lido por qualquer pessoa e serve para testes, então mantenha o prefixo único e os dados inofensivos.

# pip install "paho-mqtt>=2.0"
import json
import random
import time
import uuid

import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/a7f3k2/room1"
fan_on = False


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)
    client.subscribe(f"{PREFIX}/fan/set", qos=1)


def on_message(client, userdata, msg):
    global fan_on
    command = msg.payload.decode().strip().upper()
    if command in ("ON", "OFF"):
        fan_on = command == "ON"
        # Reporta o estado confirmado, retido para que novos dashboards o vejam na hora
        client.publish(f"{PREFIX}/fan/state", command, qos=1, retain=True)
        print("Fan is now", command)


client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=f"room-sim-{uuid.uuid4().hex[:8]}")
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_start()

temperature = 24.0
try:
    while True:
        drift = random.uniform(-0.3, 0.35) - (0.25 if fan_on else 0.0)
        temperature = max(15.0, min(35.0, temperature + drift))
        payload = {
            "temperature": round(temperature, 2),
            "humidity": round(random.uniform(40, 55), 1),
        }
        client.publish(f"{PREFIX}/telemetry", json.dumps(payload), qos=0)
        time.sleep(2)
except KeyboardInterrupt:
    pass
finally:
    client.loop_stop()
    client.disconnect()

Deixe-o rodando. Você pode acompanhar a saída com mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-a7f3k2 -v -t 'connectmq/demo/a7f3k2/#'.

Monte o flow do Node-RED Dashboard 2.0

Passo 1: assine a telemetria

Adicione um node mqtt in. Crie um novo node de configuração mqtt-broker com servidor broker.connectmq.com, porta 1883 e um client ID único, como nr-dash-a7f3k2. Defina o topic como connectmq/demo/a7f3k2/room1/telemetry, QoS 1, e a saída como a parsed JSON object.

Passo 2: divida o payload para cada widget

Os gauges esperam um único número em msg.payload, enquanto um gráfico com várias séries espera uma mensagem por série, com o nome da série em msg.topic. Um function node com três saídas faz as duas coisas:

// Function node "split telemetry" - defina Outputs como 3
const t = Number(msg.payload.temperature);
const h = Number(msg.payload.humidity);

if (Number.isNaN(t) || Number.isNaN(h)) {
    node.warn("Unexpected payload: " + JSON.stringify(msg.payload));
    return null;
}

return [
    { payload: t },                       // saída 1 -> gauge de temperatura
    { payload: h },                       // saída 2 -> gauge de umidade
    [                                      // saída 3 -> gráfico, duas séries
        { topic: "Temperature (C)", payload: t },
        { topic: "Humidity (%)", payload: h }
    ]
];

Retornar um array dentro de uma posição de saída envia várias mensagens por aquela porta, uma após a outra.

Passo 3: adicione gauges

Coloque dois nodes ui-gauge e ligue-os às saídas 1 e 2. No primeiro, clique no lápis ao lado de Group para adicionar um novo grupo chamado "Room 1", o que também cria a página e a base. Configurações úteis:

• Tipo: "Gauge 3/4" para temperatura, estilo "Tile" ou "Battery" para umidade se você preferir uma visão compacta.
• Faixa: 0 a 40 para temperatura, 0 a 100 para umidade.
• Segmentos: verde a partir de 0, âmbar a partir de 26, vermelho a partir de 30, para que a própria cor conte a história.
• Unidades: °C e %.

Passo 4: adicione um gráfico de linha

Ligue a saída 3 a um node ui-chart no mesmo grupo. Escolha o tipo "Line", deixe Series como msg.topic e deixe X como timestamp, para que cada ponto seja carimbado ao chegar. Nos limites de pontos, mantenha os últimos 300 pontos ou a última hora. Sem limite, um dashboard que roda por muito tempo continua crescendo na memória.

Os dados dos gráficos no Dashboard 2.0 ficam na memória do Node-RED, então uma reinicialização os apaga. O guia complementar sobre histórico de gráficos no Node-RED mostra como persisti-los e reenviá-los.

Passo 5: adicione um controle que publica comandos

Adicione ao grupo um ui-switch com o rótulo "Fan". Defina o payload de ligado como a string ON e o de desligado como OFF. Ligue-o a um node mqtt out com o topic connectmq/demo/a7f3k2/room1/fan/set, QoS 1, retain desativado. Comandos não devem ser retidos: um ON retido seria reenviado ao dispositivo toda vez que ele se reconectasse, mesmo horas depois.

Passo 6: reflita o estado real do dispositivo

Um switch que só mostra o que o usuário clicou pode mentir. Se o dispositivo está offline, o switch diz "ligado" enquanto o ventilador está desligado. Resolva isso alimentando o switch com o estado confirmado pelo dispositivo:

1. Adicione um segundo node mqtt in em connectmq/demo/a7f3k2/room1/fan/state, com saída como string UTF-8.
2. Ligue-o à entrada do mesmo ui-switch.
3. Nas configurações do switch, garanta que as mensagens de entrada não sejam repassadas para a saída. Caso contrário, cada atualização de estado seria republicada como um novo comando e você criaria um loop.

Como o simulador publica o estado como retained, um dashboard recém-aberto, ou um Node-RED reiniciado, mostra a posição correta imediatamente.

Passo 7: faça o deploy e abra a página

Clique em Deploy e abra http://localhost:1880/dashboard. Os gauges se movem a cada dois segundos, o gráfico desenha duas linhas e, ao ligar o ventilador, a temperatura começa a cair algumas leituras depois.

Referência de widgets para dashboards MQTT

Para projetos maiores, veja o exemplo de dashboard de OEE, que calcula os KPIs antes de chegarem aos widgets, e o tutorial do worldmap para dados de localização.

Problemas comuns e soluções

1. Os widgets nunca atualizam. Verifique o status do node mqtt in. Se ele mostra "connecting", o client ID pode estar em uso por outro cliente; torne-o único.
2. O gauge mostra NaN ou fica em zero. O payload chegou ao gauge como objeto. Garanta que apenas um número vá para o gauge.
3. O gráfico desenha uma única linha misturada. Todas as mensagens têm o mesmo msg.topic. Defina um nome de série diferente para cada valor.
4. O switch pisca ou os comandos se repetem. O repasse (pass-through) está ativado enquanto as mensagens de estado retornam ao switch. Desative-o.
5. A página pode ser acessada de qualquer lugar. O Dashboard 2.0 não tem login por padrão. Coloque o Node-RED atrás de autenticação ou de um proxy reverso antes de expô-lo.
6. O dashboard funciona na rede local, mas não remotamente. A porta 1880 geralmente está bloqueada; publique a página por um proxy com HTTPS em vez de abrir a porta.

Da demonstração para a produção

O servidor MQTT público é ótimo para este tutorial, mas seus dados são visíveis para qualquer pessoa e ele tem limites de taxa por cliente. Para uma instalação real, aponte o mesmo node de configuração mqtt-broker para um broker privado com credenciais e TLS na porta 8883. Um broker MQTT na nuvem também permite que dispositivos em vários prédios publiquem em um só lugar, que um único dashboard Node-RED pode ler. Se você vai configurar certificados pela primeira vez, o guia de TLS MQTT no Node-RED mostra o passo a passo.

Com o ConnectMQ, você obtém no portal o username, o password e o client ID gerados, e a única mudança no flow é o node de configuração. Todos os widgets, funções e topics deste tutorial continuam iguais depois que você remove o prefixo de demonstração. Optar por um broker MQTT gerenciado também elimina a necessidade de rodar e atualizar o Mosquitto na mesma máquina do seu dashboard.

Rode seu dashboard Node-RED no ConnectMQ

Crie uma conta gratuita em app.connectmq.com, escolha o plano Serverless (Free), sem cartão de crédito, e crie um broker. Cole as credenciais no node de configuração do Node-RED, mude para a porta 8883 com TLS e sua página do Dashboard 2.0 passa a ler dados privados e criptografados. O cliente MQTT no navegador do portal do ConnectMQ é prático para enviar comandos de teste ao topic do ventilador enquanto você desenha a página.

Perguntas frequentes

Qual é a diferença entre o Node-RED Dashboard e o Dashboard 2.0?

O node-red-dashboard original está descontinuado e é construído sobre AngularJS. O Dashboard 2.0, @flowfuse/node-red-dashboard, é seu substituto mantido, construído sobre Vue, com uma estrutura de páginas, grupos e widgets que vai parecer familiar.

Qual é a URL do Node-RED Dashboard 2.0?

Por padrão, o dashboard é servido em http://<node-red-host>:1880/dashboard. Você pode mudar o caminho no node de configuração ui-base.

O Dashboard 2.0 pode enviar comandos MQTT?

Sim. Ligue um ui-switch, ui-button ou ui-slider a um node mqtt out. Alimente o widget com o estado confirmado pelo dispositivo para que a interface mostre a realidade, e não apenas o último clique.

Por que meu gráfico fica vazio depois de reiniciar o Node-RED?

Os dados do gráfico ficam na memória. Persista as leituras em armazenamento de contexto ou em um banco de dados e reenvie-as na inicialização para manter o histórico entre reinicializações.