> 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-de/kilo-iot-server/devices/commands/creating-commands.md).
# 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.
## 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](/kilo-docs-de/kilo-iot-server/devices/commands/verification.md). Um herauszufinden, welche Werte das Gerät zurückmeldet — und in welcher Form — siehe [Payload-Dekodierung und Connector-Schlüssel](/kilo-docs-de/kilo-iot-server/devices/payload-decoding.md).
## 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](/kilo-docs-de/kilo-iot-server/devices/commands/verification.md).
* Führen Sie einen Befehl aus und beobachten Sie seinen Lebenszyklus — siehe [Befehle ausführen](/kilo-docs-de/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-de/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.
