产品定价 立即试用
社区版
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
API > 设备连接API > MQTT Sparkplug API
入门 文档 指南 安装 架构
常见问题
目录

MQTTSparkplugAPI

在继续前，建议您先阅读快速入门指南以了解ThingsBoard基础。此外，建议查阅设备配置文档。

Sparkplug基础

Sparkplug是一种开源软件规范，为MQTT客户端提供框架，使其能够在MQTT基础设施内无缝集成来自应用、传感器、设备和网关的数据，目前已实现至Sparkplug 3.0版本。

Sparkplug B Edge Node

ThingsBoard充当MQTT服务器，支持SparkPlug负载和主题结构，并允许来自MQTT网络边缘（EoN）节点的连接。

EoN节点是符合v3.1.1或v5.0规范的MQTT客户端应用，负责管理MQTT会话并提供参与本文档所述主题命名空间和负载定义所需的物理和/或逻辑网关功能。Edge Node负责与现有设备（PLC、RTU、流量计算机、传感器等）的本地协议接口、本地离散I/O、以及逻辑内部过程变量（PV）。

该协议规范定义了EoN节点与MQTT服务器通信的MQTT主题和消息结构。

Sparkplug B Device

单个EoN节点可代表多个物理设备和传感器，并为每个设备上传设备指标。 ThingsBoard从Sparkplug负载解码设备指标，并将其存储为相应设备的属性或时序数据。 您也可通过共享属性更新或RPC命令向Sparkplug设备发出更新。

文档信息图标

注意：
ThingsBoard仅支持Sparkplug™ B负载。

Sparkplug B主题与消息类型

Sparkplug B负载与Sparkplug主题命名空间结合，形成分层数据结构，可用带指标（通常称为标签）的文件夹结构表示。

1

spBv1.0/Sparkplug Group 1/NBIRTH /Sparkplug Node 1/Sparkplug Device 1

ThingsBoard中的Sparkplug B消息类型

Type Description
NBIRTH MQTT网络边缘（EoN）节点出生证书
NDEATH MQTT网络边缘（EoN）节点死亡证书
DBIRTH MQTT设备出生证书
DDEATH MQTT设备死亡证书
NDATA 网络边缘（EoN）节点数据消息
DDATA 设备数据消息
NCMD 网络边缘（EoN）节点命令消息
DCMD 设备命令消息
STATE 设备在线/离线状态（活动）
DRECORD 设备记录消息
NRECORD 网络边缘（EoN）节点记录消息

Group ID、edge_node_id、device_id的格式必须为有效UTF-8字符串，但不允许保留字符+（加号）、/（正斜杠）、#（井号）。 BIRTH的MQTT QoS必须为0。 -dcmd-subscribe MUST subscribe on this topic with a QoS of 1, The MQTT Will Message’s MQTT QoS MUST be 1 (at least once) 可为Sparkplug客户端定义ACL，将每个Edge Node限制在其可发布和订阅的特定主题集中。（Edge Node发布NBIRTH，设备发布DBIRTH）。

  • 含消息类型的主题示例
1
2
3
4
5
6

    $sparkplug/certificates:  spBv1.0/group_id/NBIRTH/edge_node_id
    Subscribe:  spBv1.0/group_id/NBIRTH/edge_node_id/#
    $sparkplug/certificates: spBv1.0/group_id/DBIRTH/edge_node_id/device_id
    Subscribe: spBv1.0/group_id/DBIRTH/edge_node_id/device_id/#
    $sparkplug/state: spBv1.0/STATE/sparkplug_host_id
  • 验证主题数据订阅
1
2
3
4
5
6

    Subscribe: spBv1.0/G1/DDATA/E1
    Subscribe: spBv1.0/G1/DDATA/E1/#
    Subscribe: spBv1.0/G1/DDATA/E1/+
    Subscribe: spBv1.0/G1/DDATA/E1/D1
    Subscribe: spBv1.0/G1/DDATA/E1/D1/#
    Subscribe: spBv1.0/G1/DDATA/E1/D1/+

Edge Node的持久与非持久连接

持久连接

  • 始终保持连接
  • 正常运行时从不发送MQTT DISCONNECT
  • 允许主机应用在保活期内通过BIRTH/DEATH消息跟踪实时状态

非持久连接（如GPS追踪器或周期性传感器更新）

  • 临时连接并定期发送数据
  • 离线前应发送MQTT DISCONNECT以实现优雅断开
  • 不发送DEATH消息——主机应用仅能看到带时间戳的最后已知良好数据，而非实时状态

非持久设备建议：

  • 重新连接后，在再次断开前发送DEATH证书
  • 有助于主机应用维持准确的状态跟踪

MQTT协议要求：

MQTT 3.1.1 → Clean Session = true MQTT 5.0 → Clean Start = true且Session Expiry Interval = 0

Sparkplug B负载中的别名用法

  • Alias为可选的无符号64位整数，用于标识指标，有助于减小负载大小。
  • 若未使用别名，则必须在每条消息中包含指标名称。
  • 别名为可选，但使用时须遵循以下规则：
使用别名的规则

  • [tck-id-payloads-alias-uniqueness]
    若在NBIRTH或DBIRTH中提供了别名，则该别名必须在Edge Node的所有指标中唯一。
    ▪ 同一节点的任意两个指标不得共享相同别名。

  • 在NBIRTH/DBIRTH中定义后，后续消息（NDATA、DDATA等）可仅使用别名替代完整指标名称。

  • [tck-id-payloads-alias-birth-requirement]
    NBIRTH和DBIRTH消息必须同时包含指标名称及其别名。

  • [tck-id-payloads-alias-data-cmd-requirement]
    NDATA、DDATA、NCMD和DCMD消息必须仅包含别名，必须省略指标名称。

入门

本指南将介绍如何：将Sparkplug EoN节点连接到ThingsBoard、收集设备指标并存储为ThingsBoard时序数据、以及将命令推送回设备。

步骤1. 创建设备配置

首先需为Sparkplug设备创建MQTT设备配置：

  1. 进入配置 -> 设备配置页面，点击设备配置表头的”+”图标以打开添加设备配置对话框；
  2. 将配置名称设为MQTT EoN Node或任意有意义的值；
  3. 进入传输配置选项卡并选择MQTT传输类型；
  4. 确保已勾选”MQTT Sparkplug B Edge of Network (EoN) node”复选框；
  5. 输入您希望存储为属性而非时序数据的Sparkplug指标名称。 该列表还应包含您可能希望从服务端更新并推送到设备的指标。 支持简单星号后缀作为通配符，例如：”Node Control/*“、”Device Control/*“、”Properties/*“。
Navigate to the Device profiles page and click on the "+" icon in the device profile table header to open the Add device profile dialog. Use MQTT EoN Node as profile name or any other meaningful value;
Navigate to the Device profiles page and click on the "+" icon in the device profile table header to open the Add device profile dialog. Use MQTT EoN Node as profile name or any other meaningful value;
Navigate to Transport configuration tab and select the MQTT transport type. Make sure you have selected the “MQTT Sparkplug B Edge of Network (EoN) node” checkbox. Input the names of Sparkplug metrics you would like to store as attributes instead of time series data. This list should also include metrics you may want to update from the server side and push to the device;
Navigate to Transport configuration tab and select the MQTT transport type. Make sure you have selected the “MQTT Sparkplug B Edge of Network (EoN) node” checkbox. Input the names of Sparkplug metrics you would like to store as attributes instead of time series data. This list should also include metrics you may want to update from the server side and push to the device;
MQTT EoN Node have been created.
MQTT EoN Node have been created.

步骤2. 配置EoN节点凭证

  1. 进入实体 -> 设备页面，点击设备表头的”+”图标以打开添加新设备对话框；
  2. 输入EoN节点设备名称（如Node 1）并选择现有设备配置：MQTT EoN Node。
  3. 创建设备并进入设备详情。复制访问令牌，我们将在下一步使用。注意您也可使用其他类型的凭证。
Navigate to the Devices page and click on the “+” icon in the device table header to open the Add new device dialog. Input your EoN node device name (e.g. Node 1) and select the existing device profile: MQTT EoN Node. Click Add;
Navigate to the Devices page and click on the “+” icon in the device table header to open the Add new device dialog. Input your EoN node device name (e.g. Node 1) and select the existing device profile: MQTT EoN Node. Click Add;
Navigate to the manage credentials and copy the access token. We will use it in the next step. Note that you may use other types of credentials as well.
Navigate to the manage credentials and copy the access token. We will use it in the next step. Note that you may use other types of credentials as well.

步骤3. 启动EoN节点模拟器

我们已为测试准备了sparkplug节点模拟器。 启动模拟器并连接到我们的平台实例，使用上一步的访问令牌凭证：

1

docker run -e SPARKPLUG_SERVER_URL='tcp://localhost:1883' -e SPARKPLUG_CLIENT_MQTT_USERNAME='YOUR_THINGSBOARD_DEVICE_TOKEN' thingsboard/tb-sparkplug-emulator:latest

请勿忘记将YOUR_THINGSBOARD_DEVICE_TOKEN替换为实际的令牌值。 也请将localhost替换为您的服务器主机名。

文档信息图标

请注意
在docker容器内不可将localhost用作SPARKPLUG_SERVER_URL。

image

模拟器成功启动后，您应看到以下消息：

1
2
3

2023-05-04 13:40:42,787 [pool-2-thread-1] INFO  o.t.sparkplug.SparkplugEmulation - Publishing [Sparkplug Node 1] NBIRTH
2023-05-04 13:40:42,815 [pool-2-thread-1] INFO  o.t.sparkplug.SparkplugEmulation - Publishing [Sparkplug Device 1] DBIRTH
2023-05-04 13:40:42,816 [pool-2-thread-1] INFO  o.t.sparkplug.SparkplugEmulation - Publishing [Sparkplug Device 2] DBIRTH

步骤4. 以属性和遥测形式查看设备指标

进入EoN节点设备（如Node 1）的详情并打开最新遥测选项卡。您应看到设备指标，例如Current Grid Voltage。 进入属性选项卡并选择共享属性范围。您将看到在步骤1（第5项）中先前配置的指标。

Navigate to the details of the EoN node device and open the Latest telemetry tab. You should see the device metrics, for example Current Grid Voltage;
Navigate to the details of the EoN node device and open the Latest telemetry tab. You should see the device metrics, for example Current Grid Voltage;
Navigate to the Attributes tab and select Shared attributes scope. You should see metrics that you have previously configured in the Step 1.
Navigate to the Attributes tab and select Shared attributes scope. You should see metrics that you have previously configured in the Step 1.

刷新设备页面，可见模拟器创建了两个新的Sparkplug设备：”Sparkplug Device 1”和”Sparkplug Device 2”。 两个设备各有其由模拟器生成的属性和遥测值。

此外，为这两个新设备创建了单独的设备配置，名称由您的Sparkplug节点名称+”device”组成。

Navigate to the Devices table and note that two new Sparkplug devices are created by the emulator: "Sparkplug Device 1" and "Sparkplug Device 2";
Navigate to the Devices table and note that two new Sparkplug devices are created by the emulator: "Sparkplug Device 1" and "Sparkplug Device 2";
Both devices have their own attributes and telemetry values that are generated by the emulator.
Both devices have their own attributes and telemetry values that are generated by the emulator.

步骤5. 将ThingsBoard服务端的Sparkplug指标更新推送到MQTT EoN和设备

您可通过共享属性更新或RPC命令从ThingsBoard向Sparkplug节点/设备指标推送更新。

使用共享属性更新指标

ThingsBoard共享属性用于向设备传递指标值更新。 您可通过多种方式修改共享属性——管理界面、部件、REST API或规则引擎节点。


我们手动修改属性”Outputs/LEDs/Green“和”Device Control/Scan Rate“的值。

要修改属性”Outputs/LEDs/Green”的值，需先在MQTT EoN Node设备配置中添加该指标，将其存储为共享属性而非遥测。 在传输配置选项卡中，添加新的Sparkplug指标名称——“Outputs/*“。

Go to the Profiles -> Device profiles and select MQTT EoN Node device profile. In the Transport сonfiguration tab, add a new Sparkplug metric name — “Outputs/".
Go to the Profiles -> Device profiles and select MQTT EoN Node device profile. In the Transport сonfiguration tab, add a new Sparkplug metric name — “Outputs/*".

返回设备页面并选择Sparkplug Device 1。 在共享属性选项卡中，您将看到两个新属性：”Outputs/LEDs/Green“值为”true“，”Outputs/LEDs/Yellow“值为”false“。 这些为存储为属性的指标，我们可修改并将其值发送至设备。

Go back to the Devices page and select the Sparkplug Device 1. On the Shared attributes tab, you will see two new attributes: “Outputs/LEDs/Green” with the value “true” and “Outputs/LEDs/Yellow” with the value “false”. These are metrics that are saved as attributes, and we can modify them and send values to the device.
Go back to the Devices page and select the Sparkplug Device 1. On the Shared attributes tab, you will see two new attributes: “Outputs/LEDs/Green” with the value “true” and “Outputs/LEDs/Yellow” with the value “false”. These are metrics that are saved as attributes, and we can modify them and send values to the device.

点击”铅笔”图标，取消勾选对应复选框，将属性”Outputs/LEDs/Green“的值从”true”改为”false”。然后点击更新。名为”Outputs/LEDs/Green“、值为”false“的属性将从服务器发送至设备”Sparkplug Device 1“。

在运行模拟器的终端中，您应看到以下消息：

1
2
3

2023-05-04 14:09:00,417 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Message Arrived on topic spBv1.0/Sparkplug Group 1/DCMD/Sparkplug Node 1/Sparkplug Device 1
2023-05-04 14:09:00,417 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Command: [DCMD]  nodeDeviceId: [Sparkplug Device 1]
2023-05-04 14:09:00,417 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Metric [Outputs/LEDs/Green] value [false]

如您所见，属性”Outputs/LEDs/Green“的新值已成功发送至设备。

Click on the “pencil” icon and change the value of the attribute “Outputs/LEDs/Green” from “true” to “false” by unchecking the corresponding box. Then, click Update.
Click on the “pencil” icon and change the value of the attribute “Outputs/LEDs/Green” from “true” to “false” by unchecking the corresponding box. Then, click Update.

现在修改”Device Control/Scan Rate“属性的值。点击”铅笔”图标，将值从”60000“改为”30000“。点击更新。

当”Device Control/Scan Rate“属性的新值发送至”Sparkplug Device 1“设备时，您将在终端中看到以下消息：

1
2
3

2023-05-04 14:16:51,715 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Message Arrived on topic spBv1.0/Sparkplug Group 1/DCMD/Sparkplug Node 1/Sparkplug Device 1
2023-05-04 14:16:51,715 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Command: [DCMD]  nodeDeviceId: [Sparkplug Device 1]
2023-05-04 14:16:51,715 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Metric [Device Control/Scan Rate] value [30000]
Now let’s change the value of the “Device Control/Scan Rate” attribute. Click on the “pencil” icon and change the value from “60000” to “30000”. Click Update.
Now let’s change the value of the “Device Control/Scan Rate” attribute. Click on the “pencil” icon and change the value from “60000” to “30000”. Click Update.

属性”Outputs/LEDs/Green“和”Device Control/Scan Rate“的值已更改并发送至”Sparkplug Device 1“设备。

The new attribute values for "Outputs/LEDs/Green" and "Device Control/Scan Rate" have been successfully sent to the device.
The new attribute values for "Outputs/LEDs/Green" and "Device Control/Scan Rate" have been successfully sent to the device.
  • 可通过共享属性和RPC终端（Json）发送CMD、DATA、DCMD、DDATA命令：
1

{"NCMD":{"MyFloat":123.345}}

1

{"NDATA":{"MyFloat":123.345}}

1

{"DCMD":{"MyFloat":123.345}}

1

{"DDATA":{"MyFloat":123.345}}
  • 若从共享属性（ts/kv）发送：
1
2

{"MyFloat":123.345}      // 若来自Edge Node，默认将添加"NCMD"
{"MyFloat":123.345}      // 若来自设备，默认将添加"DCMD"

使用ThingsBoard RPC命令从服务器向MQTT EoN/设备更新指标

ThingsBoard支持通过RPC（远程过程调用）功能按需更新Sparkplug EoN节点或设备的指标。为简化起见我们也使用”command”替代RPC。 您可通过REST API、部件、规则引擎或自定义脚本发送命令。 命令结构文档见此处。

命令的关键属性为method和params。 method定义Sparkplug操作，为以下之一：

  • NCMD - 发给EoN节点的命令；
  • DCMD - 发给EoN设备的命令；

params为定义指标和值的JSON。

例如，要重启Sparkplug EoN节点，应发送以下命令：

1
2
3
4

  {
    "method": "NCMD",
    "params": {"metricName": "Node Control/Reboot", "value": true}
  }

要重启Sparkplug EoN设备，应发送以下命令：

1
2
3
4

  {
    "method": "DCMD",
    "params": {"metricName": "Device Control/Reboot", "value": true}
  }

本示例中使用”RPC按钮“部件重启Sparkplug EoN节点。参见下方分步指南与截图。

进入仪表板页面并创建名为Sparkplug的新仪表板。打开仪表板，点击实体别名图标添加新别名。 命名别名（例如EoN Node），选择筛选类型”单个实体“，类型”设备“并选择Node 1。点击添加然后保存。

Go to the Dashboard page and create a new dashboard named Sparkplug;
Go to the Dashboard page and create a new dashboard named Sparkplug;
Open the dashboard and add an alias by clicking on Entity Aliases icon on the top-right. Name the alias (EoN Node, for example), select filter type “Single Entity”, type “Device” and choose our Node 1. Press Add and then Save.
Open the dashboard and add an alias by clicking on Entity Aliases icon on the top-right. Name the alias (EoN Node, for example), select filter type “Single Entity”, type “Device” and choose our Node 1. Press Add and then Save.

现在创建新部件。点击”添加新部件”，从下拉菜单选择控制部件包并选择RPC按钮部件。在数据字段选择已创建的别名（EoN Node）。 进入高级选项卡并输入按钮标签 - REBOOT NODE。在RPC设置中输入RPC方法 - “NCMD”（发给EoN节点的命令）和RPC方法参数 - “{“metricName”: “Node Control/Reboot”, “value”: true}“。点击添加并保存更改。

Click "Add New Widget";
Click "Add New Widget";
Select "Control widgets" from drop down menu;
Select "Control widgets" from drop down menu;
Select "RPC Button" widget;
Select "RPC Button" widget;
On the Data field select created alias;
On the Data field select created alias;
Go to "Advanced" tab and enter button label. In the RPC settings enter "RPC method" (command to the EoN Node) and "RPC method params". Click Add;
Go to "Advanced" tab and enter button label. In the RPC settings enter "RPC method" (command to the EoN Node) and "RPC method params". Click Add;
Save changes.
Save changes.

现在点击部件上的”REBOOT NODE“按钮。名称为”Node Control/Reboot”、值为”true”的RPC命令将从服务器发送至节点”Sparkplug Node 1“。

Click "REBOOT NODE" button on the widget. In the Terminal, you will see a message indicating that the RPC command has been sent to the device and the Sparkplug EoN Node 1 has been rebooted.
Click "REBOOT NODE" button on the widget. In the Terminal, you will see a message indicating that the RPC command has been sent to the device and the Sparkplug EoN Node 1 has been rebooted.

在运行模拟器的终端中，您应看到以下消息：

1
2
3

2023-05-04 14:27:02,215 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Message Arrived on topic spBv1.0/Sparkplug Group 1/NCMD/Sparkplug Node 1
2023-05-04 14:27:02,215 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Command: [NCMD]  nodeDeviceId: [Sparkplug Node 1]
2023-05-04 14:27:02,215 [MQTT Call: Sparkplug Node 1] INFO  o.t.sparkplug.SparkplugMqttCallback - Metric [Node Control/Reboot] value [true]

Sparkplug EoN Node 1已重启。

下一步