Command & Control
ThingsBoard RPC (Remote Procedure Call) enables bidirectional command exchange between the platform and devices. Commands can flow in either direction: the platform sends instructions to a device (server-side RPC), or a device asks the platform for data (client-side RPC).
Server-Side RPC
Section titled “Server-Side RPC”The platform sends a command to a device — turn a relay on, change a setpoint, trigger a reboot. Commands can be sent from a dashboard widget, the Rule Engine, or directly via REST API.
One-Way vs. Two-Way
Section titled “One-Way vs. Two-Way”| One-Way | Two-Way | |
|---|---|---|
| Device reply | Not expected | Required within timeout |
| Use case | Fire-and-forget commands (turn on LED) | Commands that need confirmation or a result |
| REST response | 200 OK when ThingsBoard sent the command to the device — no visibility into whether the device processed it or succeeded | Device’s reply payload |
Lightweight vs. Persistent
Section titled “Lightweight vs. Persistent”Lightweight RPC is short-lived and memory-resident. If the device is offline when the command is sent, the command is lost. Good for real-time control of always-connected devices.
Persistent RPC is stored in the database with a configurable TTL. If the device is offline, the command waits until the device reconnects. Good for devices with intermittent connectivity or power-saving modes.
How It Works
Section titled “How It Works”Request Fields
Section titled “Request Fields”| Field | Required | Description |
|---|---|---|
method | Yes | Command name, e.g. setTemperature |
params | Yes | JSON parameters. Use {} if none. |
timeout | No | Milliseconds to wait for delivery (default: 10 000, min: 5 000) |
expirationTime | No | Epoch ms timestamp — overrides timeout |
persistent | No | true to store in DB and survive device offline (default: false) |
retries | No | Retry attempts for persistent RPC on timeout |
additionalInfo | No | Metadata attached to persistent RPC Rule Engine events |
Persistent RPC States
Section titled “Persistent RPC States”Persistent commands move through a state machine. Each transition fires a Rule Engine event you can use to track commands in external systems.
| State | Meaning |
|---|---|
QUEUED | Saved; awaiting delivery |
SENT | Platform sent to device |
DELIVERED | Device acknowledged (terminal for one-way) |
SUCCESSFUL | Device replied (terminal for two-way) |
TIMEOUT | Delivery timed out; retrying if retries remain |
EXPIRED | TTL elapsed before delivery |
FAILED | All retries exhausted |
Client-Side RPC
Section titled “Client-Side RPC”A device initiates a request to the platform — for example to fetch the current time, get a weather forecast, or query an access control decision. The platform processes it through the Rule Engine and replies.
How It Works
Section titled “How It Works”Each request carries a method string and a params JSON object. The Rule Engine message includes a requestId UUID in metadata, which the RPC Call Reply node uses to route the response back to the correct device.
Sending Commands from Dashboards
Section titled “Sending Commands from Dashboards”Control widgets (RPC Button, Round Switch, Knob Control, etc.) send server-side RPC commands using the same REST API under the hood. You configure the method name and parameters directly in the widget settings — no code required.
Protocol References
Section titled “Protocol References”See the transport-specific guides for exact topics, subscribe paths, and request/response examples:
- MQTT RPC API
- HTTP RPC API
- CoAP RPC API
- LwM2M RPC — server-side only