Sparkplug Decode

Premium

Version 3.2

The Sparkplug specification version 3.0 requires all payloads to be sent in a standardised Protobuf format. This is very efficient in bandwidth use, but is not human readable. The Sparkplug Decode plugin can be used to decode the Protobuf messages and republish them as JSON.

The plugin has two decoding modes, basic, enhanced, and can disabled at runtime.

Use the setDecodeMode API command to switch modes.

Prior to version 3.2, only the basic mode was supported. This remains the default mode if no other configuration is present.

Plugin Activation

To enable the plugin it must be loaded into the broker with, by adding the following to your mosquitto.conf:

global_plugin /usr/lib/cedalo_sparkplug_decode.so

Further configuration is carried out over the API.

Basic decoding

This mode automatically processes all Sparkplug messages arriving on topics matching spBv1.0/#, decodes them into JSON and republishes them to spJv1.0/#.

This provides a human readable version of each message, which is useful for observation and debugging. Only valid Sparkplug messages will be decoded and forwarded to the spJv1.0/# topic, while all others will be ignored.

note

The decoding is a one to one conversion without any state, so a message with multiple metrics will have all metrics in the resulting JSON message, and metric aliases will be left as is.

The JSON schema used is from First draft of Sparkplug B JSON schema, however it is important to note that this feature is not currently supported by Sparkplug. It is possible that a standard JSON payload for Sparkplug may appear in the future, at which point the output of this plugin may be incompatible. For this reason it is recommended that you do not build your device management on the JSON output but use it only for observation and debugging.

Enhanced decoding

This mode processes NBIRTH, NDATA, DBIRTH, and DDATA messages only. It republishes each metric individually to its own topic and stores the metric name/alias mapping so that metrics in NDATA/DDATA messages are published with the correct name.

By default, the metrics are published to an extended Sparkplug topic. For edge nodes, the topic is of the form:

• spBv1.0/<group name>/NDATA/<edge node id>//metrics/<metric name>

For devices the topic is of the form:

• spBv1.0/<group name>/DDATA/<edge node id>/<device id>/metrics/<metric name>

Thus it is possible to subscribe to all JSON messages using a topic subscription to spBv1.0/+/+/+/+/metrics/#.

A custom topic prefix can also be specified using the setTopicPrefix API command. In this case, the topics for edge nodes and devices will be of the form:

• <topic prefix>/<group name>/<edge node id>//<metric name>
• <topic prefix>/<group name>/<edge node id>/<device id>/<metric name>

note

The template, propertyset, and propertysetlist metric datatypes are not currently supported.

Decoding disabled

To disable the processing of incoming messages,set the decode mode to none in the setDecodeMode command.

MQTT API Examples

The full MQTT API documentation is available at FIXME. This section gives some example commands and responses.

In all cases, the commands must be sent to the topic $CONTROL/cedalo/sparkplug-decode/v1 and responses will be sent to $CONTROL/cedalo/sparkplug-decode/v1/response.

The command payload is JSON with an array of commands to be processed:

{
    "commands":[
        // List of command objects
    ]
}

For example:

{
    "commands":[{
        "command": "setDecodeMode",
        "decodeMode": "enhanced",
        "correlationData": "6754df1d-2477-4ffa-ae97-419104e4037c"
    }]
}

The optional correlationData element is a string generated by the publisher and will be returned with the response to allow it to be matched to the command.

The response payload is JSON with an array of responses corresponding to the commands.

Commands that do not return data have a simple response:

{
    "responses":[{
        "command": "setDecodeMode",
        "correlationData": "6754df1d-2477-4ffa-ae97-419104e4037c"
    }]
}

Commands that produce an error include an error element:

{
    "responses":[{
        "command": "setDecodeMode",
        "error": "Invalid decodeMode value",
        "correlationData": "6754df1d-2477-4ffa-ae97-419104e4037c"
    }]
}

Commands that return data have a data object with command specific information:

{
    "responses":[{
        "command": "getDecodeMode",
        "data": {
            "decodeMode": "enhanced"
        },
        "correlationData": "6754df1d-2477-4ffa-ae97-419104e4037c"
    }]
}

Manual MQTT API Request

Although it is expected that the configuration is controlled via the Cedalo Platform or other automated means, it can be useful to be able to issue MQTT API requests manually. This can be done in a low-level manner using the commandline "request reponse" client mosquitto_rr. This tool subscribes to a single topic, publishes a message to another topic and waits for the response.

In this example we are not making use of encryption. The manual for mosquitto_rr contains all of the command line options to allow use to specifify encryption for your production environment. Note as well that your client must have the appropriate rights to make the request.

The -e argument is used to set the response topic and -t the request topic, which must be $CONTROL/cedalo/sparkplug-decode/v1/response and $CONTROL/cedalo/sparkplug-decode/v1 respectively.

The command to set the decode mode is:

mosquitto_rr -u <username> -P <password> -h <hostname> -p <port> \
    -t '$CONTROL/cedalo/sparkplug-decode/v1' \
    -e '$CONTROL/cedalo/sparkplug-decode/v1/response' \
    -m '{"commands": [{ "command": "setDecodeMode", "decodeMode": "enhanced" }]}'

The command to set the topic prefix is:

mosquitto_rr -u <username> -P <password> -h <hostname> -p <port> \
    -t '$CONTROL/cedalo/sparkplug-decode/v1' \
    -e '$CONTROL/cedalo/sparkplug-decode/v1/response' \
    -m '{"commands": [{ "command": "setDecodeMode", "decodeMode": "enhanced" }]}'