> 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/creating-commands.md).
# Criar Comandos
Defina um comando de dispositivo no Kilo IoT Server — encaminhamento MQTT ou LoRaWAN, parâmetros tipados, codificação do payload e um teste.
Um comando é uma ação reutilizável e nomeada, com entradas tipadas. Você o cria uma vez no editor de comandos; depois disso, os operadores o executam a partir da **separador Estados** aba ou de um painel, sem mexer em tópicos, layouts de bytes ou modelos de payload.
Para começar, abra a **separador Comandos & Estados** aba do dispositivo, permaneça na **Comandos** subaba e clique em **Adicionar novo comando**. O editor abre em quatro secções numeradas.
## 1. Identidade
Dê ao comando um nome claro e orientado para a ação — é o que os operadores veem quando o executam.
* **Nome do comando** — Obrigatório. Use uma designação no imperativo, como `Reiniciar controlador`, `Definir brilho`, ou `Abrir válvula`. Os nomes devem ser exclusivos no dispositivo; reutilizar um deles gera *"Já existe um comando com este nome neste dispositivo."*
* **Descrição** — Opcional, mas recomendado. Uma linha sobre o que o comando faz e quando usá-lo.
## 2. Encaminhamento
O encaminhamento diz à plataforma *onde* e *como* a mensagem é endereçada. Os campos diferem consoante o protocolo.
### Dispositivos MQTT
* **Tópico MQTT** — Onde a mensagem é publicada no broker. Obrigatório.
* Para uma ligação Cloud MQTT, o **prefixo do tópico** de leitura apenas é apresentado e você fornece o restante (por exemplo `mqtt-test-01/set`). O dispositivo deve subscrever o tópico completo — prefixo mais o seu valor.
* Para uma ligação MQTT Externa, introduza o tópico completo exatamente como é publicado no seu broker (por exemplo `devices/light-01/cmd`).
* Um tópico deve ter menos de 500 caracteres, não pode conter os curingas `#` ou `+`, não pode ter segmentos vazios (`a//b`), e não pode começar com `iot/`, `external/`, ou `external-downlink/` — esses prefixos são reservados para o tráfego próprio da plataforma.
* Se outro comando na mesma ligação já publicar para o tópico que você introduzir, o editor assinala a sobreposição para que possa evitar colidir acidentalmente duas ações no mesmo tópico.
* fPort e Confirmed downlink não se aplicam ao MQTT — essas são definições de LoRaWAN.
### Dispositivos LoRaWAN
* **fPort** — Obrigatório. A porta LoRaWAN para a qual o downlink é endereçado, um inteiro entre **1 e 223**.
* **Downlink confirmado** — Um botão de alternância:
* **Ligado — aguardar ACK MAC:** a rede aguarda que o dispositivo confirme a receção na camada de rádio.
* **Desligado — enviar e esquecer na camada MAC:** o downlink é enviado sem aguardar uma confirmação.
* Ative isto **ligado** se pretende verificar o comando com *Consulta após ACK* na secção 4 — essa estratégia aguarda a confirmação, por isso não pode ser guardada contra um downlink não confirmado.
* Os downlinks LoRaWAN são bytes brutos, por isso o payload passa sempre por um codificador — o modo enviar tal como está oferecido para MQTT não está disponível aqui.
### Dispositivos mioty
Aplica-se o downlink confirmado; fPort e tópico MQTT não se aplicam. Tal como no LoRaWAN, o payload é gerado por um codificador.
### Dispositivos que não podem receber comandos
Os dispositivos ligados ao Tracker são apenas de receção na plataforma: fazem o reporte e não existe um caminho de downlink para eles. Não oferecem uma aba Comandos.
## 3. Payload
Esta secção define o corpo da mensagem e as entradas que o moldam.
### Parâmetros
Os parâmetros são as entradas tipadas que um operador preenche no momento da execução — uma percentagem de brilho, um setpoint, um modo. Clique em **Adicionar parâmetro** para cada um. Por parâmetro:
* **Nome** e **Descrição** — a descrição é mostrada aos operadores na caixa de diálogo Executar, por isso torne-a útil.
* **Tipo** — um de:
* **Inteiro** / **Flutuante** — numérico, com opcional **Mín.**, **Max**, e **Predefinição**. Uma predefinição fora do intervalo é rejeitada, e **Max** deve ser maior do que **Mín.**.
* **String** — com opcional **Comprimento mínimo**, **Comprimento máximo**, uma opção separada por vírgulas **Enumeração** (por exemplo `auto, manual, off`), e um **Predefinição**.
* **Booleano** — com um **Predefinição** de `Sem predefinição`, `verdadeiro`, ou `falso`.
Os parâmetros tipados são o que torna os comandos seguros para serem entregues a um operador: um setpoint não pode ser enviado fora do intervalo e um modo só pode ser um dos valores permitidos.
### Construção do corpo da mensagem
**MQTT** oferece dois modos:
* **Enviar tal como está** — Publica o corpo JSON diretamente. Melhor quando o dispositivo ou um consumidor a montante aceita JSON.
* **Processar com codificador** — Executa o corpo através de uma função codificadora antes de publicar.
No modo codificador (e sempre no LoRaWAN, onde os downlinks têm de ser bytes brutos), você define um **Modelo de entrada do codificador** — o objeto JSON passado ao codec, usando `{{ parameterName }}` espaços reservados para substituir as entradas do operador. Cada espaço reservado deve corresponder a um parâmetro definido acima. Para LoRaWAN, a plataforma assinala que os downlinks são bytes, por isso é sempre necessário um codificador; você pode usar o codificador definido no conector ou ativar **Usar JS de codificador personalizado** para o substituir por uma função por comando.
Para comandos MQTT que enviam um payload literalmente (modo direto), você fornece em vez disso o alvo **Tópico MQTT** e o **Payload direto**, que é enviado tal como escrito — `{{ parameterName }}` a substituição continua a aplicar-se aos valores tipados.
## Experimentar codificador
Sempre que um comando usa um codificador, o editor inclui uma **Experimentar codificador** ferramenta (intitulada **Função de código** para LoRaWAN, **Codificador personalizado** para MQTT). Introduza entradas de teste e execute-a para ver exatamente o que será transmitido antes de guardar:
* o codificado **Saída**, ou um **Erro** se a função falhou
* o resultado como **Hex** e **Base64**, mais o payload **Tamanho** em bytes
* qualquer **registo da consola** saída e o tempo de execução
Isto transforma a codificação do payload de um jogo de adivinhação numa etapa verificável — confirma que os bytes estão corretos antes de qualquer comando chegar a um dispositivo.
## 4. Verificação
A quarta secção decide como a plataforma confirma que o comando realmente produziu efeito — enviar e esquecer, esperar pelo próximo uplink do dispositivo ou interrogar o dispositivo depois de ele confirmar. É aqui que declara qual sensor deve mudar e o que ele deve ler.
Esta secção tem uma página própria: veja [Confirmar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/verification.md). Para saber que valores o dispositivo reporta de volta — e em que formato — veja [Descodificação de payload e chaves do conector](/kilo-docs-pt/kilo-iot-server/devices/payload-decoding.md).
## Guardar
Clique em **Salvar** para adicionar o comando ao dispositivo. Ele aparece imediatamente na **Comandos** lista e na **separador Estados** aba, pronto a executar. Para o alterar mais tarde, volte a abri-lo a partir da lista Comandos com **Editar**; para o remover, use **Eliminar** (a plataforma avisa-o se outros comandos o referenciarem como comando de consulta).
## Seguinte
* Decida como a plataforma confirma que um comando funcionou — veja [Confirmar Comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/verification.md).
* Execute um comando e acompanhe o seu ciclo de vida — veja [Executar comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/executing-commands.md).
---
# 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/creating-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.
