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