Sparkplug

The Splarkplug Connection connects to an MQTT Broker and supports reading and writing data in Sparkplug format. The connection can be used to read data from one or more Group/Edge Node/Device, or can be setup to publish as a Group/Edge Node/Device.

Currently SparkplugB is supported. Below are details on the connection, input, and output settings and supported features.

Connection Settings

Host

The IP or hostname of the MQTT broker.

Port

The port of the MQTT broker.

Client ID

The ID to send to identify the connection with the broker. Leave blank to make this random. MQTT brokers require each client to have a unique ID and will disconnect clients with duplicate IDs.

Username and Password

The username and password required by the MQTT broker.

Connection Timeout

Maximum time to wait for a connection to respond. Valid range is 1–300 seconds.

Keep Alive

Maximum time to wait without sending a request to the broker. Valid range is 10-43200 seconds.

Request Timeout (ms)

Maximum time to wait for a subscription to arrive. Valid range is 100–60000 milliseconds.

Default Group Id

The default Group Id to use if the input or output settings don’t define a Group Id.

Default Edge Node Id

The default Edge Node Id to use if the input or output settings don’t define a Edge Node Id.

Use SSL

Enable for MQTT brokers that require transport layer security. information on MQTT security.

Ignore Self-Signed Certificate

When enabled, any certificate returned from the broker will be accepted. This setting should only be used for testing connectivity, but is not recommended for production.

CA Certificate

The name of the trusted certificate file used to identify the broker as part of a secure TLS connection.

Client Certificate

Used if the broker broker requires client authentication using a certificate. This is the public certificate for the client (e.g., mycert.pem).

Client Key

Used if the broker requires client authentication. This is the private key for the client (e.g., mycert.key.pem).

Input Settings

Inputs can read a single metric on a group/edge node/device or the entire Sparkplug namespace. Inputs support reading quality (good/bad) but currently do not support reading Sparkplug properties.

Setting Description
Group Id Override the Default Group Id field set in the connection settings. This makes the input listen on topic spBv1.0/<group_id>/#. Group Id can be a wildcard ‘#’ which means the input listens on all groups on the broker (i.e. spBv1.0/#). In this mode the input cannot request a birth certificate for groups/edge nodes because there is no way to discover them. Instead, it waits to receive a message from a new group/edge node and then immediately requests a birth. This can cause a delay in groups/edge nodes appearing in the read result.
Edge Node Id Override the Default Edge Node Id field set in the connection settings. This makes the input listen on topic spBv1.0/<group_id>/<msg_type>/<edge_id>/#, gathering all data and devices for the edge node. Edge Node Id can be a wildcard ‘#’ which means the input listens on a group for all edge nodes (i.e. spBv1.0/<group_id>/<msg_type>/#). In this mode the input cannot request a birth certificate for edge nodes because there is no way to discover them. Instead, it waits to receive a message from a new edge node and then immediately requests a birth. This can cause a delay in edge nodes appearing in the read result.
Device Id Allows for filtering data from an edge node by device. A wildcard # is supported to get all devices for the edge node. Leave this blank to only collect metrics for the edge node.
Metric Name Prides a way to filter the result to return only a given metric, or a branch of metrics. For example Folder/MetricA only returns MetricA, where Folder/# returns all metrics under Folder.
Message Type DATA or CMD. DATA messages include the metric information only. CMD messages capture write commands issued to the Group/Edge/Device/Metric. Note CMD’s can only be read once when they are used in a data flow. This way a single write isn’t issued multiple times.
Include Metadata When enabled, the Edge of Node, Group, and Device ID (if applicable) are included in the payload of the read. The value is included under a “value” attribute.
Include Properties When enabled, properties belonging to the value are included in the payload. The value is included under a “value” attribute. This option is only available when the Message Type is set to DATA.

Output Settings

Outputs support writing as a single or many group/edge node/devices (using Dynamic Outputs). Outputs support writing metric values and a data quality property (good/bad) as well as responding to birth/death message requests.

Setting Description
Group Id Override the Default Group Id field set in the connection settings.
Edge Node Id Override the Default Edge Node Id field set in the connection settings.
Device Id The Id for the attached device the metric belongs to. Do not set the device id if the metric belongs to the EoN.
Metric Name Optionally specify the metric name to write. Examples include: MetricA, Folder/MetricA. If you do not set a metric name, the metric name will be auto generated from the input or model instance name. This allows you to route many inputs and/or instances to a single output and simplifies configuration.
Message Type DATA or CMD. DATA sends NDATA or DDATA messages. CMD is used to send write commands for one or more metrics.
Timestamp If specified, the timestamp in the payload will be overwritten by the given timestamp. This field accepts both time since epoch in milliseconds or an ISO8601 date time string in UTC format.
Publish Type Controls how the data is published, either in Tag or Template format. In Tag format data is flattened into metrics with a “/” delimiter. In Template mode metrics are converted into SPB templates, including hierarchy.