> 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-fr/kilo-iot-server/devices/commands/creating-commands.md).
# Création de commandes
Définissez une commande d’appareil dans Kilo IoT Server — routage MQTT ou LoRaWAN, paramètres typés, encodage de charge utile et test.
Une commande est une action réutilisable et nommée avec des entrées typées. Vous la créez une fois dans l’éditeur de commandes ; ensuite, les opérateurs l’exécutent depuis le **États** onglet ou un tableau de bord sans toucher aux topics, aux dispositions d’octets ou aux modèles de charge utile.
Pour commencer, ouvrez l’onglet de l’appareil **Commandes et états** onglet, restez sur le **Commandes** sous-onglet, et cliquez sur **Ajouter une nouvelle commande**. L’éditeur s’ouvre en quatre sections numérotées.
## 1. Identité
Donnez à la commande un nom clair, orienté action — c’est ce que voient les opérateurs lorsqu’ils l’exécutent.
* **Nom de la commande** — Obligatoire. Utilisez un libellé à l’impératif tel que `Redémarrer le contrôleur`, `Régler la luminosité`, ou `Ouvrir la vanne`. Les noms doivent être uniques sur l’appareil ; réutiliser un nom déclenche *"Une commande portant ce nom existe déjà sur cet appareil."*
* **Description** — Facultatif mais recommandé. Une ligne sur ce que fait la commande et quand l’utiliser.
## 2. Routage
Le routage indique à la plateforme *où* et *comment* le message est adressé. Les champs diffèrent selon le protocole.
### Appareils MQTT
* **Topic MQTT** — Là où le message est publié sur le broker. Obligatoire.
* Pour une connexion Cloud MQTT, le **préfixe du topic** en lecture seule est affiché et vous fournissez le reste (par exemple `mqtt-test-01/set`). L’appareil doit s’abonner au topic complet — le préfixe plus votre valeur.
* Pour une connexion MQTT externe, saisissez le topic complet exactement tel qu’il est publié sur votre broker (par exemple `devices/light-01/cmd`).
* Un topic doit comporter moins de 500 caractères, ne doit pas contenir les jokers `#` ou `+`, ne doit pas comporter de segments vides (`a//b`), et ne doit pas commencer par `iot/`, `external/`, ou `external-downlink/` — ces préfixes sont réservés au trafic propre de la plateforme.
* Si une autre commande sur la même connexion publie déjà vers le topic que vous saisissez, l’éditeur signale le chevauchement afin que vous évitiez de faire entrer en collision accidentellement deux actions sur un même topic.
* fPort et la liaison descendante confirmée ne s’appliquent pas à MQTT — ce sont des paramètres LoRaWAN.
### Appareils LoRaWAN
* **fPort** — Obligatoire. Le port LoRaWAN auquel la liaison descendante est adressée, un entier compris entre **1 et 223**.
* **Liaison descendante confirmée** — Un interrupteur :
* **Activé — attendre l’ACK MAC :** le réseau attend que l’appareil accuse réception au niveau radio.
* **Désactivé — envoi sans attente à la couche MAC :** la liaison descendante est envoyée sans attendre d’accusé de réception.
* Activez cela **on** si vous comptez vérifier la commande avec *Interroger après accusé de réception* dans la section 4 — cette stratégie attend l’accusé de réception, elle ne peut donc pas être enregistrée avec une liaison descendante non confirmée.
* Les liaisons descendantes LoRaWAN sont des octets bruts, donc la charge utile passe toujours par un encodeur — le mode d’envoi tel quel proposé pour MQTT n’est pas disponible ici.
### Appareils mioty
La liaison descendante confirmée s’applique ; fPort et le topic MQTT ne s’appliquent pas. Comme pour LoRaWAN, la charge utile est générée par un encodeur.
### Appareils qui ne peuvent pas recevoir de commandes
Les appareils connectés par Tracker sont en réception seule sur la plateforme : ils remontent des données, et il n’existe aucun chemin de liaison descendante vers eux. Ils ne proposent pas d’onglet Commandes.
## 3. Charge utile
Cette section définit le corps du message et les entrées qui le structurent.
### Paramètres
Les paramètres sont les entrées typées que l’opérateur renseigne au moment de l’exécution — un pourcentage de luminosité, une consigne, un mode. Cliquez sur **Ajouter un paramètre** pour chacun d’eux. Pour chaque paramètre :
* **Nom** et **Description** — la description est affichée aux opérateurs dans la boîte de dialogue d’exécution, donc faites-en quelque chose d’utile.
* **Type** — parmi :
* **Entier** / **Flottant** — numérique, avec en option **Min**, **Max**, et **Valeur par défaut**. Une valeur par défaut hors plage est rejetée, et **Max** doit être supérieure à **Min**.
* **Chaîne** — avec en option **Longueur min**, **Longueur max**, une liste d’ **Enum** (par exemple `auto, manuel, désactivé`), et un **Valeur par défaut**.
* **Booléen** — avec une **Valeur par défaut** de `Aucune valeur par défaut`, `vrai`, ou `faux`.
Les paramètres typés permettent de confier les commandes à un opérateur en toute sécurité : une consigne ne peut pas être envoyée hors plage, et un mode ne peut être que l’une des valeurs autorisées.
### Construction du corps du message
**MQTT** offre deux modes :
* **Envoyer tel quel** — Publiez directement le corps JSON. Idéal lorsque l’appareil ou un consommateur en amont accepte du JSON.
* **Traiter avec un encodeur** — Faites passer le corps par une fonction d’encodage avant publication.
En mode encodeur (et toujours pour LoRaWAN, où les liaisons descendantes doivent être des octets bruts), vous définissez un **Modèle d’entrée de l’encodeur** — l’objet JSON transmis au codec, en utilisant `{{ parameterName }}` comme espaces réservés pour substituer les entrées de l’opérateur. Chaque espace réservé doit correspondre à un paramètre défini ci-dessus. Pour LoRaWAN, la plateforme indique que les liaisons descendantes sont des octets ; un encodeur est donc toujours requis ; vous pouvez utiliser l’encodeur défini sur le connecteur ou activer **Utiliser un JS d’encodeur personnalisé** pour le remplacer par une fonction propre à chaque commande.
Pour les commandes MQTT qui envoient une charge utile à l’identique (mode direct), vous fournissez plutôt la cible **Topic MQTT** et le **Charge utile directe**, qui est envoyée telle quelle — `{{ parameterName }}` la substitution s’applique toujours aux valeurs typées.
## Essayer l’encodeur
Chaque fois qu’une commande utilise un encodeur, l’éditeur inclut un **Essayer l’encodeur** outil (intitulé **Fonction de code** pour LoRaWAN, **Encodeur personnalisé** pour MQTT). Saisissez des entrées de test et exécutez-le pour voir exactement ce qui sera transmis avant d’enregistrer :
* le résultat encodé **Sortie**, ou une **Erreur** si la fonction a échoué
* le résultat en **Hex** et **Base64**, ainsi que la taille de la charge utile **Taille** en octets
* tout **Journal de la console** sortie et le temps d’exécution
Cela transforme l’encodage de la charge utile d’un jeu de devinettes en une étape vérifiable — vous confirmez que les octets sont corrects avant qu’une seule commande n’atteigne un appareil.
## 4. Vérification
La quatrième section décide comment la plateforme confirme que la commande a bien pris effet — envoi sans retour, attente de la prochaine liaison montante de l’appareil, ou interrogation de l’appareil après son accusé de réception. C’est là que vous déclarez quel capteur doit changer et quelle valeur il doit afficher.
Cette section a sa propre page : voir [Confirmation des commandes](/kilo-docs-fr/kilo-iot-server/devices/commands/verification.md). Pour savoir quelles valeurs l’appareil renvoie — et sous quelle forme — voir [Décodage des charges utiles et clés des connecteurs](/kilo-docs-fr/kilo-iot-server/devices/payload-decoding.md).
## Enregistrement
Cliquez sur **Enregistrer** pour ajouter la commande à l’appareil. Elle apparaît immédiatement dans la **Commandes** liste et dans l’ **États** onglet, prête à être exécutée. Pour la modifier plus tard, rouvrez-la depuis la liste des commandes avec **Modifier**; pour la supprimer, utilisez **Supprimer** (la plateforme vous avertit si d’autres commandes y font référence comme commande de requête).
## Suivant
* Décidez comment la plateforme confirme qu’une commande a fonctionné — voir [Confirmation des commandes](/kilo-docs-fr/kilo-iot-server/devices/commands/verification.md).
* Exécutez une commande et suivez son cycle de vie — voir [Exécution des commandes](/kilo-docs-fr/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-fr/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.
