Intégration Z2M Devices Monitor pour Gladys Assistant

Vous alerte quand un appareil Zigbee2MQTT ne donne plus signe de vie.

• Publiée par prohand
• Appareils
• Version 1.0.3
• Nécessite Gladys >=4.85.0
• ★ 0

Voir sur GitHubToutes les intégrations externes

Cette intégration surveille vos appareils Zigbee2MQTT et vous alerte quand l'un d'eux ne donne plus signe de vie.

Pourquoi ne pas se fier à la batterie

Le pourcentage de batterie remonté par un appareil Zigbee est une estimation grossière, rarement rafraîchie et souvent fausse : une pile CR2032 affiche couramment 100 % jusqu'au jour où le capteur cesse de répondre. Et surtout, la batterie ne dit rien des autres façons de mourir : un appareil débranché, sorti du réseau, qui a perdu sa route ou dont le routeur parent est tombé.

Un appareil Zigbee vivant parle. Les capteurs envoient leurs mesures, les routeurs répondent, tout se manifeste au moins périodiquement. Le seul fait vraiment fiable est donc : quand ai-je entendu cet appareil pour la dernière fois ? — et la seule question utile : se tait-il depuis plus longtemps qu'il ne le devrait ?

C'est exactement ce que fait cette intégration.

Ce qu'elle fait

Elle s'abonne à tout ce que publie Zigbee2MQTT sur votre broker MQTT (zigbee2mqtt/#), mémorise la date du dernier message de chaque appareil, et réévalue en continu leur silence.

Elle ne publie jamais rien sur votre réseau Zigbee : elle se contente d'écouter. Elle sait aussi faire la différence entre :

• un message publié par l'appareil → preuve qu'il est vivant ;
• un message rejoué par le broker (drapeau retained, à chaque reconnexion) → il peut dater de plusieurs jours, il ne prouve rien ;
• une commande set/get envoyée vers l'appareil par Gladys, Home Assistant ou une scène → ce n'est pas l'appareil qui parle. Sans cette distinction, un capteur mort paraîtrait vivant tant que quelque chose continue de lui parler.

Si vous avez activé l'option advanced.last_seen dans Zigbee2MQTT, l'intégration utilise l'horodatage que l'appareil joint à ses rapports : c'est la source la plus fiable, et elle rend même les messages retained exploitables. Ce n'est pas obligatoire.

Installation

1. Pré-requis

• Zigbee2MQTT en fonctionnement, publiant sur un broker MQTT ;
• ce broker doit être joignable depuis Gladys (même réseau local).

2. Configuration

Champ	À renseigner
URL du broker	L'adresse de votre broker MQTT, par exemple mqtt://192.168.1.10:1883. Les schémas mqtts://, ws:// et wss:// sont acceptés.
Nom d'utilisateur / Mot de passe	À laisser vides si votre broker accepte les connexions anonymes.
Topic de base	Le mqtt.base_topic configuré dans Zigbee2MQTT. zigbee2mqtt dans la quasi-totalité des cas.

Cliquez ensuite sur Tester la connexion MQTT : le bouton indique s'il est connecté, combien d'appareils il voit et combien de messages il a reçus. C'est le moyen le plus rapide de repérer l'erreur classique — bon broker, mauvais topic de base, et rien ne se passe.

Où trouver ces trois valeurs

Ces valeurs doivent être saisies à la main : l'intégration ne peut pas les récupérer toute seule dans Gladys. Une intégration externe tourne dans son propre conteneur et ne reçoit de Gladys que sa propre configuration ; l'API que Gladys lui expose ne donne accès ni aux réglages ni aux variables des autres intégrations. C'est une limite volontaire du bac à sable, pas un oubli : sans elle, n'importe quelle intégration du store pourrait lire les identifiants de vos autres services.

Le copier-coller reste court :

• si c'est Gladys qui a installé Zigbee2MQTT (mode « Installation depuis Gladys »), le broker est le conteneur Mosquitto que Gladys gère. Allez dans l'intégration Zigbee2MQTT → onglet Configuration, bloc « Connexion pour outils externes » : Gladys y affiche l'URL, le nom d'utilisateur et le mot de passe, avec un bouton de copie. Le mot de passe est engendré aléatoirement à la première activation, il n'y a pas de valeur « par défaut » à deviner. Ce broker écoute sur le port 1884, et l'URL affichée pointe sur localhost : remplacez localhost par l'adresse IP de votre machine Gladys, sinon localhost désignerait le conteneur de cette intégration elle-même. Le topic de base est zigbee2mqtt ;
• si vous avez votre propre broker (Zigbee2MQTT autonome, Mosquitto, Home Assistant…), reprenez simplement l'URL et les identifiants que Zigbee2MQTT utilise, c'est-à-dire le bloc mqtt: de son configuration.yaml.

3. Ajouter les appareils

Allez dans Appareils → Découvrir, puis créez les appareils que vous voulez surveiller. Vous en trouverez :

• un appareil par appareil Zigbee connu de Zigbee2MQTT ;
• un appareil Zigbee2MQTT monitor, qui résume tout le réseau.

Les appareils surveillés portent le nom Zigbee2MQTT suivi d'un suffixe, (monitor) par défaut : prise bureau (monitor). Sans lui, ils seraient impossibles à distinguer des appareils que l'intégration Zigbee2MQTT de Gladys remonte déjà sous le même nom — un sélecteur de scène afficherait deux fois « prise bureau ». Le suffixe se change (ou se vide) dans Nommage des appareils. Il ne s'applique qu'aux appareils créés ensuite : Gladys ne renomme jamais un appareil déjà ajouté, à vous de le renommer sur sa fiche.

Et quand le réseau Zigbee change ?

L'intégration relit l'inventaire de Zigbee2MQTT en continu, donc la liste de l'écran Découvrir se met à jour toute seule :

• un appareil que vous venez d'appairer apparaît dans la liste en quelques secondes, sans redémarrage ni action de votre part. En revanche, sa création dans Gladys reste manuelle : c'est vous qui décidez ce qui entre dans votre installation. C'est aussi pourquoi la scène à bâtir est celle de l'appareil Zigbee2MQTT monitor — ses compteurs comptent tous les appareils vus par Zigbee2MQTT, y compris ceux que vous n'avez pas créés dans Gladys, donc un nouvel appareil est couvert par l'alerte dès son appairage ;
• un appareil retiré de Zigbee2MQTT disparaît de l'écran Découvrir et cesse d'être compté et d'émettre des valeurs. S'il avait déjà été créé dans Gladys, sa fiche n'est pas supprimée automatiquement : elle reste, figée sur sa dernière valeur. Une intégration n'a pas le droit de supprimer vos appareils — supprimez-la depuis Appareils quand vous le souhaitez.

Les seuils de silence

Un appareil est déclaré mort dès qu'il se tait depuis plus longtemps que son seuil. Deux valeurs par défaut :

• appareils sur secteur (prises, ampoules, routeurs) : 120 minutes, ils parlent souvent ;
• appareils sur pile (capteurs) : 1440 minutes, soit 24 heures — ils dorment la plupart du temps.

Vous pouvez affiner appareil par appareil dans le champ Seuils par appareil, une paire appareil=minutes par ligne ou séparées par des virgules :

capteur boite aux lettres=4320
mouvement garage=180
0x00158d0001abcdef=60

L'appareil se désigne par son nom convivial Zigbee2MQTT ou par son adresse IEEE.

Commencez large. Un seuil trop serré produit des fausses alertes, et une alerte à laquelle on cesse de croire ne sert plus à rien. Laissez tourner quelques jours, regardez la valeur « Silence » de chaque appareil sur sa fiche (Gladys l'affiche sous le libellé Durée (entier)), puis resserrez.

Ce que chaque appareil expose

Chaque appareil surveillé expose 2 fonctionnalités :

Fonctionnalité	Nom affiché par Gladys	Description
Alive	Etat de l'entrée	On = l'appareil donne signe de vie, Off = il se tait depuis plus que son seuil. C'est la fonctionnalité sur laquelle bâtir une alerte. Son historique est conservé.
Silence	Durée (entier)	Depuis combien de minutes l'appareil n'a rien dit. Utile pour calibrer les seuils.

Si vous avez ajouté vos appareils avec la version 1.0.1 ou antérieure, leur fonctionnalité Alive était publiée dans une autre catégorie, que les écrans de Gladys dessinent sous la forme d'une étiquette vide — l'appareil semble ne porter que Silence. L'écran de découverte propose un bouton Mettre à jour sur ces appareils : cliquez-le et la fonctionnalité réapparaît, historique compris.

L'appareil Zigbee2MQTT monitor expose de son côté 5 fonctionnalités :

Fonctionnalité	Nom affiché par Gladys	Description
Silent devices	Silent devices	Le nombre d'appareils actuellement silencieux. C'est le déclencheur de la scène d'alerte.
Silent device names	Texte	Leurs noms, pour les citer dans une notification. Affiche « No silent device » tant que tout le réseau répond (texte modifiable, voir ci-dessous).
Devices alive	Devices alive	Le nombre d'appareils qui répondent.
Devices monitored	Devices monitored	Le nombre d'appareils surveillés.
Zigbee2MQTT bridge online	Etat de l'entrée	L'état du bridge Zigbee2MQTT lui-même.

Pourquoi certains noms changent à l'affichage

Gladys ne montre pas toujours le nom donné par l'intégration. Quand une fonctionnalité est la seule de son type sur son appareil, l'interface affiche à la place le libellé standard de sa catégorie — d'où Texte pour « Silent device names », Etat de l'entrée pour « Alive » et « Zigbee2MQTT bridge online », ou Compteur entier sur l'écran de modification. Les trois compteurs du moniteur partagent le même type, donc ils gardent leur nom.

C'est un comportement de Gladys, pas un réglage de cette intégration. Deux conséquences pratiques :

• dans un sélecteur de scène, repérez la fonctionnalité par ce nom affiché (« Zigbee2MQTT monitor (Texte) » = les noms des appareils silencieux) ;
• vous pouvez renommer une fonctionnalité depuis la fiche de l'appareil si le libellé standard ne vous parle pas.

Le texte affiché quand tout va bien

« Silent device names » est un texte, et il passe l'essentiel de sa vie à ne citer personne — c'est bon signe. Il affiche alors une phrase explicite plutôt qu'un tiret : No silent device par défaut. Le champ Texte affiché quand aucun appareil n'est silencieux (section Appareil Zigbee2MQTT monitor) permet de le traduire, par exemple « Aucun appareil silencieux ». Videz le champ pour revenir à la valeur par défaut : ce texte ne peut jamais être vide, Gladys n'enregistre pas un état texte vide.

Et l'intensité du signal ?

Elle n'est pas publiée par cette intégration : l'intégration Zigbee2MQTT de Gladys remonte déjà le LQI de chaque appareil, et un deuxième exemplaire de la même valeur ne ferait qu'encombrer les listes d'appareils et les sélecteurs de scène.

Être alerté : créer la scène

L'intégration lève le drapeau, Gladys envoie l'alerte. La scène la plus utile est celle bâtie sur l'appareil Zigbee2MQTT monitor : elle couvre tout le réseau, y compris les appareils que vous appairerez dans six mois.

1. Scènes → Nouvelle scène ;

2. déclencheur : La valeur d'un appareil change → appareil Zigbee2MQTT monitor, fonctionnalité Silent devices, condition supérieur à 0 ;

3. première action : Récupérer le dernier état → dans Sélectionnez un appareil, choisissez Zigbee2MQTT monitor (Texte), c'est-à-dire la fonctionnalité Silent device names.

   C'est l'étape qu'on oublie : dans Gladys, un message ne peut insérer que les valeurs récupérées par une action placée avant lui. Sans ce bloc, le sélecteur de variables du message est vide et l'alerte ne pourra pas nommer les capteurs concernés ;

4. seconde action : Envoyer un message (notification mobile, Telegram…) avec un texte du type :

   Appareil(s) Zigbee sans signe de vie : Dernière valeur de l'appareil

   Pour insérer cette variable, tapez {{ à l'endroit voulu dans le message : Gladys propose alors la valeur récupérée à l'étape 3, affichée « 1.1. Dernière valeur de l'appareil » (le numéro est la position de l'action Récupérer le dernier état dans la scène). Passez toujours par ce sélecteur plutôt que de taper la variable à la main : le message nommera les capteurs concernés au lieu de dire simplement que quelque chose ne va pas.

Pour un capteur critique en particulier (détecteur de fumée, alarme, congélateur), créez en plus une scène dédiée sur sa fonctionnalité Alive passant à Off (dans le sélecteur : nom de l'appareil (Etat de l'entrée)).

Astuce : ajoutez une condition d'horaire à la scène si vous ne voulez pas être réveillé la nuit — un capteur muet peut presque toujours attendre le matin.

Les boutons de l'écran de configuration

• Tester la connexion MQTT — état réel de la connexion, nombre d'appareils surveillés, nombre de messages reçus, et la raison précise en cas d'échec.
• Lister les appareils silencieux — qui se tait, et depuis combien de temps.
• Rafraîchir la liste des appareils — republie la liste vers Gladys, après un appairage ou un renommage dans Zigbee2MQTT.

Bon à savoir

• Les appareils sont identifiés par leur adresse IEEE, pas par leur nom. Renommer un appareil dans Zigbee2MQTT met à jour son nom dans Gladys sans perdre son historique.
• Les appareils désactivés dans Zigbee2MQTT ne sont pas surveillés par défaut : ils sont censés se taire. Une option permet de les inclure.
• Le coordinateur (la clé USB) n'est pas surveillé : ce n'est pas un appareil qui peut tomber de son côté. Utilisez la fonctionnalité Zigbee2MQTT bridge online pour cela.
• L'historique du dernier signe de vie est persisté dans le volume /data de l'intégration. Un redémarrage du conteneur ne remet donc pas tous vos appareils à zéro — sans quoi un capteur mort depuis un mois repartirait pour un seuil complet sans jamais déclencher l'alerte.
• Si vous mettez à jour depuis une version qui publiait l'intensité du signal, les appareils déjà créés dans Gladys conservent cette fonctionnalité : une intégration ne peut pas retirer une fonctionnalité d'un appareil que vous avez créé. Elle ne reçoit plus de valeur et reste figée sur la dernière. Pour la faire disparaître, supprimez l'appareil dans Gladys et recréez-le depuis Découvrir (son historique est alors perdu) ; sinon, ignorez-la.
• Un appareil jamais entendu dispose d'un seuil complet à partir du démarrage du moniteur avant d'être signalé. Une intégration fraîchement installée ne déclare donc pas tout le réseau mort à la première minute.

En cas de problème

Le bouton de test dit qu'il n'est pas connecté. Vérifiez l'URL (avec le port, 1883 par défaut), les identifiants, et que le broker autorise les connexions depuis l'adresse de Gladys.

Il est connecté, mais ne voit aucun appareil. Le topic de base ne correspond probablement pas à celui de Zigbee2MQTT. Comparez-le avec mqtt.base_topic dans votre configuration.yaml.

Un appareil est signalé silencieux alors qu'il fonctionne. Son seuil est trop serré : regardez sa fonctionnalité Silence (Durée (entier)) pour connaître son rythme réel, et donnez-lui un seuil sur mesure. Les capteurs de porte, de fuite ou les boutons sont typiquement muets pendant des jours s'il ne se passe rien.

Tous les appareils passent silencieux en même temps. Regardez d'abord Zigbee2MQTT bridge online : c'est probablement Zigbee2MQTT lui-même, le broker ou le coordinateur qui est tombé, pas vos capteurs.

Un appareil que je viens d'ajouter affiche « Pas de valeur récente ». Une fonctionnalité ne reçoit de valeur qu'une fois l'appareil créé dans Gladys : tout ce qui a été publié avant que vous cliquiez sur Ajouter n'est allé nulle part. L'intégration republie donc les états d'un appareil dès que Gladys lui signale sa création, et la valeur arrive en quelques secondes. Si le bandeau est toujours là, rechargez la page : le tableau de bord calcule ce bandeau au chargement de ses données et ne l'efface pas sur les mises à jour temps réel qui suivent.

Paramètres de configuration

Voici les paramètres demandés par Z2M Devices Monitor dans son écran de configuration dans Gladys.

Paramètre	Type	Obligatoire	Description
Comment ça marche	section	Non	Un appareil Zigbee vivant parle. Cette intégration écoute tout ce que publie Zigbee2MQTT, mémorise la dernière fois que chaque appareil s'est manifesté, et signale ceux qui se taisent depuis trop longtemps. Elle n'utilise jamais le niveau de batterie : un pourcentage de batterie Zigbee est une estimation grossière, souvent à 100% jusqu'au jour où le capteur cesse de répondre.
Broker MQTT	section	Non	Le même broker que celui utilisé par Zigbee2MQTT. L'intégration ne fait que s'abonner : elle ne publie jamais rien sur votre réseau Zigbee. Ces valeurs doivent être saisies ici : une intégration tourne dans son propre bac à sable et Gladys ne lui communique jamais les réglages d'une autre intégration. Si c'est Gladys qui a installé Zigbee2MQTT, recopiez-les depuis l'intégration Zigbee2MQTT, onglet Configuration, bloc « Connexion pour outils externes » — en remplaçant localhost dans l'URL par l'adresse IP de votre machine Gladys.
URL du broker	string	Oui	Adresse du broker MQTT, par exemple mqtt://192.168.1.10:1883 (mqtts:// et ws:// sont aussi acceptés).
Nom d'utilisateur	string	Non	Laissez vide si votre broker accepte les connexions anonymes.
Mot de passe	secret	Non
Topic de base	string	Oui	Le topic de base configuré dans Zigbee2MQTT (mqtt.base_topic).
Seuils de silence	section	Non	Un appareil est déclaré mort dès qu'il se tait depuis plus longtemps que son seuil. Les capteurs sur pile parlent bien moins souvent que les appareils sur secteur, d'où deux valeurs par défaut distinctes. Commencez large : mieux vaut être alerté quelques heures trop tard que réveillé par une fausse alerte.
Seuil pour les appareils sur secteur (min)	number	Non	S'applique aux prises, ampoules et routeurs, qui parlent souvent.
Seuil pour les appareils sur pile (min)	number	Non	S'applique aux capteurs sur pile, qui dorment la plupart du temps. 1440 minutes valent 24 heures.
Seuils par appareil	string	Non	Une paire appareil=minutes par ligne ou séparées par des virgules. L'appareil est désigné par son nom convivial Zigbee2MQTT ou son adresse IEEE. Exemple : capteur boite aux lettres=4320, 0x00158d0001abcdef=60
Nommage des appareils	section	Non	Gladys connaît très probablement déjà ces appareils sous leur nom Zigbee2MQTT, via sa propre intégration Zigbee2MQTT. Sans suffixe, un sélecteur de scène affiche deux fois le même nom sans moyen de les distinguer.
Suffixe ajouté aux noms d'appareils	string	Non	Ajouté au nom Zigbee2MQTT de chaque appareil surveillé, par exemple « prise bureau (monitor) ». Laissez vide pour garder le nom brut. N'affecte que les appareils créés ensuite : Gladys ne renomme jamais un appareil déjà ajouté.
Appareil Zigbee2MQTT monitor	section	Non	L'appareil unique qui résume tout le réseau : combien d'appareils sont surveillés, combien sont silencieux, et le nom de ceux qui se taisent — le texte qu'une notification de scène reprend. C'est sur lui qu'il faut bâtir l'alerte : ses compteurs couvrent tous les appareils connus de Zigbee2MQTT, y compris ceux que vous appairerez plus tard.
Texte affiché quand aucun appareil n'est silencieux	string	Non	Ce qu'affiche la fonctionnalité « Silent device names » tant que tout le réseau répond. Écrivez-le dans votre langue ; vide rétablit la valeur par défaut.
Avancé	section	Non
Appareils à ignorer	string	Non	Noms conviviaux ou adresses IEEE, séparés par des virgules. Les appareils ignorés ne sont pas publiés vers Gladys et ne déclenchent jamais d'alerte.
Surveiller aussi les appareils désactivés dans Zigbee2MQTT	boolean	Non	Désactivé par défaut : un appareil que vous avez désactivé volontairement est censé se taire.
Intervalle de vérification (s)	number	Non	Fréquence de réévaluation du silence de chaque appareil.

Comment installer Z2M Devices Monitor dans Gladys

1. Dans Gladys, ouvrez Intégrations : Z2M Devices Monitor apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/prohand/gladys-z2m-devices-monitor:1.0.3), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/prohand/gladys-z2m-devices-monitor.

Z2M Devices Monitor nécessite Gladys >=4.85.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes

Z2M Devices Monitor est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par prohand, et non par l'équipe cœur de Gladys.

• Parcourir toutes les intégrations externes
• Découvrir les intégrations natives intégrées à Gladys
• Créer et publier votre propre intégration externe
• Code source sur GitHub — source de cette documentation

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂