Bu sayfa, bir cihazın neyi yayımladığına (publish) ve nelere abone olduğuna (subscribe) dair referanstır. Bağlantı, oturum açma ve oturum kuralları MQTT sayfasındadır. HTTP cihazlar aynı payload’ları kullanır; bkz. Device HTTP API.
Varsayılan şemanın topic’leri
Tüm topic’ler v1/ ile başlar. QoS 1 kullanın.
| Yön | Topic | 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 | Yazılım güncelleme teklifleri (fw_*) dahil paylaşılan öznitelik değişiklikleri | Firmware güncellemeleri (OTA) |
| Aşağı | v1/rpc/req/{id} | Buluttan 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 | Provisioning isteği (yalnızca provisioning oturumunda) | Cihaz ekleme ve sahiplenme |
| Aşağı | v1/provision/res | Provisioning yanıtı | aynı |
| Yukarı | v1/hello | Cihazın kendini tanıtması (lisanslı cihazlar) | Lisanslı cihazlar |
| Yukarı | v1/csr | Sertifika imzalama isteği (lisanslı cihazlar) | Cihaz sertifikaları |
| Aşağı | v1/cert | Verilen 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 | Yalnızca gateway’ler: alt cihazlar için bildirim yapar ve bir alt cihazın özniteliklerini ister | Gateway arkasındaki cihazlar |
| Aşağı | v1/gw/rpc, v1/gw/attributes, v1/gw/attributes/res | Yalnızca gateway’ler: alt cihazlar için komutlar ve paylaşılan öznitelikler ile öznitelik isteklerine yanıtlar | Gateway arkasındaki cihazlara komutlar |
| Yukarı | v1/gw/rpc | Yalnızca gateway’ler: bir alt cihazın komuta yanıtı | aynı |
Bir cihaz yalnızca kendi downlink topic’lerine abone olabilir: v1/attributes/set, v1/attributes/res/+, v1/rpc/req/+, v1/rpc/up/res/+ ve v1/cert; gateway’ler için ayrıca v1/gw/attributes, v1/gw/rpc ve v1/gw/attributes/res. Bir cihaz başka bir cihazın mesajlarını asla almaz.
Reddedilen topic’ler
| Yayımlanan topic | Sonuç |
|---|---|
v1/ altında bilinmeyen bir topic | unknown_reserved_topic olarak reddedilir, asla saklanmaz. |
Bir downlink topic’i, gateway olmayan bir cihazdan v1/gw/* veya provisioning oturumu dışında v1/provision/req | forbidden_topic olarak reddedilir. |
İkisi de onaylanır ve atılır. Bir dakika içinde üç reddedilen topic oturumu kapatır.
Bağlantı sırası
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
Legacy uyumlu topic’ler
Legacy compatible şemalı profiller şunları da kabul eder:
| Yön | Topic |
|---|---|
| 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, provisioning veya gateway topic’i içermezler.
Özel topic’ler
Custom topics kullanan profiller, v1/ dışındaki her topic’i cihazın telemetrisi olarak kabul eder:
- Bir JSON nesnesi key’lere dönüşür. Diğer her şey (sayı, dizi, metin, binary) profilin Max raw payload (bytes) değerine kadar (varsayılan 4.096) metni olarak tek bir
rawkey’i olur. - Topic, profilin Max topic depth (8), Max topic length (128) ve Distinct topics per device (50) sınırları içinde kalmalıdır.
- Prefix keys with the topic ile her anahtar
<topic>.<key>olarak saklanır: topic’teki/karakterleri.olur, anahtar kuralı dışındaki diğer karakterler_olur. Örneğinsite1/boilervetemp,site1.boiler.tempsonucunu verir. 64 karakteri aşan birleşik anahtar atılır. Önek olmadan, iki topic’ten gelen aynı anahtar birbirinin üzerine yazılır.
Telemetri payload biçimleri
Telemetri JSON, UTF-8’dir.
Biçim A, düz nesne. Hermetry’nin aldığı zamanla damgalanan tek bir kayıt:
{"temperature": 21.5, "humidity": 40, "door_open": false}
Biçim B, tam olarak ts ve values içeren nesne. ts zamanında tek bir kayıt:
{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}
Biçim C, A ve B biçimli nesnelerden oluşan dizi. Her eleman için sırayla 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 topic’inde tek bir raw key’i olarak saklanır. v1/telemetry üzerinde bir JSON skaler (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 key olur.
Zaman damgaları
tsbir tam sayıdır: Unix epoch’tan bu yana milisaniye, UTC.- Senkronize saati olmayan bir cihaz Biçim A kullanmalıdır. Zaman damgası uydurmamalıdır.
- 10 dakikadan fazla gelecekte olan veya telemetri saklama sürenizden eski kayıtlar atılır. Asla başka bir zamana taşınmazlar.
- Aynı cihaz, key ve zamana ait tekrarlar bir kez saklanır.
Bkz. Zaman damgaları, geç gelen ve tekrarlanan okumalar.
Key’ler
- Desen:
^[A-Za-z0-9_.\-]{1,64}$. Key’ler büyük/küçük harfe duyarlıdır:abcveABCiki ayrı key’dir. - Telemetride reddedilenler:
_,fw_,current_fw_veyacfg.ile başlayan key’ler. - İpucu: nokta ile ayrılmış küçük harfli adlar kullanın, örneğin
net.wan.up.
Hatalı bir anahtar yalnızca o anahtarı düşürür; kaydın geri kalanı korunur.
Değerler
| JSON değeri | Saklanma türü | Kural |
|---|---|---|
| Tam sayı | long | ±2^53 üzerindeki değerleri string olarak gönderin. |
| Ondalıklı sayı | double | NaN ve Infinity JSON değildir ve reddedilir. |
true / false | boolean | Grafikler sayıları okur: geçmiş istiyorsanız 0/1 gönderin. |
| String | string | En fazla 1.024 karakter. Son değer olarak gösterilir, grafiğe dökülmez. |
| Nesne veya dizi | JSON | En fazla 4 KiB, 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ı düşürür.
Boyut
- Bir mesaj: en fazla 64 KiB ve en fazla 1.000 anahtar-değer noktası. Daha fazla nokta tüm mesajın atılmasına yol açar; daha büyük bir mesaj bütünüyle atılır. Bağlantı açık kalır.
- İç içe geçme derinliği: en fazla 8 seviye.
- Saniyede birden fazla örnek gönderiyorsanız mesajlarınızı toplu (batch) 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 key’leri en fazla 128 karakter 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": {}}
Provisioning
username: provision, password: empty
SUBSCRIBE v1/provision/res
PUBLISH v1/provision/req
{"deviceName": "boiler-07", "provisionDeviceKey": "pk_…", "provisionDeviceSecret": "ps_…"}
Neyin mesaj sayıldığı
Kabul edilen her telemetri veya öznitelik publish’i, içeriği ne olursa olsun aylık mesaj kotanıza bir kez sayılır. Komut yanıtları, bağlantı olayları ve alarmlar sayılmaz. 50 okumalı tek bir mesaj, tek okumalı bir mesajla aynı maliyettedir; dolayısıyla batch kullanmak kota tasarrufu sağlar.

