RPC

The MQTT RPC API lets ThingsBoard send commands to devices (server-side RPC) and lets devices call the platform for data (client-side RPC). See Command & Control for the full conceptual overview including persistent RPC and state machine, and Getting Connected for connection parameters and credential types.

ThingsBoard delivers a command to the device. The device optionally replies (two-way) or just receives it (one-way).

{"method": "setTemperature", "params": {"value": 26}}

For two-way RPC — publish the response to:

Use the same $request_id from the incoming topic.

# Subscribe to incoming RPC commands
mosquitto_sub -d -q 1 -h "mqtt.eu.thingsboard.cloud" -p 1883 -t "v2/r/req/+" -u "$ACCESS_TOKEN"

The following example is written in JavaScript and is based on mqtt.js. A pure command-line example is not available for server-side RPC: the device has to publish its response to a topic derived from the incoming request, which the command-line MQTT clients cannot do.

1. Save the mqtt-js-rpc-from-server.js file to your PC.

   The content of the mqtt-js-rpc-from-server.js file:

   var mqtt = require('mqtt');
   var client = mqtt.connect('mqtt://localhost', {
       username: process.env.TOKEN
   });
   
   client.on('connect', function () {
       console.log('connected');
       client.subscribe('v1/devices/me/rpc/request/+')
   });
   
   client.on('message', function (topic, message) {
       console.log('request.topic: ' + topic);
       console.log('request.body: ' + message.toString());
       var requestId = topic.slice('v1/devices/me/rpc/request/'.length);
       //client acts as an echo service
       client.publish('v1/devices/me/rpc/response/' + requestId, message);
   });

2. Now, follow these steps:

   • Use the RPC debug terminal widget in your ThingsBoard instance.

   • Execute the command to subscribe to RPC commands from the server:

     Install the mqtt package and start the subscriber:

     npm install mqtt --save
     export TOKEN=$ACCESS_TOKEN
     node mqtt-js-rpc-from-server.js

   • Send an RPC request connect to the device using the RPC debug terminal widget.

   • You should receive a response from the device.

The device asks ThingsBoard to perform an operation or return data — for example to fetch the current server time or query an external service via a Rule Chain.

ThingsBoard routes the request through the Rule Engine as a TO_SERVER_RPC_REQUEST message and replies on: v2/r/res/$request_id

Request and response payloads:

{"method": "getCurrentTime", "params": {}}

{"currentTime": 1735689600000}

syntax = "proto3";

message RpcRequest {
  string method = 1;
  string params = 2;
}

syntax = "proto3";

message ToServerRpcResponseMsg {
  int32 requestId = 1;
  string payload = 2;
  string error = 3;
}

A built-in client-side RPC that returns the current rate limits enforced for this device’s session. Useful for self-throttling in firmware.

Request:

{"method": "getSessionLimits", "params": {}}

Response:

{
  "maxPayloadSize": 65536,
  "maxInflightMessages": 100,
  "rateLimits": {
    "messages": "200:1,6000:60,14000:3600",
    "telemetryMessages": "100:1,3000:60,7000:3600",
    "telemetryDataPoints": "200:1,6000:60,14000:3600"
  }
}

Rate limit format: count:windowSeconds — e.g. 200:1 means 200 messages per second.