> 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/running-device-commands.md).

# Executar Comandos de Dispositivos

Faça uma regra Kilo agir por conta própria — o nó Executar Comando envia um comando ao dispositivo quando as condições são cumpridas.

Esta é a mudança que transforma o Motor de Regras de um sistema que *observa* num sistema que *age*. Até agora, quando uma regra detetava um problema, o máximo que podia fazer era disparar um alarme e colocar uma pessoa no circuito — alguém tinha de ler o alerta e ir acionar o interruptor. O **Executar Comando** nó fecha essa lacuna. Uma regra agora pode enviar um comando diretamente para um dispositivo no momento em que as suas condições são atendidas, sem ninguém no meio.

Considere o que isso significa na prática. Um sensor de fuga dispara numa sala técnica. Antes, a regra acionava um alarme e um operador corria para fechar a válvula principal — minutos de danos causados pela água de qualquer forma. Agora, a mesma regra fecha a válvula por si própria na mesma avaliação que detetou a fuga, e *então* dispara o alarme para que a equipa saiba que aconteceu. O armazenamento refrigerado sai da faixa e a regra envia um ponto de ajuste mais baixo para o controlador antes de o produto ficar em risco. Um tanque atinge a marca de nível alto e a regra fecha a entrada. Esta é automação em circuito fechado: detetar, decidir e agir, de ponta a ponta, numa única regra.

A ação é executada no mesmo [Comandos do Dispositivo](/kilo-docs-pt/kilo-iot-server/devices/commands.md) mecanismo que você usa manualmente — a regra simplesmente encaminha um comando que você já definiu no dispositivo. Assim, tudo o que torna os comandos manuais seguros (parâmetros tipados, verificação opcional, um registo completo de execução) aplica-se automaticamente quando uma regra executa um.

## Antes de começar

O nó Executar Comando envia um dos **existentes** comandos de um dispositivo. Não define novos. Portanto, antes que uma regra possa agir sobre um dispositivo:

1. **O dispositivo tem de ser controlável** — ligado por MQTT, ou um dispositivo LoRaWAN Classe C (os dispositivos Classe C escutam continuamente, para que possam receber um downlink a qualquer momento).
2. **O dispositivo tem de ter pelo menos um comando definido** — configure isto primeiro no **separador Comandos & Estados** . Consulte [Criar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/creating-commands.md).
3. **Você tem acesso para gerir a regra e os comandos do dispositivo** — ambos são regidos pela política de acesso da sua organização.

Se um dispositivo ainda não tiver comandos, não haverá nada para executar — defina primeiro o comando e depois volte à regra.

## Adicionar um nó Executar Comando

1. Abra a regra no [Editor Visual](/kilo-docs-pt/kilo-iot-server/rules-engine/visual-editor.md) e mude para **edição** modo.
2. Arraste **Executar Comando** da paleta para o canvas. Ele fica no mesmo grupo que Definir Alarme e Enriquecimento — é uma ação que a regra executa quando a execução chega até ele.
3. Ligue-o ao seu fluxo. Normalmente, vem depois de um ramo de Gateway Exclusivo — a regra avalia uma condição, e o ramo que significa "agir agora" leva ao nó Executar Comando.
4. Clique no nó para abrir o painel de propriedades e preencha os campos abaixo.
5. Clique em **Salvar**, depois **Construir** e implante a regra normalmente. O comando só é executado depois de a regra ser construída e estar em execução.

## Painel de propriedades

| Campo                 | Descrição                                                                                                                                                                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome**              | Um rótulo para o nó no canvas. Se o deixar em branco e escolher um comando, ele será preenchido com o nome do comando. Exemplo: "Fechar válvula de entrada".                                                                                          |
| **Dispositivo**       | Um menu suspenso pesquisável com os dispositivos na sua organização. Escolha o dispositivo para o qual o comando deve ser enviado.                                                                                                                    |
| **Comando**           | Um menu suspenso com os comandos definidos desse dispositivo. Desativado até um dispositivo ser selecionado; depois lista todos os comandos disponíveis no dispositivo escolhido.                                                                     |
| **Parâmetros**        | Aparece quando um comando é escolhido, com uma linha por parâmetro que o comando espera (um nível de brilho, um ponto de ajuste, uma flag abrir/fechar). Cada parâmetro é fornecido como um literal **Valor** ou uma **Expressão CEL** — veja abaixo. |
| **Entradas / Saídas** | Opcional. Expressões CEL nomeadas para modelagem avançada de dados, o mesmo padrão usado noutros nós. Use Entradas para preparar valores auxiliares e Saídas para publicar resultados para nós subsequentes.                                          |

**Salvar / Cancelar** ficam na parte inferior do painel.

### Definir parâmetros do comando: Valor ou Expressão

Cada parâmetro definido pelo comando recebe a sua própria linha, e para cada um escolhe como o valor é fornecido:

* **Valor** — um literal fixo que você digita. Use isto quando a regra deva enviar sempre o mesmo valor: um ponto de ajuste de `4`, um estado de `desligado`, um ciclo de trabalho de `100`. O campo é validado em relação à definição de parâmetros do comando, por isso um valor fora do intervalo ou do tipo errado é assinalado antes de poder guardar.
* **Expressão** — uma [CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) expressão avaliada quando a regra é executada. Isto é o que torna a ação *dinâmica*: o contexto em tempo real da regra está disponível através de `vars`, por isso um parâmetro de comando pode ser calculado a partir da própria leitura que acionou a regra. Por exemplo, defina a velocidade de uma ventoinha a partir da temperatura medida, ou passe diretamente o valor do sensor com `vars.value`.

A combinação é poderosa: um Gateway Exclusivo decide *se* agir, e uma expressão CEL no nó Executar Comando decide *que valor enviar* — assim uma única regra pode tanto reagir a um limite como responder proporcionalmente ao quanto a leitura o ultrapassou.

## O que acontece quando o nó é executado

1. A regra chega ao nó Executar Comando ao longo do seu fluxo.
2. Cada parâmetro é resolvido — literais tal como estão, expressões avaliadas em relação ao contexto atual `vars`.
3. O comando é enviado ao dispositivo como um downlink, via MQTT ou LoRaWAN, exatamente como se tivesse sido executado manualmente a partir do **separador Estados** .
4. O envio é registado no histórico de execução do dispositivo com o respetivo resultado (Pendente, Confirmado, Entregue, Aviso suave ou Falhado), por isso existe uma auditoria completa de cada ação que uma regra tomou.

Como o comando passa pelo caminho padrão de Comandos do Dispositivo, qualquer verificação configurada nesse comando aplica-se aqui também — a regra pode confirmar que o dispositivo realmente agiu, e não apenas que o downlink foi enviado. Consulte [Confirmar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/verification.md).

## Agir *e* alertar numa única regra

Agir num dispositivo não substitui o alerta — as duas coisas funcionam melhor em conjunto. Uma única regra pode fechar a válvula **e** disparar um alarme, de modo que a situação seja contida automaticamente *e* as pessoas certas sejam informadas. Uma forma comum:

| Etapa     | Nó                                   | O que faz                                                                             |
| --------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
| Detetar   | Evento de Início → Gateway Exclusivo | Associar ao sensor de fuga; ramificar quando for detetada uma fuga                    |
| Atuar     | Executar Comando                     | Enviar "fechar válvula" para a válvula de corte                                       |
| Notificar | Definir Alarme                       | Disparar um alarme Crítico para que a equipa saiba que a válvula foi fechada e porquê |

Se a própria ação puder falhar — por exemplo, se o dispositivo estiver brevemente offline — ligue um [Evento de Erro de Limite](/kilo-docs-pt/kilo-iot-server/rules-engine/node-reference.md#boundary-error-event) ao nó Executar Comando e encaminhe o caminho de erro para um Definir Alarme, para que um comando que não seja concluído continue a chegar a uma pessoa.

## Um exemplo prático

Uma regra de cadeia de frio protege um congelador farmacêutico. O Evento de Início associa-se à sonda de temperatura do congelador. Um Gateway Exclusivo encaminha qualquer leitura acima de −15 °C por um ramo de "a aquecer". Nesse ramo:

1. Um **Executar Comando** nó envia um `set_setpoint` comando para o controlador do congelador, com o parâmetro de ponto de ajuste definido como uma **Expressão** que reduz o alvo com base em quão longe a leitura se desviou — correção mais fria para um desvio maior.
2. Um **Definir Alarme** nó dispara um alarme de severidade Alta com uma mensagem de motivação que inclui a temperatura em tempo real, para que o engenheiro de plantão seja informado mesmo que a regra já tenha começado a corrigir o problema.

O produto é protegido no momento em que o desvio é detetado, e a equipa ainda obtém o quadro completo. Essa é a diferença entre uma plataforma que lhe diz que algo correu mal e uma que faz algo a respeito.

## Páginas relacionadas

* [Comandos do Dispositivo](/kilo-docs-pt/kilo-iot-server/devices/commands.md) — defina os comandos que uma regra pode executar e execute-os manualmente
* [Referência de Nó](/kilo-docs-pt/kilo-iot-server/rules-engine/node-reference.md) — todos os tipos de nó, incluindo Executar Comando, em detalhe
* [Referência CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) — a linguagem de expressões para valores dinâmicos de parâmetros
* [Widget de controlo](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/control-widget.md) — opere os mesmos comandos a partir de um painel


---

# 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/running-device-commands.md?ask=<question>&goal=<endgoal>
```

`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.