Sparkplug B Payload-Format einfach erklärt

Ein Sparkplug B Payload ist eine Protobuf-kodierte Nachricht mit einem Zeitstempel, einer Sequenznummer und einer Liste typisierter Metriken. Nach diesem Leitfaden wissen Sie, was jedes Feld bedeutet, warum die Rohbytes in einem gewöhnlichen MQTT-Client unlesbar wirken und wie Sie Payloads bei der Inbetriebnahme oder Fehlersuche an einem Edge Node schnell untersuchen.

Warum Sparkplug B Payloads wie Zeichensalat aussehen

Wenn Sie mit einem generischen Werkzeug wie mosquitto_sub den Topic spBv1.0/# abonnieren, sehen Sie lesbare Tag-Namen, umgeben von seltsamen Zeichen. Das ist keine Datenbeschädigung. Sparkplug B verwendet Google Protocol Buffers, ein binäres Serialisierungsformat. Feldnummern, Längen und Zahlenwerte werden daher als kompakte Varints und Bytes fester Breite geschrieben, nicht als Text.

Dieser Kompromiss ist gewollt. Industrielle Netzwerke laufen oft über Mobilfunk, Satellitenverbindungen oder überlastetes Ethernet in der Werkshalle, und ein Gateway an einer Siemens S7 oder einem OPC-UA-Server veröffentlicht unter Umständen Tausende von Tags. Eine binäre Kodierung hält die Nachrichten klein, bewahrt exakte numerische Typen (ein vorzeichenloser 64-Bit-Zähler bleibt ein vorzeichenloser 64-Bit-Zähler) und gibt allen Konsumenten dasselbe Schema. Der Preis: Sie benötigen das Schema, die Datei sparkplug_b.proto, um die Bytes wieder in etwas Lesbares zu verwandeln.

Probieren Sie es selbst mit einem generischen Subscriber aus:

mosquitto_sub -h broker.connectmq.com -p 1883 -i payload-viewer-7f3a -t "spBv1.0/demo-7f3a/#" -v

Alles, was ein Sparkplug Edge Node in diese Gruppe veröffentlicht, erscheint als teilweise binärer Text. Um daraus schlau zu werden, müssen Sie die zugrunde liegende Struktur verstehen.

Die Struktur eines Sparkplug B Payloads

Das Schema liegt im Projekt Eclipse Tahu als sparkplug_b.proto. Auf oberster Ebene gibt es eine einzige Payload-Nachricht:

message Payload {
    optional uint64 timestamp = 1;   // ms since Unix epoch, UTC
    repeated Metric metrics   = 2;   // the actual data
    optional uint64 seq       = 3;   // 0-255, wraps around
    optional string uuid      = 4;   // optional schema identifier
    optional bytes  body      = 5;   // optional opaque bytes
}

Feld	Typ	Zweck	Hinweise
timestamp	uint64	Erstellungszeitpunkt des Payloads	Millisekunden seit Epoch in UTC
metrics	repeated Metric	Die gemeldeten Tag-Werte	Kann eine Metrik oder Tausende enthalten
seq	uint64	Sequenznummer der Nachricht	0 bis 255, danach Rücksprung auf 0
uuid	string	Optionale Kennung für das Payload-Schema	In der Praxis selten genutzt
body	bytes	Optionale anwendungsspezifische Bytes	Wird von Sparkplug nicht interpretiert

Über das Feld seq erkennt eine Host-Anwendung verlorene Nachrichten. Das NBIRTH beginnt bei 0, und jede folgende Nachricht desselben Edge Nodes erhöht den Wert um eins. Eine Lücke bedeutet, dass etwas verloren ging, was in der Regel eine Rebirth-Anforderung auslöst. Dieser Wiederherstellungsablauf heißt Rebirth.

Das Innere einer Metrik

Die meisten interessanten Daten stecken in der Metric-Nachricht. Jede Metrik ist ein einzelner benannter Wert mit optionalen Metadaten:

message Metric {
    optional string      name          = 1;
    optional uint64      alias         = 2;
    optional uint64      timestamp     = 3;
    optional uint32      datatype      = 4;
    optional bool        is_historical = 5;
    optional bool        is_transient  = 6;
    optional bool        is_null       = 7;
    optional MetaData    metadata      = 8;
    optional PropertySet properties    = 9;
    oneof value {
        uint32 int_value       = 10;
        uint64 long_value      = 11;
        float  float_value     = 12;
        double double_value    = 13;
        bool   boolean_value   = 14;
        string string_value    = 15;
        bytes  bytes_value     = 16;
        DataSet  dataset_value  = 17;
        Template template_value = 18;
        MetricValueExtension extension_value = 19;
    }
}

Einige Punkte, an denen viele stolpern:

Name oder Alias. Birth-Nachrichten müssen den vollständigen Metriknamen enthalten, etwa Line1/Spindle/Speed. Vergibt der Edge Node einen Alias, können spätere NDATA- und DDATA-Nachrichten nur noch den numerischen Alias senden, um Bytes zu sparen. Ein Decoder, der das Birth nicht gesehen hat, kann den Alias keinem Namen mehr zuordnen.
datatype ist eine Zahl. Das Feld datatype ist ein ganzzahliger Code, etwa 3 für Int32, 9 für Float oder 12 für String. Er legt fest, wie der Wert zu interpretieren ist. Die vollständige Liste finden Sie in unserer Referenz zu den Sparkplug B Datentypen.
Das Wertfeld hängt vom Typ ab. Int8 bis UInt32 werden in int_value übertragen, Int64, UInt64 und DateTime in long_value. Vorzeichenbehaftete Werte in einem vorzeichenlosen Feld werden im Zweierkomplement kodiert. Ein Decoder muss also datatype auswerten, um eine negative Zahl korrekt wiederherzustellen.
is_null ist explizit. Eine Metrik kann ohne aktuellen Wert existieren. Statt null zu senden, setzt der Node is_null auf true, was für qualitätsbewusste Konsumenten wichtig ist.
is_historical und is_transient. Historische Metriken enthalten nachgelieferte Daten, die den Live-Wert nicht überschreiben sollen. Transiente Metriken sollen angezeigt, aber von einem Historian nicht gespeichert werden.

Ein dekodiertes Beispiel

So sieht ein typischer DDATA-Payload einer CNC-Maschine nach dem Dekodieren aus, zur besseren Lesbarkeit als JSON dargestellt:

{
  "timestamp": 1792137600123,
  "seq": 42,
  "metrics": [
    { "alias": 3, "timestamp": 1792137600120, "datatype": 9, "floatValue": 1487.5 },
    { "alias": 4, "timestamp": 1792137600120, "datatype": 11, "booleanValue": true },
    { "alias": 7, "timestamp": 1792137600121, "datatype": 3, "intValue": 4294967291 }
  ]
}

Zwei Details fallen auf. Erstens haben die Metriken Aliase, aber keine Namen. Sie brauchen also das DBIRTH, um zu wissen, dass Alias 3 die Spindeldrehzahl ist. Zweitens zeigt die Int32-Metrik im rohen vorzeichenlosen Feld den Wert 4294967291. Als vorzeichenbehaftete 32-Bit-Ganzzahl interpretiert ist das -5. Genau solche Dinge macht ein naiver Decoder falsch.

Das passende DBIRTH enthält die vollständigen Definitionen:

{
  "timestamp": 1792137590000,
  "seq": 1,
  "metrics": [
    { "name": "Spindle/Speed", "alias": 3, "datatype": 9, "floatValue": 0.0 },
    { "name": "Spindle/Running", "alias": 4, "datatype": 11, "booleanValue": false },
    { "name": "Axis/X/Offset", "alias": 7, "datatype": 3, "intValue": 0 }
  ]
}

Properties, DataSets und Templates

Neben einfachen Skalaren kann der Sparkplug B Payload auch reichhaltigere Strukturen transportieren:

PropertySet. Eine Liste von Schlüsseln und typisierten Werten, die an eine Metrik angehängt ist. Die bekannte Property Quality verwendet 192 für gut, 0 für schlecht und 500 für veraltet. Auch Einheiten, Wertebereiche und Beschreibungen lassen sich als Properties anhängen.
DataSet. Eine kleine Tabelle mit Spaltennamen, Spaltentypen und Zeilen. Nützlich für Rezepturparameter oder einen Stapel von Messwerten.
Template. Ein benutzerdefinierter Typ, vergleichbar mit einem UDT in einer SPS. Eine Template-Definition wird einmal im NBIRTH deklariert, und Instanzen verweisen darauf. Mit Templates modelliert Sparkplug Pumpen, Motoren und andere wiederkehrende Anlagenteile.
MetaData. Informationen für Bytes- und Datei-Metriken wie Content-Type, Größe, MD5 und Dateiname.

Die meisten Produktivsysteme nutzen Skalare mit einer Quality-Property. DataSets und Templates sind mächtig, erhöhen aber die Komplexität. Führen Sie sie daher erst ein, wenn eine flache Liste von Metriken unübersichtlich wird.

Sparkplug B Payloads in der Praxis lesen

Es gibt drei praktikable Wege, binäre Sparkplug-Daten in etwas Lesbares zu verwandeln.

Mit eigenem Code dekodieren

Kompilieren Sie sparkplug_b.proto für Ihre Programmiersprache und parsen Sie jede Nachricht. Für produktive Konsumenten ist das die richtige Wahl, und in Python sind es nur wenige Zeilen. Unser Tutorial zum Dekodieren von Sparkplug B in Python zeigt einen vollständigen Subscriber, einschließlich Alias-Auflösung und Behandlung vorzeichenbehafteter Ganzzahlen.

Die Tahu-Referenzbibliotheken nutzen

Das Eclipse-Tahu-Projekt stellt die kanonische Proto-Datei und Referenzimplementierungen in mehreren Sprachen bereit. Sie sind ein guter Ausgangspunkt, wenn Sie einen Edge Node oder eine Host-Anwendung bauen und ein spezifikationskonformes Verhalten wünschen.

Einen Broker nutzen, der für Sie dekodiert

Bei der Inbetriebnahme möchten Sie keinen Code schreiben, nur um zu prüfen, ob ein Tag publiziert. ConnectMQ erkennt Sparkplug-B-Topics, dekodiert Protobuf-Payloads (und JSON-kodiertes Sparkplug) und zeigt sie im Topic-Explorer des Portals in lesbarer Form an. Außerdem kann ConnectMQ Sparkplug-Daten in ISA-95-Topics erneut veröffentlichen, sodass spBv1.0/factory1/DDATA/line1/cnc1 für Werkzeuge ohne Protobuf-Unterstützung als connectmq/factory1/production/line1/cnc1/telemetry verfügbar wird. Wenn Sie Ihren eigenen Broker betreiben, benötigen Sie für dieselbe Ansicht einen separaten Dekodierdienst.

Typische Fallstricke bei Payloads

Symptom	Wahrscheinliche Ursache	Lösung
Metriken zeigen Zahlen statt Namen	Decoder hat die Birth-Nachricht verpasst	Rebirth anfordern oder den Konsumenten vor dem Node starten
Negative Werte erscheinen als riesige Zahlen	Vorzeichenbehafteter Typ aus vorzeichenlosem Feld gelesen	Zweierkomplement anhand von `datatype` anwenden
Zeitstempel liegen im Jahr 50000	Sekunden und Millisekunden verwechselt	Sparkplug-Zeitstempel sind immer Millisekunden
DecodeError im Parser	Payload ist kein Sparkplug B oder falsche Proto-Version	Prüfen, ob der Topic mit `spBv1.0` beginnt, und das Tahu-Proto verwenden
Seq springt unerwartet	Verlorene Nachrichten oder zwei Nodes mit derselben ID	Eindeutige Edge-Node-IDs sicherstellen und QoS passend wählen

Die meisten dieser Probleme tauchen bei der Inbetriebnahme auf. Wer beim Hochfahren eines neuen Gateways eine dekodierte Live-Ansicht offen hat, spart sich viel Rätselraten.

Wie sich der Payload ins Gesamtbild einfügt

Der Payload ist nur die eine Hälfte von Sparkplug. Die andere Hälfte sind der Sparkplug Topic-Namespace und die Zustandsregeln rund um Birth- und Death-Zertifikate. Zusammen machen sie Daten selbstbeschreibend und zustandsbewusst, weshalb Sparkplug als Transportschicht für einen Unified Namespace (UNS) so beliebt ist. 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. Sparkplug liefert dafür am Edge typisierte, zustandsbewusste Daten aus SPS und Maschinen, der UNS macht sie für MES, ERP und Analytics lesbar. Für die Architektursicht lesen Sie MQTT, Sparkplug B und der Unified Namespace sowie unseren Grundlagenleitfaden zu Industrial IoT mit MQTT.

Jeder standardkonforme MQTT Broker kann Sparkplug B transportieren, da der Broker den Payload für das Routing nie parsen muss. Ein Sparkplug-fähiger Broker bietet zusätzlich Transparenz: dekodierte Ansichten, lesbares Republishing und die Erkennung der Topic-Struktur machen die Binärdaten für das ganze Team zugänglich.

Starten Sie mit ConnectMQ

Richten Sie einen Sparkplug Edge Node oder Simulator mit einer eindeutigen Group ID auf den öffentlichen MQTT-Broker aus, der für Tests und Prototypen gedacht ist, und wechseln Sie zu Ihrem eigenen verwalteten MQTT-Broker, sobald Sie Zugangsdaten, Isolation und echte Produktionsdaten ins Spiel bringen. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte, und sehen Sie Ihre Sparkplug B Payloads live dekodiert im ConnectMQ Topic-Explorer.

Häufig gestellte Fragen

Ist ein Sparkplug B Payload immer Protobuf?

Die Spezifikation definiert Protobuf als Kodierung für Sparkplug B. Einige Werkzeuge erzeugen zusätzlich eine JSON-Darstellung derselben Struktur für Debugging oder Bridging, und ConnectMQ kann beide Formen dekodieren.

Warum haben meine Metriken Aliase, aber keine Namen?

Der Edge Node hat die vollständigen Namen nur in seinem Birth-Zertifikat gesendet und verwendet danach numerische Aliase, um Bandbreite zu sparen. Ihr Konsument muss die Zuordnung von Namen zu Aliasen aus dem NBIRTH oder DBIRTH speichern oder ein Rebirth anfordern, um sie erneut zu erhalten.

Wie groß darf ein Sparkplug B Payload maximal sein?

Sparkplug selbst setzt keine niedrige Grenze, wohl aber Ihr Broker. Auf dem öffentlichen MQTT-Broker von ConnectMQ sind Nachrichten auf 64 KB begrenzt, Serverless-Pläne erlauben 256 KB (kostenlos) oder 1 MB (kostenpflichtig).

Brauche ich die Proto-Datei, um Sparkplug-Daten zu lesen?

Ja, sofern kein Werkzeug die Dekodierung für Sie übernimmt. Die Datei sparkplug_b.proto aus Eclipse Tahu ist das kanonische Schema, und jeder Sparkplug-Decoder baut darauf auf.

Sparkplug B Payload-Format: Metriken, Datentypen und Protobuf