Befehle an Geräte senden

Ein Befehl (auch RPC genannt) veranlasst ein Gerät, etwas zu tun: neu starten, einen Ausgang schalten, einen Test ausführen. Jeder Befehl wird als Anfrage gespeichert, und Sie können ihn verfolgen, bis das Gerät antwortet. Befehle werden nur über TLS-Sitzungen gesendet (sofern das Profil einen Befehl im Klartext nicht erlaubt), niemals über die Flows, die Telemetrie verarbeiten, und jeder Befehl wird anhand der Berechtigungen des Absenders geprüft.

Der Befehlskatalog

Jedes Geräteprofil hat einen Reiter Commands: „Die Befehle, die Bediener an die Geräte dieses Profils senden dürfen; jede Stufe benötigt eine eigene Berechtigung.“ Zum Bearbeiten wird die Berechtigung zum Verwalten von Befehlen (Administratoren) benötigt.

Wählen Sie Add command und füllen Sie aus:

From a template beginnt das Formular mit einem Befehl, den die Plattform bereits sendet (etwa eine Board-Steuerung). Import ersetzt den gesamten Katalog durch einen Export ({"commands": [ … ]}); Export zeigt den Katalog als JSON. Ein Profil enthält bis zu 200 Befehle.

Stufen

Einen Befehl senden

1. Öffnen Sie das Gerät und den Reiter Commands.
2. Wählen Sie unter Choose a command einen Befehl (oder Other method (raw), nur für Eigentümer) und füllen Sie dessen Parameters aus.
3. Legen Sie bei Bedarf die Optionen fest:

1. Wählen Sie Send. Ein Befehl mit hoher Auswirkung fragt Send {method}? („Dieser Befehl wirkt sich auf das Gerät aus (es kann neu starten oder seine Sitzung verlieren).“) und, wenn er eine Phrase hat, Type {phrase} to confirm.

Ist das Gerät offline, warnt der Reiter: „Das Gerät ist offline: Ohne „persistent“ schlägt der Befehl sofort fehl.“

Dashboards, SCADA-Symbole, Regeln und Flows können ebenfalls Befehle senden. Eine Board-Steuerung sendet nur Befehle der Stufe Basic. Siehe Control cards.

Befehlszustände

Ein langlaufender Befehl zeigt Running on the device, bis sein Ergebnis eintrifft; ein Befehl ohne Antwort zeigt No answer: the outcome is unknown; eine Antwort nach dem Ende zeigt Answered after the end.

Der Verlauf

Der History auf dem Reiter Commands listet Method, Status, Sent by (Console, API, A flow, Firmware update, An alarm action, A dashboard control), Created, Completed und Duration. Öffnen Sie einen Befehl, um seine Request, Response und Progress zu sehen, um Cancel command zu wählen, solange er in der Warteschlange steht oder gesendet ist, oder um Send again zu wählen. Geheime Parameter werden maskiert.

Standardgrenzwerte: 10 Befehle pro Gerät und Minute sowie 600 pro Organisation und Minute; Parameter bis 16 KiB JSON; eine Antwort bis 64 KiB. Der Verlauf wird 90 Tage aufbewahrt.

Auf dem Gerät

Das Gerät abonniert v1/rpc/req/+ und empfängt:

PUBLISH v1/rpc/req/42
{"method": "sys.ping", "params": {"host": "8.8.8.8", "count": 3}}

Bei einem zweiseitigen Befehl antwortet es mit derselben ID:

PUBLISH v1/rpc/res/42
{"ok": true, "result": {"sent": 3, "received": 3, "avg_ms": 18.2}}

Regeln für das Gerät:

• Ein Befehl kann zweimal eintreffen. Merken Sie sich mindestens die letzten 32 Anfrage-IDs für 10 Minuten und führen Sie dieselbe ID nie zweimal aus.
• Enthält die Anfrage expirationTime und ist diese Zeit verstrichen, führen Sie sie nicht aus; antworten Sie mit {"ok": false, "error": "expired"}.
• Ist eine Anfrage größer, als das Gerät verarbeiten kann, führen Sie sie nicht aus; antworten Sie mit {"ok": false, "error": "payload_too_large"}.
• Befehle werden erst zugestellt, nachdem das Gerät v1/rpc/req/+ auf dieser Verbindung abonniert hat.

HTTP-Geräte warten auf Befehle mit GET /api/v1/rpc und antworten mit POST /api/v1/rpc/{id}. Siehe Device HTTP API.

Langlaufende Befehle

PUBLISH v1/rpc/res/43
{"ok": true, "accepted": true, "job_id": "43"}

PUBLISH v1/attributes
{"rpc_result": {"job_id": "43", "method": "sys.traceroute", "ok": true, "result": {...}, "ts": 1759572042000}}

Anfragen vom Gerät

Ein Gerät kann auch die Cloud anfragen: Veröffentlichen Sie an v1/rpc/up/req/{id} mit {"method": …, "params": …} und lesen Sie die Antwort auf v1/rpc/up/res/{id}. Ihre Flows empfangen diese Anfragen und beantworten sie.

LoRaWAN und Gateway-Kindgeräte

• LoRaWAN-Geräte erhalten Roh-Downlinks mit dem Befehl lora.downlink. Siehe Sending downlinks.
• Befehle an Geräte hinter einem Gateway sind in Entwicklung. Siehe Commands to devices behind a gateway.

Per API

{
    "method": "sys.ping",
    "params": {
        "host": "8.8.8.8",
        "count": 3
    },
    "timeoutMs": 10000
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"sys.ping","params":{"host":"8.8.8.8","count":3},"timeoutMs":10000}'

{
    "rpc": {
        "rpcId": "…",
        "deviceId": "…",
        "method": "sys.ping",
        "status": "SUCCESSFUL",
        "outcome": null,
        "response": {
            "ok": true,
            "result": {
                "sent": 3,
                "received": 3,
                "avg_ms": 18.2
            }
        },
        "tier": "basic",
        "highImpact": false,
        "source": "api",
        "…": "…"
    }
}

{
    "rpc": {
        "rpcId": "…",
        "deviceId": "…",
        "method": "sys.reboot",
        "status": "QUEUED",
        "…": "…"
    }
}

{
    "message": "This command needs confirm: true.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "confirm_required"
    }
}

{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Einen Befehl liest du mit GET /tenant/{tenantId}/api/iot/rpc/{rpcId}, und du brichst ihn mit POST …/rpc/{rpcId}/cancel ab (nur solange er QUEUED oder SENT ist; wird protokolliert). Das Feld outcome zeigt running, unknown oder late, wie oben beschrieben. Siehe Commands API.

Die Webhook-Ereignisse rpc.completed und rpc.failed informieren andere Systeme über das Ergebnis. Befehle mit hoher Auswirkung und Raw-Befehle werden bei ihrer Erstellung und bei ihrem Abschluss im Audit-Log erfasst.