This page is for people who write device firmware or gateway software for Hermetry. It explains how the device protocol is versioned and the rules a device follows so that it keeps working as Hermetry changes. The topics and payloads themselves are in MQTT topics and payload reference; connection and login rules are in MQTT.
Two version marks
| Mark | Where | Meaning |
|---|---|---|
v1/ | The start of every topic of the default scheme | The version of the topic names. A change that breaks topics would use new topics under v2/; the v1/ topics are not renamed. |
roltek-device-protocol/1 | The protocol field of the device’s hello message | The major version of the protocol the device speaks. Hermetry stores the major version on the device. |
The two marks are independent: a new protocol major does not by itself mean new topic names.
The hello message
A device that describes itself (licensed devices do) publishes to v1/hello once per connection, with QoS 1. Devices that do not send hello keep working with the default topics.
| Field | What it holds |
|---|---|
model | The device model |
serial | The serial number. It must match the device’s registered serial, or the message is refused with hello_serial_mismatch. |
fw | The firmware version |
hw | The hardware revision |
profile_hash | A hash of the device’s settings profile |
capabilities | The features the device supports (below) |
protocol | roltek-device-protocol/1 |
Capabilities
A device lists only what it supports.
| Capability | Meaning |
|---|---|
telemetry | Sends readings |
attributes | Sends client attributes and takes shared attributes |
rpc | Takes commands |
rpc.persistent | Takes commands kept until the device is back online |
ota | Takes firmware updates |
cfg | Takes configuration through cfg.* shared attributes (needs cfg_hash) |
claim | Can be claimed with a claim window |
csr | Asks for a device certificate |
store_forward | Buffers readings while offline and sends them later |
gateway | Reports for child devices |
The capability list of protocol 1 is fixed since 23 October 2026.
Compatible and breaking changes
Compatible changes keep the protocol version. Hermetry may add new optional fields, capability values, command methods, attribute keys, error codes and telemetry keys at any time. A device must therefore ignore what it does not know: an unknown field, an unknown shared attribute key, an unknown error code.
Breaking changes need a new major version: renaming or removing a topic, field, attribute key or state; changing the type or meaning of a field; or making a limit stricter than a correct device of the current version could exceed.
When a message is refused
Protocol 1 has no error topic. A message Hermetry cannot accept is dropped and still acknowledged (PUBACK), so a device does not resend it. Hermetry counts the reason; it is not sent to the device.
| What happened | What Hermetry does |
|---|---|
| JSON nested deeper than 8 levels | Drops it (invalid_payload) |
Client attributes or hello that are not a JSON object | Drops it (invalid_payload) |
| Telemetry that is not JSON at all (text, binary) | Keeps it as the single key raw, up to the profile’s raw size (raw_too_large above it) |
A topic under v1/ that does not exist | Drops it (unknown_reserved_topic) |
| A topic the device may not publish to | Drops it (forbidden_topic) |
| Three refused topics within a minute | Closes the session |
| A SUBSCRIBE to a topic the device may not read | Answers SUBACK 0x80 |
| Messages over the profile’s rate limits | Drops the extra messages; more than three times the limit within 60 seconds closes the session (rate_limit) |
Over HTTP the device API answers with a status instead:
| Status | Code |
|---|---|
| 400 | invalid_payload, hello_serial_mismatch |
| 413 | payload_too_large, raw_too_large |
| 429 | rate_limited, with a Retry-After header |
The codes Hermetry records for stored readings (key_invalid, bad_ts and others) are listed in Error messages.
Command error codes
Commands in both directions (cloud to device on v1/rpc/req/{id}, device to cloud on v1/rpc/up/req/{id}) answer errors as {"ok": false, "error": "<code>"} with one of these codes:
| Code | Meaning |
|---|---|
unsupported_method | The receiver does not know the method |
bad_params | The parameters are missing or wrong |
busy | The receiver cannot run it now |
timeout | The operation timed out on the receiver |
expired | The request’s expirationTime has passed |
forbidden | The method is switched off by a local policy |
payload_too_large | The request is larger than the receiver takes |
internal | Anything else |
A receiver treats **any other code as internal**.
A request from the device to the cloud is answered by your flows. If no flow answers within 5 seconds, Hermetry answers unsupported_method. Two methods are always answered by Hermetry itself:
| Method | Answer |
|---|---|
getCurrentTime | {"ok": true, "result": {"ts": <server time in ms>}} |
getSessionLimits | The effective per-device limits of the device’s profile |
Rules for the device
- Ignore what you do not understand: malformed downlink messages, unknown shared attribute keys and unknown fields.
- Answer an unknown command with
unsupported_method; treat an unknown error code asinternal. - Run a command id once. A command may arrive twice; see Sending commands to devices.
- Resend when there is no acknowledgement. With no PUBACK within 20 seconds, resend the message with the DUP flag; after three resends, reconnect.
- Retry a timed-out answer once. If an attribute request or a device request gets no answer, ask once more.
- Back off on refused connections. On CONNACK 1 (protocol version not supported) stop retrying; on CONNACK 3 back off normally; on CONNACK 4 or 5 back off for a long time. The codes are in MQTT.
- Stay below your limits. Ask for them with
getSessionLimitsafter connecting and keep under 80 % of each. The defaults are in Limits and quotas.

