Sending commands to devices

A command (also called RPC) asks a device to do something: reboot, switch an output, run a test. Every command is stored as a request, and you can follow it until the device answers. Commands are sent only over TLS sessions (unless the profile allows a command in clear), never through the flows that process telemetry, and each one is checked against the sender’s permissions.

The command catalog

Each device profile has a Commands tab: “The commands operators may send to the devices of this profile; each tier needs its own permission.” Editing it needs the permission to manage commands (administrators).

Select Add command and fill in:

From a template starts the form from a command the platform already sends (such as a board control). Import replaces the whole catalog with an export ({"commands": [ … ]}); Export shows the catalog as JSON. A profile holds up to 200 commands.

Tiers

Send a command

1. Open the device and its Commands tab.
2. Pick a command under Choose a command (or Other method (raw), owners only) and fill in its Parameters.
3. Set the options if needed:

1. Select Send. A high-impact command asks Send {method}? (“This command has an impact on the device (it may restart or lose its session).”) and, when it has a phrase, Type {phrase} to confirm.

If the device is offline, the tab warns: “The device is offline: without “persistent” the command fails at once.”

Dashboards, SCADA symbols, rules and flows can also send commands. A board control sends only basic-tier commands. See Control cards.

Command states

A long-running command shows Running on the device until its result arrives; a command that timed out shows No answer: the outcome is unknown; an answer after the end shows Answered after the end.

The history

The History on the Commands tab lists Method, Status, Sent by (Console, API, A flow, Firmware update, An alarm action, A dashboard control), Created, Completed and Duration. Open a command to see its Request, Response and Progress, to Cancel command while it is queued or sent, or to Send again. Secret parameters are masked.

Limits by default: 10 commands per device per minute and 600 per organisation per minute; parameters up to 16 KiB of JSON; an answer up to 64 KiB. History is kept for 90 days.

On the device

The device subscribes to v1/rpc/req/+ and receives:

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

For a two-way command it answers on the same id:

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

Rules for the device:

• A command may arrive twice. Remember at least the last 32 request ids for 10 minutes and never run the same id twice.
• If the request carries expirationTime and it has passed, do not run it; answer {"ok": false, "error": "expired"}.
• If a request is larger than the device can take, do not run it; answer {"ok": false, "error": "payload_too_large"}.
• Commands are delivered only after the device has subscribed to v1/rpc/req/+ on this connection.

HTTP devices wait for commands with GET /api/v1/rpc and answer with POST /api/v1/rpc/{id}. See Device HTTP API.

Long-running commands

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

Requests from the device

A device can also ask the cloud: publish to v1/rpc/up/req/{id} with {"method": …, "params": …} and read the answer on v1/rpc/up/res/{id}. Your flows receive and answer these requests.

LoRaWAN and gateway children

• LoRaWAN devices take raw downlinks with the command lora.downlink. See Sending downlinks.
• Commands to devices behind a gateway are in development. See Commands to devices behind a gateway.

By 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"
}

Read a command with GET /tenant/{tenantId}/api/iot/rpc/{rpcId} and cancel it with POST …/rpc/{rpcId}/cancel (only while QUEUED or SENT; audited). The outcome field reads running, unknown or late as described above. See Commands API.

The webhook events rpc.completed and rpc.failed tell other systems the outcome. High-impact and raw commands are written to the audit log when they are created and when they end.