Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Protokol sürümleri ve cihaz kuralları

Cihaz protokolünün nasıl sürümlendirildiği, bir cihazın hello içinde neyi bildirdiği, kullandığı hata kodları ve bir şey ters gittiğinde nasıl tepki vermesi gerektiği.

Bu sayfa Hermetry için cihaz yazılımı veya ağ geçidi yazılımı yazan kişilere yöneliktir. Cihaz protokolünün nasıl sürümlendirildiğini ve Hermetry değiştikçe çalışmaya devam etmesi için bir cihazın uyması gereken kuralları açıklar. Konular ve yükler MQTT konu ve yük başvurusunda yer alır; bağlantı ve oturum açma kuralları MQTT sayfasındadır.

İki sürüm işareti

İşaretNeredeAnlamı
v1/Varsayılan şemadaki her konunun başıKonu adlarının sürümü. Konuları bozan bir değişiklik v2/ altında yeni konular kullanır; v1/ konuları yeniden adlandırılmaz.
roltek-device-protocol/1Cihazın hello mesajındaki protocol alanıCihazın kullandığı protokolün ana sürümü. Hermetry ana sürümü cihazda saklar.

İki işaret birbirinden bağımsızdır: yeni bir protokol ana sürümü, tek başına yeni konu adları anlamına gelmez.

Hello mesajı

Kendini tanımlayan cihazlar (lisanslı cihazlar bunu yapar) her bağlantıda bir kez, QoS 1 ile v1/hello konusuna yayın yapar. hello göndermeyen cihazlar varsayılan konularla çalışmaya devam eder.

Alanİçeriği
modelCihaz modeli
serialSeri numarası. Cihazın kayıtlı seri numarasıyla eşleşmelidir; aksi halde mesaj hello_serial_mismatch ile reddedilir.
fwFirmware sürümü
hwDonanım revizyonu
profile_hashCihazın ayar profilinin hash değeri
capabilitiesCihazın desteklediği özellikler (aşağıda)
protocolroltek-device-protocol/1

Yetenekler

Bir cihaz yalnızca desteklediklerini listeler.

YetenekAnlamı
telemetryÖlçüm değerleri gönderir
attributesİstemci öznitelikleri gönderir ve paylaşılan öznitelikleri alır
rpcKomutları alır
rpc.persistentCihaz yeniden çevrimiçi olana kadar saklanan komutları alır
otaFirmware güncellemelerini alır
cfgcfg.* paylaşılan öznitelikleri üzerinden yapılandırmayı alır (cfg_hash gerektirir)
claimBir talep penceresiyle sahiplenilebilir
csrCihaz sertifikası ister
store_forwardÇevrimdışıyken ölçümleri tamponlar ve sonra gönderir
gatewayAlt cihazlar için rapor verir

Protokol 1’in yetenek listesi 23 Ekim 2026’dan beri sabittir.

Geriye uyumlu ve uyumsuz değişiklikler

Geriye uyumlu değişiklikler protokol sürümünü korur. Hermetry istediği zaman yeni isteğe bağlı alanlar, yetenek değerleri, komut metotları, öznitelik anahtarları, hata kodları ve ölçüm anahtarları ekleyebilir. Bu nedenle bir cihaz tanımadığı şeyleri yok saymalıdır: bilinmeyen bir alan, bilinmeyen bir paylaşılan öznitelik anahtarı, bilinmeyen bir hata kodu.

Uyumsuz değişiklikler yeni bir ana sürüm gerektirir: bir konu, alan, öznitelik anahtarı veya durumun yeniden adlandırılması ya da kaldırılması; bir alanın türünün veya anlamının değiştirilmesi; ya da mevcut sürümün doğru çalışan bir cihazının aşabileceğinden daha katı bir sınır getirilmesi.

Bir mesaj reddedildiğinde

Protokol 1’in hata konusu yoktur. Hermetry’nin kabul edemediği bir mesaj düşürülür ama yine de onaylanır (PUBACK), böylece cihaz onu yeniden göndermez. Hermetry nedeni sayar; cihaza gönderilmez.

Ne olduHermetry ne yapar
8 seviyeden daha derin iç içe geçmiş JSONDüşürür (invalid_payload)
JSON nesnesi olmayan istemci öznitelikleri veya helloDüşürür (invalid_payload)
Hiç JSON olmayan ölçümler (metin, ikili veri)Tek anahtar raw olarak tutar, profilin ham boyut sınırına kadar (üzerindeyse raw_too_large)
v1/ altında var olmayan bir konuDüşürür (unknown_reserved_topic)
Cihazın yayın yapamayacağı bir konuDüşürür (forbidden_topic)
Bir dakika içinde üç reddedilen konuOturumu kapatır
Cihazın okuyamayacağı bir konuya SUBSCRIBESUBACK 0x80 ile yanıtlar
Profilin hız sınırlarını aşan mesajlarFazla mesajları düşürür; 60 saniye içinde sınırın üç katını aşmak oturumu kapatır (rate_limit)

HTTP üzerinden cihaz API’si bunun yerine bir durum döndürür:

DurumKod
400invalid_payload, hello_serial_mismatch
413payload_too_large, raw_too_large
429rate_limited, Retry-After başlığıyla

Hermetry’nin saklanan ölçümler için kaydettiği kodlar (key_invalid, bad_ts ve diğerleri) Hata mesajları sayfasında listelenmiştir.

Komut hata kodları

İki yönde giden komutlar (buluttan cihaza v1/rpc/req/{id} üzerinden, cihazdan buluta v1/rpc/up/req/{id} üzerinden) hataları şu kodlardan biriyle {"ok": false, "error": "<code>"} biçiminde yanıtlar:

KodAnlamı
unsupported_methodAlıcı metodu tanımaz
bad_paramsParametreler eksik veya hatalı
busyAlıcı şu an çalıştıramaz
timeoutİşlem alıcıda zaman aşımına uğradı
expiredİsteğin expirationTime değeri geçti
forbiddenMetot yerel bir ilke ile kapatılmış
payload_too_largeİstek alıcının kabul ettiğinden büyük
internalDiğer her durum

Alıcı **diğer tüm kodları internal olarak işler**.

Cihazdan buluta gelen istek uygulamalarınız tarafından yanıtlanır. 5 saniye içinde hiçbir akış yanıt vermezse Hermetry unsupported_method yanıtı verir. İki metot her zaman Hermetry tarafından yanıtlanır:

MetotYanıt
getCurrentTime{"ok": true, "result": {"ts": <server time in ms>}}
getSessionLimitsCihazın profilinin cihaz başına etkin sınırları

Cihaz için kurallar

  1. Anlamadığınızı yok sayın: bozuk aşağı yönlü mesajlar, bilinmeyen paylaşılan öznitelik anahtarları ve bilinmeyen alanlar.
  2. Bilinmeyen bir komuta unsupported_method ile yanıt verin; bilinmeyen bir hata kodunu internal olarak işleyin.
  3. Bir komut kimliğini bir kez çalıştırın. Bir komut iki kez gelebilir; bkz. Cihazlara komut gönderme.
  4. Onay yoksa yeniden gönderin. 20 saniye içinde PUBACK gelmezse mesajı DUP bayrağıyla yeniden gönderin; üç yeniden gönderimden sonra yeniden bağlanın.
  5. Zaman aşımına uğrayan yanıtı bir kez yeniden deneyin. Bir öznitelik isteği veya cihaz isteği yanıt almazsa bir kez daha sorun.
  6. Reddedilen bağlantılarda geri çekilin. CONNACK 1 (protokol sürümü desteklenmiyor) durumunda denemeyi durdurun; CONNACK 3’te normal şekilde geri çekilin; CONNACK 4 veya 5’te uzun süre geri çekilin. Kodlar MQTT sayfasındadır.
  7. Sınırlarınızın altında kalın. Bağlandıktan sonra getSessionLimits ile sınırları isteyin ve her birinin %80’inin altında kalın. Varsayılanlar Sınırlar ve kotalar sayfasındadır.