Subflows do Node-RED para Lógica MQTT Reutilizável

Os subflows do Node-RED permitem empacotar um grupo de nodes em um único node reutilizável, de modo que a lógica escrita uma vez possa ser colocada em qualquer aba e configurada a cada uso. Neste guia você vai criar um subflow de alertas MQTT com configurações próprias, adicionar status e tratamento de erros e reutilizá-lo em vários topics do ConnectMQ sem copiar uma única função.

O problema que os subflows resolvem

Fluxos MQTT costumam se repetir. Todo topic de sensor precisa dos mesmos passos: converter o payload, verificar se ele faz sentido, comparar um valor com um limiar, publicar um alerta e talvez limitar a taxa de alertas para não inundar o operador. Na primeira vez, você monta esses nodes à mão. Na quinta, copia e cola. Na vigésima, uma correção de bug significa editar vinte function nodes, e sempre fica um para trás.

Um subflow resolve isso. Você define a lógica uma vez como template, e cada lugar onde a usa é uma instância desse template. Altere o template e todas as instâncias são atualizadas no próximo deploy. Cada instância ainda pode ter as próprias configurações, como um limiar ou topic de alerta diferente, por meio das propriedades do subflow.

Os link nodes são uma boa opção quando você quer uma única cadeia de processamento compartilhada. Os subflows do Node-RED são melhores quando cada uso precisa de configuração e estado próprios.

Como funcionam os subflows do Node-RED

Um subflow tem um template e instâncias:

• Template. Abre como uma aba própria no editor e contém os nodes, uma porta de entrada opcional (0 ou 1), quantas portas de saída quiser e uma porta de status opcional.
• Instâncias. Aparecem na paleta em "subflows" e se comportam como qualquer outro node. Cada instância tem o próprio contexto de flow e os próprios valores para as propriedades do subflow.
• Propriedades. Definidas na janela de edição do template, cada uma com nome, tipo e valor padrão. Dentro do subflow, os nodes as leem como variáveis de ambiente: env.get("THRESHOLD") em uma função, ou ${THRESHOLD} digitado como valor inteiro de um campo de texto de um node.

Você pode criar um subflow do zero pelo menu (Subflows → Create Subflow) ou, mais comumente, selecionar nodes existentes e escolher Subflows → Selection to Subflow. O Node-RED liga as entradas e saídas para você com base nos fios que cruzavam o limite da seleção.

Crie um subflow de alerta MQTT

O objetivo: um node que recebe uma mensagem de telemetria MQTT já convertida, verifica um campo contra um limiar, repassa os dados normais pela saída 1 e emite uma mensagem de alerta pela saída 2, com um tempo de espera para que o mesmo dispositivo não gere alerta a cada segundo.

Passo 1: crie o template e as propriedades

Crie um novo subflow, chame-o de "Threshold alert" e defina inputs como 1 e outputs como 2. Abra as propriedades do subflow e adicione:

Você também pode atribuir a cada propriedade um widget de interface (texto, número, checkbox, seleção), o que deixa as instâncias mais amigáveis para colegas que nunca abrem o template.

Passo 2: adicione a lógica

Dentro do template, ligue entrada → função → duas saídas. A função:

// Function dentro do subflow "Threshold alert", 2 saídas
const field = env.get("FIELD");
const threshold = Number(env.get("THRESHOLD"));
const cooldownMs = Number(env.get("COOLDOWN_S")) * 1000;

const value = msg.payload && msg.payload[field];
if (typeof value !== "number") {
    node.error(`Field "${field}" missing or not numeric on ${msg.topic}`, msg);
    return [null, null];
}

let alertMsg = null;
if (value > threshold) {
    const lastAlerts = flow.get("lastAlerts") || {};
    const now = Date.now();
    if (!lastAlerts[msg.topic] || now - lastAlerts[msg.topic] > cooldownMs) {
        lastAlerts[msg.topic] = now;
        flow.set("lastAlerts", lastAlerts);
        alertMsg = {
            topic: msg.topic.replace(/\/telemetry$/, "/alert"),
            payload: {
                field: field,
                value: value,
                threshold: threshold,
                severity: env.get("SEVERITY"),
                ts: new Date(now).toISOString()
            }
        };
    }
}

node.status({ fill: alertMsg ? "red" : "green", shape: "dot", text: `${field}=${value}` });
return [msg, alertMsg];

Observe que flow, aqui, é o contexto da própria instância. Duas instâncias do subflow não compartilham suas tabelas de tempo de espera, que é exatamente o que você quer.

Passo 3: exiba o status na instância

Habilite a porta de status do subflow e ligue a ela um node Status (com escopo na função). O node da instância na sua aba principal passa a mostrar o mesmo ponto verde ou vermelho e o último valor, para que você monitore muitas instâncias com uma olhada.

Passo 4: use em vários topics

Na aba principal, adicione um node mqtt in para cada origem, ou um com wildcard, e ligue-os a instâncias separadas com configurações diferentes. Para um teste rápido, publique no servidor MQTT público, que serve para testes e não para dados de produção, substituindo e2a7 pela sua própria sequência aleatória:

mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-sub-e2a7 \
  -t "connectmq/demo/e2a7/furnace1/telemetry" -m '{"temp": 912}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-sub-e2a7 \
  -t "connectmq/demo/e2a7/tank1/telemetry" -m '{"level": 97}'

A primeira instância verifica FIELD=temp com THRESHOLD=850 para fornos; a segunda verifica FIELD=level com THRESHOLD=95 para tanques. Ligue a segunda saída de cada instância a um único node mqtt out compartilhado, com topic vazio, para que os alertas sejam publicados no topic definido pela função.

Um subflow com a própria assinatura MQTT

Um subflow não precisa de entrada. Um subflow com zero entradas pode conter o próprio node mqtt in, cujo topic é ${TOPIC}, uma propriedade do subflow. Cada instância então assina um topic diferente, compartilhando um único node de configuração de broker, de modo que todas as instâncias usam a mesma conexão com o broker.

Isso fica organizado em dashboards com muitos painéis de máquinas idênticos: uma instância do subflow por máquina, cada uma com TOPIC e um nome de exibição. A contrapartida é que a assinatura fica fixa no momento do deploy. Se precisar mudar topics em tempo real, combine subflows com a assinatura MQTT dinâmica do Node-RED.

Mantenha o node de configuração do broker fora do subflow, no fluxo principal ou no escopo global. Colocar uma configuração de broker dentro do template criaria uma conexão com o broker por instância, cada uma precisando do próprio client ID.

Tratamento de erros dentro de subflows

Erros lançados dentro de uma instância, incluindo a chamada node.error(..., msg) acima, podem ser capturados por um node Catch dentro do template do subflow. Se nenhum node Catch interno tratá-los, eles se propagam para os nodes Catch da aba que contém a instância. Um padrão comum é tratar dentro do subflow os erros conhecidos e recuperáveis e deixar os inesperados subirem para um único tratador de "errors" por aba.

Checklist de subflows do Node-RED

1. Dê a cada propriedade um padrão sensato para que uma nova instância funcione de imediato.
2. Prefira propriedades a valores fixos no código; tudo o que muda entre usos pertence a uma propriedade.
3. Mantenha os subflows focados: uma tarefa cada, como "parse", "alert" ou "rate limit".
4. Adicione uma porta de status para que as instâncias sejam observáveis no canvas.
5. Mantenha os nodes de configuração do broker fora do template.
6. Documente o subflow no campo de descrição; ele aparece na barra lateral de ajuda de cada instância.
7. Versione seus templates com git usando os projetos do Node-RED, para que uma alteração no template seja revisada como código.

Para o lado do código, nosso guia do function node do Node-RED aborda com mais profundidade retornos com várias saídas e envios assíncronos, e o guia de contexto no Node-RED explica como o contexto de flow da instância se relaciona com o do pai por meio de $parent. A documentação oficial de subflows em nodered.org lista todas as opções do template.

Rode lógica reutilizável do Node-RED no ConnectMQ

Os subflows facilitam escalar de três sensores para trezentos, por exemplo ao levar o mesmo alerta de temperatura para todas as câmaras frias de um frigorífico, e o seu broker deve escalar junto. O ConnectMQ é um broker MQTT gerenciado com TLS, MQTT 5 e um portal onde você pode definir regras de alerta por limiar e acompanhar os topics de alerta que seus subflows publicam. Quando o plano gratuito ficar pequeno, os planos Serverless (Paid) suportam até 1.000 conexões, e os clusters Dedicated isolam totalmente o seu tráfego. Crie seu primeiro broker em app.connectmq.com no plano Serverless gratuito, sem cartão de crédito. Se ainda estiver escolhendo a infraestrutura, leia nosso guia sobre o modelo de broker MQTT na nuvem e, para uma introdução completa, veja o tutorial de MQTT no Node-RED.

Perguntas frequentes

Qual a diferença entre um subflow e um grupo no Node-RED?

Um grupo é uma caixa visual em volta de nodes em uma aba. Um subflow é um template reutilizável que aparece como node na paleta e pode ser instanciado muitas vezes com configurações diferentes.

Como passo configurações para um subflow do Node-RED?

Defina propriedades no template do subflow e depois atribua valores em cada instância. Dentro do subflow, leia-as com env.get("NAME") ou digitando ${NAME} em uma propriedade de node.

Cada instância de subflow tem o próprio contexto?

Sim. O contexto de flow dentro de um subflow pertence àquela instância, então as instâncias não interferem umas nas outras. Use o prefixo $parent. para acessar o contexto do fluxo que a contém.

Nodes MQTT dentro de instâncias de subflow abrem conexões extras com o broker?

Não, se todos usarem o mesmo node de configuração de broker definido fora do subflow. O Node-RED compartilha uma conexão por node de configuração de broker.