Reserved keys and attributes

Some telemetry keys and attributes have a fixed meaning in Hermetry. Some may not be written by you at all; others are written by the platform or the device and read by features such as firmware updates, site status or cameras. This page lists them, so that you can avoid clashes and use the ones you need.

Rules at a glance

Rule	Telemetry	Attributes
Characters	A–Z a–z 0–9 _ . -	Same
Length	1 to 64	1 to 128 (shared keys other than cfg.*: 57)
Never a key		deleted
Reserved prefix	_, fw_, current_fw_, cfg.	_ (platform); fw_, current_fw_ (firmware)
Case	Case-sensitive	Case-sensitive

A telemetry key with a reserved prefix is dropped with key_reserved; the rest of the message is stored. An attribute write with a reserved key is refused with keys_invalid and the key’s reason reserved. See Telemetry keys and Attributes.

Keys you may never write

People, the API and flows may not write these as server or shared attributes:

Key or pattern	Owner	Purpose
_*	The platform	Internal keys
fw_*	Firmware updates	The update offered to the device (shared) and the device’s progress (client)
current_fw_*	The device	What the device runs
*.state, *.reason	The device or gateway	The result of a desired value: a gateway answers <key>.state and <key>.reason for a shared attribute it applied to a child
cfg_rejected, cfg_applied_ts, cfg_hash	The device	Its configuration bookkeeping
attr_error	The device	An attribute it could not apply
rpc_result	The device	The result of a long-running command
cert_not_after	The device	When its certificate expires
time_quality	The device or gateway	Whether time stamps come from a synchronised clock
session_limits	The platform	The device’s effective rate limits, computed when they are sent and never stored
deleted		The marker of removed keys on the wire

Firmware keys

Written by Hermetry as shared attributes when an update is offered:

Key	Content
fw_title, fw_version	The package’s name and version
fw_size	Size in bytes
fw_checksum, fw_checksum_algorithm	Lower-case hex and SHA256
fw_url	A short-lived HTTPS download address, valid 15 minutes
fw_sig	The detached signature, when there is one
fw_allow_metered	Whether the device may download over a metered link

Reported by the device as client attributes:

Key	Content
fw_state	DOWNLOADING, DOWNLOADED, VERIFIED, UPDATING, UPDATED, FAILED
fw_error	An error code, with FAILED
fw_progress	0 to 100 while downloading
fw_wait	metered, quota_exhausted or approval while the device holds the update
current_fw_title, current_fw_version	What runs now; sent after every connect

See Firmware updates (OTA).

Configuration keys

Key	Scope	Meaning
cfg.*	Shared only	Desired configuration, up to 128 characters per key. The device reports back what it applied. On a licensed device whose settings are managed on its Settings tab, a write answers 409: change it there.
cfg_rejected, cfg_applied_ts, cfg_hash	Client	The device’s answer about its configuration

See Remote device settings.

Telemetry keys with a meaning

Key	Read by	Meaning
status	Site status, site views, 3D tints	critical, alarm, error, fault, danger, 2, true mean Critical; warning, warn, 1 mean Warning; anything else OK. A card can read another key instead. See Site status and the status key.
raw	Decoders, flows	A body that is not a JSON object, stored as text (4,096 bytes by default). See Telemetry keys.
<topic>.<key>		Keys of a custom topic when the profile prefixes keys with the topic
lat, lng	Map cards of the ready solutions	Position. Other boards can use any column names.
<element>.<field>	Process drawings	Readings of a drawn element, for example p1.running, pt.value

Attributes written by modules

Key	Scope	Written by	Meaning
liveUrl	Server	Cameras	The camera’s live link while live view is on
liveUrlHigh	Server	Cameras	The higher-quality link, when the camera has a second usable H.264 stream
esim.capability, esim.profiles	Client	Licensed routers	The router’s eSIM chip and profiles. eSIM management is in development.

See Cameras on dashboards.

Command method families

Some command methods belong to a module and only that module may send them: for example tunnel.* (remote access) and esim.*. A request for them answers 403 rpc_method_reserved. Factory reset, pairing, Wi-Fi forget and cloud.forget are never sent from the cloud. See Sending commands to devices.

Names used by the ready solutions

The ready solutions read these keys and server attributes. They are not reserved; use them to make your devices fit a solution.

Solution	Telemetry keys	Server attributes
Water site	level_cm, level_pct, rssi; p1.running, p2.running, pt.value, fm.value, *.status, manual, p1_run, p2_run, phase1–phase3, thermal1, thermal2, consumption	lowLevelThreshold, highLevelThreshold, capacityCm, minPressure
Remote sites	air_temp, air_hum, door_open, water_leak, smoke, battery_env, battery_water, battery_door, battery_smoke; ups_a_*, ups_b_*	highTempThreshold, lowTempThreshold, highHumThreshold, lowHumThreshold
Weather stations	air_temp, air_hum, baro_pressure, rain_intensity, acc_rainfall, wind_speed_avg, wind_speed_min, wind_speed_max, wind_dir_avg, wind_dir_min, wind_dir_max, rain_reset
Sensor regions	air_temp, air_hum, battery, plan_x, plan_y; station: acc_rainfall, pressure, light, wind_dir, wind_speed	maxTempThreshold, minTempThreshold, warnTempThreshold, maxHumThreshold, minHumThreshold, warnHumThreshold; region asset: floorPlan
Personnel tracking	lat, lng, zone, event, battery, air_temp, light	forbiddenZone; zone asset: beacon

See Ready solutions.

Other reserved names

Name	Where
provision	An MQTT username reserved for provisioning sessions
Topics under v1/	Only the documented topics; an unknown one is rejected as unknown_reserved_topic
Organisation addresses such as admin	Reserved names cannot be an organisation’s address. See Create your account and choose a region.
Display names such as admin, support, owner	Reserved for people’s display names; an organisation can reserve more. See Your profile, language and time zone.

Related

• MQTT topics and payload reference
• Telemetry and attributes API
• Glossary