Attributes – Hermetry

Attributes are named values that describe or configure a device, as opposed to telemetry, which is a time series of readings. A firmware version, a serial number, a reporting interval, a per-device alarm limit or a room number are attributes. Each attribute keeps only its current value and when it last changed.

The three scopes

Scope	Shown as	Written by	Seen by the device	Typical use
Client	Client	the device	its own	Firmware version, IP address, capabilities, the applied configuration
Shared	Shared	the cloud: people, the API, rules, flows, firmware updates	yes, pushed on change	Desired configuration (`cfg.`), firmware offers (`fw_`)
Server	Server	the cloud	never	Per-device limits for alarm rules, notes, asset numbers, data for dashboards

“Shared attributes are sent to the device.” “Server attributes stay on the platform.” “Client attributes are reported by the device and cannot be changed here.”

The Attributes tab

Open the device and its Attributes tab. Pick the scope (Server, Shared, Client) and use Search keys and values. Each row shows the Key, the Value, when it was Updated, and for configuration keys their sync status.

To add or change a value you need the permission Write server and shared device attributes (administrators by default):

Select Add attribute (or Edit on a row).
Enter the New key and the Value as JSON: a number (300), true or false, "text" in quotes, an array or an object.
Save. Delete removes a key after Delete key?

Values marked Write-only are secret configuration values: they can be set, never read back.

Key rules

Up to 128 characters from A–Z a–z 0–9 _ . -, case-sensitive.
deleted is never a key, and keys starting with _ are reserved for the platform.
People, the API and flows may not write keys the platform or the device owns: fw_* and current_fw_* (firmware), keys ending in .state or .reason, the device bookkeeping keys (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality) and session_limits.
cfg.* keys are shared attributes only.
Other shared keys are at most 57 characters, so the device’s <key>.reason answer still fits the 64-character device key limit.

Value rules

Item	Limit
Nesting depth	8 levels
A server or client value	64 KiB
A shared value	Must fit the device’s downlink limit (64 KiB by default, 4 KiB for licensed devices)
`null`	Not a value: delete the key instead

The device side

Send client attributes (only the keys sent change):

PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}

Ask for attributes, for example after every connect:

PUBLISH v1/attributes/req/7
{"clientKeys": "current_fw_version,lan.ip", "sharedKeys": "cfg.telemetry.interval_s"}

answer on v1/attributes/res/7
{"client": {...}, "shared": {...}}

An empty request {} returns all shared attributes. A key list entry ending in .* (for example cfg.*) asks for every key with that prefix.

Receive shared changes on v1/attributes/set. Only changed keys are sent. A removed key arrives as {"deleted": ["cfg.wifi.guest.enabled"]}. Apply updates idempotently: a message may arrive twice.

See MQTT topics and payload reference for every topic.

Configuration keys (`cfg.*`)

Shared attributes that start with cfg. are the desired configuration. The device applies them and reports the applied value as a client attribute with the same key. Hermetry compares the two and shows each key’s status:

Status	Meaning
In sync	The device reports the value you set.
Pending	You set a value; the device has not reported it yet.
Rejected	The device refused it. The row shows Reason: reason.
Drifted	The device reports another value than the one you set.
Unknown key	The key is not declared on the profile’s Configuration keys tab.

A key the device cannot apply is reported in the client attribute cfg_rejected:

{"cfg_rejected": {"cfg.wifi.radio0.channel": "out_of_range"}}

Reasons: unknown_key, bad_type, out_of_range, apply_failed, read_only, busy.

Declare the keys a device accepts, with type, label and limits, on the profile’s Configuration keys tab. See Device profiles. Licensed devices use remote device settings for their full configuration.

Where attributes are used

Per-device alarm limits. An alarm rule’s value attribute:maxTemp reads the device’s server attribute maxTemp (then its shared one). A device without the attribute is not checked for that limit. See Alarm conditions reference.
Dashboards. Attribute cards and tables show server and shared attributes. Client attributes are not offered there.
Flows. The enrich.device block adds a device’s attributes to a message; flows can also write attributes.
Gateway children. A shared attribute sent to a child point is applied by the gateway, which reports <key>.state and <key>.reason.

API

Call	Does	Permission
`GET /tenant/{tenantId}/api/iot/devices/{deviceId}/attributes?scope=server&keys=a,b`	Read attributes: `scope` is `client`, `shared` or `server` (all when left out), up to 100 keys	View device attributes
`POST …/attributes/server` or `…/attributes/shared`	Write up to 100 keys: `{"maxTemp": 80}`	Write server and shared device attributes
`DELETE …/attributes/server?keys=a,b`	Delete keys	Write server and shared device attributes

Client attributes cannot be written through the API (405). A write through the API always wins over the stored value, and is announced to your flows. See Telemetry and attributes API.

Audit and export

Every attribute save and delete is written to the audit log and the device’s Log tab with the keys, never the values. An organisation export includes attributes, with values that look secret masked.