Dies ist die Referenz dafür, was ein Gerät veröffentlicht und abonniert. Verbindung, Anmeldung und Sitzungsregeln stehen unter MQTT. HTTP-Geräte verwenden dieselben Nutzlasten; siehe Device HTTP API.
Themen des Standardschemas
Alle Themen beginnen mit v1/. Verwenden Sie QoS 1.
| Richtung | Thema | Verwendung | Seite |
|---|---|---|---|
| Aufwärts | v1/telemetry | Telemetrie | unten |
| Aufwärts | v1/attributes | Client-Attribute | Attribute |
| Aufwärts | v1/attributes/req/{id} | Attribute anfordern | Attribute |
| Abwärts | v1/attributes/res/{id} | Antwort auf eine Attributanforderung | Attribute |
| Abwärts | v1/attributes/set | Änderungen gemeinsamer Attribute, einschließlich Firmware-Angeboten (fw_*) | Firmware-Updates (OTA) |
| Abwärts | v1/rpc/req/{id} | Befehl aus der Cloud | Befehle an Geräte senden |
| Aufwärts | v1/rpc/res/{id} | Antwort auf einen Befehl | gleich |
| Aufwärts | v1/rpc/up/req/{id} | Anforderung vom Gerät an die Cloud | gleich |
| Abwärts | v1/rpc/up/res/{id} | Antwort auf eine Geräteanforderung | gleich |
| Aufwärts | v1/provision/req | Provisionierungsanforderung (nur in einer Provisionierungssitzung) | Geräte hinzufügen und beanspruchen |
| Abwärts | v1/provision/res | Provisionierungsantwort | gleich |
| Aufwärts | v1/hello | Die Selbstbeschreibung des Geräts (lizenzierte Geräte) | Lizenzierte Geräte |
| Aufwärts | v1/csr | Zertifikatsignierungsanforderung (lizenzierte Geräte) | Gerätezertifikate |
| Abwärts | v1/cert | Das ausgestellte Zertifikat | gleich |
| Aufwärts | v1/claim | Beanspruchungsfenster öffnen oder schließen (lizenzierte Geräte) | Geräte hinzufügen und beanspruchen |
| Aufwärts | v1/gw/connect, v1/gw/disconnect, v1/gw/telemetry, v1/gw/attributes, v1/gw/attributes/req | Nur Gateways: Meldung für untergeordnete Geräte und Anfrage nach Attributen eines untergeordneten Geräts | Geräte hinter einem Gateway |
| Abwärts | v1/gw/rpc, v1/gw/attributes, v1/gw/attributes/res | Nur Gateways: Befehle und gemeinsame Attribute für untergeordnete Geräte sowie Antworten auf Attributanfragen | Commands to devices behind a gateway |
| Aufwärts | v1/gw/rpc | Nur Gateways: Antwort eines untergeordneten Geräts auf einen Befehl | gleich |
Ein Gerät darf nur seine Abwärtsthemen abonnieren: v1/attributes/set, v1/attributes/res/+, v1/rpc/req/+, v1/rpc/up/res/+ und v1/cert, dazu v1/gw/attributes, v1/gw/rpc und v1/gw/attributes/res für Gateways. Ein Gerät erhält nie Nachrichten eines anderen Geräts.
Abgelehnte Themen
| Veröffentlicht an | Ergebnis |
|---|---|
Ein unbekanntes Thema unter v1/ | Abgelehnt als unknown_reserved_topic, wird nie gespeichert. |
Ein Abwärtsthema, v1/gw/* von einem Gerät, das kein Gateway ist, oder v1/provision/req außerhalb einer Provisionierungssitzung | Abgelehnt als forbidden_topic. |
Beide werden quittiert und verworfen. Drei abgelehnte Topics innerhalb einer Minute schließen die Sitzung.
Verbindungsablauf
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-kompatible Themen
Profile mit dem Schema Legacy-kompatibel akzeptieren außerdem:
| Richtung | Thema |
|---|---|
| Aufwärts | v1/devices/me/telemetry |
| Aufwärts und abwärts | v1/devices/me/attributes |
| Aufwärts | v1/devices/me/attributes/request/{id} |
| Abwärts | v1/devices/me/attributes/response/{id} |
Sie übertragen keine Befehls-, Beanspruchungs-, Provisionierungs- oder Gateway-Themen.
Benutzerdefinierte Themen
Profile mit Benutzerdefinierte Themen akzeptieren jedes Thema außerhalb von v1/ als Telemetrie des Geräts:
- Ein JSON-Objekt wird zu Schlüsseln. Alles andere (eine Zahl, ein Array, Text, Binärdaten) wird zum einzelnen Schlüssel
raw, als sein Text, bis zur Max. Rohnutzlast (Bytes) des Profils (standardmäßig 4.096). - Das Thema muss innerhalb der Max. Thementiefe (8), Max. Themenlänge (128) und Verschiedene Themen pro Gerät (50) bleiben.
- Mit Prefix keys with the topic wird jeder Schlüssel als
<topic>.<key>gespeichert: Das/des Topics wird zu., andere Zeichen außerhalb der Schlüsselregel werden zu_. Zum Beispiel ergebensite1/boilerundtempden Wertsite1.boiler.temp. Ein zusammengesetzter Schlüssel mit mehr als 64 Zeichen wird verworfen. Ohne Präfix überschreibt sich derselbe Schlüssel aus zwei Topics selbst.
Formen der Telemetrie-Nutzlast
Telemetrie ist JSON, UTF-8.
Form A, ein flaches Objekt. Ein Datensatz, versehen mit dem Zeitpunkt, zu dem Hermetry ihn empfangen hat:
{"temperature": 21.5, "humidity": 40, "door_open": false}
Form B, ein Objekt mit genau ts und values. Ein Datensatz bei ts:
{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}
Form C, ein Array aus Objekten der Form A und Form B. Ein Datensatz pro Element, in Reihenfolge:
[
{"ts": 1759572000000, "values": {"sys.cpu_load": 0.42}},
{"ts": 1759572060000, "values": {"sys.cpu_load": 0.38}},
{"net.wan.up": true}
]
Kein JSON. Ein Body, der kein JSON ist, wird als ein raw-Schlüssel im Standard-Telemetriethema gespeichert. Ein JSON-Skalar (42, "on") auf v1/telemetry wird abgelehnt (bad_form).
Ein Objekt mit ts und values plus einem weiteren Mitglied ist Form A, nicht Form B: Alle seine Mitglieder werden zu Schlüsseln.
Zeitstempel
tsist eine Ganzzahl: Millisekunden seit der Unix-Epoche, UTC.- Ein Gerät ohne synchronisierte Uhr muss Form A verwenden. Es darf keinen Zeitstempel erfinden.
- Datensätze, die mehr als 10 Minuten in der Zukunft liegen oder älter als Ihre Telemetrie-Aufbewahrung sind, werden verworfen. Sie werden nie auf einen anderen Zeitpunkt verschoben.
- Duplikate desselben Geräts, Schlüssels und Zeitpunkts werden nur einmal gespeichert.
Siehe Zeitstempel, verspätete und doppelte Messwerte.
Schlüssel
- Muster:
^[A-Za-z0-9_.\-]{1,64}$. Schlüssel unterscheiden Groß- und Kleinschreibung:abcundABCsind zwei Schlüssel. - In der Telemetrie abgelehnt: Schlüssel, die mit
_,fw_,current_fw_odercfg.beginnen. - Tipp: Verwenden Sie durch Punkte getrennte Namen in Kleinschreibung, zum Beispiel
net.wan.up.
Ein fehlerhafter Schlüssel verwirft nur diesen Schlüssel; der Rest des Datensatzes bleibt erhalten.
Werte
| JSON-Wert | Gespeichert als | Regel |
|---|---|---|
| Ganzzahl | long | Über ±2^53 als Zeichenkette senden. |
| Bruchzahl | double | NaN und Infinity sind kein JSON und werden abgelehnt. |
true / false | boolean | Diagramme lesen Zahlen: Senden Sie 0/1, wenn Sie einen Verlauf möchten. |
| Zeichenkette | string | Bis zu 1.024 Zeichen. Wird als letzter Wert angezeigt, nicht im Diagramm. |
| Objekt oder Array | JSON | Bis zu 4 KiB, unverändert gespeichert. |
null | nichts | Bedeutet „keine Messung“. Es löscht nichts. |
Ein fehlerhafter Wert verwirft nur diesen Schlüssel.
Größe
- Eine Nachricht: bis zu 64 KiB und bis zu 1.000 Schlüssel-Wert-Punkte. Mehr Punkte verwerfen die gesamte Nachricht; eine größere Nachricht wird als Ganzes verworfen. Die Verbindung bleibt bestehen.
- Verschachtelungstiefe: bis zu 8 Ebenen.
- Bündeln Sie Ihre Nachrichten, wenn Sie mehr als eine Messung pro Sekunde senden.
Client-Attribute
PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}
Attributschlüssel dürfen bis zu 128 Zeichen lang sein. Siehe Attribute.
Befehle
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": {}}
Provisionierung
username: provision, password: empty
SUBSCRIBE v1/provision/res
PUBLISH v1/provision/req
{"deviceName": "boiler-07", "provisionDeviceKey": "pk_…", "provisionDeviceSecret": "ps_…"}
Was als Nachricht zählt
Jede akzeptierte Telemetrie- oder Attributveröffentlichung zählt einmal auf Ihr monatliches Nachrichtenkontingent, unabhängig vom Inhalt. Antworten auf Befehle, Verbindungsereignisse und Alarme zählen nicht. Eine Nachricht mit 50 Messwerten kostet dasselbe wie eine mit einem einzigen Messwert, daher spart Bündeln Kontingent.

