Attributs – Hermetry

Les attributs sont des valeurs nommées qui décrivent ou configurent un appareil, par opposition à la télémétrie, qui est une série temporelle de mesures. Une version de firmware, un numéro de série, un intervalle de remontée, une limite d’alarme propre à l’appareil ou un numéro de salle sont des attributs. Chaque attribut ne conserve que sa valeur actuelle et la date de sa dernière modification.

Les trois portées

Portée	Affiché comme	Écrit par	Vu par l’appareil	Usage typique
Client	Client	l’appareil	le sien	Version du firmware, adresse IP, capacités, la configuration appliquée
Partagé	Partagé	le cloud : les utilisateurs, l’API, les règles, les flux, les mises à jour du firmware	oui, envoyé à chaque modification	Configuration souhaitée (`cfg.`), offres de firmware (`fw_`)
Serveur	Serveur	le cloud	jamais	Limites propres à chaque appareil pour les règles d’alarme, notes, numéros d’inventaire, données pour les tableaux de bord

« Les attributs partagés sont envoyés à l’appareil. » « Les attributs serveur restent sur la plateforme. » « Les attributs client sont remontés par l’appareil et ne peuvent pas être modifiés ici. »

L’onglet Attributs

Ouvrez l’appareil et son onglet Attributs. Choisissez la portée (Serveur, Partagé, Client) et utilisez Rechercher clés et valeurs. Chaque ligne affiche la Clé, la Valeur, la date de Mise à jour et, pour les clés de configuration, leur état de synchronisation.

Pour ajouter ou modifier une valeur, vous avez besoin de la permission Écrire les attributs serveur et partagés de l’appareil (administrateurs par défaut) :

Sélectionnez Ajouter un attribut (ou Modifier sur une ligne).
Saisissez la Nouvelle clé et la Valeur au format JSON : un nombre (300), true ou false, "texte" entre guillemets, un tableau ou un objet.
Enregistrez. Supprimer retire une clé après la question Supprimer clé ?

Les valeurs marquées Écriture seule sont des valeurs de configuration secrètes : elles peuvent être définies, mais jamais relues.

Règles de clés

Jusqu’à 128 caractères parmi A–Z a–z 0–9 _ . -, sensibles à la casse.
deleted n’est jamais une clé, et les clés commençant par _ sont réservées à la plateforme.
Les utilisateurs, l’API et les flux ne peuvent pas écrire les clés que la plateforme ou l’appareil gèrent : fw_* et current_fw_* (firmware), les clés se terminant par .state ou .reason, les clés de gestion de l’appareil (cfg_rejected, cfg_applied_ts, cfg_hash, attr_error, rpc_result, cert_not_after, time_quality) et session_limits.
Les clés cfg.* ne concernent que les attributs partagés.
Les autres clés partagées comptent au maximum 57 caractères, afin que la réponse <clé>.reason de l’appareil tienne dans la limite de 64 caractères des clés d’appareil.

Règles de valeurs

Élément	Limite
Profondeur d’imbrication	8 niveaux
Une valeur serveur ou client	64 Kio
Une valeur partagée	Doit tenir dans la limite de liaison descendante de l’appareil (64 Kio par défaut, 4 Kio pour les appareils sous licence)
`null`	Ce n’est pas une valeur : supprimez plutôt la clé

Côté appareil

Envoyer les attributs client (seules les clés envoyées changent) :

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

Demander les attributs, par exemple après chaque connexion :

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

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

Une requête vide {} renvoie tous les attributs partagés. Une entrée de liste de clés se terminant par .* (par exemple cfg.*) demande toutes les clés ayant ce préfixe.

Recevoir les modifications partagées sur v1/attributes/set. Seules les clés modifiées sont envoyées. Une clé supprimée arrive sous la forme {"deleted": ["cfg.wifi.guest.enabled"]}. Appliquez les mises à jour de façon idempotente : un message peut arriver deux fois.

Voir la référence des topics et charges utiles MQTT pour chaque topic.

Clés de configuration (`cfg.*`)

Les attributs partagés commençant par cfg. constituent la configuration souhaitée. L’appareil les applique et remonte la valeur appliquée sous forme d’attribut client portant la même clé. Hermetry compare les deux et affiche l’état de chaque clé :

État	Signification
Synchronisé	L’appareil remonte la valeur que vous avez définie.
En attente	Vous avez défini une valeur ; l’appareil ne l’a pas encore remontée.
Rejeté	L’appareil l’a refusée. La ligne affiche Motif : motif.
Dérivé	L’appareil remonte une autre valeur que celle que vous avez définie.
Clé inconnue	La clé n’est pas déclarée dans l’onglet Clés de configuration du profil.

Une clé que l’appareil ne peut pas appliquer est signalée dans l’attribut client cfg_rejected :

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

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

Déclarez les clés qu’un appareil accepte, avec leur type, leur libellé et leurs limites, dans l’onglet Clés de configuration du profil. Voir Profils d’appareils. Les appareils sous licence utilisent les paramètres distants de l’appareil pour leur configuration complète.

Utilisation des attributs

Limites d’alarme propres à l’appareil. La valeur attribute:maxTemp d’une règle d’alarme lit l’attribut serveur maxTemp de l’appareil (puis son attribut partagé). Un appareil sans cet attribut n’est pas contrôlé pour cette limite. Voir Référence des conditions d’alarme.
Tableaux de bord. Les cartes et tableaux d’attributs affichent les attributs serveur et partagés. Les attributs client n’y sont pas proposés.
Flux. Le bloc enrich.device ajoute les attributs d’un appareil à un message ; les flux peuvent aussi écrire des attributs.
Enfants de passerelle. Un attribut partagé envoyé à un point enfant est appliqué par la passerelle, qui remonte <clé>.state et <clé>.reason.

API

Appel	Action	Permission
`GET /tenant/{tenantId}/api/iot/devices/{deviceId}/attributes?scope=server&keys=a,b`	Lire les attributs : `scope` vaut `client`, `shared` ou `server` (tous si omis), jusqu’à 100 clés	Consulter les attributs de l’appareil
`POST …/attributes/server` ou `…/attributes/shared`	Écrire jusqu’à 100 clés : `{"maxTemp": 80}`	Écrire les attributs serveur et partagés de l’appareil
`DELETE …/attributes/server?keys=a,b`	Supprimer des clés	Écrire les attributs serveur et partagés de l’appareil

Les attributs client ne peuvent pas être écrits par l’API (405). Une écriture par l’API l’emporte toujours sur la valeur stockée et est signalée à vos flux. Voir API de télémétrie et d’attributs.

Audit et export

Chaque enregistrement et suppression d’attribut est inscrit dans le journal d’audit et dans l’onglet Journal de l’appareil, avec les clés, jamais les valeurs. Un export de l’organisation inclut les attributs, les valeurs qui ressemblent à des secrets étant masquées.