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. Pour savoir quelles valeurs l’appareil renvoie — et sous quelle forme — voir Décodage des charges utiles et clés des connecteurs.

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.

• Exécutez une commande et suivez son cycle de vie — voir Exécution des commandes.