RPC功能

客户端RPC
- 设备发送客户端RPC
- 平台处理客户端RPC
服务端RPC

ThingsBoard允许你从服务端应用程序向设备发送远程RPC调用，你也可以将命令发送到设备并接收命令执行的结果。

同样你可以执行来自设备的请求，在后端应用进行某些计算或服务端逻辑处理然后将结果反馈到设备。

本指南涵盖ThingsBoard RPC功能，阅读本指南后你将掌握以下内容：

RPC调用类型
基础RPC实例
RPC客户端和服务器端API
RPC部件

Thinsboard RPC功能可以分为两种类型：设备发起的RPC调用和服务端发起的RPC调用，为了使用更熟悉的名称我们将源自设备的RPC调用命名为客户端RPC调用，将源自服务器的RPC调用命名为服务端RPC调用。

客户端RPC

客户端RPC功能可以将请求从设备发送平台并将响应返回组设备。

客户端RPC调用的典型用例：

灌溉系统通过平台获取天预报气服务进行灌溉。
设备没有系统时钟通过平台请求当前。
门禁读卡器向第三方安全系统发送请求决定开门方式。

设备向平台发送一条消息由规则引擎处理和使用设备属性、遥测或存储在平台中的数据进行计算或者调用外部系统处理消息之后将结果返回给设备。

客户端RPC请求由两个必须的字段组成：

method - 表示json字符串格式的方法名
params - 表示json字符串格式的对象参数列表

请求示例：

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

响应实例：内容可以是数据，字符串，JOSN

1631881236974

设备发送客户端RPC

ThingsBoard提供特定的API用来从设备发送RPC命令，目前LwM2M和SNMP协议还不能支持RPC其它的相关支持协议请查下成API和示例：

平台处理客户端RPC

客户端RPC命令被转换成”TO_SERVER_RPC_REQUEST”的message type的规则引擎消息并包含唯一的UUID标识符并保存在”requestId”元数据字段中；你可以将自己的规则琏中通过transformation, enrichment或其它节点类型来处理输入消息，如果输入消息转换成响应消息就可以使用RPC Call Reply节点向设备发送回复。

例如：修改根规则链处理”getCurrentTime”客户端RPC并回复当前时间，使用带有以下JS代码的”Script”转换节点：

var rpcResponse;
if (msg.method === "getCurrentTime"){
   rpcResponse = new Date().getTime();
} else {
   rpcResponse = "Unknown RPC request method: " + msg.method;  
}
return {msg: rpcResponse, metadata: metadata, msgType: msgType};

编辑Rule Chain替换"log"节点为"script"节点并添加"rpc call reply"节点

服务端RPC

服务端RPC功能将请求从平台发送到设备，并可选择将响应返回给平台。

服务端RPC调用的典型用例是各种远程控制：重启、打开/关闭、修改gpio状态、修改配置参数等。

服务端RPC调用可以分为单向和双向：

单向RPC请求直接发送请求，并且不对设备响应做任何处理。
双向RPC请求会发送到设备，并且超时期间内接收到来自设备的响应。

ThingsBoard3.3以前版本仅支持轻量级的RPC调用只能控制在30秒以内这是平台的REST API调用的默认超时，因为没有将其存储到数据库中服务器挂掉之后部件会向其它服务器发送相同请求，轻量级的RPC消耗资源较少这是因为它处理不调用任何输入/输出只会存储审计日志和规则引擎消息。

ThingsBoard3.3版本开始提供了持久化的RPC调用支持并且具有可配置的生命周期存储，如果设备长时间无法访问时持久化则非常有用通常在网络连接不佳或省电模式 (PSM)情况下。

RPC结构

RPC请求主体由多个字段组成：

method - 必须，RPC调用方法。例如：”getCurrentTime”或”getWeatherForecast”。
params - 必须，RPC调用参数；JSON字符串如果不需要则可以是”{}”。
timeout - 可选，RPC调用超时；默认值为10000（10秒）最小值为5000（5秒）。
expirationTime - 可选，RPC到期时间(以毫秒为单位，UTC 时区). 如果存在则覆盖timeout。
persistent - 可选，RPC持久化；参加[persistent]与[lightweight]的RPC默认值为”false”。
retries - 可选，RPC重试持久化次数；网络或设备出现故障时重新发送持久化的RPC次数。
additionalInfo - 可选，RPC附加信息；定义将添加[persistent RPC events]的元数据。

请求示例：

{
   "method": "setGPIO",
   "params": {
     "pin": 4,
     "value": 1
   },
  "timeout": 30000
}

响应示例：

{
   "pin": 4,
   "value": 1,
   "changed": true
}

发送服务器端RPC

服务端RPC使用REST API或仪表板部件进行发送平台收到RPC会验证payload权限然后RPC命令被转换为规则引擎消息并添加其它参数后最终将命令发送给设备。

命令发送详情：

REST API

如果需要发送RPC请求需要使用下面URL执行HTTP POST请求：

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

url说明：

http(s)://host:port表示ThingsBoard服务器URL，例如https://thingsboard.cloud
callType表示oneway或者twoway
deviceId表示设备ID

请求正文是一个有效的JSON参见上面的RPC请求对象。

例如：

set-gpio-request.sh
set-gpio-request.json

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"

{
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

注意： 你需要将$JWT_TOKEN换成有效JWT访问令牌并且必须是TENANT_ADMIN或CUSTOMER_USER角色需要拥有$DEVICE_ID标识的设备用户，通过以下指南获取令牌。

当用户通过REST API发送轻量级RPC时API调用包含来自设备的回复或错误代码。例如：

{
   "pin": 4,
   "value": 1,
   "changed": true
}

当用户通过REST API发送持久化RPC时响应包含唯一标识符”rpcId”。例如：

{
   "rpcId": "b10bb1a0-0afd-11ec-a08f-1b3182194747"
}

可以使用此标识符来跟踪命令的状态有关详细信息请参阅持久化RPC状态。

仪表板

控制部件用于向设备发送RPC命令最常用的有”RPC Button”, “Round Switch”, “Switch Control”和”Knob Control”，这些部件通过高级设置可以自定义RPC方法名和参数同时还可以自定义部件使用控制API完成命令发送。

规则引擎

部件或REST API发送的所有服务端RPC命令最终都会转换成”RPC_CALL_FROM_SERVER_TO_DEVICE”的message type规则引擎消息。

消息包含基于唯一的UUID标识符并存储在”requestUUID”元数据字段中，你可以将自己的规则琏中通过transformation, enrichment或其它节点类型来处理输入消息，最后使用RPC Call Request节点将消息发送给设备。

使用generator节点创建RPC：

var msg = { method: "rpcCommand", params: {} };
var metadata = { 
    expirationTime: new Date().getTime() + 60000,
    oneway: true,
    persistent: false
};
var msgType = "RPC_CALL_FROM_SERVER_TO_DEVICE";

return { msg: msg, metadata: metadata, msgType: msgType };

编辑root Rule Chain添加generator节点连接到"rpc call request"节点

设备上处理服务器RPC

ThingsBoard提供特定的API用来从设备发送RPC命令，其它的相关支持协议请查下成API和示例：

持久化RPC

状态

ThingsBoard有7种RPC的持久化状态：

QUEUED - RPC创建并保存到数据库尚未将RPC发送到设备，默认情况下平台将尝试一次发送所有待处理的RPC调用在某些情况下设备队列中有多个消息可能会导致网络阻塞建议使用”ACTORS_RPC_SEQUENTIAL”配置参数设置RPC调用顺序。
SENT - ThingsBoard尝试将RPC发送到设备。
DELIVERED - 设备已确认RPC这是one-way RPC的最后一步；
SUCCESSFUL - ThingsBoard收到two-way RPC的回复；
TIMEOUT - ThingsBoard传输层（MQTT/CoAP/LwM2M 等）检测到RPC传输超时；使用相应配置参数控制超时： MQTT_TIMEOUT（默认10秒）、COAP_TIMEOUT（默认10秒）、LWM2M_TIMEOUT（默认12 秒）默认平台不会重试RPC的传递并且状态将更改为失败可以在RPC主体中配置重试次数最大重试次数由”ACTORS_RPC_MAX_RETRIES”配置参数控制（默认为 5）。
EXPIRED - RPC未交付或平台未在配置的到期时间内收到来自设备的回复；
FAILED - 配置的重试次数期间未能传递RPC或者设备固件不支持此类命令。

规则链事件

RPC状态的更改作为单独的消息推送到规则引擎每个RPC状态都有相应的消息类型。见下图：

消息包含有关RPC请求的详细信息包括来自RPC请求正文的实体ID和”additionalInfo”。

“RPC Successful”消息还包含来自设备的回复如果想在外部系统中处理来自设备的回复这些消息很有用。

请参阅下面的成功RPC消息示例：

{
    "id": {
        "entityType": "RPC",
        "id": "bea26301-1aec-11ec-9441-73a37bbb7cd2"
    },
    "createdTime": 1632236465459,
    "tenantId": {
        "entityType": "TENANT",
        "id": "ab937a40-3f98-11eb-a8d6-f5a87f07d4be"
    },
    "deviceId": {
        "entityType": "DEVICE",
        "id": "3e46db70-e480-11eb-9d0e-1f8899a6f9b3"
    },
    "expirationTime": 1632236525354,
    "request": {
        "id": "bea26301-1aec-11ec-9441-73a37bbb7cd2",
        "tenantId": {
            "entityType": "TENANT",
            "id": "ab937a40-3f98-11eb-a8d6-f5a87f07d4be"
        },
        "deviceId": {
            "entityType": "DEVICE",
            "id": "3e46db70-e480-11eb-9d0e-1f8899a6f9b3"
        },
        "oneway": false,
        "expirationTime": 1632236525354,
        "body": {
            "method": "rpcCommand",
            "params": "{}"
        },
        "persisted": true,
        "retries": null
    },
    "response": {
        "test": "passed"
    },
    "status": "SUCCESSFUL",
    "additionalInfo": "{\"param1\":\"value1\",\"param2\":\"value2\"}"
}

TTL配置

持久化RPC的生存时间由系统管理员使用RPC TTL天数配置参数在租户配置中设置。

系统管理员使用SQL_TTL_RPC_ENABLED配置参数完全禁用从数据库中清除持久化RPC。

RPC清理过程的频率使用SQL_RPC_TTL_CHECKING_INTERVAL参数控制默认设置为2小时。

本页目录