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
| Kennzeichen | Wo | Bedeutung |
|---|---|---|
v1/ | Der Anfang jedes Topics des Standardschemas | Die 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/1 | Das Feld protocol in der hello-Nachricht des Geräts | Die 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.
| Feld | Inhalt |
|---|---|
model | Das Gerätemodell |
serial | Die Seriennummer. Sie muss mit der registrierten Seriennummer des Geräts übereinstimmen, sonst wird die Nachricht mit hello_serial_mismatch abgelehnt. |
fw | Die Firmware-Version |
hw | Die Hardware-Revision |
profile_hash | Ein Hash des Einstellungsprofils des Geräts |
capabilities | Die Funktionen, die das Gerät unterstützt (siehe unten) |
protocol | roltek-device-protocol/1 |
Capabilities
Ein Gerät listet nur auf, was es unterstützt.
| Capability | Bedeutung |
|---|---|
telemetry | Sendet Messwerte |
attributes | Sendet Client-Attribute und nimmt Shared Attributes entgegen |
rpc | Nimmt Befehle entgegen |
rpc.persistent | Nimmt Befehle entgegen, die gehalten werden, bis das Gerät wieder online ist |
ota | Nimmt Firmware-Updates entgegen |
cfg | Nimmt Konfiguration über Shared Attributes cfg.* entgegen (benötigt cfg_hash) |
claim | Kann über ein Claim-Fenster beansprucht werden |
csr | Fordert ein Gerätezertifikat an |
store_forward | Puffert Messwerte im Offline-Betrieb und sendet sie später |
gateway | Meldet 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 ist | Was Hermetry tut |
|---|---|
| JSON, das tiefer als 8 Ebenen verschachtelt ist | Verwirft es (invalid_payload) |
Client-Attribute oder hello, die kein JSON-Objekt sind | Verwirft 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 existiert | Verwirft es (unknown_reserved_topic) |
| Ein Topic, auf dem das Gerät nicht veröffentlichen darf | Verwirft es (forbidden_topic) |
| Drei abgelehnte Topics innerhalb einer Minute | Schließt die Session |
| Ein SUBSCRIBE auf ein Topic, das das Gerät nicht lesen darf | Antwortet mit SUBACK 0x80 |
| Nachrichten über den Ratenlimits des Profils | Verwirft 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:
| Status | Code |
|---|---|
| 400 | invalid_payload, hello_serial_mismatch |
| 413 | payload_too_large, raw_too_large |
| 429 | rate_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:
| Code | Bedeutung |
|---|---|
unsupported_method | Der Empfänger kennt die Methode nicht |
bad_params | Die Parameter fehlen oder sind falsch |
busy | Der Empfänger kann es jetzt nicht ausführen |
timeout | Die Operation ist beim Empfänger in ein Timeout gelaufen |
expired | Die expirationTime der Anfrage ist abgelaufen |
forbidden | Die Methode ist durch eine lokale Richtlinie abgeschaltet |
payload_too_large | Die Anfrage ist größer, als der Empfänger annimmt |
internal | Alles 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:
| Methode | Antwort |
|---|---|
getCurrentTime | {"ok": true, "result": {"ts": <server time in ms>}} |
getSessionLimits | Die effektiven Limits pro Gerät aus dem Profil des Geräts |
Regeln für das Gerät
- Ignorieren Sie, was Sie nicht verstehen: fehlerhafte Downlink-Nachrichten, unbekannte Shared-Attribute-Schlüssel und unbekannte Felder.
- Beantworten Sie einen unbekannten Befehl mit
unsupported_method; behandeln Sie einen unbekannten Fehlercode alsinternal. - Führen Sie eine Befehls-ID nur einmal aus. Ein Befehl kann zweimal eintreffen; siehe Befehle an Geräte senden.
- 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.
- Wiederholen Sie eine ausgebliebene Antwort einmal. Bleibt die Antwort auf eine Attributanfrage oder eine Geräteanfrage aus, fragen Sie ein weiteres Mal.
- 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.
- Bleiben Sie unter Ihren Limits. Fragen Sie sie nach dem Verbinden mit
getSessionLimitsab und bleiben Sie unter 80 % jedes Limits. Die Standardwerte stehen unter Limits und Kontingente.

