MQTT konuları ve yük başvurusu

Bu, bir cihazın yayımladığı ve abone olduğu konuların başvuru kaynağıdır. Bağlantı, oturum açma ve oturum kuralları MQTT sayfasındadır. HTTP cihazları aynı yük biçimlerini kullanır; bkz. Device HTTP API.

Varsayılan şemanın konuları

Tüm konular v1/ ile başlar. QoS 1 kullanın.

Yön	Konu	Kullanım	Sayfa
Yukarı	`v1/telemetry`	Telemetri	aşağıda
Yukarı	`v1/attributes`	İstemci öznitelikleri	Öznitelikler
Yukarı	`v1/attributes/req/{id}`	Öznitelik isteme	Öznitelikler
Aşağı	`v1/attributes/res/{id}`	Öznitelik isteğine yanıt	Öznitelikler
Aşağı	`v1/attributes/set`	Paylaşılan öznitelik değişiklikleri, yazılım güncellemesi tekliflerini (`fw_*`) dahil	Yazılım güncellemeleri (OTA)
Aşağı	`v1/rpc/req/{id}`	Buluttan gelen komut	Cihazlara komut gönderme
Yukarı	`v1/rpc/res/{id}`	Komuta yanıt	aynı
Yukarı	`v1/rpc/up/req/{id}`	Cihazdan buluta istek	aynı
Aşağı	`v1/rpc/up/res/{id}`	Cihaz isteğine yanıt	aynı
Yukarı	`v1/provision/req`	Sağlama isteği (yalnızca sağlama oturumunda)	Cihaz ekleme ve sahiplenme
Aşağı	`v1/provision/res`	Sağlama yanıtı	aynı
Yukarı	`v1/hello`	Cihazın kendini tanıtımı (lisanslı cihazlar)	Lisanslı cihazlar
Yukarı	`v1/csr`	Sertifika imzalama isteği (lisanslı cihazlar)	Cihaz sertifikaları
Aşağı	`v1/cert`	Düzenlenen sertifika	aynı
Yukarı	`v1/claim`	Sahiplenme penceresini açma veya kapatma (lisanslı cihazlar)	Cihaz ekleme ve sahiplenme
Yukarı	`v1/gw/connect`, `v1/gw/disconnect`, `v1/gw/telemetry`, `v1/gw/attributes`, `v1/gw/attributes/req` (Geliştirme aşamasında)	Yalnızca ağ geçitleri: alt cihazlar için bildirim	Ağ geçidinin arkasındaki cihazlar
Aşağı	`v1/gw/attributes`, `v1/gw/attributes/res`, `v1/gw/rpc`	Yalnızca ağ geçitleri; Geliştirme aşamasında (alt cihazlara komutlar ve paylaşılan öznitelikler)	aynı

Bir cihaz yalnızca aşağı yönlü konularına abone olabilir: v1/attributes/set, v1/attributes/res/+, v1/rpc/req/+, v1/rpc/up/res/+ ve v1/cert; ağ geçitleri için ayrıca v1/gw/attributes, v1/gw/rpc ve v1/gw/attributes/res. Bir cihaz asla başka bir cihazın iletilerini almaz.

Reddedilen konular

Yayımlandığı yer	Sonuç
`v1/` altında bilinmeyen bir konu	`unknown_reserved_topic` olarak reddedilir, hiçbir zaman saklanmaz.
Bir aşağı yönlü konu, ağ geçidi olmayan bir cihazdan `v1/gw/*` veya sağlama oturumu dışında `v1/provision/req`	`forbidden_topic` olarak reddedilir.

Her ikisi de onaylanır ve atılır. Bir dakika içinde üç reddedilen konu oturumu kapatır.

Bağlantı dizisi

CONNECT
SUBSCRIBE v1/attributes/set      (QoS 1)
SUBSCRIBE v1/attributes/res/+    (QoS 1)
SUBSCRIBE v1/rpc/req/+           (QoS 1)
SUBSCRIBE v1/rpc/up/res/+        (QoS 1, only if the device sends requests)
PUBLISH   v1/attributes/req/1    {}          catch-up: all shared attributes
PUBLISH   v1/attributes          current state
PUBLISH   v1/telemetry           buffered data first, then live data

Eski uyumlu konular

Eski uyumlu şemalı profiller ayrıca şunları kabul eder:

Yön	Konu
Yukarı	`v1/devices/me/telemetry`
Yukarı ve aşağı	`v1/devices/me/attributes`
Yukarı	`v1/devices/me/attributes/request/{id}`
Aşağı	`v1/devices/me/attributes/response/{id}`

Komut, sahiplenme, sağlama veya ağ geçidi konusu taşımazlar.

Özel konular

Özel konular şemalı profiller, v1/ dışındaki her konuyu cihazın telemetrisi olarak kabul eder:

Bir JSON nesnesi anahtarlara dönüşür. Diğer her şey (sayı, dizi, metin, ikili veri) tek bir raw anahtarı olur; metni olarak, profilin Maks. ham yük (bayt) değerine (varsayılan 4.096) kadar.
Konu, profilin Maks. konu derinliği (8), Maks. konu uzunluğu (128) ve Cihaz başına farklı konu (50) sınırları içinde kalmalıdır.
Anahtarları konuyla öne ekle seçildiğinde her anahtar <konu>.<anahtar> olarak saklanır: konudaki / karakterleri . olur, anahtar kuralının dışındaki diğer karakterler _ olur. Örneğin site1/boiler ve temp site1.boiler.temp verir. 64 karakteri aşan birleşik anahtar atılır. Öneksiz kullanımda, iki konudaki aynı anahtar birbirinin üzerine yazar.

Telemetri yük biçimleri

Telemetri JSON, UTF-8 biçimindedir.

Biçim A, düz nesne. Hermetry’nin aldığı zamanla damgalanan tek kayıt:

{"temperature": 21.5, "humidity": 40, "door_open": false}

Biçim B, tam olarak ts ve values içeren nesne. ts zamanındaki tek kayıt:

{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}

Biçim C, biçim A ve biçim B nesnelerinden oluşan dizi. Her öğe için sırasıyla bir kayıt:

[
  {"ts": 1759572000000, "values": {"sys.cpu_load": 0.42}},
  {"ts": 1759572060000, "values": {"sys.cpu_load": 0.38}},
  {"net.wan.up": true}
]

JSON değil. JSON olmayan bir gövde, varsayılan telemetri konusunda tek bir raw anahtarı olarak saklanır. v1/telemetry üzerindeki bir JSON skaleri (42, "on") reddedilir (bad_form).

ts ve values ile birlikte başka bir üye içeren nesne biçim B değil, biçim A’dır: tüm üyeleri anahtar olur.

Zaman damgaları

ts bir tamsayıdır: Unix epoch’tan itibaren UTC milisaniye.
Senkronize saati olmayan cihaz biçim A kullanmalıdır. Zaman damgası uydurmamalıdır.
10 dakikadan fazla gelecekteki kayıtlar veya telemetri saklama süresinden daha eski kayıtlar düşürülür. Asla başka bir zamana taşınmazlar.
Aynı cihaza, anahtara ve zamana ait yinelenenler bir kez saklanır.

Bkz. Zaman damgaları, geç ve yinelenen okumalar.

Anahtarlar

Desen: ^[A-Za-z0-9_.\-]{1,64}$. Anahtarlar büyük/küçük harfe duyarlıdır: abc ve ABC iki ayrı anahtardır.
Telemetride reddedilen anahtarlar: _, fw_, current_fw_ veya cfg. ile başlayanlar.
İpucu: nokta ile ayrılmış küçük harfli adlar kullanın, örneğin net.wan.up.

Hatalı bir anahtar yalnızca o anahtarı atar; kaydın geri kalanı korunur.

Değerler

JSON değeri	Saklandığı biçim	Kural
Tamsayı	long	±2^53 üzerindeyse metin olarak gönderin.
Kesirli	double	NaN ve Infinity JSON değildir ve reddedilir.
`true` / `false`	boolean	Grafikler sayı okur: geçmiş istiyorsanız `0`/`1` gönderin.
Metin	string	1.024 karaktere kadar. Son değer olarak gösterilir, grafiğe çizilmez.
Nesne veya dizi	JSON	4 KiB’a kadar, olduğu gibi saklanır.
`null`	hiçbir şey	“Okuma yok” anlamına gelir. Hiçbir şeyi silmez.

Hatalı bir değer yalnızca o anahtarı atar.

Boyut

Tek bir ileti: 64 KiB’a ve 1.000 anahtar-değer noktasına kadar. Daha fazla nokta tüm iletiyi düşürür; daha büyük bir ileti bütünüyle atılır. Bağlantı açık kalır.
İç içe geçme derinliği: 8 düzeye kadar.
Saniyede birden fazla örnek gönderiyorsanız iletilerinizi toplu gönderin.

İstemci öznitelikleri

PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}

Öznitelik anahtarları 128 karaktere kadar olabilir. Bkz. Öznitelikler.

Komutlar

PUBLISH v1/rpc/req/42                              (down)
{"method": "sys.ping", "params": {"host": "8.8.8.8", "count": 3}}

PUBLISH v1/rpc/res/42                              (up)
{"ok": true, "result": {"sent": 3, "received": 3, "avg_ms": 18.2}}

PUBLISH v1/rpc/up/req/5                            (up)
{"method": "app.request", "params": {}}

Sağlama

username: provision, password: empty
SUBSCRIBE v1/provision/res
PUBLISH   v1/provision/req
{"deviceName": "boiler-07", "provisionDeviceKey": "pk_…", "provisionDeviceSecret": "ps_…"}

İleti neyi sayar

Kabul edilen her telemetri veya öznitelik yayını, içeriği ne olursa olsun aylık ileti kotanıza bir kez sayılır. Komut yanıtları, bağlantı olayları ve alarmlar sayılmaz. 50 okuma içeren tek bir ileti, tek okumalı bir iletiyle aynı maliyete sahiptir; bu yüzden toplu gönderim kotadan tasarruf sağlar.