Using SparkplugCmd Utility as Sparkplug Edge Node

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, 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 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

edgeNode mqtt://test.mosquitto.org easyGroup easySparkplugDemo
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

!!!

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

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

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

Command: edgeNode device

!!!

Command: edgeNode device get

!!!

Command: edgeNode device readMetric

!!!

Command: edgeNode device writeMetric

!!!

Command: edgeNode clear

!!!

Command: edgeNode addDevice

!!!