Sparkplug B Datentypen legen genau fest, wie jeder Metrikwert kodiert wird, von einer vorzeichenbehafteten 8-Bit-Ganzzahl bis zu einer vollständigen Tabelle mit Zeilen und Spalten. Diese Referenz listet jeden Datentyp-Code mit dem zugehörigen Protobuf-Feld auf, erklärt Metrik-Properties und Qualitätscodes und zeigt dekodierte Beispiele, damit Sie jeden Typ erkennen, wenn Sie echten Datenverkehr untersuchen.
Warum Sparkplug eigene Datentypen hat
JSON kennt Zahlen, Strings und Booleans. Industrielle Systeme in Maschinenbau und Prozessindustrie brauchen mehr Präzision. Ein SPS-Register, etwa in einer Siemens S7, kann eine vorzeichenlose 16-Bit-Ganzzahl sein, ein Zähler ein vorzeichenloser 64-Bit-Wert, und ein Zeitstempel darf nicht mit einer gewöhnlichen Zahl verwechselt werden. Sparkplug B gibt jeder Metrik einen expliziten datatype-Code, damit eine Host-Anwendung am anderen Ende der Welt den Wert genau so interpretiert, wie der Edge Node ihn gemeint hat.
Der Datentyp wird in Birth-Nachrichten für jede Metrik deklariert. Datennachrichten dürfen ihn weglassen, weshalb Konsumenten die Datentypen aus den Births speichern, wie in unserem Leitfaden zum Sparkplug B Payload beschrieben.
Skalare Sparkplug B Datentypen
| Code | Name | Protobuf-Wertfeld | Hinweise |
|---|---|---|---|
| 0 | Unknown | keins | Platzhalter, sollte in gültigen Metriken nicht vorkommen |
| 1 | Int8 | int_value | Vorzeichenbehaftet, Zweierkomplement in einem vorzeichenlosen Feld |
| 2 | Int16 | int_value | Vorzeichenbehaftet, Zweierkomplement |
| 3 | Int32 | int_value | Vorzeichenbehaftet, Zweierkomplement |
| 4 | Int64 | long_value | Vorzeichenbehaftet, Zweierkomplement in uint64 |
| 5 | UInt8 | int_value | Vorzeichenlos |
| 6 | UInt16 | int_value | Vorzeichenlos |
| 7 | UInt32 | int_value | Vorzeichenlos |
| 8 | UInt64 | long_value | Vorzeichenlos |
| 9 | Float | float_value | 32-Bit IEEE 754 |
| 10 | Double | double_value | 64-Bit IEEE 754 |
| 11 | Boolean | boolean_value | true oder false |
| 12 | String | string_value | UTF-8-Text |
| 13 | DateTime | long_value | Millisekunden seit Unix-Epoch, UTC |
| 14 | Text | string_value | Längerer Text, gleiche Kodierung wie String |
| 15 | UUID | string_value | UUID in String-Form |
| 16 | DataSet | dataset_value | Tabelle mit typisierten Spalten und Zeilen |
| 17 | Bytes | bytes_value | Rohe Binärdaten |
| 18 | File | bytes_value | Dateiinhalt, beschrieben durch MetaData |
| 19 | Template | template_value | Benutzerdefinierter Typ oder Instanz |
Die Codes 20 und 21 (PropertySet und PropertySetList) werden für Property-Werte verwendet, nicht für Metrikwerte.
Die Falle bei vorzeichenbehafteten Ganzzahlen
Der häufigste Dekodierfehler bei Sparkplug ist das direkte Lesen vorzeichenbehafteter Ganzzahlen. Da int_value ein vorzeichenloses 32-Bit-Feld ist, kommt ein Int32 mit dem Wert -5 als 4294967291 an, und ein Int64 mit dem Wert -1 als 18446744073709551615 in long_value. Der Konsument muss anhand des deklarierten Datentyps das Zweierkomplement anwenden. Edge Nodes müssen beim Kodieren umgekehrt vorgehen. Zeigt ein Dashboard plötzlich eine Temperatur von vier Milliarden Grad an, ist das fast immer der Grund.
DateTime ist keine Zahl
Eine DateTime-Metrik und eine Int64-Metrik nutzen dasselbe Feld, bedeuten aber Unterschiedliches. Behandeln Sie DateTime als Millisekunden seit Epoch in UTC und rechnen Sie den Wert für die Anzeige um. Senden Sie niemals Sekunden und niemals Ortszeit.
Array-Datentypen
Sparkplug definiert außerdem Arrays skalarer Typen. Sie werden in bytes_value als gepackte Little-Endian-Werte übertragen, eine Kodierung, die Sparkplug 3.0 präzise festlegt (was sonst noch präzisiert wurde, zeigt unser Vergleich zu Sparkplug 3.0).
| Code | Name | Code | Name |
|---|---|---|---|
| 22 | Int8Array | 29 | UInt64Array |
| 23 | Int16Array | 30 | FloatArray |
| 24 | Int32Array | 31 | DoubleArray |
| 25 | Int64Array | 32 | BooleanArray |
| 26 | UInt8Array | 33 | StringArray |
| 27 | UInt16Array | 34 | DateTimeArray |
| 28 | UInt32Array |
Die Array-Unterstützung unterscheidet sich zwischen Produkten. Wenn Sie herstellerübergreifend auf Arrays angewiesen sind, testen Sie sie frühzeitig mit beiden Seiten am selben Broker.
Metrik-Flags
Jede Metrik kann boolesche Flags tragen, die beeinflussen, wie Konsumenten sie behandeln:
| Flag | Bedeutung | Verhalten des Konsumenten |
|---|---|---|
| is_null | Die Metrik existiert, hat aber keinen Wert | Als null oder schlechte Qualität anzeigen, nicht durch null ersetzen |
| is_historical | Wert stammt aus der Vergangenheit, etwa aus Store and Forward | Speichern, aber den Live-Wert nicht überschreiben |
| is_transient | Wert soll nicht historisiert werden | Anzeigen, aber nicht speichern |
Metriken haben außerdem einen optionalen timestamp, getrennt vom Zeitstempel des Payloads. Nutzen Sie ihn, um festzuhalten, wann der Wert an der Quelle erfasst wurde.
Metrik-Properties
Eine Metrik kann ein PropertySet tragen: parallele Listen aus Schlüsseln und typisierten Werten. Property-Werte nutzen dieselben Datentyp-Codes sowie PropertySet (20) und PropertySetList (21), die Verschachtelung ermöglichen.
Die Quality-Property
Die einzige Property, der die Spezifikation eine festgelegte Bedeutung gibt, ist Quality, ein Int32:
| Wert | Bedeutung |
|---|---|
| 192 | Gut |
| 0 | Schlecht |
| 500 | Veraltet |
Ein Host, der eine Metrik mit Quality 0 erhält, sollte sie als schlecht anzeigen, selbst wenn ein Wert vorhanden ist. Viele Edge-Plattformen setzen Quality 500, wenn sie den Kontakt zum zugrunde liegenden Gerät verlieren, den Node aber verbunden halten.
Weitere gängige Properties
Einheiten, Wertebereiche, Beschreibungen und Anzeigeformate werden häufig als Properties übertragen, ihre Schlüsselnamen sind aber Konventionen der jeweiligen Plattform und nicht Teil der Spezifikation. Einigen Sie sich auf ein gemeinsames Property-Vokabular für alle Edge Nodes, sonst sieht Ihre Host-Anwendung dasselbe Konzept unter verschiedenen Schlüsseln.
DataSets
Ein DataSet ist eine kleine typisierte Tabelle innerhalb einer einzigen Metrik. Es hat eine Spaltenanzahl, Spaltennamen, einen Datentyp-Code pro Spalte und eine Liste von Zeilen. Jeder Zeilenwert nutzt eine eingeschränkte Menge an Feldern: int, long, float, double, boolean oder string.
Dekodiert könnte eine Tabelle mit Rezepturparametern so aussehen:
{
"name": "Recipe/Steps",
"datatype": 16,
"datasetValue": {
"numOfColumns": 3,
"columns": ["Step", "Temperature", "Duration"],
"types": [3, 9, 7],
"rows": [
{ "elements": [{ "intValue": 1 }, { "floatValue": 180.0 }, { "intValue": 600 }] },
{ "elements": [{ "intValue": 2 }, { "floatValue": 220.0 }, { "intValue": 300 }] }
]
}
}
DataSets eignen sich für Gruppen zusammengehöriger Werte, die beieinander bleiben müssen. Für strukturierte Anlagenmodelle passen Templates meist besser; siehe Sparkplug Templates und UDTs.
Dekodierte Beispiele
Hier ein Ausschnitt aus einem Birth mit mehreren Datentypen und einer Quality-Property, wie Sie ihn nach dem Dekodieren sehen würden:
[
{ "name": "Pump/Running", "alias": 1, "datatype": 11, "booleanValue": true },
{ "name": "Pump/Speed", "alias": 2, "datatype": 9, "floatValue": 1475.0,
"properties": { "keys": ["Quality"], "values": [{ "type": 3, "intValue": 192 }] } },
{ "name": "Pump/StartCount", "alias": 3, "datatype": 8, "longValue": "18342" },
{ "name": "Pump/LastService", "alias": 4, "datatype": 13, "longValue": "1789000000000" },
{ "name": "Pump/Offset", "alias": 5, "datatype": 2, "intValue": 4294967286 },
{ "name": "Pump/Serial", "alias": 6, "datatype": 12, "stringValue": "P-0042" }
]
Beachten Sie den Int16-Offset: Der Rohwert 4294967286 ergibt nach Zweierkomplement -10. Beachten Sie außerdem, dass manche JSON-Darstellungen 64-Bit-Werte als Strings ausgeben, um Genauigkeitsverluste in JavaScript zu vermeiden.
Datentypen in der Praxis prüfen
Am schnellsten prüfen Sie Datentypen, indem Sie dekodierte Births lesen. ConnectMQ dekodiert Sparkplug B im Topic-Explorer des Portals, sodass Sie ein NBIRTH oder DBIRTH öffnen und Datentyp und Wert jeder Metrik prüfen können, ohne Code zu schreiben. Für automatisierte Prüfungen ordnet der Decoder aus unserem Tutorial zum Dekodieren von Sparkplug B in Python Codes den Namen zu und übernimmt die Vorzeichenumrechnung.
Wenn Sie auf dem öffentlichen MQTT-Broker testen, verwenden Sie eine zufällige Group ID und denken Sie daran, dass dort alles für jeden lesbar ist. Er eignet sich für Tests und Prototypen, nicht für echte Produktionsdaten.
Checkliste für Datentypen bei der Edge-Node-Konfiguration
- Ordnen Sie jedem Sparkplug-Typ den Typ des Quellregisters zu; erweitern Sie nicht alles auf Double.
- Verwenden Sie vorzeichenlose Typen für Zähler, die nie negativ werden.
- Verwenden Sie DateTime für Zeitstempel, immer in Millisekunden UTC.
- Setzen Sie Quality bei Metriken, deren Quelle unabhängig vom Node ausfallen kann.
- Verwenden Sie is_null statt null, wenn ein Wert nicht verfügbar ist.
- Kennzeichnen Sie Store-and-Forward-Daten als historisch.
- Einigen Sie sich auf einheitliche Property-Schlüsselnamen für alle Edge Nodes.
- Testen Sie Arrays, DataSets und Templates vor dem Rollout durchgängig.
Wo Datentypen ins Bild passen
Korrekte Datentypen sorgen dafür, dass Sparkplug-Daten Historians, SCADA, MES und einen Unified Namespace (UNS) ohne Korrekturen pro Tag speisen können. Im UNS wird die ISA-95-Equipment-Hierarchie (Enterprise → Site → Area → Line → Cell) zur Topic-Struktur auf dem MQTT-Broker, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur. Ein UInt16 aus einem SPS-Register muss dort als derselbe Typ ankommen, sonst rechnet jede nachgelagerte Anwendung falsch. Wie Sparkplug und UNS zusammenspielen, erklärt der Artikel Sparkplug B und Unified Namespace; weitere Architekturhinweise finden Sie im Leitfaden zu Industrial IoT mit MQTT. Jeder konforme MQTT Broker transportiert diese Payloads; ein verwalteter MQTT-Broker, der sie zusätzlich dekodiert, beschleunigt die Überprüfung erheblich.
Starten Sie mit ConnectMQ
Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte. Verbinden Sie Ihren Edge Node und prüfen Sie Datentyp, Wert und Qualität jeder Metrik im ConnectMQ Topic-Explorer.
Häufig gestellte Fragen
Wie viele Sparkplug B Datentypen gibt es?
Die Spezifikation definiert skalare Typen mit den Codes 1 bis 19, die Property-Set-Typen 20 und 21 sowie die Array-Typen 22 bis 34. Code 0 steht für Unknown.
Warum erscheint mein negativer Sparkplug-Wert als riesige Zahl?
Vorzeichenbehaftete Ganzzahlen werden in vorzeichenlosen Protobuf-Feldern gespeichert. Wenden Sie anhand des deklarierten Datentyps das Zweierkomplement an oder nutzen Sie einen Decoder, der das für Sie erledigt.
Was bedeutet Quality 192 bei Sparkplug?
Es bedeutet gute Qualität. Die Quality-Property verwendet 192 für gut, 0 für schlecht und 500 für veraltet.
Sind Sparkplug-Datentypen in Datennachrichten Pflicht?
In Birth-Nachrichten sind sie Pflicht, in NDATA und DDATA optional. Konsumenten sollten sich den Datentyp jeder Metrik aus dem Birth merken.
