Sparkplug

The Sparkplug 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. Below are details on the connection, input, and output settings and supported features.

Connection Settings

Setting	Description
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 / Edge Id	The default Group Id and Edge Id to use if the input or output settings don’t override them. If these are set the connection will setup a Last Will NDEATH message for the node on connect. The connection will also subscribe using the Group/Edge for NCMD messages to listen and respond to NBIRTH requests. If this isn’t desired, leave these blank and set the Group/Edge in the Input and Output settings
Use SSL	Enable for MQTT brokers that require transport layer 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 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

The connection holds a cache for each unique Edge Node and Device being published to the broker. The cache includes metrics, values, properties, alias mappings and templates.

If an input is configured to read a specific Group/Edge/Device, the first read subscribes and then requests a BIRTH from the Edge Node or Device. The BIRTH response populates the cache with the current state. This includes metrics, values, properties, alias mapping, and templates.

If the input contains wildcards for the Group, Edge, or Device the first read subscribes and then listens for messages. When an Edge Node or Device message is received, the connection then requests a BIRTH to initialize the cache. If a BIRTH response is received, the cache is initialized and DATA messages update the values. If a BIRTH is not received, the cache is populated by DATA messages as they are received. In this case aliasing will not work as it requires the BIRTH.

Reading an input reads and filters the cache depending on the input settings. Subscribing to in input generates events when data changes in the cache. Note these data changes include both Sparkplug BIRTH and DATA messages.

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/#).
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>/#).
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 reads return the current values for metrics in the cache. Note the includes data received by the SparkplugB BIRTH and DATA messages. CMD reads 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 and 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.