Native Sparkplug

What is Sparkplug?

Sparkplug is a specification maintained by the Eclipse Sparkplug Working Group under the Eclipse Foundation. Its goal is to provide improved Plug & Play IIoT over MQTT. You can get more information from https://sparkplug.eclipse.org/.

Neowit supports the current Sparkplug 3.0.0 version of the specification and we provide an MQTT broker and an optional Primary Host Application that you can use to synchronize your Edge Node application with.

Technical information

Connecting

The integration settings page will show the connection details you need to use to connect to our MQTT broker. See our MQTT page for more details on this.

Primary Host Application

Neowit has implemented a Host application that will passively listen to all NBIRTH / NDEATH / DBIRTH / DDEATH / DDATA messages and automatically ingest metrics if they match the criteria described below.

The host will publish its STATE to the following topic: "spBv1.0/STATE/<:integrationID>". If you're app or edge node supports syncing with a Sparkplug Primary Host application, you can set the app id to be id of the integration.

Supported DBIRTH metric names

If you want the devices and sensors to automatically show up in the Neowit app, you need to specify a set of metrics that Neowit can use to describe the Device and its sensors. This is done in the Sparkplug DBIRTH message, as per the specification the DBIRTH message should contain all metrics that are available on the device. If you want to change the specification after you've sent a DBIRTH you can use NDEATH / NBIRTH as per the specification.

Device description metrics

Metric Name	Sparkplug Data Type	Description
/neowit/v1/device/name	String (12)	A human readable name
/neowit/v1/device/vendor	String (12)	Vendor of device
/neowit/v1/device/model	String (12)	Model of device
/neowit/v1/device/deepLink	String (12)	Optional http link for more information

Sensor description metrics

For each metric you want to be associated with the device, you need to give it a metric name that can be understood by our metric store. The name of the available metric types are available in a table from the integration configuration page. After you found a suitable sensor name, you can construct your metric using the following pattern "/neowit/v1/sensor/name/:SENSOR_NAME". For example if you want to send a temperature metric, you'd use the metric name "/neowit/v1/sensor/name/TEMP".

Sensor Value Data Types

Currently, we support the following Sparkplug data types for ingress into our metrics storage.

Name	Data Type
Int8	1
Int16	2
Int32	3
Int64	4
UInt8	5
UInt16	6
UInt32	7
UInt64	8
Float	9
Double	10
Boolean	11

Example DBIRTH Device description

The below DBIRTH (shown as JSON instead of protobuf to make it human readable) will be translated to a Neowit Device as follows:

Sparkplug DBIRTH

PUBLISH spBv1.0/group1/DBIRTH/node1/device1
{
        "timestamp": 1486144502122,
        "metrics": [{
            "name": "/neowit/v1/device/name",
            "alias": 1,
            "timestamp": 1479123452194,
            "dataType": "String",
            "value": "My Device Name"
        }, {
            "name": "/neowit/v1/device/vendor",
            "alias": 2,
            "timestamp": 1479123452194,
            "dataType": "String",
            "value": "My Trusted Manufacturer"
        }, {
            "name": "/neowit/v1/device/model",
            "alias": 3,
            "timestamp": 1479123452194,
            "dataType": "String",
            "value": "Awesome Device 1.3"
        }, {
            "name": "/neowit/v1/device/deepLink",
            "alias": 4,
            "timestamp": 1479123452194,
            "dataType": "String",
            "value": "https://contoso.com/myDevice/123"
        }, {
            "name": "/neowit/v1/sensor/name/TEMP",
            "alias": 5,
            "timestamp": 1479123452194,
            "dataType": "Double",
            "value": 42.3
        }, {
            "name": "/neowit/v1/diagnostics/name/BATTERY",
            "alias": 6,
            "timestamp": 1479123452194,
            "dataType": "Double",
            "value": 80.3
        }],
        "seq": 2
}

Neowit REST API

{
   "id": "<neowitIdOfDevice>",
   "integrationId": "<neowitMqttIntegrationId>",
   "externalId": "group1.node1.device1",
   "name": "My Device Name",
   "vendor": "My Trusted Manufacturer",
   "deviceName": "Awesome Device 1.3",
   "deepLink": "https://contoso.com/myDevice/123",
   "status": "STATUS_CONNECTED"
   "sensors": ["TEMP"],
   "diagnostics": ["BATTERY"]
}

Example DDATA Metrics update

After the Edge application has announced all of its supported sensors in the DBIRTH message, it can then start publishing DDATA of the update metrics for persisting in our metrics store.

Sparkplug DDATA

PUBLISH spBv1.0/group1/DDATA/node1/device1
{
        "timestamp": 1486144503122,
        "metrics": [{

            "name": "/neowit/v1/sensor/name/TEMP",
            "alias": 5,
            "timestamp": 1486144503122,
            "dataType": "Double",
            "value": 30.3
        }, {
            "name": "/neowit/v1/diagnostics/name/BATTERY",
            "alias": 6,
            "timestamp": 1486144503122,
            "dataType": "Double",
            "value": 10
        }],
        "seq": 3
}