Using SparkplugCmd Utility as Sparkplug host application

Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.

For general information about the SparkplugCmd tool, see Category:SparkplugCmd Utility.

Principles of Operation

The SparkplugCmd utility can act as Sparkplug host application, and it can subscribe to data from Sparkplug edge nodes and devices, or publish data (send commands) to them.

The SparkplugCmd utility automatically handled connections to and disconnections from the MQTT broker, i.e. you do not have to issue separate commands for them. Also, the SparkplugCmd utility publishes its status (online/offline) to the MQTT broker, so that it can be configured as primary host application for edge nodes that support this functionality.

Commands, Arguments and Options

The commands described here can be entered at the SparkplugCmd> prompt, or directly on the command-line invoking the SparkplugCmd utility.

Command: consumer

The consumer command (shortened: c) contains sub-commands that allow you to consume Sparkplug data, i.e. act as a Sparkplug host application component in the Sparkplug system.

Arguments

The argument that follows the consumer command is the resource descriptor for the Sparkplug broker that should be used. If omitted, it defaults to mqtt://localhost, i.e. it connects to the MQTT broker on your local machine, using unauthenticated TCP connection on port 1883.

For further information on the URL syntax in resourceDescriptor, and the configurable parameters of the MQTT channel, see OpcLabs.MqttNet communication package.

If you simply enter the consumer command (optionally with a broker URL), the SparkplugCmd enters an interactive mode for this command, and you can continue by issuing one or more sub-commands, each on a separate line. Alternatively, you can include the sub-command directly following the consumer command (with its optional broker URL), in which case the sub-command will be performed immediately.

Options

The consumer command has following specific options:

-ci|--clientId <string>	Client ID
-hi|--hostId <string>	Host ID
-sv|--sparkplugVersion <sparkplugVersion>	Sparkplug version (default PayloadB)

The clientId option sets the client ID that will be used for the connection to the MQTT broker. When this value is empty (which is the default), the component will generate the client ID automatically, attempting to make it unique in the Sparkplug system.

The hostId option sets the Sparkplug host ID of the Sparkplug host application. When this value is empty (which is the default), the component will auto-generate a host ID that is conformant with the Sparkplug syntactic rules. It also attempts to make it unique within the Sparkplug system. Edge nodes can be configured to use this host ID as the primary host application ID, and adjust their behavior based on the status of the primary host.

With the sparkplugVersion option, you can set a combination of following flags: None|Specification22|Specification30|PayloadA|PayloadB . The flags represent the versions of the Sparkplug specification, payload encoding schemes and their versions.

Examples

• consumer, or shortened c

This command will simply show the consumer> prompt, and allow you to enter further sub-commands. The sub-commands will all connect to "mqtt://localhost".

• consumer mqtt://test.mosquitto.org, or shortened c //test.mosquitto.org

This command will show the consumer> prompt, and allow you to enter further sub-commands. The sub-commands will all connect to the specified MQTT broker.

• consumer subscribePayload easyGroup, or shortened c sp easyGroup

This command will connect to "mqtt://localhost" and subscribe to all payloads from the Sparkplug group with ID "easyGroup". Details of the sub-command are explained further below.

Command: consumer subscribePayload

Use the subscribePayload command (shortened: sp) to subscribe to payload notifications from an edge node or device. The received payloads are displayed in a table form.

With this command, each metric can be included no more than once within the displayed payload. For this reason, this command is not suitable for historical data. Use the consumer subscribeMetric command for historical data instead.

Arguments

The command has following arguments:

groupId	Group ID (default #)
edgeNodeId	Edge Node ID (default #)
deviceId	Device ID (default #)
metricName	Metric Name (default #)

The arguments act as filters. They can be exact IDs or names, or you can use "#" (the default) to specify "don't care".

Options

The subscribePayload command has following specific options:

-aum|--allowUnknownMetrics <bool>	Allow Unknown Metrics (default True)
-ct|--componentTypes <sparkplugComponentTypes>	Component Types (default Any)
-dcs|--deliverCompleteDataset <bool>	Deliver Complete Dataset (default False)

The allowUnknownMetrics determines whether the payloads can contain unknown metrics (i.e. metrics without a Birth). When set to False, unknown metrics will be dropped from the payload notifications.

The componentTypes option allows you to specify whether you want to see notification from edge node(s), device(s), or both. Possible values are: None|EdgeNode|Device|Any.

The deliverCompleteDataset option determines whether the notifications will always contain the complete dataset (set of metrics) in the payload. When set to True, metrics not included in the Data message will be automatically filled in with their latest known values.

Examples

• Subscribe to all payload notifications from Sparkplug edge nodes and devices on "mqtt://test.mosquitto.org":

consumer mqtt://test.mosquitto.org
subscribePayload

• Subscribe to payload notifications from Sparkplug edge node "easyEdgeNode" in group "easyGroup" on "mqtt://localhost" (and all its devices):

consumer 
subscribePayload easyGroup easyEdgeNode

Sub-commands

By default, the subscriptions last one minute, or until the you press X on the keyboard. Use the !wait sub-command to specify a different duration, or 'Infinite'.

Command: consumer subscribeMetric

Use the subscribeMetric command (shortened: sm) to subscribe to metric notifications from an edge node or device. Each received metric notification is displayed separately (the payloads are "unpacked").

Arguments

The arguments are the same as for the consumer subscribePayload command.

Options

The subscribeMetric command has following specific options:

-aum|--allowUnknownMetrics <bool>	Allow Unknown Metrics (default True)
-ct|--componentTypes <sparkplugComponentTypes>	Component Types (default Any)
-hf|--historicalFilter <booleanFilter>	Historical Filter (default Any)
-hf|--transientFilter <booleanFilter>	Transient Filter (default Any)

The allowUnknownMetrics determines whether the payloads can contain unknown metrics (i.e. metrics without a Birth). When set to False, unknown metrics will be dropped from the payload notifications.

The componentTypes option allows you to specify whether you want to see notification from edge node(s), device(s), or both. Possible values are: None|EdgeNode|Device|Any.

The historicalFilter and transientFilter options allow you to specify filters for historical and transient metrics. Possible values are: Always|Never|WhenFalse|WhenTrue. Using these options, you can select e.g. to show only metrics that are historical, metrics thar are *not* historical, etc.

Sub-commands

By default, the subscriptions last one minute, or until the you press X on the keyboard. Use the !wait sub-command to specify a different duration, or 'Infinite'.

Command: consumer publishMetric

Use the publishMetric (shortened: pm) command to publish a command metric to an edge node or device.

Arguments

The command has following arguments:

metricName	Metric Name
typedValue	Value to be written
groupId	Group ID
edgeNodeId	Edge Node ID
deviceId	Device ID

The typedValue consists of a Sparkplug data type identifier, enclosed in square brackets, followed immediately by the actual value. Possible Sparkplug data types are: Unknown|Int8|Int16|Int32|Int64|UInt8|UInt16|UInt32|UInt64|Float|Double|Boolean|String|DateTime|Text|Uuid|DataSet|Bytes|File|Template|PropertySet|PropertySetList|Int8Array|Int16Array|Int32Array|Int64Array|UInt8Array|UInt16Array|UInt32Array|UInt64Array|FloatArray|DoubleArray|BooleanArray|StringArray|DateTimeArray.

Omit the deviceId argument if you are publishing to an edge node metric. Include non-empty deviceId if you are publishing to a device metric.

Examples

Example: consumer publishMetric Static/Int32Value [Int32]3141 easyGroup easySparkplugDemo data

Command: consumer edgeNodeRebirth

Use the edgeNodeRebirth command (shortened: enr) to publish a command to rebirth an edge node. This is a shortcut for publishing a 'true' boolean value to the metric named "Node Control/Rebirth" on the given edge node. This metric is used to request a new NBIRTH and DBIRTH(s) from the edge node.

Example: consumer edgeNodeRebirth easyGroup easySparkplugDemo