> 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/node-reference.md).
# Referência de Nós
Referência de nós para o Rules Engine — Start, End, Script, Gateway, Set Alarm, Enrichment, Boundary.
Cada regra de automação é construída a partir de um conjunto de tipos de nós que você arrasta para a tela do editor visual, conecta com fluxos e configura por meio de um painel de propriedades. Esta página documenta cada tipo de nó — o que faz, quando usá-lo, como aparece na tela e cada campo no seu painel de propriedades.
Esta página documenta os nós atualmente disponíveis na paleta ativa: **Evento de Início**, **Evento de fim**, **Tarefa de script**, **Gateway exclusivo**, **Definir alarme**, **Executar Comando**, **Enriquecimento**, e **Evento de erro de borda**. Nós transitórios ou planejados são intencionalmente excluídos até fazerem parte da superfície ativa do editor.
Para uma visão geral da própria tela — paleta, barra de ferramentas e fluxo geral de edição — veja [Editor Visual](/kilo-docs-pt/kilo-iot-server/rules-engine/visual-editor.md).
***
## Evento de Início
O Evento de início é o ponto de entrada de cada regra. Ele decide o que aciona a regra — seja a leitura do sensor de um dispositivo ou um salvo [gatilho](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md) que avalia uma condição para um ou mais dispositivos. Toda regra deve ter exatamente um Evento de início.
### Aparência visual
Um círculo com um ícone de envelope dentro.
### Quando usar
Toda regra começa aqui. Você não pode criar uma regra válida sem um Evento de início.
### Painel de propriedades
Selecione o Evento de início na tela — um ícone de lápis e um ícone de lixeira aparecem abaixo dele. Clique no **lápis** para abrir o painel de propriedades à direita.
**Nome** — Um campo de texto para o rótulo do nó. Espaço reservado: *por ex., Alarme de incêndio*.
**Origem do início** — Um seletor com duas opções que decide o que o restante do painel solicitará. Um Evento de início nomeia uma fonte ou a outra; nomear ambas, ou nenhuma, é rejeitado.
| Opção | De onde a regra começa |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Leitura do sensor** | As leituras de um dispositivo. A regra dispara cada vez que esse sensor envia um relatório. |
| **Condição de disparo** | Um salvo [gatilho](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md). A sua condição pode agir imediatamente ou após uma duração e pode avaliar um ou mais dispositivos de forma independente. A regra é executada quando o gatilho a sinaliza. |
**Filtro de evento** — Exibido quando **Origem do início** é **Leitura do sensor**. Uma seção com o título "Defina quais dispositivos podem iniciar esta regra." contendo dois campos:
| Campo | Descrição |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dispositivo** | Lista suspensa de preenchimento automático pesquisável. Espaço reservado: *Selecionar dispositivo*. Lista todos os dispositivos da sua organização. |
| **Sensor** | Lista suspensa de preenchimento automático. Espaço reservado: *Selecionar sensor*. Desativado até que um dispositivo seja escolhido. Mostra apenas os sensores pertencentes ao dispositivo selecionado. |
**Condição de disparo** — Exibido em vez do Filtro de evento quando **Origem do início** é **Condição de disparo**. Um único preenchimento automático, espaço reservado *Selecionar gatilho*, listando os gatilhos definidos na aba **Gatilhos** .
> Apenas a primeira página de gatilhos é carregada, e o campo informa isso quando há mais. Se o gatilho de que você precisa não estiver na lista, é por isso — veja [Gatilhos](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md).
**Ativar agendamento** — Um interruptor de alternância (Desativado por padrão). Quando ativado, os campos a seguir aparecem:
| Campo | Descrição |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Intervalo de tempo** | Aparece quando Agendamento está Ativado, com o título *"Intervalo de tempo. A regra só fica ativa durante este período:"*. Um **botão Alterar agendamento** abre o editor, onde você escolhe os dias da semana em que a regra pode ser executada e os **De** e **Até** horários. Fora dessa janela, a regra não é executada. Para uma origem de gatilho, o monitoramento e as contagens regressivas continuam; apenas a execução da regra tentada é ignorada. |
| **Fuso horário** | Uma lista suspensa com fusos horários padrão, para que a janela signifique a mesma coisa independentemente de onde o visualizador esteja. |
**Entradas** — Opcional. Uma lista de expressões CEL avançadas para preparação de dados. A maioria das regras deixa isso em branco e lê a leitura recebida diretamente. Cada entrada tem:
* Um nome de entrada (campo de texto)
* Um indicador de tipo (bloqueado para "Expression")
* Um campo de expressão CEL
* Adicione novas entradas com o **+ Adicionar entrada** botão. Remova uma entrada com o botão de exclusão.
**Saídas** — Opcional. Mesma estrutura de Entradas, com seu próprio **+ Adicionar saída** botão. Use saídas para publicar valores nomeados em `vars` para nós subsequentes.
**Salvar / Cancelar** — Na parte inferior do painel. Clique em **Guardar** para aplicar as alterações, ou em **Cancelar** para descartar.
### Como os dados fluem a partir do Evento de início
As variáveis de processo dependem do **Origem do início**.
**Leitura do sensor** fornece:
| Variável | Conteúdo |
| ---------------- | ----------------------------------- |
| `vars.value` | O valor reportado pelo sensor |
| `vars.sensor_id` | O identificador exclusivo do sensor |
| `vars.timestamp` | O timestamp da leitura |
**Condição de disparo** fornece:
| Variável | Conteúdo |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `vars.device_name` | O nome do dispositivo monitorado que satisfez o gatilho |
| `vars.subject_kind` | O tipo de recurso monitorado; atualmente `device` |
| `vars.subject_id` | O identificador exclusivo do dispositivo monitorado |
| `vars.sensor_id` | O identificador do sensor usado para associar a execução e qualquer alarme ao dispositivo monitorado |
| `vars.detector_id` | O identificador exclusivo do gatilho |
| `vars.timestamp` | O horário do sinal do gatilho em segundos Unix |
Uma regra iniciada por gatilho não recebe `vars.value`. Veja [Dados disponíveis para a regra](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md#data-available-to-the-rule) antes de converter uma regra iniciada por sensor.
O Evento de início também pode remodelar os dados recebidos antes que o restante da regra seja executado:
* **Entradas** criar variáveis auxiliares locais ao nó para esta etapa
* **Saídas** escrever valores nomeados nas variáveis de processo que os nós subsequentes podem referenciar
### Exemplo
Uma regra de conformidade de armazenamento refrigerado para um armazém farmacêutico vincula o Evento de início a uma sonda de temperatura dentro da unidade de armazenamento. O Agendamento é deixado desativado, já que a sonda vale a pena ser monitorada o tempo todo; se fosse uma regra que só deveria ser executada fora do horário comercial, **botão Alterar agendamento** definiria esses dias e horários de acordo com o fuso horário local da instalação. Nenhuma entrada é necessária — o valor bruto da temperatura é suficiente para o gateway subsequente avaliar.
***
## Evento de fim
O Evento de fim encerra um caminho de fluxo. Quando a execução alcança um Evento de fim, esse ramo da regra está concluído.
### Aparência visual
Um círculo com uma borda grossa.
### Quando usar
Cada ramo da sua regra deve terminar com um Evento de fim. Uma regra com vários ramos (após um Gateway exclusivo, por exemplo) precisa de vários Eventos de fim — um por ramo.
### Painel de propriedades
| Campo | Descrição |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um campo de texto para o rótulo do nó. Normalmente fica como "Fim" ou recebe um nome que descreve o resultado desse ramo (por ex., "Normal — nenhuma ação", "Alarme disparado"). |
Nenhuma outra configuração é necessária.
### Exemplo
Uma regra que verifica se uma leitura de temperatura está acima ou abaixo de um limite tem dois ramos saindo de um Gateway exclusivo. Cada ramo termina com seu próprio Evento de fim — um rotulado "Dentro da faixa", o outro passando por um nó Definir alarme.
***
## Tarefa de script
A Tarefa de script avalia uma [CEL](https://cel.dev) expressão. Use-a para transformar dados recebidos, calcular valores derivados, classificar leituras ou preparar variáveis para decisões posteriores.
### Aparência visual
Um retângulo arredondado com um ícone de script (documento com linhas) no canto superior esquerdo.
### Quando usar
* Converter um valor bruto de sensor em uma classificação de severidade
* Calcular a diferença entre dois valores (após o enriquecimento)
* Preparar uma string formatada para uma mensagem de alarme
* Definir uma sinalização que os gateways subsequentes avaliam
### Painel de propriedades
| Campo | Descrição |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| **Nome** | Um campo de texto para o rótulo do nó. Padrão: "Script". Exemplo: "Classificar severidade". |
| **Script** | Um campo de expressão CEL em várias linhas (6 linhas). É aqui que você escreve a expressão a ser avaliada. |
**Entradas** — Uma lista de parâmetros de entrada avaliados antes da execução do script. Cada entrada tem um nome, um indicador de tipo (bloqueado para "Expression") e um campo de expressão CEL. Use-os para criar variáveis auxiliares locais para a tarefa. Adicione entradas com **+ Adicionar entrada**. Remova com o botão de exclusão.
**Saídas** — Mesma estrutura de Entradas, com seu próprio **+ Adicionar saída** botão. Use-os para publicar valores nomeados para nós subsequentes.
**Salvar / Cancelar** — Na parte inferior do painel.
### Como os resultados são armazenados
O padrão mais claro é fazer a Tarefa de script retornar um **mapa** (uma estrutura chave-valor). Cada chave é mesclada individualmente às variáveis de processo. Por exemplo, se a expressão da Tarefa de script for:
```cel
{"level": vars.value > 80 ? "critical" : "normal", "needs_action": vars.value > 80}
```
Então os nós subsequentes podem referenciar `vars.level` (uma string) e `vars.needs_action` (um booleano) de forma independente.
Você também pode usar a **Saídas** seção da tarefa para publicar valores nomeados adicionais após a execução do script. Na prática, mapas e saídas explícitas são o padrão mais fácil de revisar, restaurar e depurar depois.
### Exemplo
Uma equipe de operações que monitora sensores de vibração classifica as leituras antes de encaminhá-las por um gateway:
```cel
{"severity": vars.value > 90 ? "critical" : vars.value > 70 ? "warning" : "normal"}
```
O Gateway exclusivo subsequente então verifica `vars.severity == "critical"` em um ramo e `vars.severity == "warning"` em outro, com um ramo padrão para leituras "normais" que segue para um Evento de fim.
***
## Gateway exclusivo
O Gateway exclusivo é um ponto de decisão. Ele avalia as condições em seus fluxos de saída e encaminha a execução para exatamente **um** ramo — o primeiro cuja condição seja verdadeira. Isso é roteamento XOR: um e somente um caminho é seguido.
### Aparência visual
Um losango.
### Quando usar
* Encaminhar para ações diferentes com base em um limite (acima vs. abaixo)
* Ramificar com base em uma classificação de severidade (crítica, aviso, normal)
* Verificar se os dados enriquecidos alteram a decisão
* Fornecer um caminho de retorno padrão quando nenhuma condição específica corresponder
### Painel de propriedades
Clique no Gateway exclusivo na tela para abrir seu painel de propriedades. No topo, aparece um aviso: *"As condições são avaliadas sequencialmente (de cima para baixo). A primeira condição satisfeita executa seu fluxo, e todas as condições restantes são ignoradas."*
**Nome** — Um campo de texto para o rótulo do nó. Espaço reservado: *por ex., MSG Smoke*.
**Fluxos** — Uma lista de todas as conexões de saída deste gateway. Cada item de fluxo mostra:
| Elemento | Descrição |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Alça de arrastar** | Reordene os fluxos arrastando-os. A ordem determina a prioridade de avaliação — a primeira condição correspondente vence. |
| **Número do fluxo** | "Fluxo 1", "Fluxo 2" etc. Se este fluxo for o padrão, um rótulo "Fluxo padrão" aparece. |
| **Nome do sistema** | Um campo de texto para o identificador interno do fluxo. |
| **Etiqueta** | Um campo de texto para o rótulo de exibição na seta da tela. Oculto para o fluxo padrão. |
| **Cor** | Um seletor de cores para distinguir visualmente os ramos na tela. Oculto para o fluxo padrão. |
| **Condição (expressão)** | Uma expressão CEL que deve avaliar para `verdadeiro` para que este caminho seja executado. Espaço reservado: *por ex., vars.value > 10*. Oculto para o fluxo padrão. |
| **Definir como padrão** | Um botão que designa este fluxo como caminho de retorno. Dica de ferramenta: *"Escolha uma das condições para agir como caminho de retorno quando todas as outras condições forem falsas."* |
| **Eliminar** | Remove o fluxo. Uma caixa de diálogo de confirmação avisa: *"Isso também removerá a conexão correspondente na tela."* |
Quando você altera qual fluxo é o padrão, aparece um aviso: *"Ao alterar o fluxo padrão, o campo Condição será excluído permanentemente do fluxo definido como padrão."* O fluxo que antes era padrão recupera seu campo Condição.
Se o gateway ainda não tiver conexões de saída, a seção Fluxos mostra um estado vazio: *"Desenhe conexões a partir deste gateway na tela para adicionar fluxos."* Você deve primeiro desenhar conexões na tela — os fluxos não podem ser adicionados apenas pelo painel de propriedades.
**Entradas** — Opcional. Mesma estrutura da seção Entradas do Evento de início (nome, tipo, expressão CEL, + Adicionar entrada).
**Saídas** — Opcional. Mesma estrutura da seção Saídas do Evento de início (nome, tipo, expressão CEL, + Adicionar saída).
**Salvar / Cancelar** — Na parte inferior do painel.
### Preciso dos parâmetros de entrada e saída?
Não. Ambos são opcionais, e um gateway que simplesmente verifica se um valor está acima de um limite não precisa de nenhum dos dois — deixe-os em branco e escreva `vars.value > 70` diretamente na condição do fluxo.
Use-os quando uma condição, de outra forma, seria longa, ou quando você repetir o mesmo cálculo em vários fluxos.
**Uma Entrada** calcula um valor antes de o gateway decidir e lhe dá um nome curto que as próprias condições de fluxo do gateway podem usar. Para converter uma leitura em Celsius uma vez e compará-la duas vezes, adicione uma entrada:
| Campo | Valor |
| --------------- | ----------------------------- |
| Nome da entrada | `tempF` |
| Expressão | `vars.temperature * 1.8 + 32` |
Então escreva as condições de fluxo como `vars.tempF > 158` e `vars.tempF > 104` em vez de repetir a conversão em cada uma.
Uma entrada pertence ao gateway em que você a definiu. Nós posteriores não podem lê-la.
**Uma Saída** funciona ao contrário. Ela é avaliada depois que o ramo é escolhido e grava seu resultado nas variáveis da regra, para que nós mais adiante possam usá-lo — uma mensagem de alarme pode referenciar `vars.tempF` mesmo que a conversão tenha acontecido no gateway.
O mesmo vale em qualquer lugar em que Entradas e Saídas apareçam: uma entrada é um auxiliar para o nó que você está configurando; uma saída é como esse nó passa algo adiante.
### Como funciona a avaliação de condições
As condições são avaliadas **de cima para baixo** na ordem em que aparecem na lista de Fluxos. A primeira condição que retorna `verdadeiro` é o caminho seguido. Todas as condições restantes são ignoradas, independentemente de também serem verdadeiras.
O fluxo padrão não tem expressão de condição. Ele é executado somente quando **todas as outras condições avaliam para falso**. Todo Gateway exclusivo deve ter um fluxo padrão — sem um, se nenhuma condição corresponder, a execução da regra trava nesse ramo.
O fluxo padrão cobre o caso em que nada correspondeu. Ele não cobre uma condição que falha ao ser avaliada: se uma expressão não puder ser avaliada — normalmente porque referencia uma variável que a regra não possui, ou retorna algo diferente de `verdadeiro`/`falso` — o gateway para ali e a regra não segue adiante por esse caminho. Em uma sessão de depuração, o gateway é contornado em vermelho; veja [Depurar Regras](/kilo-docs-pt/kilo-iot-server/rules-engine/debugging-rules.md#what-the-markers-on-the-canvas-mean).
Um gateway também precisa ramificar ou mesclar: dê a ele dois ou mais fluxos de saída para tomar uma decisão, ou dois ou mais fluxos de entrada para reunir caminhos novamente. Um gateway com um fluxo de entrada e um fluxo de saída é rejeitado quando você monta a regra — conecte esses dois nós diretamente em vez disso.
### Exemplo
Uma regra de umidade de armazém usa um Gateway exclusivo com três fluxos:
| Fluxo | Condição | Leva a |
| ----------------- | ----------------- | -------------------------------------------- |
| Fluxo 1 — Crítico | `vars.value > 85` | Definir alarme (violação crítica de umidade) |
| Fluxo 2 — Aviso | `vars.value > 70` | Definir alarme (aviso de umidade) |
| Fluxo 3 — Padrão | *(nenhuma)* | Evento de fim (nenhuma ação) |
Como as condições são avaliadas de cima para baixo, uma leitura de 90% corresponde ao Fluxo 1 e ignora o Fluxo 2. Uma leitura de 75% falha no Fluxo 1, mas corresponde ao Fluxo 2. Uma leitura de 60% falha em ambos e cai para o padrão.
***
## Definir alarme
O nó Definir alarme dispara um alarme com base em uma Definição de alarme preconfigurada. Quando a execução chega a este nó, ele cria um evento de alarme que inicia a política de escalonamento, envia notificações pelos canais configurados e aparece na caixa de entrada de alarmes.
### Aparência visual
Um retângulo arredondado com um ícone de sino no canto superior esquerdo.
### Quando usar
* Disparar um alerta crítico quando a leitura de um sensor cruza um limite perigoso
* Gerar um alarme de aviso que notifica a equipe de operações por e-mail e SMS
* Gerar alarmes com mensagens dinâmicas que incluem os valores reais do sensor
### Pré-requisitos
Antes de poder usar um nó Definir alarme, você deve ter pelo menos uma **Definição de alarme** configurada na seção Alertas. As Definições de alarme especificam o nível de severidade, as etapas de escalonamento, os canais de notificação e as políticas de destinatários. O nó Definir alarme referencia uma definição existente — ele não cria uma.
Veja [Alertas operacionais](/kilo-docs-pt/kilo-iot-server/alarm.md) sobre como criar e gerenciar Definições de alarme.
### Painel de propriedades
O cabeçalho do painel diz **"Definir alarme"** com o subtítulo: *"Selecione um alarme. Um novo alarme pode ser criado na página Alarmes."* A palavra "página Alarmes" vincula-se à [seção Alertas e notificações](/kilo-docs-pt/kilo-iot-server/alarm.md) .
| Campo | Descrição |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um campo de texto para o rótulo do nó. Exemplo: "Disparar alarme crítico". |
| **Escolher alarme** | Uma lista suspensa de preenchimento automático pesquisável. Lista as Definições de alarme existentes na sua organização. Pesquise pelo nome do alarme para encontrar a definição de que precisa. |
| **Mensagem de motivação** | Um campo de expressão CEL em várias linhas (3 linhas). Espaço reservado: `"Temperatura é " + string(vars.temp) + " graus"`. A expressão deve avaliar para uma string — este texto é anexado ao evento de alarme, fornecendo contexto aos responsáveis sobre o que disparou o alarme e por quê. |
**Entradas** — Uma lista de parâmetros de entrada. Cada entrada tem um nome, um indicador de tipo (bloqueado para "Expression") e um campo de expressão CEL. Adicione entradas com **+ Adicionar entrada**. Remova com o botão de exclusão.
**Saídas** — Mesma estrutura de Entradas, com seu próprio **+ Adicionar saída** botão.
**Salvar / Cancelar** — Na parte inferior do painel.
### Exemplos de mensagem de motivação
A mensagem de motivação é uma expressão CEL, então você pode incorporar valores de sensores em tempo real e variáveis calculadas:
```cel
"Temperatura " + string(vars.value) + " graus excede o limite de segurança"
```
```cel
"Leitura de umidade de " + string(vars.value) + "% na Zona A — acima do nível " + string(vars.severity)
```
```cel
"Concentração de CO2 em " + string(vars.value) + " ppm, excedendo o limite em " + string(vars.value - 800) + " ppm"
```
### O que acontece quando o nó é executado
1. Um evento de alarme é criado com a severidade e a configuração da Definição de alarme selecionada
2. A expressão da mensagem de motivação é avaliada e anexada ao evento
3. A política de escalonamento do alarme começa — notificações são enviadas pelos canais e aos destinatários definidos na Definição de alarme
4. O evento de alarme aparece na caixa de entrada de alarmes para acompanhamento e resolução
O nó Definir alarme **não** define severidade, canais, agendamentos ou escalonamento por si só. Isso vem da Definição de alarme selecionada. A regra decide **quando** disparar; a Definição de alarme decide **como** esse alarme é tratado.
### Exemplo
Uma regra de monitoramento ambiental de sala de servidores chega ao nó Definir alarme quando a temperatura excede 35 graus Celsius. O nó está configurado com uma Definição de alarme chamada "Superaquecimento da sala de servidores" (severidade: Crítica, escalonamento: SMS para o engenheiro de plantão imediatamente, e-mail para o gerente da instalação após 5 minutos). A mensagem de motivação diz:
```cel
"A temperatura da sala de servidores é " + string(vars.value) + " graus — atenção imediata necessária"
```
***
## Executar Comando
O nó Executar comando envia um comando a um dispositivo quando a regra o alcança — a ação que permite a uma regra controlar hardware, e não apenas alertar sobre ele. Ele despacha um dos [Comandos de Dispositivo](/kilo-docs-pt/kilo-iot-server/devices/commands.md) predefinidos de um dispositivo como um downlink, para que uma regra possa fechar uma válvula, enviar um ponto de ajuste ou alternar um relé automaticamente no momento em que suas condições forem atendidas.
Para o fluxo de trabalho completo, exemplos e o padrão agir-e-alertar, veja [Executar comandos em dispositivos](/kilo-docs-pt/kilo-iot-server/rules-engine/running-device-commands.md). Esta entrada cobre os campos do nó.
### Aparência visual
Um retângulo arredondado com um ícone de comando no canto superior esquerdo. Ele fica no mesmo grupo de atividades que Definir alarme e Enriquecimento.
### Quando usar
* Fechar uma válvula, alternar um relé ou parar uma bomba no instante em que um limite é ultrapassado
* Enviar um novo ponto de ajuste para um controlador em resposta a uma leitura
* Definir um valor proporcionalmente — por exemplo, a velocidade do ventilador derivada da temperatura medida
### Pré-requisitos
O dispositivo de destino deve ser **controlável** (MQTT, ou um dispositivo LoRaWAN Classe C) e já deve ter **pelo menos um comando definido** na sua **Comandos e Estados** aba. O nó executa comandos existentes; ele não os cria. Veja [Criando comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/creating-commands.md).
### Painel de propriedades
| Campo | Descrição |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um campo de texto para o rótulo do nó. Se deixado em branco, ele preenche com o nome do comando selecionado. Exemplo: "Fechar válvula de entrada". |
| **Dispositivo** | Uma lista pendente de preenchimento automático pesquisável com os dispositivos da sua organização. Seleciona o dispositivo para o qual o comando é enviado. |
| **Comando** | Uma lista pendente de preenchimento automático dos comandos definidos do dispositivo escolhido. Desativada até ser selecionado um dispositivo. |
| **Parâmetros** | Uma linha por cada parâmetro que o comando selecionado espera. Cada parâmetro é fornecido como um literal **Valor** (validado em relação ao tipo e ao intervalo do parâmetro) ou uma **Expressão CEL** (avaliada em tempo de execução, com `vars` disponível). |
| **Entradas / Saídas** | Expressões CEL nomeadas opcionais para modelação avançada de dados, seguindo o mesmo padrão de outros nós. |
**Salvar / Cancelar** — Na parte inferior do painel. Guardar fica desativado até que estejam selecionados um dispositivo e um comando e todos os parâmetros sejam válidos.
### O que acontece quando o nó é executado
1. Cada parâmetro é resolvido — literais tal como estão, expressões avaliadas em relação ao atual `vars`.
2. O comando é enviado para o dispositivo como um downlink (MQTT ou LoRaWAN), exatamente como seria numa execução manual.
3. O envio é registado no histórico de execução do dispositivo com o respetivo resultado (Pendente, Confirmado, Entregue, Aviso suave ou Falhado). Qualquer verificação configurada no comando também se aplica aqui.
Associe um nó Executar Comando a um [Evento de erro de borda](#boundary-error-event) quando um envio falhado ainda assim deve chegar a uma pessoa através de um caminho de recurso.
### Exemplo
Uma regra de deteção de fugas associa o seu Evento Inicial a um sensor de fugas. Um Gateway Exclusivo encaminha uma leitura de "fuga detetada" para um nó Executar Comando que envia um `fechar` comando para a válvula de corte de água, seguido de um nó Definir Alarme que dispara um alarme Crítico. A água é interrompida automaticamente e a equipa é notificada de que isso aconteceu.
***
## Enriquecimento
O nó Enriquecimento obtém a leitura mais recente de outro sensor. Isto permite-lhe tomar decisões com base em dados de vários sensores dentro de uma única regra, sem necessidade de criar regras separadas para cada um.
### Aparência visual
Um retângulo arredondado com um ícone de transferência por download no canto superior esquerdo.
### Quando usar
* Comparar uma leitura de temperatura interior com a temperatura exterior atual
* Verificar um sensor de humidade antes de decidir se um aumento de temperatura é preocupante
* Correlacionar uma leitura de CO2 com um sensor de ocupação para determinar se níveis elevados são esperados
* Verificar um sensor de referência antes de disparar um alarme
### Painel de propriedades
O cabeçalho do painel diz **"Enriquecimento de Dados"** com o subtítulo: *"Anexar metadados relevantes aos dados de dispositivo recebidos antes do processamento."*
| Campo | Descrição |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um campo de texto para o rótulo do nó. Espaço reservado: *ex.: Anexar Temperatura da Sala aos Dados do Sensor*. |
| **Dispositivo** | Lista pendente de preenchimento automático pesquisável. Lista todos os dispositivos da sua organização — o mesmo padrão de seletor do Evento Inicial. |
| **Sensor** | Lista pendente filtrada. Desativada até ser selecionado um dispositivo. Mostra apenas os sensores pertencentes ao dispositivo escolhido. |
| **Variável de saída** | Um campo de texto para o nome da variável sob a qual os dados obtidos são armazenados. Espaço reservado: *Metadados do utilizador*. Após a execução do nó, o resultado fica disponível como `vars.`. |
**Entradas** — Uma lista de parâmetros de entrada. Cada entrada tem um nome, um indicador de tipo (bloqueado para "Expression") e um campo de expressão CEL. Adicione entradas com **+ Adicionar entrada**. Remova com o botão de exclusão.
**Saídas** — Mesma estrutura de Entradas, com seu próprio **+ Adicionar saída** botão.
**Salvar / Cancelar** — Na parte inferior do painel.
### Como os dados enriquecidos estão estruturados
Após a execução do nó Enriquecimento, a leitura obtida fica disponível como `vars.` com a seguinte estrutura:
| Propriedade | Conteúdo |
| ----------------------------------- | ------------------------------------------------ |
| `vars..sensor_id` | O identificador do sensor |
| `vars..value` | O valor da leitura mais recente |
| `vars..type` | O tipo de dados do sensor |
| `vars..timestamp_ms` | Carimbo de data/hora da leitura em milissegundos |
Por exemplo, se o nome da variável for `outdoor_temp`, os nós seguintes podem referenciar `vars.outdoor_temp.value` para obter a leitura mais recente da temperatura exterior.
### Tratamento de erros
O nó Enriquecimento pode falhar se o sensor de destino estiver offline, nunca tiver reportado ou não estiver acessível. Combine sempre um nó Enriquecimento com um **Evento de erro de borda** (ver abaixo) para lidar graciosamente com estas falhas. Sem tratamento de erros, um enriquecimento falhado interrompe esse caminho de execução.
### Exemplo
Uma regra de monitorização de centro de dados compara a temperatura ambiente no interior de uma sala de servidores com o sensor de temperatura exterior do edifício. O nó Enriquecimento obtém dados do sensor exterior para uma variável chamada `external_temp`. Um Script Task seguinte calcula o diferencial:
```cel
{"temp_delta": vars.value - vars.external_temp.value}
```
Um Gateway Exclusivo verifica então se `vars.temp_delta > 15` — um diferencial elevado pode indicar uma falha de AVAC, uma vez que a temperatura interna está a subir independentemente das condições exteriores.
***
## Evento de erro de borda
O Evento de Erro de Fronteira é um gestor de erros que se associa a um nó de tarefa. Se a tarefa à qual está associado falhar durante a execução, o Evento de Erro de Fronteira captura a falha e encaminha a execução para um caminho de recurso em vez de terminar a regra.
### Aparência visual
Um pequeno círculo com um ícone de raio, posicionado na margem do nó de tarefa a que está associado. Fica na borda do nó pai, e não como um elemento autónomo na tela.
### Quando usar
* Um nó Enriquecimento obtém dados de um sensor que pode estar offline
* Um Script Task avalia uma expressão que depende de dados opcionais
* Um nó Definir Alarme referencia uma Definição de Alarme que pode ter sido desativada
* Qualquer tarefa em que a falha deva desencadear uma resposta específica em vez de silêncio
### Como associá-lo
Arraste um Evento de Erro de Fronteira a partir da paleta e largue-o num nó de tarefa existente (Script Task, Definir Alarme ou Enriquecimento). Ele encaixa na margem desse nó. Em seguida, desenhe uma única ligação de saída do Evento de Erro de Fronteira para o caminho de recurso — normalmente outro Definir Alarme, um Script Task que regista o contexto da falha ou um Evento Final.
### Regras
* Um Evento de Erro de Fronteira tem de estar associado a um nó de tarefa. Não pode existir como um nó autónomo na tela.
* Tem de ter exatamente **um** fluxo de saída.
* Não pode ter fluxos de entrada (para além da sua associação implícita à tarefa pai).
### Painel de propriedades
| Campo | Descrição |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um campo de texto para o rótulo do nó. Predefinição: "Error". Exemplo: "Sensor offline fallback". |
| **Código de erro** | Um campo de texto. Espaço reservado: *Especifique o código de erro aqui*. Utilizado para rotulagem e anotação no editor — veja a ressalva abaixo. |
| **Mensagem** | Um campo de texto multilinha (3 linhas). Espaço reservado: *Escreva a mensagem de erro aqui*. Utilizado para rotulagem e anotação no editor — veja a ressalva abaixo. |
**Entradas / Saídas** — O painel de propriedades pode apresentar campos de Entrada e Saída no Evento de Erro de Fronteira. No entanto, o motor de automação não processa Entradas nem Saídas neste tipo de nó. Se precisar de transformar dados ou publicar valores no caminho de erro, adicione Entradas e Saídas ao **nó seguinte** ao qual o fluxo de saída do evento de fronteira se liga — por exemplo, o Script Task de recurso, Definir Alarme ou Evento Final.
**Salvar / Cancelar** — Na parte inferior do painel.
**Ressalva importante:** Os campos Código de erro e Mensagem são campos de rotulagem e anotação no editor. Não permitem correspondência seletiva em tempo de execução por código de erro. O motor encaminha **todos** os erros da tarefa associada através do evento de fronteira, independentemente do código introduzido. O comportamento principal suportado é o próprio caminho de recurso: quando a tarefa associada falha por qualquer motivo, o caminho de erro é executado em vez de parar silenciosamente esse ramo.
### Exemplo
Uma regra de conformidade com vários sensores enriquece leituras interiores com um sensor de referência exterior. O nó Enriquecimento do sensor exterior tem um Evento de Erro de Fronteira associado. Se o sensor exterior estiver inacessível:
1. O Evento de Erro de Fronteira captura a falha
2. O seu fluxo de saída conduz a um nó Definir Alarme configurado com uma definição de alarme "Sensor Offline"
3. A equipa de operações recebe uma notificação de que o sensor de referência exterior não está a reportar, por isso sabe que a comparação de conformidade não pôde ser realizada
Sem o Evento de Erro de Fronteira, a falha de enriquecimento interromperia silenciosamente esse caminho de execução — e a equipa não saberia que o sensor estava offline.
***
## Ligações (Fluxos de Sequência)
As ligações são as setas entre nós na tela. Definem a ordem de execução — os dados fluem ao longo destas setas de um nó para o seguinte.
### Desenhar ligações
Use a **Ferramenta Global de Ligação** da paleta, ou passe o cursor sobre um nó de origem até aparecerem as pegas de ligação e arraste da origem para o nó de destino.
### Regras de ligação
| Regra | Detalhes |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Eventos Iniciais** | Um fluxo de saída. Sem fluxos de entrada. |
| **Eventos Finais** | Sem fluxos de saída. Um ou mais fluxos de entrada. |
| **Nós de tarefa** (Script Task, Definir Alarme, Executar Comando, Enriquecimento) | Um fluxo de saída. Um fluxo de entrada (ou associação de Evento de Erro de Fronteira). |
| **Gateways Exclusivos** | Um fluxo de entrada. Vários fluxos de saída (um por ramo). |
| **Eventos de Erro de Fronteira** | Exatamente um fluxo de saída. Sem fluxos de entrada (associado implicitamente ao pai). |
### Condições nos fluxos do gateway
Cada fluxo de saída de um Gateway Exclusivo — exceto o fluxo predefinido designado — tem de ter uma expressão de condição CEL. Estas condições têm de avaliar para um valor booleano (`verdadeiro` ou `falso`).
O fluxo predefinido deve **não** ter uma condição. Só é executado quando todas as outras condições avaliarem para falso.
Se criar um fluxo a partir de um gateway sem definir uma condição, a etapa de compilação assinalará isso como um erro e a regra não será compilada com êxito.
### Rótulos e cores dos fluxos
Os fluxos dos Gateways Exclusivos podem ter rótulos e cores (configurados no painel de propriedades do gateway). Use-os para tornar diagramas complexos legíveis à primeira vista — por exemplo, rotule um ramo "Crítico" a vermelho e outro "Aviso" a âmbar, com o ramo predefinido "Normal" a verde.
---
# 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/node-reference.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.
