> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/automation-patterns.md). # Padrões de Automação Padrões de automação para o Kilo IoT — alarmes de limiar, enriquecimento por múltiplos sensores, escalonamento, CEL dinâmica. Esta página apresenta padrões de automatização comprovados para implementações IoT empresariais. Cada padrão descreve um cenário operacional real, a estrutura do diagrama BPMN, as expressões CEL envolvidas e quando usar o padrão. A maioria destes padrões é construída visualmente, organizando nós no canvas BPMN. O CEL aparece nos pontos focados em que a regra precisa de lógica exata, classificação ou mensagens dinâmicas. Como o CEL suporta condições aninhadas, valores calculados, comparações entre sensores e geração de texto dinâmico, a gama de automatizações que pode modelar é ampla — desde uma única verificação de limite até fluxos de trabalho multi-etapa, multi-sensor, com caminhos de fallback e escalonamento gradual. Estes padrões baseiam-se nos tipos de nós e nas ferramentas de canvas abordados em [Referência de Nó](/kilo-docs-pt/kilo-iot-server/rules-engine/node-reference.md) e [Editor Visual](/kilo-docs-pt/kilo-iot-server/rules-engine/visual-editor.md). Se é novo no Rules Engine, comece por [Criar Regras](/kilo-docs-pt/kilo-iot-server/rules-engine/creating-rules.md) para compreender os fundamentos. *** ## Padrão 1: Alarme simples de limite O padrão de automatização mais comum. Um sensor reporta um valor, a regra verifica se este excede um limite e gera um alarme se isso acontecer. ### Estrutura do diagrama ``` Evento de início → Tarefa de script → Gateway exclusivo → Definir alarme → Evento de fim ↓ (predefinição) Evento de fim ``` ### Configuração **Evento de início:** Associado ao dispositivo e sensor-alvo — por exemplo, uma sonda de temperatura de armazenamento refrigerado a reportar em graus Celsius. **Tarefa de script** — "Verificar limite": ``` {"above_threshold": vars.value > 30.0} ``` Esta expressão cria um sinal booleano. O gateway usa este sinal para decidir se deve gerar um alarme. **Gateway exclusivo** — Dois ramos: * **Ramo de alarme:** Condição `vars.above_threshold == true` — encaminha para o nó Definir alarme * **Ramo predefinido:** Encaminha para um Evento de fim (não é necessária nenhuma ação quando a leitura está dentro do intervalo) **Definir alarme:** Configurado com uma [Definição de alarme](/kilo-docs-pt/kilo-iot-server/alarm.md) existente e uma mensagem de motivação como `"Leitura da temperatura excedeu 30 C"`. O nó Definir alarme aciona a definição — a severidade, os canais e o escalonamento são configurados na página de Alarmes, não na própria regra. ### Quando usar este padrão * Monitorização da temperatura de armazenamento refrigerado — alertar quando a temperatura sobe acima do limite seguro * Monitorização ambiental de sala de servidores — alertar quando a temperatura ambiente ou a humidade excede os limites operacionais * Monitorização de vibração de equipamento — alertar quando a magnitude da vibração excede a linha de base * Qualquer cenário de um único sensor e um único limite em que uma leitura fora do intervalo exija atenção imediata *** ## Padrão 2: Escalonamento multinível Quando um único limite não é suficiente, este padrão classifica a leitura em níveis de severidade e encaminha cada nível para uma definição de alarme diferente — permitindo diferentes canais de notificação, cadeias de escalonamento e procedimentos de resposta para cada severidade. ### Estrutura do diagrama ``` Evento de início → Tarefa de script → Gateway exclusivo → Definir alarme (Crítico) → Evento de fim ↓ (aviso) Definir alarme (Aviso) → Evento de fim ↓ (predefinição) Evento de fim ``` ### Configuração **Tarefa de script** — "Classificar severidade": ``` {"level": vars.value > 80 ? "critical" : vars.value > 50 ? "warning" : "normal"} ``` Esta expressão avalia a leitura e atribui um nível de severidade como uma string. **Gateway exclusivo** — Três ramos: * **Ramo crítico:** Condição `vars.level == "critical"` — encaminha para a definição de alarme Crítico (SMS para o engenheiro de plantão, email para o gestor da instalação) * **Ramo de aviso:** Condição `vars.level == "warning"` — encaminha para a definição de alarme de Aviso (email para a equipa de operações) * **Ramo predefinido:** Encaminha para um Evento de fim (leituras normais não requerem ação) ### Quando usar este padrão * Monitorização de HVAC com resposta gradual — aviso quando uma zona sai do intervalo de conforto, crítico quando atinge níveis inseguros * Conformidade ambiental — aviso quando uma leitura se aproxima de um limite regulamentar, crítico quando o ultrapassa * Monitorização da bateria — aviso aos 20%, crítico aos 10%, com diferente urgência de notificação para cada um * Qualquer cenário em que diferentes níveis de severidade exijam diferentes velocidades de resposta, canais ou equipas *** ## Padrão 3: Comparação entre sensores Algumas decisões requerem dados de mais de um sensor. Este padrão obtém uma segunda leitura usando um nó de Enriquecimento, calcula a relação entre os dois valores e decide com base no resultado. ### Estrutura do diagrama ``` Evento de início → Enriquecimento → Tarefa de script → Gateway exclusivo → Definir alarme → Evento de fim ↓ (predefinição) Evento de fim ``` ### Configuração **Evento de início:** Associado a um sensor de temperatura interior. **Enriquecimento** — "Obter temperatura exterior": Configurado para recuperar a leitura mais recente de um sensor de temperatura exterior no mesmo local. O valor enriquecido passa a estar disponível como variável nos nós subsequentes. **Tarefa de script** — "Calcular diferencial": ``` {"delta": vars.value - vars.outdoor_temp.value, "needs_alarm": vars.value - vars.outdoor_temp.value > 10} ``` Esta expressão calcula a diferença de temperatura entre os sensores interior e exterior e assinala se a diferença excede o limite. **Gateway exclusivo** — Dois ramos: * **Ramo de alarme:** Condição `vars.needs_alarm == true` — encaminha para Definir alarme * **Ramo predefinido:** Encaminha para Evento de fim **Definir alarme:** Configurado com uma mensagem de motivação como `"O diferencial de temperatura interior/exterior excede 10 graus"`. ### Importante: adicione tratamento de erros Os nós de Enriquecimento dependem de dados externos — o sensor-alvo pode estar offline, inacessível ou a devolver dados desatualizados. Anexe sempre um **Evento de Erro de Limite** ao nó de Enriquecimento. Ver [Padrão 4](#pattern-4-error-safe-enrichment) para a abordagem completa de tratamento de erros. ### Quando usar este padrão * Monitorização da eficiência do HVAC — alertar quando o diferencial de temperatura interior/exterior indica falha de isolamento ou avaria do HVAC * Monitorização de pressão diferencial — comparar sensores de pressão entre zonas de sala limpa * Validação de sensor redundante — comparar leituras de dois sensores que medem a mesma métrica e alertar se divergirem significativamente * Qualquer cenário em que uma decisão dependa da relação entre dois pontos de dados, e não de um limiar absoluto *** ## Padrão 4: Enriquecimento com segurança contra erros Qualquer regra que utilize um nó de Enriquecimento deve lidar com a possibilidade de o enriquecimento falhar. Este padrão envolve o nó de Enriquecimento com um Evento de erro de fronteira que encaminha para um alarme de fallback, garantindo que a regra nunca falhe silenciosamente quando um sensor de referência não estiver disponível. ### Estrutura do diagrama ``` Evento de início → Enriquecimento → Tarefa de script → Gateway exclusivo → Definir alarme → Evento de fim | ↓ (predefinição) [Erro de fronteira] Evento de fim ↓ Definir alarme (Fallback) → Evento de fim ``` ### Configuração **Enriquecimento:** A mesma configuração do Padrão 3 — obtém uma leitura de um sensor secundário. **Evento de erro de fronteira:** Associado ao nó de Enriquecimento. Se o enriquecimento falhar por qualquer motivo (sensor offline, timeout, dados em falta), o evento de erro capta a falha e encaminha para o caminho de fallback. **Definir alarme (Fallback):** Configurado com uma definição de alarme diferente e uma mensagem de motivação como `"Sensor de referência offline — impossível calcular o diferencial. É necessária verificação manual."` Isto garante que a sua equipa de operações saiba que a verificação automatizada não pôde ser concluída. ### Quando usar este padrão * Qualquer regra que use Enriquecimento e não possa correr o risco de falhar silenciosamente * Cenários de monitorização críticos em que uma leitura de comparação em falta é, por si só, uma condição que merece alerta * Fluxos de trabalho de conformidade em que cada falha de monitorização deve ser documentada * Como boa prática padrão: associe um Evento de erro de fronteira a cada nó de Enriquecimento em cada regra *** ## Padrão 5: Pipeline de transformação de dados Alguns dados de sensores requerem pré-processamento antes de poderem ser avaliados de forma significativa. Este padrão encadeia múltiplas Tarefas de script para transformar leituras brutas através de etapas de conversão de unidades, calibração ou normalização antes do gateway de decisão. ### Estrutura do diagrama ``` Evento de início → Tarefa de script (Converter) → Tarefa de script (Calibrar) → Gateway exclusivo → Definir alarme → Evento de fim ↓ (predefinição) Evento de fim ``` ### Configuração **Tarefa de script** — "Converter unidades": ``` {"celsius": (vars.value - 32) * 5.0 / 9.0} ``` Converte uma leitura em Fahrenheit para Celsius. Ajuste a fórmula às suas necessidades específicas de conversão. **Tarefa de script** — "Aplicar desvio de calibração": ``` {"calibrated": vars.celsius - 1.5, "above_threshold": vars.celsius - 1.5 > 25.0} ``` Aplica um desvio de calibração conhecido (neste exemplo, o sensor lê 1,5 graus acima) e verifica o valor corrigido em relação ao limite. **Gateway exclusivo** — Dois ramos: * **Ramo de alarme:** Condição `vars.above_threshold == true` * **Ramo predefinido:** Encaminha para Evento de fim ### Quando usar este padrão * Sensores a reportar em unidades não padrão que precisam de conversão antes da comparação com o limiar * Sensores com desvios de calibração conhecidos que têm de ser corrigidos antes da avaliação * Normalização de dados para sensores de diferentes fabricantes que reportam a mesma métrica em escalas diferentes * Qualquer cenário em que dados brutos de sensores exijam uma ou mais etapas de transformação antes de serem significativos para a tomada de decisões *** ## Padrão 6: Enriquecimento condicional com lógica de fallback Um padrão mais avançado que combina enriquecimento, transformação, tratamento de erros e decisões com vários ramos numa única regra robusta. Este padrão representa um fluxo de trabalho de automatização de nível de produção. ### Estrutura do diagrama ``` Evento de início → Enriquecimento → Tarefa de script (Analisar) → Gateway exclusivo → Definir alarme (Crítico) → Evento de fim | ↓ (aviso) [Erro de fronteira] Definir alarme (Aviso) → Evento de fim ↓ ↓ (predefinição) Tarefa de script (Fallback) → Definir alarme (Offline) → Evento de fim ``` ### Configuração **Enriquecimento:** Obtém uma leitura de referência (por exemplo, a humidade exterior para um armazém). **Evento de erro de fronteira:** Capta falhas de enriquecimento e encaminha para uma Tarefa de script de fallback dedicada. **Tarefa de script (Fallback):** ``` {"level": "offline"} ``` Define o nível como "offline" para que o alarme de fallback seja acionado. **Tarefa de script (Analisar):** ``` {"delta": vars.value - vars.reference.value, "level": vars.value - vars.reference.value > 20 ? "critical" : vars.value - vars.reference.value > 10 ? "warning" : "normal"} ``` **Gateway exclusivo** — Três ramos: * **Crítico:** `vars.level == "critical"` * **Aviso:** `vars.level == "warning"` * **Predefinição:** Evento de fim Este padrão trata o caminho feliz (o enriquecimento é bem-sucedido, os dados são analisados, o alarme apropriado é acionado), o caminho de aviso e o caminho de falha (o enriquecimento falha, a equipa de operações é alertada para o problema do sensor) — tudo numa única regra. *** ## Melhores práticas para criar regras de automatização ### Comece simples, adicione complexidade quando necessário Comece com o Padrão 1 (limite simples) e só adicione enriquecimento, classificação multinível ou etapas de transformação quando o cenário operacional realmente os exigir. Uma regra simples que funciona de forma fiável é melhor do que uma complexa e difícil de depurar. ### Dê nomes descritivos aos seus nós Nomes de nós predefinidos como "Tarefa de script 1" não têm significado durante a resolução de problemas. Dê nomes aos nós de acordo com o que fazem: "Verificar limite de temperatura", "Classificar severidade", "Obter leitura exterior". O seu eu futuro — e os seus colegas — irão agradecer quando reverem a regra às 3 da manhã. ### Adicione sempre um ramo predefinido nos Gateways Cada Gateway exclusivo deve ter um ramo predefinido que encaminhe para um Evento de fim. Isto garante que a regra termina de forma graciosa mesmo que nenhuma das condições explícitas corresponda. Sem um ramo predefinido, a regra não tem caminho para valores inesperados. ### Associe sempre Eventos de erro de fronteira a nós de Enriquecimento O enriquecimento depende de dados externos. Se o sensor-alvo estiver offline, eliminado ou temporariamente inacessível, o enriquecimento falhará. Um Evento de erro de fronteira fornece um fallback gracioso — encaminhando para um alarme de "sensor offline" ou ignorando completamente a lógica dependente do enriquecimento. ### Use janelas de supressão de alarmes para evitar inundações de notificações Quando um limite é continuamente excedido, as definições de supressão e repetição da definição de alarme impedem que os operadores sejam inundados com notificações duplicadas. Configure estas definições na sua [Definições de alarmes](/kilo-docs-pt/kilo-iot-server/alarm.md) em vez de tentar incorporar a lógica de supressão na própria regra. ### Mantenha as expressões simples As expressões CEL devem ser fáceis de ler e compreender. Se uma expressão crescer para além de uma única linha, divida a lógica em várias Tarefas de script. Cada tarefa trata de um cálculo, e os resultados seguem para a próxima etapa como variáveis. ### Uma regra por preocupação Resista à tentação de criar uma única regra que monitorize simultaneamente temperatura, humidade, CO2 e vibração. Regras separadas são mais fáceis de versionar, testar, implementar e depurar de forma independente. Se uma regra precisar de ser atualizada ou revertida, as outras continuam a correr sem serem afetadas. ### Construa e implemente deliberadamente Depois de fazer alterações, construa a regra para a validar. Reveja o nome e o comentário do artefacto de compilação. Implemente apenas quando tiver a certeza de que a regra está correta. O fluxo explícito de construir e depois implementar existe para evitar que alterações não testadas cheguem à produção. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/automation-patterns.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.