Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

MQTT-Themen und Nutzlast-Referenz

Jedes MQTT-Thema – Telemetrie, Attribute, Befehle, Provisionierung, Zertifikate, Beanspruchung, Gateway – die Nutzlastformen sowie die Regeln für Schlüssel und Werte.

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.

RichtungThemaVerwendungSeite
Aufwärtsv1/telemetryTelemetrieunten
Aufwärtsv1/attributesClient-AttributeAttribute
Aufwärtsv1/attributes/req/{id}Attribute anfordernAttribute
Abwärtsv1/attributes/res/{id}Antwort auf eine AttributanforderungAttribute
Abwärtsv1/attributes/setÄnderungen gemeinsamer Attribute, einschließlich Firmware-Angeboten (fw_*)Firmware-Updates (OTA)
Abwärtsv1/rpc/req/{id}Befehl aus der CloudBefehle an Geräte senden
Aufwärtsv1/rpc/res/{id}Antwort auf einen Befehlgleich
Aufwärtsv1/rpc/up/req/{id}Anforderung vom Gerät an die Cloudgleich
Abwärtsv1/rpc/up/res/{id}Antwort auf eine Geräteanforderunggleich
Aufwärtsv1/provision/reqProvisionierungsanforderung (nur in einer Provisionierungssitzung)Geräte hinzufügen und beanspruchen
Abwärtsv1/provision/resProvisionierungsantwortgleich
Aufwärtsv1/helloDie Selbstbeschreibung des Geräts (lizenzierte Geräte)Lizenzierte Geräte
Aufwärtsv1/csrZertifikatsignierungsanforderung (lizenzierte Geräte)Gerätezertifikate
Abwärtsv1/certDas ausgestellte Zertifikatgleich
Aufwärtsv1/claimBeanspruchungsfenster öffnen oder schließen (lizenzierte Geräte)Geräte hinzufügen und beanspruchen
Aufwärtsv1/gw/connect, v1/gw/disconnect, v1/gw/telemetry, v1/gw/attributes, v1/gw/attributes/reqNur Gateways: Meldung für untergeordnete Geräte und Anfrage nach Attributen eines untergeordneten GerätsGeräte hinter einem Gateway
Abwärtsv1/gw/rpc, v1/gw/attributes, v1/gw/attributes/resNur Gateways: Befehle und gemeinsame Attribute für untergeordnete Geräte sowie Antworten auf AttributanfragenCommands to devices behind a gateway
Aufwärtsv1/gw/rpcNur Gateways: Antwort eines untergeordneten Geräts auf einen Befehlgleich

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 anErgebnis
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 ProvisionierungssitzungAbgelehnt 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:

RichtungThema
Aufwärtsv1/devices/me/telemetry
Aufwärts und abwärtsv1/devices/me/attributes
Aufwärtsv1/devices/me/attributes/request/{id}
Abwärtsv1/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 ergeben site1/boiler und temp den Wert site1.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

  • 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 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: abc und ABC sind zwei Schlüssel.
  • In der Telemetrie abgelehnt: Schlüssel, die mit _, fw_, current_fw_ oder cfg. 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-WertGespeichert alsRegel
GanzzahllongÜber ±2^53 als Zeichenkette senden.
BruchzahldoubleNaN und Infinity sind kein JSON und werden abgelehnt.
true / falsebooleanDiagramme lesen Zahlen: Senden Sie 0/1, wenn Sie einen Verlauf möchten.
ZeichenkettestringBis zu 1.024 Zeichen. Wird als letzter Wert angezeigt, nicht im Diagramm.
Objekt oder ArrayJSONBis zu 4 KiB, unverändert gespeichert.
nullnichtsBedeutet „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.

Verwandt