Using SparkplugCmd Utility as Sparkplug Edge Node

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.

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: edgeNode

The edgeNode command (shortened: en) creates a Sparkplug edge node with pre-defined content (metrics on the edge node itself, and devices with further metrics on them). By default, the edge node will connect (when started) to "mqtt://localhost" (unauthenticated TCP connection, using port 1883).

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

CAUTION: Each edgeNode command invocation works on a separate, new edge node component. If you want to perform multiple operations with the same edge node, issue the edgeNode command (and its arguments) just once, entering its interactive mode (manifested by the edgeNode> prompt on the console). Then, issue the sub-commands (such as start), leaving out the edgeNode command prefix.

Arguments

The command has following arguments:

resourceDescriptor	Sparkplug broker descriptor (default mqtt://localhost/)
groupId	Group ID (default easyGroup)
edgeNodeId	Edge Node ID

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

The edgeNodeId argument sets the ID of the Sparkplug edge node. When this value is empty (which is the default), the component will auto-generate an edge node ID that is conformant with the Sparkplug syntactic rules. It also attempts to make it unique within the Sparkplug system. Sparkplug host applications use the edge node ID to subscribe to metrics from the edge node and its devices, and to send commands to them.

Options

The edgeNode command has following specific options:

-ci|--clientId <string>	Client ID
-phi|--primaryHostId <string>	Primary Host ID
-sv|--sparkplugVersion <sparkplugVersion>	Sparkplug version

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 primaryHostId option sets the Sparkplug host ID of the Sparkplug primary host application for this edge node. When this value is empty (which is the default), the edge node will not be tied to anyprimary host application, and it will publish data whenever it is connected to the broker. When this value is set to a non-empty string, the edge node will observer the status of the specified primary host application, and will only publish data when the primary host application is online.

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

• edgeNode, or shortened en

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

• edgeNode mqtt://test.mosquitto.org, or shortened en //test.mosquitto.org

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

• edgeNode mqtt://test.mosquitto.org easyGroup easySparkplugDemo start, or shortened en //test.mosquitto.org easyGroup easySparkplugDemo start

This command will connect to "mqtt://test.mosquitto.org" and act as an edge node with ID "easySparkplugDemo" in Sparkplug group with ID "easyGroup". The start sub-command is explained further below.

Command: edgeNode start

This command starts the Sparkplug edge node, using the parameters specified in the edgeNode command. The node then runs until it is stopped by the user, or a specified time elapses. It can also be left running (see the !sustain sub-command).

While the start command is executing, events related to the edge node operations are displayed on the console. This includes connection and status information, and also data about commands being sent to the edge node or its devices.

Sub-commands

By default, the edge node runs until the you press X on the keyboard. Use the !wait sub-command to specify a finite duration. The edge node then stops automatically (unless the !sustain sub-command is used).

You can use the !sustain sub-command to leave the edge node running, while continue working with SparkplugCmd. This will allow you, for example, to view or modify the values of the metrics in the edge node and its devices. The edge can then be stopped using the stop command.

CAUTION: With the !sustain sub-command, when the SparkplugCmd is at the command prompt, it does not show the incoming events related to the edge node operations, because it would interfere with entering user commands. You can press Enter on an empty command line, even repeatedly, to force display of the events accumulated while the output was suppressed.

Examples

Start the edge node with ID "easySparkplugDemo" in Sparkplug group "easyGroup", connecting it to "mqtt://test.mosquitto.org". The edge node will start publishing immediately.

edgeNode mqtt://test.mosquitto.org easyGroup easySparkplugDemo
start

As above, but specifying "easyApplication" as the primary host ID. The edge will only start publishing when the "easyApplication" comes online.

edgeNode mqtt://test.mosquitto.org easyGroup easySparkplugDemo --primaryHostId easyApplication
start

Command: edgeNode stop

This command stops the running Sparkplug edge node. It only makes sense when the start command was used with the !sustain sub-command.

Command: edgeNode performRebirth

The performRebirth command (shortened: pr) performs a rebirth of the edge node. The edge node must be started, i.e. this command only makes sense when the start command was used with the !sustain sub-command.

During the rebirth, the edge node

1. stops sending Data messages,
2. sends a Birth sequence (edge node Birth and device Birth messages),
3. resumes sending Data messages.

This operation does not cause disconnection and reconnection to the MQTT broker.

The performRebirth command has no arguments.

Examples

edgeNode mqtt://test.mosquitto.org
start !sustain
performRebirth
stop

Command: edgeNode get

This command can be used to obtain and display the current settings of the edge node.

Use this command without further options to display a table of metrics defined directly on the edge node.

Use this command with the -!viewValue option (shortened: -!vv) to display all properties of the edge node.

Use get Devices to display a table of devices that the edge node has.

Command: edgeNode readMetric

The readMetric command (shortened: rm) reads current data from the specified metric on the edge node, and displays them. The edge node must be started, i.e. this command only makes sense when the start command was used with the !sustain sub-command.

Arguments

The command has a single argument, metricName, which is the name of the metric you want to read.

Examples

Read a metric named "Simple" on the edge node:

edgeNode mqtt://test.mosquitto.org
start !sustain
readMetric Simple
stop

Command: edgeNode writeMetric

The writeMetric command (shortened: wm) writes data to the specified metric on the edge node. The edge node must be started, i.e. this command only makes sense when the start command was used with the !sustain sub-command.

The new metric data will be picked up in the next polling cycle, and published if it has changed.

Arguments

The command has following arguments:

metricName	Metric Name
typedValue	Value to be written

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.

Examples

This example creates and starts the edge node, and then writes a 32-bit signed integer value 3141 into the metric named "Simple" directly on the edge node:

edgeNode mqtt://test.mosquitto.org
start !sustain
writeMetric Simple [Int32]3141
stop

Command: edgeNode device

The device command (shortened: d) provides operations on a specified device within the Sparkplug edge node.

If you simply enter the device command (optionally with an arguments, but no sub-commands), the SparkplugCmd enters an interactive mode for this command (showing a device> prompt to indicate this fact), and you can continue by issuing one or more sub-commands, each on a separate line. Alternatively, you can include some sub-command directly following the device command (with its optional arguments), in which case the sub-command will be performed immediately.

Arguments

This command has a single deviceId argument, which is the name of the device on the edge node that you want to work with.

Command: edgeNode device get

This command can be used to obtain and display the current settings of the Sparkplug device.

Use this command without further options to display a table of metrics defined on the Sparkplug device.

Use this command with the -!viewValue option (shortened: -!vv) to display all properties of the Sparkplug device.

Examples

This example displays a table of all metrics defined in the "data" device:

edgeNode mqtt://test.mosquitto.org
device data get

Command: edgeNode device readMetric

This command works as Command: edgeNode readMetric, but it operates on a metric in the Sparkplug device, instead of an edge node.

Examples

Read a metric named "Static/Int32Value" on the "data" device:

edgeNode mqtt://test.mosquitto.org
start !sustain
device data
readMetric Static/Int32Value

Command: edgeNode device writeMetric

This command works as Command: edgeNode writeMetric, but it operates on a metric in the Sparkplug device, instead of an edge node.

Examples

Writes a 32-bit signed integer value 3141 into the metric named "Static/Int32Value" on the "data" device:

edgeNode mqtt://test.mosquitto.org
start !sustain
device data
writeMetric Static/Int32Value [Int32]3141

Command: edgeNode clear

This command removes all devices and metrics from the edge node.

Command: edgeNode addDevice

This command adds a device to the Sparkplug edge node.

Arguments

The addDevice command has one argument, which is the name of the device. Currently, you can use one of the following pre-defined device names:

console

Contains metrics that allow interaction with the console.

data

Contains metrics that show various data types, access modes, and behaviors.

demo

Contains several metrics that demonstrate various features of the tool.

For more information about the metrics in the available devices, see Demo Contents.

Demo Contents

By default, the edge node created with the SparkplugCmd contains:

• The 'Demo' Metrics directly on the edge node
• A device named "console", with 'Console' Metrics
• A device named "data", with 'Data' Metrics
• A device named "demo", with 'Demo' Metrics (i.e. a second instance of the metrics that also exist directly on the edge node).

You can use the edgeNode clear and edgeNode addDevice command to manipulate the available metrics and devices.

'Console' Metrics

This set of metrics provides interaction with the console:

• "Write" metric: A value sent to this metric is outputted on the console.
• "WriteLine" metric: A value sent to this metric is outputted on the console, and a new line is started.

'Data' Metrics

This set of metrics shows various data types, access modes, and behaviors.

• "Constant/XXXXValue" metrics: Read-only metrics with constant values.
• "Dynamic/XXXXValue" metrics: Metrics with dynamically changing values.
• "FullyWritable/XXXXValue" metrics: Metrics that have not only writable value, but also writable timestamp.
• "ReadOnly/XXXXValue" metrics: Read-only metrics. Their values can be changed through corresponding "WriteOnly/XXXXValue" metrics.
• "Static/XXXXValue" metrics": Metrics with static values which can be changed through writing to them (so-called "registers").
• "WriteOnly/XXXXValue" metrics: Write-only metrics of various data types. Their values are reflected in the corresponding "ReadOnly/XXXXValue" metrics.

'Demo' Metrics

This set of metrics demonstrates various features of the component:

• Metrics directly on the root level: "Ramp", "Simple", "Simple2"
• Metrics organized in folders (nested metrics): "Random", "Nested/Random", "Nested/FurtherNested/Random"
• Metrics that cannot be written to: "WriteFailure"