Sparkplug B Payload Formatı Açıklandı

Sparkplug B payload, bir zaman damgası, bir sıra numarası ve tipli metriklerden oluşan bir liste taşıyan, Protobuf ile kodlanmış bir mesajdır. Bu rehberin sonunda her alanın ne anlama geldiğini, ham baytların sıradan bir MQTT client'ında neden okunamaz göründüğünü ve bir edge node'u devreye alırken ya da hata ayıklarken payload'ları nasıl hızlıca inceleyeceğinizi öğrenmiş olacaksınız.

Sparkplug B Payload'ları Neden Anlamsız Görünür?

mosquitto_sub gibi genel amaçlı bir araçla spBv1.0/# topic'ine abone olursanız, tuhaf karakterlerle çevrili okunabilir tag adlarından oluşan bir karışım görürsünüz. Bu bir bozulma değildir. Sparkplug B, binary bir serileştirme formatı olan Google Protocol Buffers'ı kullanır; bu nedenle alan numaraları, uzunluklar ve sayısal değerler metin olarak değil, kompakt varint'ler ve sabit genişlikli baytlar olarak yazılır.

Bu bilinçli bir tercihtir. Endüstriyel ağlar çoğu zaman hücresel bağlantılar, uydu backhaul'ları veya yoğun tesis Ethernet'i üzerinden çalışır ve bir gateway binlerce tag yayınlayabilir. Binary kodlama mesajları küçük tutar, sayısal tipleri birebir korur (64 bit işaretsiz bir sayaç 64 bit işaretsiz sayaç olarak kalır) ve her tüketiciye aynı şemayı sunar. Bedeli ise baytları yeniden insan tarafından okunabilir hâle getirmek için şemaya, yani sparkplug_b.proto dosyasına ihtiyaç duymanızdır.

Genel amaçlı bir subscriber ile kendiniz deneyin:

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

Bu gruba bir Sparkplug edge node'unun yayınladığı her şey kısmen binary metin olarak yazdırılır. Bunu anlamlandırmak için alttaki yapıyı kavramanız gerekir.

Sparkplug B Payload Yapısı

Şema, Eclipse Tahu projesinde sparkplug_b.proto adıyla bulunur. En üst seviyede tek bir Payload mesajı vardır:

message Payload {
    optional uint64 timestamp = 1;   // Unix epoch'tan bu yana ms, UTC
    repeated Metric metrics   = 2;   // asıl veri
    optional uint64 seq       = 3;   // 0-255, başa döner
    optional string uuid      = 4;   // isteğe bağlı şema tanımlayıcısı
    optional bytes  body      = 5;   // isteğe bağlı opak baytlar
}

Alan	Tip	Amaç	Notlar
timestamp	uint64	Payload'ın oluşturulduğu zaman	UTC olarak epoch'tan bu yana milisaniye
metrics	repeated Metric	Raporlanan tag değerleri	Tek bir metrik ya da binlercesini içerebilir
seq	uint64	Mesaj sıra numarası	0'dan 255'e, sonra 0'a döner
uuid	string	Payload şeması için isteğe bağlı tanımlayıcı	Pratikte nadiren kullanılır
body	bytes	Uygulamaya özgü isteğe bağlı baytlar	Sparkplug tarafından yorumlanmaz

seq alanı, bir host uygulamasının kayıp mesajları tespit etmesini sağlar. NBIRTH 0'dan başlar ve aynı edge node'dan gelen her sonraki mesaj bunu bir artırır. Bir boşluk, bir şeyin kaçırıldığı anlamına gelir ve genellikle bir rebirth isteğini tetikler. Bu kurtarma akışına rebirth denir.

Bir Metriğin İçi

İlginç verilerin çoğu Metric mesajında bulunur. Her metrik, isteğe bağlı meta verilere sahip tek bir adlandırılmış değerdir:

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;
    }
}

İnsanların sıkça takıldığı birkaç nokta:

name ve alias. Birth mesajları, Line1/Spindle/Speed gibi tam metrik adını içermek zorundadır. Edge node bir alias atarsa, sonraki NDATA ve DDATA mesajları bayt tasarrufu için yalnızca sayısal alias'ı gönderebilir. Birth mesajını görmemiş bir decoder, alias'ı tekrar bir ada eşleyemez.
datatype bir sayıdır. datatype alanı; Int32 için 3, Float için 9 veya String için 12 gibi bir tamsayı kodudur. Değer alanının nasıl yorumlanacağını söyler. Tam liste Sparkplug B veri tipleri referansımızda yer alıyor.
Değer alanı tipe bağlıdır. Int8'den UInt32'ye kadar olan tipler int_value içinde, Int64, UInt64 ve DateTime ise long_value içinde taşınır. İşaretsiz bir alandaki işaretli değerler ikiye tümleyen (two's complement) olarak kodlanır; bu yüzden bir decoder negatif bir sayıyı doğru şekilde geri elde etmek için datatype alanına bakmak zorundadır.
is_null açıkça belirtilir. Bir metrik, mevcut bir değeri olmadan da var olabilir. Node sıfır göndermek yerine is_null değerini true yapar; bu, kaliteyi dikkate alan tüketiciler için önemlidir.
is_historical ve is_transient. Historical metrikler, canlı değerin üzerine yazmaması gereken geriye dönük doldurulmuş veriler taşır. Transient metrikler gösterilmeli ancak bir historian tarafından saklanmamalıdır.

Çözülmüş Bir Örnek

Bir CNC makinesinden gelen tipik bir DDATA payload'ının çözüldükten sonra nasıl göründüğü aşağıda; okunabilirlik için JSON olarak gösterilmiştir:

{
  "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 }
  ]
}

İki ayrıntıya dikkat edin. Birincisi, metriklerin alias'ları var ama adları yok; bu yüzden alias 3'ün iş mili hızı olduğunu bilmek için DBIRTH'e ihtiyacınız var. İkincisi, Int32 metriği ham işaretsiz alanda 4294967291 değerini gösteriyor. İşaretli 32 bit tamsayı olarak yorumlandığında bu değer -5'tir. Basit bir decoder'ın yanlış yaptığı şey tam olarak budur.

Eşleşen DBIRTH ise tam tanımları içerir:

{
  "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 }
  ]
}

Property'ler, DataSet'ler ve Template'ler

Basit skaler değerlerin ötesinde, Sparkplug B payload daha zengin yapılar taşıyabilir:

PropertySet. Bir metriğe eklenmiş anahtarlar ve tipli değerlerden oluşan bir liste. Yaygın olarak bilinen Quality property'si iyi için 192, kötü için 0 ve bayat (stale) için 500 kullanır. Mühendislik birimleri, aralıklar ve açıklamalar da property olarak eklenebilir.
DataSet. Sütun adları, sütun tipleri ve satırlardan oluşan küçük bir tablo. Reçete parametreleri veya bir grup okuma için kullanışlıdır.
Template. Bir PLC'deki UDT'ye benzeyen, kullanıcı tanımlı bir tip. Template tanımı NBIRTH içinde bir kez bildirilir ve örnekler ona referans verir. Sparkplug pompaları, motorları ve diğer tekrarlanan ekipmanları template'lerle modeller.
MetaData. Bayt ve dosya metrikleri için içerik tipi, boyut, MD5 ve dosya adı gibi bilgiler.

Üretim sistemlerinin çoğu, Quality property'si eklenmiş skaler değerler kullanır. DataSet'ler ve template'ler güçlüdür ancak karmaşıklık ekler; bu yüzden onları yalnızca düz bir metrik listesinin yönetimi zorlaştığında devreye alın.

Sparkplug B Payload'larını Pratikte Okumak

Binary Sparkplug verisini okunabilir bir şeye dönüştürmek için üç pratik seçeneğiniz var.

Kendi kodunuzla çözün

sparkplug_b.proto dosyasını kendi dilinize derleyin ve her mesajı parse edin. Üretimdeki tüketiciler için doğru seçim budur ve Python'da yalnızca birkaç satır tutar. Python ile Sparkplug B çözme eğitimimiz, alias çözümleme ve işaretli tamsayı işleme dahil eksiksiz bir subscriber'ı adım adım anlatıyor.

Tahu referans kütüphanelerini kullanın

Eclipse Tahu projesi, kanonik proto dosyasını ve çeşitli dillerde referans implementasyonları sağlar. Bir edge node veya host uygulaması geliştirirken spesifikasyonla uyumlu davranış istediğinizde iyi bir başlangıç noktasıdır.

Sizin yerinize çözen bir broker kullanın

Devreye alma sırasında, yalnızca bir tag'in yayın yapıp yapmadığını kontrol etmek için kod yazmak istemezsiniz. ConnectMQ, Sparkplug B topic'lerini algılar, Protobuf (ve JSON kodlu Sparkplug) payload'larını çözer ve portaldaki topic gezgininde okunabilir biçimde gösterir. Ayrıca Sparkplug verisini ISA-95 topic'lerine yeniden yayınlayabilir; böylece spBv1.0/factory1/DDATA/line1/cnc1, Protobuf konuşmayan araçlar için connectmq/factory1/production/line1/cnc1/telemetry olarak kullanılabilir hâle gelir. Kendi broker'ınızı barındırıyorsanız, aynı görünümü elde etmek için ayrı bir çözümleme servisine ihtiyacınız olur.

Yaygın Payload Tuzakları

Belirti	Olası neden	Çözüm
Metrikler ad yerine sayı gösteriyor	Decoder birth mesajını kaçırdı	Rebirth isteyin veya tüketiciyi node'dan önce başlatın
Negatif değerler devasa sayılar olarak görünüyor	İşaretli tip, işaretsiz alandan okundu	`datatype` değerine göre ikiye tümleyen uygulayın
Zaman damgaları 50000 yılı gibi görünüyor	Saniye ile milisaniye karıştırılmış	Sparkplug zaman damgaları her zaman milisaniyedir
Parser'da DecodeError	Payload Sparkplug B değil veya proto sürümü yanlış	Topic'in `spBv1.0` ile başladığını kontrol edin ve Tahu proto'sunu kullanın
Seq beklenmedik şekilde atlıyor	Kayıp mesajlar veya aynı ID'ye sahip iki node	Edge node ID'lerinin benzersiz olduğundan emin olun ve QoS'u uygun şekilde kullanın

Bunların çoğu devreye alma sırasında ortaya çıkar. Yeni bir gateway'i ayağa kaldırırken çözülmüş canlı bir görünümü açık tutmak, çok fazla tahmin yürütmekten kurtarır.

Payload Büyük Resme Nasıl Oturur?

Payload, Sparkplug'ın yalnızca yarısıdır. Diğer yarısı Sparkplug topic namespace ile birth ve death sertifikaları etrafında kurulan durum kurallarıdır. Birlikte veriyi kendini tanımlayan ve durumdan haberdar bir yapıya kavuştururlar; Sparkplug'ın bir Unified Namespace için taşıma katmanı olarak popüler olmasının nedeni de budur. Mimari bakış açısı için MQTT, Sparkplug B ve Unified Namespace yazımızı ve MQTT ile Endüstriyel IoT ana rehberimizi okuyun.

Standartlara uygun her MQTT broker Sparkplug B taşıyabilir, çünkü broker'ın yönlendirme için payload'ı parse etmesi hiçbir zaman gerekmez. Sparkplug'dan haberdar bir broker'ın kattığı şey görünürlüktür: çözülmüş görünümler, okunabilir yeniden yayınlama ve topic yapısı algılama, binary veriyi tüm ekip için anlaşılır kılar.

ConnectMQ ile Başlayın

Bir Sparkplug edge node'unu veya simülatörünü benzersiz bir grup ID'si kullanarak herkese açık MQTT test broker'ına yönlendirin; kimlik bilgilerine ve izolasyona ihtiyaç duyduğunuzda kendi tam yönetilen MQTT servisinize geçin. app.connectmq.com adresinde kredi kartı gerekmeden ücretsiz bir Serverless broker oluşturun ve Sparkplug B payload'larınızın ConnectMQ topic gezgininde canlı olarak çözüldüğünü izleyin.

Sık Sorulan Sorular

Sparkplug B payload her zaman Protobuf mudur?

Spesifikasyon, Sparkplug B için kodlama olarak Protobuf'u tanımlar. Bazı araçlar hata ayıklama veya köprüleme amacıyla aynı yapının JSON temsilini de üretir ve ConnectMQ her iki biçimi de çözebilir.

Metriklerimin neden alias'ı var ama adı yok?

Edge node tam adları yalnızca birth sertifikasında gönderdi ve bant genişliğinden tasarruf etmek için sonrasında sayısal alias'lar kullanıyor. Tüketiciniz ad-alias eşlemesini NBIRTH veya DBIRTH'ten saklamalı ya da bunu yeniden almak için bir rebirth istemelidir.

Bir Sparkplug B payload'ının maksimum boyutu nedir?

Sparkplug'ın kendisi küçük bir sınır koymaz, ancak broker'ınız koyar. ConnectMQ herkese açık broker'ında mesajlar 64 KB ile sınırlıdır; Serverless planları ise 256 KB (ücretsiz) veya 1 MB (ücretli) izin verir.

Sparkplug verisini okumak için proto dosyasına ihtiyacım var mı?

Evet, sizin yerinize çözen bir araç kullanmıyorsanız. Eclipse Tahu'daki sparkplug_b.proto dosyası kanonik şemadır ve her Sparkplug decoder'ı bunun üzerine kuruludur.

Sparkplug B Payload Formatı: Metrikler, Veri Tipleri ve Protobuf