Sparkplug ist ein Protokoll, welches auf MQTT aufbaut. Bei Sparkplug ist, anders als bei MQTT, das Kommunikationsverhalten und -format zwischen den Teilnehmern, auch Edge of network (EoN) Nodes genannt, definiert.
Beim Start können Teilnehmer des Netzwerkes anderen Teilnehmern mitteilen, welche Datenpunkte (hier im Kontext Metric genannt) und Kommandos sie zur Verfügung stellen. Die Daten können entweder den EoN selbst oder einen Device des EoNs zugeordnet werden.
Der Sparkplug-Treiber kann an einem Sparkplug-Netzwerk als EoN teilnehmen. Für weitere Informationen über das Protokoll, siehe https://sparkplug.eclipse.org/.
Konfiguration
Der Treiber wird komplett über seine Konfigurationsdatei konfiguriert.
MQTT Konfiguration
Sparkplug nutzt zur Kommunikation das Protokoll MQTT. Die MQTT-Verbindung kann über im Abschnitt “MQTT” konfiguriert werden.
Der Treiber unterstützt Sparkplug-Netzwerke mit mehreren MQTT-Brokern. Es können in der Konfiguration mehrere MQTT-Adressen über Leerzeichen getrennt angegeben werden.
TLS Konfiguration
Falls die Verbindung zum MQTT-Broker verschlüsselt ist, kann die Verschlüsselung im Abschnitt “TLS” konfiguriert werden.
Sparkplug Konfiguration
Im Abschnitt “Sparkplug” werden Sparkplug spezifische Einstellungen vorgenommen.
Der Treiber unterstützt die Sparkplug-Versionen 2 und 3, wobei die Unterstützung der veralteten Version 2 nur rudimentär ist. Die Version kann mit “SparkplugMajorVersion” gesetzt werden.
Der Sparkplug Gruppe kann über den Eintrag “GroupId” gesetzt werden. Der Treiber nimmt am SparkplugNetzwerk als EoN Node teil. Die ID des Nodes kann über “EdgeNodeId” gesetzt werden.
Wenn sich im Sparkplug-Netzwerk ein “primärer Host” befindet, kann die ID dieses Hosts mit “PrimaryHostID” angegeben werden. Der Treiber wird dann darauf warten, dass der Host online ist. Falls der Host offline ist, wird der Treiber die Verbindung nicht aufbauen.
Der Treiber unterstützt die Verwendung von Aliase für Metrics. Wenn andere Teilnehmer dies nicht unterstützen, kann das mit “UseAlias” ausgeschaltet werden.
Datenpunkte
Alle Datenpunkte haben das Format ‘type id’. id kann beliebig gewählt werden, muss aber kleiner als 7 Zeichen sein. Die ID wird nur zur Identifikation des Datenpunktes benutzt und nicht für die Sparkplug-Kommunikation. Type ist entweder ‘state’ oder ‘metric’
State
Mit einem State-Datenpunkt wird der Status der Devices des lokalen EoNs abgebildet. Der State-Datenpunkt ist beschreibbar, so das ein Device des EoNs online oder offline gesetzt werden kann.
Metric
Daten werden bei Sparklpug über Metricen definiert. Der Treiber kann Metricen über Datenpunkte unterstützen.
Die Adresse der Datenpunkte hat das Format ‘metric id’.
Der Name der Metric kann über den ‘name’-Eintrag des Datenpunktes gesetzt werden.
Im Format-String des Datenpunktes kann definiert werden, zu welcher Gruppe, zu welchem EoN Node und zu welchem Device die Metric gehört. Dazu können im format-String die Einträge ‘group:“group_id’, ‘node:“node_id” ’ und ‘device:“device_id” ’ gesetzt werden. Wenn keine Gruppe oder Node angegeben wird, wird die Gruppe beziehungsweise der Node des Treibers genommen.
Eine Metric kann Properties haben, um zum Beispiel den Wert einer Einheit zuzuordnen. Der Treiber unterstützt konstante Properties, die über den format-String mit ‘properties:{}’ angegeben werden können. Das Format der Properties ist ein JSON-Objekt bestehend aus Strings.
Beispiele
splg.cfg
#This section configures the mqtt connection
[MQTT]
# A list of brokers
# The format of a broker is 'address:port'. Multiple brokers are seperated by spaces
#
# Type: String
# Default: 127.0.0.1:1883 127.0.0.1:8883
Brokers = 127.0.0.1:1883 127.0.0.1:8883
# The client id of the mqtt client
#
# Type: String
# Default: gateway
ClientId = gateway
# User name for authentication
#
# Type: String
# Default:
User =
# Password for authentication
#
# Type: String
# Default:
Password =
# Default Quality of Service for data messages.
#
# Type: Int
# Default: 0
DefaultQoS = 0
# Timer to send MQTT ping requests in seconds
#
# Type: Int
# Default: 300
KeepAlive = 300
# Timeout for mqtt request in milliseconds
#
# Type: Int
# Default: 10000
MqttTimeout = 10000
# Timeout for IO operations in seconds
#
# Type: Int
# Default: 5
IOTimeout = 5
# Max pending messages
#
# Type: Int
# Default: 100
MaxPending = 100
#This section configures the encryption used by the mqtt connection
[TLS]
# The encryption to use.
# '' => Use encryption for port 8883, elso don't.
# 'Off' => No encryption
# 'On' => Use an encrypted connection.
# Automatically use the highest TLS version supported by the broker.
# 'SSLv3_0' => use at least SSL Version 3.0
# 'TLSv1_0' => use at least TLS Version 1
# 'TLSv1_1' => use at least TLS Version 1.1
# 'TLSv1_2' => use at least TLS Version 1.2
# 'TLSv1_3' => use at least TLS Version 1.3
#
# Type: String
# Default:
Encryption =
# If set to true, the broker TLS certificate is not verified.
# This is usefull for self signed certificates or certificates that are unknown by the operating system.
# Currently it is not possible to upload custom CA files.
#
# Type: bool
# Default: false
DontVerifyCert =
# Use the Server Name Indication extension for TLS.
# This is needed, if the TLS server is hosting multiple Domains.
# If empty, the SNI extension is not used for the TLS connection.
#
# Type: string
# Default:
SNI =
#This section configures the sparklpug connection
[Sparkplug]
# The major sparkplug version to use.
# Version 2 and Version 3 are supported.
#
# Type: Int
# Default: 3
SparkplugMajorVersion = 3
# Timer of the sparkplug loop in milliseconds
#
# Type: Int
# Default: 100
Timer = 100
# The group this EoN belongs to
#
# Type: String
# Default: group0
GroupId = group0
# The id of this node
#
# Type: String
# Default: gateway
EdgeNodeId = gateway
# The id of the Primary Host Application.
#
# If no ID is given, the driver will not handle STATE messages.
#
# Type: String
# Default:
PrimaryHostID =
# If set to true, the sparkplug driver will use an alias for the name of the metric instead of the full metric name.
# This feature must be supported by the other sparkplug applications.
# See the sparkplug specification for more informations.
#
# Type: bool
# Default: true
UseAlias = true
# This is the maximum pending value changes the driver is buffering for each device.
# The driver will send all value changes on each timer step if the device is online.
# The driver will drop the oldest value change if the limit is reached.
#
# Type: int
# Default: 25
MaxPendingValues = 25
splg.txt
# The address has the format 'type id'
#
# The type can be either failure, state or metric.
# The id must be unique and must not be greater than 7 characters!
#
#
# A failure datapoint is set to true on communication failures by this driver.
# The id must not be set.
#
#
# The state datapoint controlls if a device is online or offline.
# If this datapoint is set to 0, the device state is set to online and else to offline.
# The device name must be given in the format string with 'device: "device ID"'.
# If no state is given for a device, the device is always set to online.
#
#
# The metric datapoint defines a metric. The metric name is set with the "name"-property.
# If the metric belongs to a device, the device must be given in the format string with 'device: "deviceID"'.
# The node and group of the metric can be given with 'node: "node_ID"' and 'group: "group_ID"' in the format string.
# If no node is given, the datapoint will belong to the local node and if no group is given, the local group is taken.
# The remote node must not use metric aliases!
#
# The data type of the metric can be set by setting 'type' in the format string.
# Type can be one of BIT, BOOL, UINT8, UINT16, UINT32, UINT64, SINT8, SINT16, SINT32, SINT64, FLOAT32, FLOAT64, STRING, BYTES.
#
# Static properties of the metric can be defined with the 'properties' token.
# The format of the properties is a json object where the keys are the properties keys and the values are the static properties values.
# Dynamic property values are currently not supported.
# The communication failure datapoint
[M failure]
name = Communication failure
# A state datapoint for the device 'sensor 1'.
# If set to true, the device is set to online.
[S state 0]
name = State of Sensor 1
format = device:"sensor1"
# A metric of the EoN. The name of the metric is 'temperature'.
# The metric has a property "unit" and its data type is a floating data point with double precision.
[Y metric 0]
name = temperature
format = properties:{"unit": "°C"} type:"FLOAT64"
# A metric of the device 'sensor1' with the name 'A/B/C/D'
[Y metric 1]
name = A/B/C/D
format = device:"sensor1"
# A metric of the device 'sensor1' with the name 'A/B/C/E'
[A metric 2]
name = A/B/C/E
format = device:"sensor1"
# A metric of the device 'sensor1' with the name 'A/B/C/F'
[M metric 3]
name = A/B/C/F
format = device:"sensor1"