Sparkplug API

Sparkplug is an open-source MQTT specification that defines a standard topic namespace and payload format for industrial IoT devices. ThingsBoard acts as a Sparkplug-aware MQTT broker supporting Sparkplug B up to version 3.0.

The EoN Node is any MQTT v3.1.1 or v5.0 client that manages a session and acts as a gateway between field devices (PLCs, RTUs, sensors) and the MQTT broker. ThingsBoard connects to EoN Nodes directly — each EoN Node is represented as a device in ThingsBoard.

A single EoN Node may represent multiple physical devices. ThingsBoard decodes metrics from the Sparkplug payload and stores them as device Attributes or Time-Series Data. You can push updates back to device metrics via shared attribute changes or RPC commands.

Only the EoN Node authenticates with ThingsBoard — it’s the single MQTT client that performs CONNECT, so it’s the only entity that holds credentials (Access Token, MQTT Basic, or X.509 Certificate), configured exactly as described in Connecting to ThingsBoard.

Sparkplug B Devices announced under a node via DBIRTH are created automatically as child device records once the node’s session is authenticated — they never have, and never need, their own certificate, token, or any other credential. Attempting to configure credentials on a child device has no effect on authentication; the connection is always evaluated at the EoN Node level.

To prevent naming collisions across different groups or nodes, ThingsBoard enforces a fully qualified, unique namespacing convention for Sparkplug child devices (topics that include a deviceId) using their hierarchy:

{groupId}:{nodeId}:{deviceId}

• Avoids Collisions: Ensures that multiple devices with the same deviceId can coexist seamlessly if they belong to different Groups or Nodes.
• Clear Identification: Makes it easy to identify the exact Group and Node a device belongs to directly from the ThingsBoard device list.

spBv1.0/{group_id}/{message_type}/{edge_node_id}[/{device_id}]

Group ID, edge node ID, and device ID must be valid UTF-8 strings — the characters +, /, and # are reserved and must not be used.

BIRTH messages must use QoS 0. NCMD/DCMD subscriptions must use QoS 1. The MQTT Will Message (NDEATH) must use QoS 1.

Persistent (recommended for always-on devices):

• Stay connected at all times
• Never send DISCONNECT during normal operation
• Host Applications track real-time state via BIRTH/DEATH messages within the Keep Alive period

Non-Persistent (GPS trackers, periodic sensors):

• Connect temporarily, send data, then disconnect
• Send MQTT DISCONNECT before going offline for a graceful disconnect
• Do not send DEATH messages — Host Applications only see the Last Known Good data with a timestamp

For non-persistent devices: send a DEATH certificate upon reconnecting before disconnecting again so the Host Application maintains accurate state.

Protocol settings for non-persistent sessions:

• MQTT 3.1.1 → cleanSession = true
• MQTT 5.0 → cleanStart = true and sessionExpiryInterval = 0

An alias is an optional uint64 that identifies a metric to reduce payload size. Rules:

• If no alias is used, the metric Name must be included in every message.
• Aliases defined in NBIRTH/DBIRTH must be unique across all metrics of that node.
• NBIRTH/DBIRTH must include both the metric name and its alias.
• NDATA, DDATA, NCMD, DCMD must use only the alias — the name must be omitted.

1. Go to Profiles → Device profiles and click + to add a new profile.
2. Name it (e.g. MQTT EoN Node) and go to the Transport configuration tab.
3. Select MQTT transport type and enable MQTT Sparkplug B Edge of Network (EoN) node.
4. Enter metric names to store as shared attributes instead of telemetry — these are the metrics you want to push back to the device. Wildcard suffix * is supported (e.g. Node Control/*, Device Control/*, Properties/*).
5. Save the profile.

1. Go to Entities → Devices and click + to add a device.
2. Name it (e.g. Node 1) and select the profile created in Step 1.
3. Open the device details and copy the Access Token (or configure other credential types — see Authentication above for what this device applies to).

Use the access token as the MQTT username, connect to port 1883 (plain) or 8883 (TLS), and begin publishing BIRTH and DATA messages following the Sparkplug B topic structure.

For testing, use the ThingsBoard Sparkplug emulator:

docker run -e SPARKPLUG_SERVER_URL='tcp://mqtt.thingsboard.cloud:1883' -e SPARKPLUG_CLIENT_MQTT_USERNAME='YOUR_ACCESS_TOKEN' thingsboard/tb-sparkplug-emulator:latest

The emulator will publish NBIRTH for the node and DBIRTH for two simulated devices. ThingsBoard automatically creates child device records for each Sparkplug device using the {groupId}:{nodeId}:{deviceId} unique naming format.

• Latest telemetry tab of the EoN Node device shows metric values published via NDATA/DDATA.
• Shared attributes tab shows metrics configured in Step 1 that ThingsBoard stores as attributes instead of telemetry.

Child devices (e.g. Group_A:Node_5:Sparkplug_Device_1) appear automatically on the Devices page with their own telemetry and attributes.

Change a shared attribute in the UI, dashboard widget, or REST API. ThingsBoard automatically sends the updated value to the device as a DCMD (for device metrics) or NCMD (for node metrics).

Payload format when sending from shared attributes (ThingsBoard adds the command wrapper automatically):

{"MyFloat": 123.345}

To send an explicit command type, use this format as the attribute value:

{"NCMD": {"MyFloat": 123.345}}
{"DCMD": {"MyFloat": 123.345}}
{"NDATA": {"MyFloat": 123.345}}
{"DDATA": {"MyFloat": 123.345}}

Send a server-side RPC using the REST API, a dashboard widget, or a Rule Chain node. See Command & Control for the full RPC reference.

Reboot an EoN Node:

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

Reboot a device:

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