For the complete documentation index, see llms.txt. This page is also available as Markdown.

Befehle erstellen

Definieren Sie einen Gerätebefehl im Kilo IoT Server — MQTT- oder LoRaWAN-Routing, typisierte Parameter, Payload-Codierung und ein Test.

Ein Befehl ist eine wiederverwendbare, benannte Aktion mit typisierten Eingaben. Sie erstellen ihn einmal im Befehls-Editor; danach führen Bediener ihn von der Status Registerkarte oder einem Dashboard aus, ohne Topics, Byte-Layouts oder Payload-Vorlagen anzufassen.

Zu Beginn öffnen Sie die Befehle & Status Registerkarte, bleiben Sie auf der Befehle Unterregisterkarte und klicken Sie auf Neuen Befehl hinzufügen. Der Editor öffnet sich in vier nummerierten Abschnitten.

The Commands sub-tab of a device with no commands defined yet and the Add new command button
The command editor showing the Identity, Routing, and Payload sections

1. Identität

Geben Sie dem Befehl einen klaren, handlungsorientierten Namen — so sehen ihn Bediener bei der Ausführung.

  • Befehlsname — Erforderlich. Verwenden Sie eine imperative Bezeichnung wie Controller neu starten, Helligkeit einstellen, oder Ventil öffnen. Namen müssen auf dem Gerät eindeutig sein; die Wiederverwendung eines Namens führt zu "Ein Befehl mit diesem Namen existiert auf diesem Gerät bereits."

  • Beschreibung — Optional, aber empfohlen. Eine Zeile dazu, was der Befehl tut und wann er verwendet werden soll.

2. Weiterleitung

Die Weiterleitung sagt der Plattform wo und wie die Nachricht adressiert wird. Die Felder unterscheiden sich je nach Protokoll.

MQTT-Geräte

  • MQTT-Topic — Wohin die Nachricht auf dem Broker veröffentlicht wird. Erforderlich.

    • Bei einer Cloud-MQTT-Verbindung wird das schreibgeschützte Topic-Präfix angezeigt und Sie geben den Rest an (zum Beispiel mqtt-test-01/set). Das Gerät muss das vollständige Topic abonnieren — Präfix plus Ihr Wert.

    • Bei einer externen MQTT-Verbindung geben Sie das vollständige Topic genau so ein, wie es auf Ihrem Broker veröffentlicht wird (zum Beispiel devices/light-01/cmd).

    • Ein Topic darf höchstens 500 Zeichen lang sein, darf die Platzhalter # oder +nicht enthalten, darf keine leeren Segmente haben (a//b), und darf nicht mit iot/, external/, oder external-downlink/ beginnen — diese Präfixe sind für den eigenen Datenverkehr der Plattform reserviert.

  • Wenn ein anderer Befehl auf derselben Verbindung bereits zu dem von Ihnen eingegebenen Topic veröffentlicht, markiert der Editor die Überschneidung, damit Sie vermeiden können, versehentlich zwei Aktionen auf einem Topic kollidieren zu lassen.

  • fPort und bestätigter Downlink gelten nicht für MQTT — das sind LoRaWAN-Einstellungen.

LoRaWAN-Geräte

  • fPort — Erforderlich. Der LoRaWAN-Port, an den der Downlink adressiert ist, eine Ganzzahl zwischen 1 und 223.

  • Bestätigter Downlink — Ein Schalter:

    • Ein — auf MAC-Bestätigung warten: das Netzwerk wartet darauf, dass das Gerät den Empfang auf der Funkschicht bestätigt.

    • Aus — Senden ohne Bestätigung auf MAC-Ebene: der Downlink wird gesendet, ohne auf eine Bestätigung zu warten.

    • Schalten Sie dies ein wenn Sie den Befehl mit Abfrage nach Bestätigung in Abschnitt 4 verifizieren möchten — diese Strategie wartet auf die Bestätigung, daher kann sie nicht gegen einen unbestätigten Downlink gespeichert werden.

  • LoRaWAN-Downlinks sind Rohbytes, daher geht die Payload immer durch einen Encoder — der für MQTT angebotene Modus „unverändert senden“ ist hier nicht verfügbar.

mioty-Geräte

Bestätigter Downlink gilt; fPort und MQTT-Topic nicht. Wie bei LoRaWAN wird die Payload von einem Encoder erzeugt.

Geräte, die keine Befehle annehmen können

Tracker-verbundene Geräte sind auf der Plattform nur empfangsseitig: Sie senden Daten ein, und es gibt keinen Downlink-Pfad zurück zu ihnen. Sie bieten keine Registerkarte Befehle.

3. Payload

Dieser Abschnitt definiert den Nachrichtentext und die Eingaben, die ihn formen.

Parameter

Parameter sind die typisierten Eingaben, die ein Bediener zur Ausführungszeit ausfüllt — ein Helligkeitswert, ein Sollwert, ein Modus. Klicken Sie auf Parameter hinzufügen für jeden einzelnen. Pro Parameter:

  • Name und Beschreibung — die Beschreibung wird Bedienern im Dialog Ausführen angezeigt, machen Sie sie also nützlich.

  • Typ — einer von:

    • Ganzzahl / Gleitkommazahl — numerisch, mit optionalem Minimum, Maximum, und Standardwert. Ein Standardwert außerhalb des Bereichs wird abgelehnt, und Maximum muss größer sein als Minimum.

    • Zeichenfolge — mit optionalem Mindestlänge, Maximallänge, einem optionalen, kommagetrennten Enum (zum Beispiel auto, manuell, aus), und einem Standardwert.

    • Booleschen Wert — mit einem Standardwert von Kein Standardwert, wahr, oder falsch.

Typisierte Parameter machen Befehle sicher genug, um sie einem Bediener zu übergeben: Ein Sollwert kann nicht außerhalb des Bereichs gesendet werden, und ein Modus kann nur einen der zulässigen Werte haben.

Erstellen des Nachrichtentexts

MQTT bietet zwei Modi:

  • Unverändert senden — Den JSON-Body direkt veröffentlichen. Am besten, wenn das Gerät oder ein vorgelagerter Verbraucher JSON akzeptiert.

  • Mit Encoder verarbeiten — Den Body vor dem Veröffentlichen durch eine Encoder-Funktion laufen lassen.

Im Encoder-Modus (und immer für LoRaWAN, wo Downlinks Rohbytes sein müssen) definieren Sie eine Encoder-Eingabevorlage — das JSON-Objekt, das an den Codec übergeben wird, wobei {{ parameterName }} Platzhalter verwendet werden, um die Eingaben des Bedieners einzusetzen. Jeder Platzhalter muss zu einem oben definierten Parameter passen. Für LoRaWAN weist die Plattform darauf hin, dass Downlinks Bytes sind, daher ist immer ein Encoder erforderlich; Sie können den auf dem Connector definierten Encoder verwenden oder Benutzerdefiniertes Encoder-JS verwenden aktivieren, um ihn durch eine Funktion pro Befehl zu überschreiben.

Für MQTT-Befehle, die eine Payload unverändert senden (Direktmodus), geben Sie stattdessen das Ziel MQTT-Topic und die Direkte Payload, die unverändert gesendet wird — {{ parameterName }} Ersetzung gilt weiterhin für typisierte Werte.

Encoder testen

Wenn ein Befehl einen Encoder verwendet, enthält der Editor ein Encoder testen Tool (mit dem Titel Codefunktion für LoRaWAN, Benutzerdefinierter Encoder für MQTT). Geben Sie Testeingaben ein und führen Sie es aus, um genau zu sehen, was übertragen wird, bevor Sie speichern:

  • die codierte Ausgabe, oder einen Fehler wenn die Funktion fehlgeschlagen ist

  • das Ergebnis als Hex und Base64, plus die Payload- Größe in Bytes

  • jede Konsolenprotokoll Ausgabe und die Ausführungszeit

Dadurch wird Payload-Encoding von einem Ratespiel zu einem überprüfbaren Schritt — Sie bestätigen, dass die Bytes korrekt sind, bevor überhaupt ein einzelner Befehl ein Gerät erreicht.

4. Verifizierung

Im vierten Abschnitt wird festgelegt, wie die Plattform bestätigt, dass der Befehl tatsächlich wirksam wurde — senden und vergessen, auf den nächsten Uplink des Geräts warten oder das Gerät abfragen, nachdem es bestätigt hat. Hier legen Sie fest, welcher Sensor sich ändern soll und welchen Wert er anzeigen soll.

Dieser Abschnitt hat eine eigene Seite: siehe Befehle bestätigen. Um herauszufinden, welche Werte das Gerät zurückmeldet — und in welcher Form — siehe Payload-Dekodierung und Connector-Schlüssel.

Speichern

Klicken Sie auf Speichern um den Befehl zum Gerät hinzuzufügen. Er erscheint sofort in der Befehle Liste und auf der Status Registerkarte, bereit zur Ausführung. Um ihn später zu ändern, öffnen Sie ihn erneut aus der Befehlsliste mit Bearbeiten; um ihn zu entfernen, verwenden Sie Löschen (die Plattform warnt Sie, wenn andere Befehle ihn als Abfragebefehl referenzieren).

Weiter

  • Entscheiden Sie, wie die Plattform bestätigt, dass ein Befehl funktioniert hat — siehe Befehle bestätigen.

  • Führen Sie einen Befehl aus und beobachten Sie seinen Lebenszyklus — siehe Befehle ausführen.

Zuletzt aktualisiert