Community Edition
ThingsBoard Documentation
Cloud Professional Edition Community Edition Edge IoT Gateway License Server Trendz Analytics
Try it now Pricing
Documentation > Key concepts > Remote commands to devices
Getting Started
Guides Installation Architecture API FAQ

On this page

Using RPC capabilities

ThingsBoard allows you to send Remote Procedure Calls (RPC) from server-side applications to devices and vice versa. Basically, this feature allows you to send commands to devices and receive results of commands execution. Similarly, you can execute a request from the device, apply some calculations or other server-side logic on the back-end and send the response back to the device. This guide covers ThingsBoard RPC capabilities. After reading this guide, you will get familiar with the following topics:

  • RPC types;
  • Basic RPC use-cases;
  • RPC client-side and server-side APIs;
  • RPC widgets.

RPC call types

Thinsboard RPC feature can be divided into two types based on a originator: device-originated and server-originated RPC. In order to use more familiar names, we will name device-originated RPC calls as a client-side RPC and server-originated RPC as server-side RPC.

image

Server-side RPC can be divided into one-way and two-way:

  • One-way RPC request is sent to the device without delivery confirmation and obviously does not provide any response from the device. RPC may fail only if there is no active connection with the target device within a configurable timeout period.

    image

  • Two-way RPC request is sent to the device and expects to receive a response from the device within a certain timeout. The Server-side request is blocked until the target device replies to the request.

    image

Device RPC API

ThingsBoard provides a convenient API to send and receive RPC commands from applications running on the device. This API is specific for each supported network protocol. You can review API and examples on the corresponding reference page:

Server-side RPC API

ThingsBoard provides System RPC Service that allows you to send RPC calls from server-side applications to the device. In order to send an RPC request you need to execute an HTTP POST request to the following URL:

1
http(s)://host:port/api/plugins/rpc/{callType}/{deviceId}

where

  • callType is either oneway or twoway;
  • deviceId is your target Device ID.

The request body should be a valid JSON object with two elements:

  • method - method name, JSON string;
  • params - method parameters, JSON object.

For example:

1
2
3
curl -v -X POST -d @set-gpio-request.json http://localhost:8080/api/plugins/rpc/twoway/$DEVICE_ID \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
1
2
3
4
5
6
7
{
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

Please note that in order to execute this request, you will need to substitute $JWT_TOKEN with a valid JWT token. This token should belong to either

  • user with TENANT_ADMIN role;
  • user with CUSTOMER_USER role that owns the device identified by $DEVICE_ID.

You can use the following guide to get the token.

Persistent RPC

Since version 3.3, ThingsBoard provides the new feature: Persistent RPC. Unlike basic RPC, Persistent RPC has an increased timeout and the command is stored in the database for configurable amount of time. Persistent RPC is extremely useful when your device is in power-saving mode. Power-saving mode (or PSM) is when the device temporary is turning off to save the battery energy. You can set the PSM in the device profile or device configuration. This feature is available for CoAP and LWM2M only. After you send an RPC request to this device, the request will be saved in the database for the time you configured and the device will receive the request and send the response when it is turned on again.
In addition, every time you send the Persistent RPC, the response will contain RPC ID. Whenever you need to find a specific RPC and view its states and responses, you can do it with that ID through the database.

Persistent RPC Configuration

To configure parameters for sending a Persistent RPC request, first, you need to edit the ThingsBoard configuration file:

1
sudo nano /etc/thingsboard/conf/thingsboard.conf

Then, add the following lines to the configuration file to add these parameters:

1
2
export SQL_TTL_RPC_ENABLED=true
export SQL_RPC_TTL_CHECKING_INTERVAL=7200000

Where:

  1. SQL_TTL_RPC_ENABLED
    parameter is for configuring whether Persistent RPC data will be removed from the database in case it’s outdated.

  2. SQL_RPC_TTL_CHECKING_INTERVAL
    parameter is for configuring how often Persistent RPC will be checked whether it’s outdated. By default, this parameter is set to two hours (in milliseconds).

The system administrator can configure the default parameter for the tenants through the Tenant Profile. This is RPC TTL days configuration parameter. Configuring this parameter will change the number of days when RPC will be deleted from the database. See the screenshot below:

RPC Rule chain events

In the Rule chain, you are able to configure events that will be dispatched every time you send an RPC request: RPC queued, RPC delivered, RPC successful, RPC timeout, RPC failed. Configured RPC events reflect RPC states.

Persistent RPC States

Once you send an RPC, you can observe what exactly happened with the request that you sent in the Rule node events tab. RPC states determine steps that happen when you send RPC request. There are five possible states that can occur when the request is sent:

QUEUED - RPC was saved to the database;
DELIVERED - RPC was delivered to the device (for two-way RPC);
SUCCESSFUL - if RPC is one-way, SUCCESSFUL means that RPC was delivered to the device. If RPC is two-way, SUCCESSFUL means that we’ve already received response from the device;
TIMEOUT - RPC was not delivered to the device;
FAILED - an error occurred either while sending RPC, or during one of the steps.

Usage of Persistent RPC

To send the Persistent RPC through ThingsBoard, you need to add RPC Debug Terminal widget to your dashboard. How to add RPC Debug Terminal and use this widget, you can read here. Then, follow these steps to test the Persistent RPC:

  • Click the orange pencil icon in the lower corner of the screen to enter dashboard edit mode.
  • Click the pencil icon in the upper right corner of the RPC debug terminal to enter widget edit mode.
  • Move to the Advanced tab, increase request timeout of RPC and check the box "RPC request persistent" to enable it. Click the orange checkmark icon in the upper corner of the window to apply the changes.
  • Click the orange checkmark icon in the lower corner of the screen to save all applied changes.
  • In the tutorial, we will use the command "test". As you can see, the response contains RPC ID.

RPC Rule Nodes

It is possible to integrate RPC actions into processing workflow. There are 2 Rule Nodes for working with RPC requests.

RPC widgets

See widgets library for more details.