> 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/devices/commands/executing-commands.md).
# Executar Comandos
Envie comandos de dispositivo a partir do separador Estados no Kilo IoT Server e acompanhe cada um até confirmado, aviso suave ou falhado.
Uma vez que um dispositivo tenha comandos definidos, a **separador Estados** sub-aba da **separador Comandos & Estados** aba é onde você o opera. Ela mostra o que você pode executar, permite enviar um comando com os seus parâmetros e regista o resultado de tudo o que você enviou.
## Comandos disponíveis
A **Comandos disponíveis** lista todos os comandos definidos no dispositivo:
| Coluna | Mostra |
| --------------- | --------------------------------------- |
| **Nome** | O nome orientado para a ação do comando |
| **Descrição** | O que faz |
| **Parâmetros** | Quantas entradas digitadas ele requer |
| **Verificação** | Como a plataforma confirma o resultado |
| **Executar** | A ação que envia o comando |
Se a tabela estiver vazia, o dispositivo ainda não tem comandos — abra a **Comandos** sub-aba e defina um (ver [Criar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/creating-commands.md)).
## Executar um comando
Clique em **Executar** num comando para abrir a **Executar comando** diálogo.
* Se o comando não tiver parâmetros, o diálogo apenas confirma que não há nada a definir — prima **Executar** para o enviar.
* Se tiver parâmetros, preencha cada **Valor**. As entradas numéricas mostram o intervalo permitido (por exemplo `Mín: 0 - Máx: 100`), e o diálogo impõe os limites definidos no comando, por isso não pode enviar um valor que o dispositivo rejeitaria.
* Clique em **Executar** para enviar, ou **Cancelar** para voltar atrás.
O comando é enviado para o dispositivo e a plataforma começa a acompanhá-lo de acordo com a estratégia de verificação do comando.
## Quando um dispositivo está offline
Se não houver comunicação do dispositivo dentro da sua janela esperada, surge um banner no topo do separador Estados indicando que o dispositivo está offline, juntamente com a última vez que foi visto. Os comandos não podem ser executados interativamente num dispositivo offline — mas os comandos em fila são enviados automaticamente quando o dispositivo volta a ligar-se, por isso a intenção de controlo nunca se perde silenciosamente.
## Execuções recentes
Cada envio é registado na **Execuções recentes** tabela, dando-lhe um histórico contínuo da atividade de controlo no dispositivo:
| Coluna | Mostra |
| -------------- | ----------------------------------------------- |
| **Comando** | Qual comando foi executado |
| **Iniciado** | Quando foi enviado |
| **Atualizado** | Quando o seu estado mudou pela última vez |
| **Estado** | O resultado do ciclo de vida (abaixo) |
| **Detalhes** | Uma nota em linguagem simples sobre o resultado |
### Estado de execução
A plataforma resume todo o ciclo de vida da entrega em cinco resultados claros:
* **Pendente** — Em curso. O comando foi enviado e está a passar pela entrega e, se configurado, pela verificação.
* **Confirmado** — Sucesso verificado. A verificação foi configurada e o estado reportado pelo dispositivo correspondia ao esperado.
* **Entregue** — O downlink foi aceite para entrega, mas o comando usa **Sem verificação**, por isso a plataforma não está a verificar se o dispositivo atuou sobre ele. O comando foi enviado; o seu efeito não é verificado por design — distinto do verificado **Confirmado**.
* **Aviso leve** — Entregue e reconhecido, mas a plataforma não conseguiu confirmar o efeito dentro da janela de convergência. Trate isto como «não foi possível verificar», e não como «falhou definitivamente» — vale a pena analisar, mas é bem possível que o comando tenha funcionado.
* **Falhado** — O comando não foi executado. A **Detalhes** coluna explica porquê — por exemplo, uma falha de validação ou uma fila de downlink do dispositivo cheia.
A **Detalhes** texto fornece a razão legível por humanos por detrás de cada estado, por isso triagem de um comando problemático raramente exige sair da página.
### Razões comuns na coluna Detalhes
Quando um comando cai em **Aviso leve** ou **Falhado**, a coluna Detalhes nomeia a causa em linguagem simples. As que verá com mais frequência:
| O que os Detalhes dizem | O que significa |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| A fila de downlink do dispositivo está cheia. | A fila de downlink pendente do dispositivo está saturada — aguarde ou limpe-a antes de reenviar. |
| Falha na validação. | O pedido não passou na validação — verifique os parâmetros e o payload do comando. |
| Payload demasiado grande para o dispositivo. | O payload codificado excede o que o dispositivo aceita à sua taxa de dados atual. |
| Enviado, mas o dispositivo não confirmou a receção. | O downlink foi enviado, mas não voltou qualquer confirmação (downlinks confirmados). |
| Enviado, mas o dispositivo não confirmou o estado esperado a tempo. | Entregue, mas o estado esperado do sensor não chegou dentro da janela de convergência. |
| Dispositivo offline — comando não entregue a tempo. | O dispositivo não estava alcançável dentro da sua janela de receção. |
| Nenhum gateway disponível para alcançar o dispositivo. | Nenhum gateway estava ao alcance para transmitir o downlink. |
| A autenticação do broker falhou. | A ligação MQTT rejeitou a publicação — verifique as credenciais do conector. |
| Não foi possível enviar o comando. Tente novamente mais tarde. | Um erro transitório de envio — tente novamente. |
| Payload inválido — verifique o comando. | O payload estava malformado para o dispositivo — reveja o codificador ou o modelo. |
Estes são os casos comuns; podem aparecer outras mensagens, e a plataforma transmite a razão subjacente quando tem uma mais específica.
## Operar comandos a partir de um painel
Para o controlo do dia a dia, nem precisa de abrir a página de detalhes do dispositivo. Adicione um [Widget de controlo](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/control-widget.md) a um painel, associe-o ao comando de um dispositivo controlável, e qualquer pessoa com acesso a esse painel pode operar o dispositivo com um único Interruptor ou Botão — suportado pelo mesmo pipeline de execução e histórico descritos aqui.
Também pode enviar um comando pedindo. O [Assistente de IA para IoT](/kilo-docs-pt/kilo-iot-server/ai-assistant.md) integrado listará os comandos de um dispositivo, executará um após mostrar o que está prestes a enviar e esperar pela sua confirmação, e depois reportará o estado de entrega — e um cliente externo ligado através do [Servidor MCP](/kilo-docs-pt/kilo-iot-server/api/mcp-server.md) pode fazer o mesmo. De qualquer forma, o envio passa pelo pipeline descrito nesta página e fica no mesmo histórico.
## Relacionado
* [Criar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/creating-commands.md) — defina as ações que um dispositivo pode executar
* [Confirmar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/verification.md) — defina como a plataforma verifica um resultado
* [Exemplo: Tomada Inteligente](/kilo-docs-pt/kilo-iot-server/devices/commands/smart-socket-example.md) — criar e verificar dois comandos de ponta a ponta
* [Widget de controlo](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/control-widget.md) — colocar um comando num painel
* [Construindo com IA](/kilo-docs-pt/kilo-iot-server/ai-assistant/building-with-ai.md) — executar um comando pedindo ao assistente
* [Servidor MCP](/kilo-docs-pt/kilo-iot-server/api/mcp-server.md) — executar um comando a partir do ChatGPT, Claude ou outro cliente de IA
---
# 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/devices/commands/executing-commands.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.
