New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Protocol versions and device rules

How the device protocol is versioned, what a device announces in hello, the error codes it uses, and how it must react when something goes wrong.

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

MarkWhereMeaning
v1/The start of every topic of the default schemeThe 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/1The protocol field of the device’s hello messageThe 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.

FieldWhat it holds
modelThe device model
serialThe serial number. It must match the device’s registered serial, or the message is refused with hello_serial_mismatch.
fwThe firmware version
hwThe hardware revision
profile_hashA hash of the device’s settings profile
capabilitiesThe features the device supports (below)
protocolroltek-device-protocol/1

Capabilities

A device lists only what it supports.

CapabilityMeaning
telemetrySends readings
attributesSends client attributes and takes shared attributes
rpcTakes commands
rpc.persistentTakes commands kept until the device is back online
otaTakes firmware updates
cfgTakes configuration through cfg.* shared attributes (needs cfg_hash)
claimCan be claimed with a claim window
csrAsks for a device certificate
store_forwardBuffers readings while offline and sends them later
gatewayReports 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 happenedWhat Hermetry does
JSON nested deeper than 8 levelsDrops it (invalid_payload)
Client attributes or hello that are not a JSON objectDrops 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 existDrops it (unknown_reserved_topic)
A topic the device may not publish toDrops it (forbidden_topic)
Three refused topics within a minuteCloses the session
A SUBSCRIBE to a topic the device may not readAnswers SUBACK 0x80
Messages over the profile’s rate limitsDrops 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:

StatusCode
400invalid_payload, hello_serial_mismatch
413payload_too_large, raw_too_large
429rate_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:

CodeMeaning
unsupported_methodThe receiver does not know the method
bad_paramsThe parameters are missing or wrong
busyThe receiver cannot run it now
timeoutThe operation timed out on the receiver
expiredThe request’s expirationTime has passed
forbiddenThe method is switched off by a local policy
payload_too_largeThe request is larger than the receiver takes
internalAnything 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:

MethodAnswer
getCurrentTime{"ok": true, "result": {"ts": <server time in ms>}}
getSessionLimitsThe effective per-device limits of the device’s profile

Rules for the device

  1. Ignore what you do not understand: malformed downlink messages, unknown shared attribute keys and unknown fields.
  2. Answer an unknown command with unsupported_method; treat an unknown error code as internal.
  3. Run a command id once. A command may arrive twice; see Sending commands to devices.
  4. Resend when there is no acknowledgement. With no PUBACK within 20 seconds, resend the message with the DUP flag; after three resends, reconnect.
  5. Retry a timed-out answer once. If an attribute request or a device request gets no answer, ask once more.
  6. 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.
  7. Stay below your limits. Ask for them with getSessionLimits after connecting and keep under 80 % of each. The defaults are in Limits and quotas.