Los atributos son valores con nombre que describen o configuran un dispositivo, a diferencia de la telemetría, que es una serie temporal de lecturas. Una versión de firmware, un número de serie, un intervalo de envío de datos, un límite de alarma por dispositivo o un número de sala son atributos. Cada atributo solo conserva su valor actual y la fecha de su último cambio.
Los tres ámbitos
| Ámbito | Se muestra como | Lo escribe | Lo ve el dispositivo | Uso típico |
|---|---|---|---|---|
| Client | Client | el dispositivo | el propio | Versión de firmware, dirección IP, capacidades, la configuración aplicada |
| Shared | Shared | la nube: personas, la API, reglas, flujos, actualizaciones de firmware | sí, enviado al cambiar | Configuración deseada (cfg.*), ofertas de firmware (fw_*) |
| Server | Server | la nube | nunca | Límites por dispositivo para reglas de alarma, notas, números de activo, datos para paneles |
«Los atributos compartidos se envían al dispositivo.» «Los atributos de servidor permanecen en la plataforma.» «Los atributos de cliente los informa el dispositivo y no se pueden cambiar aquí.»
La pestaña Attributes
Abre el dispositivo y su pestaña Attributes. Elige el ámbito (Server, Shared, Client) y usa Search keys and values. Cada fila muestra la Key, el Value, la fecha de Updated y, en las claves de configuración, su estado de sincronización.
Para añadir o cambiar un valor necesitas el permiso Write server and shared device attributes (administradores por defecto):
- Selecciona Add attribute (o Edit en una fila).
- Introduce la New key y el Value en JSON: un número (
300),trueofalse,"text"entre comillas, un array o un objeto. - Guarda. Delete elimina una clave tras confirmar Delete key?
Los valores marcados como Write-only son valores de configuración secretos: se pueden establecer, pero nunca leer.
Reglas de claves
- Hasta 128 caracteres de
A–Z a–z 0–9 _ . -, distinguen mayúsculas y minúsculas. deletednunca es una clave, y las claves que empiezan por_están reservadas para la plataforma.- Las personas, la API y los flujos no pueden escribir claves que son propiedad de la plataforma o del dispositivo:
fw_*ycurrent_fw_*(firmware), claves que terminan en.stateo.reason, las claves de control del dispositivo (cfg_rejected,cfg_applied_ts,cfg_hash,attr_error,rpc_result,cert_not_after,time_quality) ysession_limits. - Las claves
cfg.*son solo atributos compartidos. - Las demás claves compartidas tienen como máximo 57 caracteres, para que la respuesta
<key>.reasondel dispositivo quepa en el límite de 64 caracteres de claves del dispositivo.
Reglas de valores
| Elemento | Límite |
|---|---|
| Profundidad de anidamiento | 8 niveles |
| Un valor de servidor o de cliente | 64 KiB |
| Un valor compartido | Debe caber en el límite de downlink del dispositivo (64 KiB por defecto, 4 KiB para dispositivos con licencia) |
null | No es un valor: elimina la clave en su lugar |
El lado del dispositivo
Enviar atributos de cliente (solo cambian las claves enviadas):
PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}Pedir atributos, por ejemplo después de cada conexión:
PUBLISH v1/attributes/req/7
{"clientKeys": "current_fw_version,lan.ip", "sharedKeys": "cfg.telemetry.interval_s"}
answer on v1/attributes/res/7
{"client": {...}, "shared": {...}}Una petición vacía {} devuelve todos los atributos compartidos. Una entrada de lista de claves que termina en .* (por ejemplo cfg.*) pide todas las claves con ese prefijo.
Recibir cambios compartidos en v1/attributes/set. Solo se envían las claves cambiadas. Una clave eliminada llega como {"deleted": ["cfg.wifi.guest.enabled"]}. Aplica las actualizaciones de forma idempotente: un mensaje puede llegar dos veces.
Consulta la referencia de temas y cargas MQTT para ver cada tema.
Claves de configuración (cfg.*)
Los atributos compartidos que empiezan por cfg. son la configuración deseada. El dispositivo las aplica y comunica el valor aplicado como atributo de cliente con la misma clave. Hermetry compara ambos y muestra el estado de cada clave:
| Estado | Significado |
|---|---|
| Sincronizado | El dispositivo informa del valor que estableciste. |
| Pendiente | Has establecido un valor; el dispositivo aún no lo ha informado. |
| Rechazado | El dispositivo lo ha rechazado. La fila muestra Reason: reason. |
| Desviado | El dispositivo informa de un valor distinto al que estableciste. |
| Clave desconocida | La clave no está declarada en la pestaña Configuration keys del perfil. |
Una clave que el dispositivo no puede aplicar se informa en el atributo de cliente cfg_rejected:
{"cfg_rejected": {"cfg.wifi.radio0.channel": "out_of_range"}}Motivos: unknown_key, bad_type, out_of_range, apply_failed, read_only, busy.
Declara las claves que acepta un dispositivo, con tipo, etiqueta y límites, en la pestaña Configuration keys del perfil. Consulta Device profiles. Los dispositivos con licencia usan la configuración remota del dispositivo para su configuración completa.
Dónde se usan los atributos
- Límites de alarma por dispositivo. El valor de una regla de alarma
attribute:maxTemplee el atributo de servidormaxTempdel dispositivo (y después el compartido). Un dispositivo sin el atributo no se comprueba para ese límite. Consulta Alarm conditions reference. - Paneles. Las tarjetas y tablas de atributos muestran atributos de servidor y compartidos. Los atributos de cliente no se ofrecen allí.
- Flujos. El bloque enrich.device añade los atributos de un dispositivo a un mensaje; los flujos también pueden escribir atributos.
- Hijos de gateway. Un atributo compartido enviado a un punto hijo lo aplica el gateway, que informa de
<key>.statey<key>.reason.
API
| Llamada | Hace | Permiso |
|---|---|---|
GET /tenant/{tenantId}/api/iot/devices/{deviceId}/attributes?scope=server&keys=a,b | Lee atributos: scope es client, shared o server (todos si se omite), hasta 100 claves | Ver atributos del dispositivo |
POST …/attributes/server o …/attributes/shared | Escribe hasta 100 claves: {"maxTemp": 80} | Escribir atributos de servidor y compartidos del dispositivo |
DELETE …/attributes/server?keys=a,b | Eliminar claves | Escribir atributos de servidor y compartidos del dispositivo |
Los atributos de cliente no se pueden escribir mediante la API (405). Una escritura por la API siempre prevalece sobre el valor almacenado y se notifica a tus flujos. Consulta Telemetry and attributes API.
Auditoría y exportación
Cada guardado y eliminación de atributos se registra en el registro de auditoría y en la pestaña Log del dispositivo, con las claves y nunca los valores. Una exportación de la organización incluye los atributos, con los valores que parecen secretos enmascarados.