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

MQTT topic’leri ve payload referansı

Tüm MQTT topic'leri – telemetri, öznitelikler, komutlar, provisioning, sertifikalar, sahiplenme, gateway – payload biçimleri ile key ve değer kuralları.

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önTopicKullanımSayfa
Yukarıv1/telemetryTelemetriaş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/setYazılım güncelleme teklifleri (fw_*) dahil paylaşılan öznitelik değişiklikleriFirmware güncellemeleri (OTA)
Aşağıv1/rpc/req/{id}Buluttan komutCihazlara komut gönderme
Yukarıv1/rpc/res/{id}Komuta yanıtaynı
Yukarıv1/rpc/up/req/{id}Cihazdan buluta istekaynı
Aşağıv1/rpc/up/res/{id}Cihaz isteğine yanıtaynı
Yukarıv1/provision/reqProvisioning isteği (yalnızca provisioning oturumunda)Cihaz ekleme ve sahiplenme
Aşağıv1/provision/resProvisioning yanıtıaynı
Yukarıv1/helloCihazın kendini tanıtması (lisanslı cihazlar)Lisanslı cihazlar
Yukarıv1/csrSertifika imzalama isteği (lisanslı cihazlar)Cihaz sertifikaları
Aşağıv1/certVerilen sertifikaaynı
Yukarıv1/claimSahiplenme 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/reqYalnızca gateway’ler: alt cihazlar için bildirim yapar ve bir alt cihazın özniteliklerini isterGateway arkasındaki cihazlar
Aşağıv1/gw/rpc, v1/gw/attributes, v1/gw/attributes/resYalnızca gateway’ler: alt cihazlar için komutlar ve paylaşılan öznitelikler ile öznitelik isteklerine yanıtlarGateway arkasındaki cihazlara komutlar
Yukarıv1/gw/rpcYalnı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 topicSonuç
v1/ altında bilinmeyen bir topicunknown_reserved_topic olarak reddedilir, asla saklanmaz.
Bir downlink topic’i, gateway olmayan bir cihazdan v1/gw/* veya provisioning oturumu dışında v1/provision/reqforbidden_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önTopic
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 raw key’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ğin site1/boiler ve temp, site1.boiler.temp sonucunu 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ı

  • ts bir 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: abc ve ABC iki ayrı key’dir.
  • Telemetride reddedilenler: _, fw_, current_fw_ veya cfg. 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ğeriSaklanma türüKural
Tam sayılong±2^53 üzerindeki değerleri string olarak gönderin.
Ondalıklı sayıdoubleNaN ve Infinity JSON değildir ve reddedilir.
true / falsebooleanGrafikler sayıları okur: geçmiş istiyorsanız 0/1 gönderin.
StringstringEn fazla 1.024 karakter. Son değer olarak gösterilir, grafiğe dökülmez.
Nesne veya diziJSONEn fazla 4 KiB, olduğu gibi saklanır.
nullhiç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.

İlgili