ThingsBoard RPC订阅教程

一、RPC功能概述

ThingsBoard的RPC（远程过程调用）功能分为服务端RPC 和客户端RPC两种模式。服务端RPC是指平台向设备发送控制命令，设备执行后返回响应；客户端RPC则是设备主动向平台发起请求，平台处理后返回结果。服务端RPC又分为单向RPC（oneway）和双向RPC（twoway）两种类型。

二、环境准备

1. 安装ThingsBoard

使用Docker快速部署：

复制代码

docker run -d -p 9090:9090 -p 1883:1883 -p 7070:7070 \
  --name my34tbp --restart always \
  thingsboard/tb-postgres:3.4.0

9090端口：HTTP服务
1883端口：MQTT服务
7070端口：边缘计算RPC服务

2. 创建设备

登录ThingsBoard管理界面（:9090），在"设备管理"中创建新设备，获取设备的访问令牌（Access Token）。

三、MQTT协议RPC订阅

1. 客户端订阅RPC主题

设备端需要订阅以下主题来接收服务端的RPC命令：

复制代码

# 订阅RPC请求主题
client.subscribe("v1/devices/me/rpc/request/+", 1)

# 订阅属性更新主题（可选）
client.subscribe("v1/devices/me/attributes", 1)

当服务端发送RPC命令时，设备会收到类似以下格式的消息：

复制代码

{
  "method": "toggle_gpio",
  "params": {"pin": 1}
}

2. 服务端发送RPC命令

服务端可以通过REST API或仪表板小部件发送RPC命令：

单向RPC（oneway）：

复制代码

{
  "method": "setValue",
  "params": {"pin": 7, "value": 1}
}

双向RPC（twoway）：

复制代码

{
  "method": "getValue",
  "params": {"pin": 88, "value": 99}
}

3. 设备响应RPC命令

设备处理完RPC命令后，需要向服务端发送响应：

复制代码

{
  "device": "Device A",
  "id": "$request_id",
  "data": {"success": true}
}

其中$request_id是请求的唯一标识符。

四、HTTP协议RPC使用

1. 客户端RPC（设备发起）

设备通过HTTP POST请求调用平台服务：

复制代码

import requests
import json

base_url = "https://thingsboard-instance-url"
access_token = "device-access-token"

# 构建RPC请求URL
url = f"{base_url}/api/v1/{access_token}/rpc"

# 发送RPC请求
payload = {
    "method": "getTime",
    "params": {}
}
response = requests.post(url, json=payload)
print(response.json())

2. 服务端RPC（平台发起）

平台通过HTTP API向设备发送命令：

复制代码

import requests
import json

base_url = "https://thingsboard-instance-url"
device_id = "your-device-id"

# 单向RPC
url = f"{base_url}/api/plugins/rpc/oneway/{device_id}"

# 双向RPC
url = f"{base_url}/api/plugins/rpc/twoway/{device_id}"

payload = {
    "method": "setLed",
    "params": {"state": "on"}
}
response = requests.post(url, json=payload)
print(response.json())

五、网关RPC订阅

如果使用网关模式，设备通过网关连接ThingsBoard，需要订阅以下主题：

复制代码

// 订阅网关RPC主题
mqttClient.subscribe("v1/gateway/rpc");

服务端发送的RPC消息格式：

复制代码

{
  "device": "Device A",
  "data": {
    "id": "$request_id",
    "method": "toggle_gpio",
    "params": {"pin": 1}
  }
}

网关处理完命令后，使用以下格式回复：

复制代码

{
  "device": "Device A",
  "id": "$request_id",
  "data": {"success": true}
}

六、RPC持久化状态

ThingsBoard支持RPC命令的持久化，包含7种状态：

QUEUED：RPC已创建并保存到数据库，尚未发送到设备
SENT：ThingsBoard尝试将RPC发送到设备
DELIVERED：设备已确认RPC（单向RPC的最后一步）
SUCCESSFUL：ThingsBoard收到双向RPC的回复
TIMEOUT：RPC传输超时
FAILED：RPC发送失败
EXPIRED：RPC已过期

七、常见问题排查

设备无法收到RPC命令：检查设备是否在线，是否正确订阅了RPC主题
RPC超时：调整MQTT_TIMEOUT配置参数（默认10秒）
权限问题：确保设备令牌正确，设备与网关已建立连接
网络问题：检查MQTT连接是否正常，防火墙是否开放1883端口