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
| İşaret | Nerede | Anlamı |
|---|---|---|
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/1 | Cihazı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 |
|---|---|
model | Cihaz modeli |
serial | Seri numarası. Cihazın kayıtlı seri numarasıyla eşleşmelidir; aksi halde mesaj hello_serial_mismatch ile reddedilir. |
fw | Firmware sürümü |
hw | Donanım revizyonu |
profile_hash | Cihazın ayar profilinin hash değeri |
capabilities | Cihazın desteklediği özellikler (aşağıda) |
protocol | roltek-device-protocol/1 |
Yetenekler
Bir cihaz yalnızca desteklediklerini listeler.
| Yetenek | Anlamı |
|---|---|
telemetry | Ölçüm değerleri gönderir |
attributes | İstemci öznitelikleri gönderir ve paylaşılan öznitelikleri alır |
rpc | Komutları alır |
rpc.persistent | Cihaz yeniden çevrimiçi olana kadar saklanan komutları alır |
ota | Firmware güncellemelerini alır |
cfg | cfg.* paylaşılan öznitelikleri üzerinden yapılandırmayı alır (cfg_hash gerektirir) |
claim | Bir talep penceresiyle sahiplenilebilir |
csr | Cihaz sertifikası ister |
store_forward | Çevrimdışıyken ölçümleri tamponlar ve sonra gönderir |
gateway | Alt 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 oldu | Hermetry ne yapar |
|---|---|
| 8 seviyeden daha derin iç içe geçmiş JSON | Düşürür (invalid_payload) |
JSON nesnesi olmayan istemci öznitelikleri veya hello | Düşü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 konu | Düşürür (unknown_reserved_topic) |
| Cihazın yayın yapamayacağı bir konu | Düşürür (forbidden_topic) |
| Bir dakika içinde üç reddedilen konu | Oturumu kapatır |
| Cihazın okuyamayacağı bir konuya SUBSCRIBE | SUBACK 0x80 ile yanıtlar |
| Profilin hız sınırlarını aşan mesajlar | Fazla 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:
| Durum | Kod |
|---|---|
| 400 | invalid_payload, hello_serial_mismatch |
| 413 | payload_too_large, raw_too_large |
| 429 | rate_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:
| Kod | Anlamı |
|---|---|
unsupported_method | Alıcı metodu tanımaz |
bad_params | Parametreler eksik veya hatalı |
busy | Alı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 |
forbidden | Metot yerel bir ilke ile kapatılmış |
payload_too_large | İstek alıcının kabul ettiğinden büyük |
internal | Diğ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:
| Metot | Yanıt |
|---|---|
getCurrentTime | {"ok": true, "result": {"ts": <server time in ms>}} |
getSessionLimits | Cihazın profilinin cihaz başına etkin sınırları |
Cihaz için kurallar
- Anlamadığınızı yok sayın: bozuk aşağı yönlü mesajlar, bilinmeyen paylaşılan öznitelik anahtarları ve bilinmeyen alanlar.
- Bilinmeyen bir komuta
unsupported_methodile yanıt verin; bilinmeyen bir hata kodunuinternalolarak işleyin. - Bir komut kimliğini bir kez çalıştırın. Bir komut iki kez gelebilir; bkz. Cihazlara komut gönderme.
- 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.
- 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.
- 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.
- Sınırlarınızın altında kalın. Bağlandıktan sonra
getSessionLimitsile sınırları isteyin ve her birinin %80’inin altında kalın. Varsayılanlar Sınırlar ve kotalar sayfasındadır.

