Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Befehle an Geräte senden

Einen Befehlskatalog mit Stufen definieren, Befehle senden, deren Status und Ablauf verfolgen, sie auf dem Gerät beantworten und Geräteanfragen empfangen.

Ein Befehl (auch RPC genannt) fordert ein Gerät auf, 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 zur Verwaltung von Befehlen benötigt (Administratoren).

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

FeldBedeutung
MethodDer Name im Protokoll, namespace.verb, zum Beispiel sys.info. Buchstaben, Ziffern, _ und ..
Label, DescriptionWas Bediener sehen.
TierBasic, Privileged oder Critical: wer ihn senden darf (siehe unten).
High impact (asks for a confirmation)Der Absender muss bestätigen; der Befehl wird höchstens einmal gesendet und protokolliert.
Typed confirmation phraseOptional, nur bei hoher Auswirkung: Der Bediener gibt sie zum Senden ein (zum Beispiel REBOOT).
One-way (no answer)Das Gerät antwortet nicht.
Long-running (the answer only says it started)Das Gerät antwortet sofort und meldet das Ergebnis später.
Default timeout (ms)1.000 bis 600.000. Leer: die Default RPC timeout des Profils.
Persistent by default (delivered when the device comes back)Befehl in die Warteschlange stellen, während das Gerät offline ist.
ParametersAufgebaut mit Fields (Name, Label, Typ Text, Number, Yes / no, Choice oder Any value (JSON), required, min, max, choices) oder als Advanced (JSON). Bis zu 50 Parameter.
Masked parametersParameternamen, deren Werte nie im Verlauf angezeigt werden.

From a template startet 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

StufeWer ihn senden darf (Standard)
BasicBenutzer
PrivilegedAdministratoren
CriticalAdministratoren
Raw (eine Methode, die nicht im Katalog steht)Eigentümer

Hinweis

Manche Befehle werden unabhängig von dem Anfragenden nie gesendet: Werksreset, Kopplung, Vergessen des WLAN und cloud.forget. Manche Methodenfamilien gehören zu einem Modul, und nur dieses Modul sendet sie (zum Beispiel tunnel.* für den Fernzugriff und esim.*). Profile, die nur das Themenschema Legacy compatible verwenden, enthalten keine Befehle: „RPC ist für Geräte mit dem Schema Legacy compatible nicht verfügbar; verwenden Sie gemeinsame Attribute (Reiter Attributes), um Einstellungen zu senden.“

Einen Befehl senden

  1. Öffnen Sie das Gerät und seinen 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:
OptionBedeutungStandard
Do not wait for an answer (one-way)Das Gerät antwortet nicht.Aus (zweiseitig)
Answer timeout (seconds)Wie lange auf die Antwort gewartet wird, 1 bis 600 Sekunden.Der Standard des Befehls, sonst 10 Sekunden
Deliver when the device comes back (persistent)Den Befehl in der Warteschlange halten, während das Gerät offline ist.Der Standard des Befehls
Give up after (minutes)Wann ein wartender Befehl aufgegeben wird.24 Stunden; höchstens 7 Tage
  1. Wählen Sie Send. Ein Befehl mit hoher Auswirkung fragt Send sys.reboot? („Dieser Befehl wirkt sich auf das Gerät aus (es kann neu starten oder seine Sitzung verlieren).“) und, wenn er eine Phrase hat, Type REBOOT 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.

Befehlsstatus

StatusAngezeigt alsBedeutung
QUEUEDQueuedGespeichert, wartet auf das Gerät.
SENTSentAn das Gerät gesendet.
DELIVEREDDeliveredDas Gerät hat ihn empfangen.
SUCCESSFULSuccessfulDas Gerät hat mit Erfolg geantwortet.
FAILEDFailedDas Gerät hat mit einem Fehler geantwortet.
TIMEOUTTimed outKeine Antwort rechtzeitig. Das bedeutet „es kam keine Antwort an“, nicht „er wurde nicht ausgeführt“.
EXPIREDExpiredEr ist abgelaufen, bevor er zugestellt werden konnte.
CANCELLEDCancelledJemand hat ihn abgebrochen.

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

Der Verlauf

Der History im 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 sind maskiert.

Standardmäßige Grenzen: 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 ankommen. 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 sie überschritten, 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 mit GET /api/v1/rpc auf Befehle 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 fragen: 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 antworten darauf.

LoRaWAN

  • LoRaWAN-Geräte nehmen Roh-Downlinks mit dem Befehl lora.downlink entgegen. Siehe Sending downlinks.

Per API

POST/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc

Einen Befehl an ein Gerät senden. Body-Felder: method (erforderlich), params, oneway, persistent, timeoutMs (1,000 bis 600,000), expiresInS (1 bis 604,800), wait, confirm, confirmText, source (console, api oder dashboard_control). params darf höchstens 16 KiB JSON umfassen. Ein bidirektionaler, nicht persistenter Aufruf mit einem Timeout von höchstens 30 Sekunden wartet auf das Ende und antwortet mit 200. Jeder andere Aufruf antwortet sofort mit 202. Ein Befehl mit hoher Auswirkung benötigt "confirm": true.

Anfragetext application/json

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

Beispiel curl

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}'

Antworten

200OK
{
    "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",
        "…": "…"
    }
}
202Akzeptiert
{
    "rpc": {
        "rpcId": "…",
        "deviceId": "…",
        "method": "sys.reboot",
        "status": "QUEUED",
        "…": "…"
    }
}
400Ungültige Anfrage
{
    "message": "This command needs confirm: true.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "confirm_required"
    }
}
403Verboten

Kein Antworttext.

404Nicht gefunden
{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}
429Zu viele Anfragen

Kein Antworttext.

Einen Befehl lesen mit GET /tenant/{tenantId}/api/iot/rpc/{rpcId} und ihn mit POST …/rpc/{rpcId}/cancel abbrechen (nur solange er QUEUED oder SENT ist; wird im Audit-Log 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 protokolliert.