MQTT-Topics und Referenz der Nutzlasten

Dies ist die Referenz dafür, was ein Gerät veröffentlicht und abonniert. Verbindungs-, Anmelde- und Sitzungsregeln stehen unter MQTT. HTTP-Geräte verwenden dieselben Nutzlasten; siehe Device HTTP API.

Topics des Standardschemas

Alle Topics beginnen mit v1/. Verwenden Sie QoS 1.

Richtung	Topic	Verwendung	Seite
Aufwärts	`v1/telemetry`	Telemetrie	unten
Aufwärts	`v1/attributes`	Client-Attribute	Attributes
Aufwärts	`v1/attributes/req/{id}`	Attribute anfordern	Attributes
Abwärts	`v1/attributes/res/{id}`	Antwort auf eine Attributanfrage	Attributes
Abwärts	`v1/attributes/set`	Änderungen geteilter Attribute, einschließlich Firmware-Angebote (`fw_*`)	Firmware updates (OTA)
Abwärts	`v1/rpc/req/{id}`	Befehl aus der Cloud	Sending commands to devices
Aufwärts	`v1/rpc/res/{id}`	Antwort auf einen Befehl	gleich
Aufwärts	`v1/rpc/up/req/{id}`	Anfrage vom Gerät an die Cloud	gleich
Abwärts	`v1/rpc/up/res/{id}`	Antwort auf eine Geräteanfrage	gleich
Aufwärts	`v1/provision/req`	Provisionierungsanfrage (nur in einer Provisionierungssitzung)	Adding and claiming devices
Abwärts	`v1/provision/res`	Provisionierungsantwort	gleich
Aufwärts	`v1/hello`	Die Selbstbeschreibung des Geräts (licensed devices)	Licensed devices
Aufwärts	`v1/csr`	Zertifikatsignierungsanfrage (licensed devices)	Device certificates
Abwärts	`v1/cert`	Das ausgestellte Zertifikat	gleich
Aufwärts	`v1/claim`	Claim-Fenster öffnen oder schließen (licensed devices)	Adding and claiming devices
Aufwärts	`v1/gw/connect`, `v1/gw/disconnect`, `v1/gw/telemetry`, `v1/gw/attributes`, `v1/gw/attributes/req` (In Entwicklung)	Nur für Gateways: Meldung für untergeordnete Geräte	Devices behind a gateway
Abwärts	`v1/gw/attributes`, `v1/gw/attributes/res`, `v1/gw/rpc`	Nur für Gateways; In Entwicklung (Befehle und geteilte Attribute an untergeordnete Geräte)	gleich

Ein Gerät darf nur seine Downlink-Topics 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 niemals Nachrichten eines anderen Geräts.

Abgelehnte Topics

Veröffentlicht an	Ergebnis
Ein unbekanntes Topic unter `v1/`	Abgelehnt als `unknown_reserved_topic`, nie gespeichert.
Ein Downlink-Topic, `v1/gw/*` von einem Gerät, das kein Gateway ist, oder `v1/provision/req` außerhalb einer Provisionierungssitzung	Abgelehnt als `forbidden_topic`.

Beide werden bestätigt 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

Kompatible Legacy-Topics

Profile mit dem Schema Legacy compatible akzeptieren außerdem:

Richtung	Topic
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 enthalten keine Befehls-, Claiming-, Provisionierungs- oder Gateway-Topics.

Benutzerdefinierte Topics

Profile mit Custom topics akzeptieren jedes Topic 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 raw payload (bytes) des Profils (standardmäßig 4.096).
Das Topic muss innerhalb der Max topic depth (8), Max topic length (128) und Distinct topics per device (50) des Profils bleiben.
Mit Prefix keys with the topic wird jeder Schlüssel als <topic>.<key> gespeichert: Die / des Topics werden zu ., andere Zeichen außerhalb der Schlüsselregel werden zu _. Zum Beispiel ergeben site1/boiler und temp site1.boiler.temp. Ein zusammengesetzter Schlüssel über 64 Zeichen wird verworfen. Ohne Präfix überschreibt derselbe Schlüssel aus zwei Topics sich 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 zum Zeitpunkt 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-Telemetrie-Topic 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

ts ist 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 niemals auf einen anderen Zeitpunkt verschoben.
Duplikate desselben Geräts, Schlüssels und Zeitpunkts werden einmal gespeichert.

Siehe Timestamps, late and duplicate readings.

Schlüssel

Muster: ^[A-Za-z0-9_.\-]{1,64}$. Schlüssel unterscheiden Groß- und Kleinschreibung: abc und ABC sind zwei Schlüssel.
In der Telemetrie abgelehnt: Schlüssel, die mit _, fw_, current_fw_ oder cfg. beginnen.
Tipp: Verwenden Sie punktgetrennte Namen in Kleinschreibung, zum Beispiel net.wan.up.

Ein ungültiger 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.
Bruch	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 als Diagramm.
Objekt oder Array	JSON	Bis zu 4 KiB, unverändert gespeichert.
`null`	nichts	Bedeutet „kein Messwert“. Es löscht nichts.

Ein ungültiger Wert verwirft nur diesen Schlüssel.

Größe

Eine Nachricht: bis zu 64 KiB und bis zu 1.000 Schlüssel-Wert-Paare. Mehr Punkte verwerfen die gesamte Nachricht; eine größere Nachricht wird komplett verworfen. Die Verbindung bleibt bestehen.
Verschachtelungstiefe: bis zu 8 Ebenen.
Bündeln Sie Ihre Nachrichten, wenn Sie mehr als eine Probe 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 Attributes.

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. Befehlsantworten, Verbindungsereignisse und Alarme zählen nicht. Eine Nachricht mit 50 Messwerten kostet dasselbe wie eine mit einem einzigen Messwert, daher spart Bündeln Kontingent.