Cette page s’adresse aux administrateurs et intégrateurs qui modifient les réglages des appareils depuis Hermetry, manuellement ou via l’API, sur un appareil ou sur plusieurs. Elle explique les règles qui régissent l’onglet Settings et comment les utiliser en toute sécurité. Comment ouvrir l’onglet, créer des baselines et lancer des jobs est expliqué dans Remote device settings ; les routes figurent dans Firmware and device settings API.
Valeurs souhaitées et valeurs remontées
Pour chaque section de réglages d’un appareil, Hermetry conserve deux documents :
- Desired : ce que Hermetry a demandé en dernier à l’appareil d’exécuter, avec un numéro de révision qui augmente à chaque modification.
- Reported : ce que l’appareil indique exécuter, avec la révision qu’il a appliquée.
Chaque modification envoie la section entière à l’appareil, et non seulement les clés modifiées. L’appareil n’applique une section que si sa révision est supérieure à la dernière qu’il a appliquée. Une section restée trop longtemps en attente de l’appareil est retirée ; l’appareil conserve alors les réglages qu’il possède.
| États dans l’onglet Settings | Signification |
|---|---|
| En attente | Envoyée, ou en attente que l’appareil se connecte |
| L’appareil l’essaie | L’appareil exécute la modification à titre d’essai et l’annule automatiquement s’il ne peut plus joindre le cloud |
| Appliquée | L’appareil exécute la modification |
| Annulée par l’appareil | L’appareil l’a essayée puis est revenu en arrière |
| Refusée par l’appareil | L’appareil ne l’a pas acceptée |
| Appareil hors ligne | La modification a attendu trop longtemps (7 jours pour une modification unique) et a été retirée |
| À vérifier après mise à jour | Une mise à jour du firmware a modifié la description de la section ; une personne doit la relire et enregistrer |
| Modifiée sur l’appareil | Dérive : l’appareil exécute d’autres valeurs que celles demandées par Hermetry (voir ci-dessous) |
| Non modifiable depuis ici | Hermetry n’a jamais défini cette section ; elle affiche seulement ce que l’appareil indique |
Construction d’une modification
Il existe deux façons d’écrire une section, qui traitent différemment ce que l’on omet.
| Méthode | Utilisée par | Ce que vous envoyez |
|---|---|---|
| Section complète | L’onglet Settings, PUT | Toutes les valeurs de la section. Ce qui est omis ne fait pas partie de la nouvelle section. |
| Merge patch | PATCH, baselines, jobs de réglages | Uniquement ce qui change, sous forme de JSON merge patch (RFC 7386) |
Un merge patch suit exactement ces règles :
- Les objets fusionnent clé par clé. Une clé non nommée conserve sa valeur.
nullsupprime la clé.- Toute autre valeur remplace entièrement l’ancienne. Une liste est toujours remplacée entièrement : pour modifier une entrée d’une liste, envoyez la liste complète.
Le patch est appliqué au dernier document desired de la section, et non à ce que l’appareil remonte. Ce n’est que lorsque Hermetry n’a jamais défini la section qu’un patch part des valeurs remontées ; si l’appareil n’a pas encore remonté la section non plus, l’écriture est refusée (section_not_reported).
Bonnes pratiques :
- Ne placez dans une baseline que ce que vous voulez modifier. Tout le reste reste tel quel sur chaque appareil.
- Ne mettez jamais de
nulldans une baseline, sauf si la clé doit disparaître de chaque appareil du job. - Gardez hors des baselines les listes propres à chaque appareil (par exemple des listes d’adresses différentes selon le site) : la liste de la baseline remplace celle de chaque appareil.
- Les réglages que la description marque comme modifiables uniquement sur l’appareil sont conservés à partir du rapport de l’appareil. Une modification de ceux-ci est refusée (
remote_forbidden). - Utilisez
?dryRun=true(ou Check dans un job) pour voir quels réglages une modification touche et si elle nécessite une confirmation, avant tout envoi.
Révisions et If-Match
La lecture d’une section renvoie sa révision desired dans l’en-tête ETag, sous la forme W/"7". Chaque écriture doit renvoyer cette révision dans If-Match ; "7" et 7 sont également acceptés.
| Réponse | Signification |
|---|---|
428 if_match_required | L’écriture n’avait pas de If-Match |
412 rev_mismatch | Quelqu’un a modifié la section après votre lecture |
En cas de 412, relisez la section, reconstruisez votre modification sur le nouveau document et écrivez à nouveau. Ne recopiez pas la nouvelle révision dans l’en-tête pour renvoyer l’ancien document : cela écraserait la modification de l’autre personne. L’onglet Settings effectue la même vérification (« Quelqu’un d’autre a modifié ces réglages depuis leur ouverture. Rechargez-les pour voir la dernière version. »).
Dérive
Une section présente une dérive lorsque l’appareil a appliqué une modification de Hermetry puis remonte ensuite des valeurs différentes, généralement parce que quelqu’un l’a modifiée directement sur l’appareil. L’onglet affiche « Modifiée sur l’appareil » et les différences. Hermetry ne corrige pas la dérive de lui-même. Vous choisissez :
| Action | Effet |
|---|---|
| Renvoyer les nôtres | Renvoie les valeurs desired de Hermetry sous une nouvelle révision |
| Garder celles de l’appareil | Enregistre les valeurs actuelles de l’appareil comme nouvelles valeurs desired |
Résolvez la dérive avant de modifier autrement une section en dérive. Un merge patch, donc un job de réglages, part du dernier document desired ; il renvoie donc aussi les valeurs de Hermetry pour les réglages en dérive.
Définissez qui est responsable de chaque réglage. Si des techniciens sur site doivent pouvoir modifier quelque chose, gardez-le hors des baselines et des jobs.
Secrets
- Les réglages secrets (mots de passe, clés) ne sont jamais affichés ni renvoyés. Ils apparaissent sous la forme
{ "set": true }. - Un nouveau secret parvient à l’appareil sous forme de référence à usage unique. L’appareil récupère la valeur une seule fois par une requête signée ; une référence non récupérée expire au bout de 30 jours. Un appareil dont le firmware ne peut pas récupérer les références ne reçoit aucun secret : la modification est refusée (
secret_ref_unsupported). - Pour conserver le secret actuel de l’appareil, laissez le champ inchangé (dans l’API,
{ "$keep": true }). - Les baselines ne peuvent pas contenir de secrets (
secret_not_allowed). Définissez-les sur chaque appareil. secret_pending: une modification antérieure contient un secret que l’appareil n’a pas encore récupéré. Attendez, ou saisissez à nouveau le secret.secrets_need_rewritelors de Renvoyer : la modification contient des secrets que l’appareil ne peut plus récupérer. Saisissez-les à nouveau et enregistrez.
Jobs de réglages
Un job applique une baseline, ou une seule modification, à de nombreux appareils par vagues. Bonnes pratiques :
- Sélectionnez par modèle et firmware que vous avez testés. L’étape Check affiche les appareils par modèle et firmware, ainsi que les sections qu’un modèle ne possède pas.
- Respectez les vagues. Par défaut : 1 %, puis 10 %, puis le reste. La première vague est un échantillon aléatoire fixe des appareils sélectionnés.
- Comprenez le seuil. Une vague réussit lorsque, parmi les appareils ayant répondu, au moins 95 % ont appliqué la modification et au plus 1 % l’ont annulée (valeurs par défaut). Les appareils ayant refusé comptent parmi ceux ayant répondu, donc ils font baisser la part des appliquées. Les appareils encore hors ligne ne comptent pas. Une vague est jugée lorsque tous ses appareils ont répondu, ou 30 minutes après son début (par défaut) sur les appareils ayant répondu d’ici là ; les autres continuent en arrière-plan. Une vague réussie lance immédiatement la suivante, sans délai d’attente. Une vague où aucun appareil n’a répondu met le job en pause.
- Choisissez la conduite à tenir en cas de conflit. Une seule modification à la fois peut être en cours sur la section d’un appareil. Un job attend la modification d’un autre job (et passe l’appareil après 24 heures) ou le passe immédiatement. Une modification faite par une personne pendant l’attente du job prévaut.
- Définissez la durée d’attente des appareils hors ligne : 7 jours par défaut, de 1 à 90.
- Rappelez-vous que l’annulation ne revient pas en arrière. Les appareils déjà modifiés conservent leurs nouveaux réglages.
Un job écrit avec les droits de son créateur, et un job qui modifie des réglages sensibles doit être confirmé lors de sa création. Au plus 5 jobs s’exécutent ou attendent en pause à la fois, un job contient jusqu’à 5 000 appareils, et il envoie les modifications à 200 appareils au maximum par minute.
Mises à jour du firmware et anciens firmwares
- Après une mise à jour du firmware, Hermetry convertit les valeurs souhaitées enregistrées vers la description des réglages du nouveau firmware. Ce qu’il ne peut pas convertir en toute sécurité est marqué « Check after update ». La section reste dans cet état tant qu’une personne ne l’a pas enregistrée ; les rapports de l’appareil ne la ferment pas, et une tâche considère un tel appareil comme refusé.
- Fenêtre de support : les écritures de réglages s’arrêtent 24 mois après la date de publication du firmware de l’appareil, telle qu’indiquée dans sa description des réglages. Les réglages restent lisibles (« Read only: update the firmware to change settings »). Une écriture répond
409firmware_too_oldavec la date de fin de la fenêtre. - Une tâche n’exclut pas ces appareils à l’avance. Ils sont refusés lorsque leur tour arrive et comptent dans le seuil de la vague. Mettez d’abord leur firmware à jour, ou excluez-les de la sélection.
Fréquence des modifications
Les modifications unitaires depuis l’onglet Settings et l’API, Send again inclus, sont limitées à 600 par minute et par organisation ; au-delà, 429 write_rate_limited. Les écritures d’une tâche sur ses propres appareils ne comptent pas dans cette limite.

