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

Protokollversionen und Geräteregeln

Wie das Geräteprotokoll versioniert wird, was ein Gerät in hello ankündigt, welche Fehlercodes es verwendet und wie es reagieren muss, wenn etwas schiefgeht.

Diese Seite richtet sich an alle, die Geräte-Firmware oder Gateway-Software für Hermetry entwickeln. Sie erklärt, wie das Geräteprotokoll versioniert wird und welche Regeln ein Gerät befolgt, damit es auch bei Änderungen an Hermetry weiter funktioniert. Die Topics und Payloads selbst stehen in der Referenz zu MQTT-Topics und Payloads; die Regeln für Verbindung und Anmeldung stehen unter MQTT.

Zwei Versionskennzeichen

KennzeichenWoBedeutung
v1/Der Anfang jedes Topics des StandardschemasDie Version der Topic-Namen. Eine Änderung, die Topics inkompatibel macht, würde neue Topics unter v2/ verwenden; die v1/-Topics werden nicht umbenannt.
roltek-device-protocol/1Das Feld protocol in der hello-Nachricht des GerätsDie Hauptversion des Protokolls, das das Gerät spricht. Hermetry speichert die Hauptversion am Gerät.

Die beiden Kennzeichen sind unabhängig voneinander: Eine neue Protokoll-Hauptversion bedeutet nicht von selbst neue Topic-Namen.

Die hello-Nachricht

Ein Gerät, das sich selbst beschreibt (lizenzierte Geräte tun das), veröffentlicht einmal pro Verbindung mit QoS 1 auf v1/hello. Geräte, die kein hello senden, funktionieren weiter mit den Standard-Topics.

FeldInhalt
modelDas Gerätemodell
serialDie Seriennummer. Sie muss mit der registrierten Seriennummer des Geräts übereinstimmen, sonst wird die Nachricht mit hello_serial_mismatch abgelehnt.
fwDie Firmware-Version
hwDie Hardware-Revision
profile_hashEin Hash des Einstellungsprofils des Geräts
capabilitiesDie Funktionen, die das Gerät unterstützt (siehe unten)
protocolroltek-device-protocol/1

Capabilities

Ein Gerät listet nur auf, was es unterstützt.

CapabilityBedeutung
telemetrySendet Messwerte
attributesSendet Client-Attribute und nimmt Shared Attributes entgegen
rpcNimmt Befehle entgegen
rpc.persistentNimmt Befehle entgegen, die gehalten werden, bis das Gerät wieder online ist
otaNimmt Firmware-Updates entgegen
cfgNimmt Konfiguration über Shared Attributes cfg.* entgegen (benötigt cfg_hash)
claimKann über ein Claim-Fenster beansprucht werden
csrFordert ein Gerätezertifikat an
store_forwardPuffert Messwerte im Offline-Betrieb und sendet sie später
gatewayMeldet für untergeordnete Geräte

Die Capability-Liste von Protokoll 1 ist seit dem 23. Oktober 2026 festgeschrieben.

Kompatible und inkompatible Änderungen

Kompatible Änderungen behalten die Protokollversion bei. Hermetry darf jederzeit neue optionale Felder, Capability-Werte, Befehlsmethoden, Attributschlüssel, Fehlercodes und Telemetrieschlüssel hinzufügen. Ein Gerät muss daher ignorieren, was es nicht kennt: ein unbekanntes Feld, einen unbekannten Shared-Attribute-Schlüssel, einen unbekannten Fehlercode.

Inkompatible Änderungen erfordern eine neue Hauptversion: das Umbenennen oder Entfernen eines Topics, Felds, Attributschlüssels oder Zustands; das Ändern von Typ oder Bedeutung eines Felds; oder ein Limit, das strenger ist, als es ein korrektes Gerät der aktuellen Version überschreiten könnte.

Wenn eine Nachricht abgelehnt wird

Protokoll 1 hat kein Fehler-Topic. Eine Nachricht, die Hermetry nicht annehmen kann, wird verworfen und trotzdem bestätigt (PUBACK), sodass das Gerät sie nicht erneut sendet. Hermetry zählt den Grund; er wird nicht an das Gerät gesendet.

Was passiert istWas Hermetry tut
JSON, das tiefer als 8 Ebenen verschachtelt istVerwirft es (invalid_payload)
Client-Attribute oder hello, die kein JSON-Objekt sindVerwirft es (invalid_payload)
Telemetrie, die überhaupt kein JSON ist (Text, Binärdaten)Speichert sie unter dem einzelnen Schlüssel raw, bis zur Raw-Größe des Profils (darüber raw_too_large)
Ein Topic unter v1/, das nicht existiertVerwirft es (unknown_reserved_topic)
Ein Topic, auf dem das Gerät nicht veröffentlichen darfVerwirft es (forbidden_topic)
Drei abgelehnte Topics innerhalb einer MinuteSchließt die Session
Ein SUBSCRIBE auf ein Topic, das das Gerät nicht lesen darfAntwortet mit SUBACK 0x80
Nachrichten über den Ratenlimits des ProfilsVerwirft die überzähligen Nachrichten; mehr als das Dreifache des Limits innerhalb von 60 Sekunden schließt die Session (rate_limit)

Über HTTP antwortet die Geräte-API stattdessen mit einem Status:

StatusCode
400invalid_payload, hello_serial_mismatch
413payload_too_large, raw_too_large
429rate_limited, mit einem Retry-After-Header

Die Codes, die Hermetry für gespeicherte Messwerte erfasst (key_invalid, bad_ts und weitere), sind unter Fehlermeldungen aufgeführt.

Fehlercodes für Befehle

Befehle in beide Richtungen (Cloud zu Gerät auf v1/rpc/req/{id}, Gerät zu Cloud auf v1/rpc/up/req/{id}) melden Fehler als {"ok": false, "error": "<code>"} mit einem dieser Codes:

CodeBedeutung
unsupported_methodDer Empfänger kennt die Methode nicht
bad_paramsDie Parameter fehlen oder sind falsch
busyDer Empfänger kann es jetzt nicht ausführen
timeoutDie Operation ist beim Empfänger in ein Timeout gelaufen
expiredDie expirationTime der Anfrage ist abgelaufen
forbiddenDie Methode ist durch eine lokale Richtlinie abgeschaltet
payload_too_largeDie Anfrage ist größer, als der Empfänger annimmt
internalAlles andere

Ein Empfänger behandelt **jeden anderen Code als internal**.

Eine Anfrage vom Gerät an die Cloud wird von Ihren Flows beantwortet. Antwortet innerhalb von 5 Sekunden kein Flow, antwortet Hermetry mit unsupported_method. Zwei Methoden beantwortet immer Hermetry selbst:

MethodeAntwort
getCurrentTime{"ok": true, "result": {"ts": <server time in ms>}}
getSessionLimitsDie effektiven Limits pro Gerät aus dem Profil des Geräts

Regeln für das Gerät

  1. Ignorieren Sie, was Sie nicht verstehen: fehlerhafte Downlink-Nachrichten, unbekannte Shared-Attribute-Schlüssel und unbekannte Felder.
  2. Beantworten Sie einen unbekannten Befehl mit unsupported_method; behandeln Sie einen unbekannten Fehlercode als internal.
  3. Führen Sie eine Befehls-ID nur einmal aus. Ein Befehl kann zweimal eintreffen; siehe Befehle an Geräte senden.
  4. Senden Sie erneut, wenn keine Bestätigung kommt. Kommt innerhalb von 20 Sekunden kein PUBACK, senden Sie die Nachricht mit dem DUP-Flag erneut; nach drei Wiederholungen verbinden Sie sich neu.
  5. Wiederholen Sie eine ausgebliebene Antwort einmal. Bleibt die Antwort auf eine Attributanfrage oder eine Geräteanfrage aus, fragen Sie ein weiteres Mal.
  6. Gehen Sie bei abgelehnten Verbindungen in den Backoff. Bei CONNACK 1 (Protokollversion nicht unterstützt) hören Sie mit Wiederholungen auf; bei CONNACK 3 gehen Sie normal in den Backoff; bei CONNACK 4 oder 5 warten Sie lange. Die Codes stehen unter MQTT.
  7. Bleiben Sie unter Ihren Limits. Fragen Sie sie nach dem Verbinden mit getSessionLimits ab und bleiben Sie unter 80 % jedes Limits. Die Standardwerte stehen unter Limits und Kontingente.