MQTT Sparkplug API

Netilion MQTT Sparkplug API

This document explains how external controllers, gateways, and edge devices can send data to Netilion using the Sparkplug protocol 3.0.

IMPORTANT To use the MQTT Sparkplug API, you must have a Netilion subscription that supports third‑party FieldEdge add‑ons. This capability is not included in a Netilion Connect subscription. Please contact your Netilion Sales Partner to clarify which Netilion subscription best fits your needs.

Cloud Endpoints

Your device connects directly to the secure MQTT broker of Netilion.

Available environments:

• Global: mqtt2.netilion.endress.com:8883
• India only: in.mqtt2.netilion.endress.com:8883

All communication requires TLS encryption.

Security & Access

To connect successfully, the following is required:

TLS Encryption

Your device must trust the cloud’s TLS root certificate. Download it here: https://developer.netilion.endress.com/resources/certificates/

Netilion Data Model Setup

To ensure that Sparkplug topics from connected external edge devices are accepted, the Netilion data model must be configured accordingly. This configuration consists of three key elements:

• Location Node – Represents the physical or logical location within the system hierarchy.
• Edge Device Object – Represents the actual physical edge device.
• Asset Objects – Each connected device must be represented by a corresponding asset object to ensure proper mapping and reliable data flow.

A FieldEdge Uplink AddOn must be assigned to the subscription.

Location Node

A location node object groups related objects within the Netilion data model. It is important that all connected devices (asset objects) are grouped under this node object. A hierarchical node structure below this location node is also possible.

Create the node in Netilion under All Objects. Set the node type to “Location” and assign it to the edge device object.

The Node ID is used as part of the Sparkplug topic structure.

Edge Device Object

Create a 3rd‑party edge device on the Netilion Edge Device page and assign it to the corresponding location node. A free FieldEdge Uplink AddOn must be assigned to the subscription to create the edge device.

The generated Edge ID is used as part of the Sparkplug topic structure.

Asset Objects

Create for each device which you want to integrate a corressponding asset object.

The device’s serialnumber is applied as unique key and part of the Sparkplug topic structue.

Technical User Credentials

In Netilion in the properties of your corresponding edge device object you can create the credentials of the needed technical user.

ClientID

In MQTT, the ClientID is a unique identifier that every client must provide when connecting to an MQTT broker. For Netilion the ClientID must begin with the authenticated technical username. A suffix may be appended to distinguish multiple clients under the same account.

Valid Formats

• <username>
• <username>-<client-specific-identifier>

Data Model and Topic Structure

Netilion uses the standard Sparkplug topic format:

spBv1.0/<Node ID>/<Message Type>/<Edge ID>/<device's serialnumber>

Components:

• Node ID → The assigned node identifier
• Edge ID → The assigned edge device identifier
• Device Serialnumber → The connected instrument or controller. This must correspond to a Netilion asset.

Correct ID assignment ensures that all incoming data is routed to the right assets.

Supported Sparkplug Message Types

Message Type	Description	Supported
NBIRTH	Edge device announces it is online	yes
NDEATH	Edge device goes offline	yes
DBIRTH	Device announces all values it can send	yes
DDEATH	Device goes offline	yes
NDATA	Edge device live or historical data updates	partly
DDATA	Live or historical data updates	yes
NCMD	Cloud → Edge device control commands	no
DCMD	Cloud → device control commands	yes, optional
STATE	Sparkplug Host Applications to denote is online or not	no

Edge Device Definition (NBIRTH)

When a edge device first connects, it sends a NBIRTH message.

Device Definition (DBIRTH)

When a device first connects, it sends a DBIRTH message describing its available values.

Each DBIRTH message can include:

• Value names (e.g. temperature, volumeflow, pump_on)
• Data type (supported types Float, Integer, Boolean, etc.)
• Engineering unit (Netilion Unit Codes must be used: https://developer.netilion.endress.com/development/date_unit_currency/#units)
• Device Health State
• receive DCMD as Boolean (e.g. desired_state)
• send events as Boolean (e.g. LocalEvent)

Example Payload:

{
    "definition" : {
        "Properties/Device Health" : {
            "dataType" : "Int32"
        },
        "VolumeFlow": {
            "dataType": "Float",
            "properties": {
                "UnitCode": {
                    "type": "String",
                    "value": "litre_per_hour"
                }
            }
        },
        "desired_state": {
            "dataType": "Boolean"
        },
        "Events/LocalEvent":{
            "dataType": "Boolean"
        }
    },
    "payload" : {
        "metrics" : [
            {
                "name": "Properties/Device Health",
                "value": 0
            },
            {
                "name": "VolumeFlow",
                "value": 500
            }
        ]
    }
}

Live and Historical Data (DDATA)

Devices can send:

• Live values
• Backfilled historical values (with device timestamps)
• Multiple values in one message (recommended for efficiency)

Example Payload with multiple values, with timestamps in one message:

{
    "metrics": [
        {
            "timestamp": "2025-07-01T01:24:34.991Z",
            "value": 6,
            "name": "ValueName",
            "isHistorical": true
        },
        {
            "timestamp": "2025-07-02T02:23:12.992Z",
            "value": 7,
            "name": "ValueName",
            "isHistorical": true
        },
        {
            "timestamp": "2025-07-03T03:23:12.993Z",
            "value": 8,
            "name": "ValueName",
            "isHistorical": true
        },
        {
            "timestamp": "2025-07-04T04:23:12.994Z",
            "value": 9,
            "name": "ValueName",
            "isHistorical": true
        },
        {
            "timestamp": "2025-07-05T05:23:12.995Z",
            "value": 10,
            "name": "ValueName",
            "isHistorical": true
        }
    ]
}

Netilion accepts:

• Timestamps: ISO 8601 or Unix epoch
• Value types: see chapter “Supported data types”

Device Health / Status Codes

Netilion maps Sparkplug health values to standardized status categories.

Health Code	Netilion Interpretation
0	OK
1	Failure
2	Check Function
3	Out of Specification
4	Maintenance Required

Status can be sent in DBIRTH or DDATA.

Events

Devices can report local events using Sparkplug values with the prefix:

Events/<EventName>

Examples:

• Pump started
• Valve closed
• Local alarm
• Process step completed

Events appear directly in Netilion’s event logs

Example DDATA Payload:

{
    "metrics": [ {
        "name": "Events/LocalEvent",
        "value": 1,
        }
    ]
}

Remote Commands “DCMD” (Optional)

If enabled, the Netilion can send control commands to the device, such as:

• Switching equipment on/off
• Changing operating modes
• Triggering device actions

Topic structure:

spBv1.0/<Node ID>/DCMD/<Edge ID>/<device's serialnumber>

Example DCMD Payload received from Netilion:

{
    "metrics": [
        "value": false,
        "type": "Boolean",
        "name": "desired_state",
        "timestamp": "2026-02-11T14:26:29.624Z"
    ]
}

Requirements:

• Ensure the proper use of a Netilion Application that supports remote commands, along with the correct configuration of the associated asset in accordance with the user guide for the specific Netilion Application
• The DBIRTH and DDATA Message must follow the user guide for the specific Netilion Application

WARNING Safety Considerations for DCMD Deployment. When deploying asset actions using DCMD on a customer site, it is essential to introduce it in a controlled, safe, and secure manner, particularly where field equipment can be influenced remotely via Sparkplug commands.

The following actions should support this:

• Define remote asset actions. Clearly document which asset actions can be triggered remotely and confirm device support for each action.
• Perform onsite risk assessment. Assess risks related to remote command execution during testing and define mitigation measures before activation.
• Review customer SOPs. Verify that remote operation complies with customer Standard Operating Procedures and required approvals.
• Verify controller safety behavior. Ensure installed controllers handle remote commands safely and do not bypass local safety mechanisms.

Supported data types

The following data types are supported by the Netilion Sparkplug API Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Float, Double, Boolean

Rate Limits

To ensure platform stability:

Limit	Value
Maximum Sparkplug messages per device per minute	60
Maximum payload size	256 MB per message