Vos entités sous surveillance

Etre prévenu si une entité devient indisponible est indispensable pour un système domotique robuste. Mettre en place un tel système de surveillance est le sujet de cet article.
Vos entités sous surveillance

Sommaire

Votre système domotique est au cœur de votre logement, et gère potentiellement des fonctions critiques : chauffage, VMC, capteurs d'incendie ou alarme. Mais que se passe-t-il si des devices ne répondent plus ? Les conséquences peuvent être fâcheuses.

Cet article vous propose de mettre sous surveillance vos différents composants, à travers la vérification de la disponibilité d'entités critiques.

Principe

Un BluePrint va permettre de créer une ou plusieurs automatisations qui vont, à intervalles réguliers, vérifier vos entités critiques. Si une des entités devient indisponible (état "unavailable"), alors l'automatisation vous enverra une notification.

La principale difficulté est d'identifier toutes les entités à surveiller. Nous vous proposons pour cela 2 méthodes au choix :

  1. Méthode 1 : utilisation des étiquettes ("labels")
    À partir de la version 2024.4 de Home Assistant, il est possible d'associer aux entités des étiquettes. Nous proposons d'associer aux entités critiques à surveiller une étiquette spécifique ("check" par exemple).
  2. Méthode 2 : utilisation d'expressions avec des "wildcards"
    Si vos entités sont correctement nommées, alors il est possible de les lister juste avec une chaine de caractère et des wildcard, comme on le ferait dans n'importe quelle recherche (dans un gestionnaire de fichier par exemple, en mettant des wildcard "*" dans le champ de recherche de fichiers).
⚠️
La méthode 1 (étiquettes) est très flexible et la plus simple, mais impose d'associer une étiquette à toutes vos entités à surveiller.

La méthode 2 (wildcard) n'oblige pas à tagger, mais suppose que vous avez un nommage propre et normalisé de vos entités, ce qui est toujours fortement conseillé.

Chacun choisira la méthode qu'il juge la plus appropriée (voir les 2), en fonction de son système, du nombre d'entités et de la qualité de ses nommages.

Méthode 1 - sélection par étiquettes

La méthode 1 propose de surveiller toutes les entités qui ont une étiquette donnée.

Lors de la création de l'automatisation de surveillance, le blueprint va vous demander plusieurs paramètres :

  • La ou les heures où elle doit s'exécuter (jusqu'à 4 heures différentes dans la journée)
  • Une étiquette ("label") : l'étiquette que vous aurez utilisé pour "tagger" toutes vos entités critiques.
  • Enfin la notification à transmettre : le service à appeler et le message à envoyer, avec la liste des entités non disponibles.
⚠️
Vous devez avoir une version de Home Assistant 2024.4 ou supérieure.

Tagger les entités

Allez dans Paramètres - Appareils & Services puis sélectionner l'onglet Entités.

Cliquer en haut à droite sur "Ajouter une étiquette" et créer votre étiquette, par exemple "check". Vous pouvez maintenant associer le tag "check" à vos entités critiques.

Cliquez sur le sélecteur dans le bandeau.

Retrouver et sélectionner les entités à surveiller, puis cliquer sur "Ajouter une étiquette" en haut à droite.

Importer le blueprint

Afin de pouvoir ensuite créer une automatisation, il faut tout d'abord importer le blueprint depuis mon repository Github.

Aller dans Paramètres, puis Automatisations et scènes, et enfin cliquer sur l'onglet Blueprint.

Cliquer sur le bouton en bas à droite Importer un blueprint.

Entrer l'adresse du blueprint :

https://github.com/argonaute199/availability-check/blob/main/availability_check_label.yaml

Voilà, le blueprint availability_check_label est importé et vous pouvez maintenant créer des automatisations de surveillance l'utilisant.

Création de l'automatisation

Grace au BluePrint, nous allons pouvoir créer une automatisation qui se déclenche de 1 à 4 fois par jours, vérifie les entités sélectionnées et envoie une notification si une des entités n'est pas disponible.

Aller dans Paramètres, puis Automatisations et scènes, et enfin rester sur l'onglet Automatisations.

Cliquer sur le bouton en bas à droite Créer une automatisation. Vous devriez voir le BluePrint Availability check label.

Cliquer dessus. Vous devriez alors avoir accès aux paramètres de l'automatisation.

  • Remplir de 1 à 4 heures d'exécution dans la journée. Laissez à zéro un champ heure si vous ne souhaitez pas l'utiliser. Par exemple ne remplissez que "Heure 1" et "Heure 2" si vous ne souhaitez lancer la surveillance que 2 fois par jour.
    Il ne faut donc pas déclencher l'automatisation à minuit, car les heures à 0 ne sont pas prises en compte...
  • Spécifier le label. Recopier le label choisi, par exemple check.
  • Spécifier la notification à exécuter.
    Cliquer sur Ajouter une action
    Choisir une notification disponible. J'utilise les notifications Telegram (telegram bot: Send Message), mais vous pouvez utiliser les notifications par défaut de Home Assistant (persistante_notification: create).

    Enfin dans le champ message, entrer le code un texte du type "Attention, devices non disponibles :" puis à la ligne {{entities}} qui à l'exécution sera remplacé par la liste des noms des entités non disponibles.
💡
Il est conseillé de passe le champ en mode YAML (cliquer sur les 3 points à droite du champ pour le menu) comme ci-dessous, et vérifier que le message est le même que ci-dessous.

Enregistrer votre automatisation, elle est créée et prête à être exécutée. Vous pouvez passer au chapitre Test de l'automatisation.

💡
N'hésitez pas à créer 2 ou 3 automatisations différentes qui surveillent des groupes d'entités plus ou moins critiques. Il vous sera alors nécessaire de créer plusieurs étiquettes (check1, check2...).
Les entités critiques seront surveillées 4 fois pas jour. Celles qui le sont moins 1 à 2 fois seulement.

Méthode 2 - sélection par "wildcards"

La méthode 2 propose, elle, de sélectionner les entités à surveiller en définissant une liste de chaines de caractères avec des "wildcards".

Lors de la création de l'automatisation, le blueprint va vous demander plusieurs paramètres :

  • La ou les heures où il doit s'exécuter (jusqu'à 4 heures différentes dans la journée)
  • Un filtre de sélection : une liste de chaînes de caractère avec des "wildcard", qui permet de retrouver toutes les entités à surveiller (voir chapitre suivant)
  • Les entités à exclure : entités qui ressortent dans le filtre, mais que l'on souhaite exclure de la surveillance.
  • Enfin la notification à transmettre : le service à appeler et le message à envoyer.

Filtre de sélection - les wildcards

La première étape est de créer un filtre de sélection, soit une liste de chaines de caractères avec des "wildcard" qui permettra de filtrer les entités et retrouver celles qui sont à surveiller.

Le wildcard est ".*" (un point suivi d'une étoile).

Exemple 1

Vous voulez retourner toutes les entités relatives aux capteurs d'ouverture.

Par exemple, les entités sont des "binary_sensors" dont le nom se termine par "contact" (binary_sensors.aqara_fenetre_bureau_contact par exemple).

=> Filtre de sélection des détecteurs de fenêtre
binary_sensor.*contact

Exemple 2

Vous voulez retourner toutes les entités relatives aux capteurs de températures.

Par exemple, les entités sont des "sensors" dont le nom se termine par "temperature". J'ai l'habitude de mettre début de nom le fabricant et j'ai des Oregon et des Aqara. Les températures des autres devices ne m'intéressent pas.

Je vais donc créer un filtre avec 2 chaines de caractères (une pour les aqara et une les oregon), séparées par une virgule.

=> Filtre de sélection des capteurs de température Aqara et Oregon : sensor.aqara.*temperature, sensor.oregon.*temperature
💡
Vous pouvez créer un filtre de sélection avec autant de chaines de caractères séparées par des virgules que vous voulez.
Pour sélectionner toutes les entités à surveiller, il est probable que le filtre regroupera 5 à 10 chaines différentes.

Test des filtres de sélection

Il est important de tester votre filtre de sélection et de vérifier ce qu'il retourne effectivement.

Pour cela, aller dans Home Assistant dans "outils de développement". Puis cliquez sur l'onglet "Modèle".

Dans le champ Editeur de Modèle, copier le code suivant :

{% set selector = 'sensor.*' %}

{% set result = namespace(entities=[]) %}
{% set entity_filter = selector.replace(' ', '').split(',') %}

{% for item in entity_filter %}
  {% for state in states | selectattr('entity_id', 'match', item)%}
    {% set result.entities = result.entities + [state.entity_id] %}
  {% endfor %}
{% endfor %}
{{result.entities|unique|join('\n')}} 

Puis dans la première ligne avec le code set selector, remplacez le code sensor.* par votre filtre de sélection.

Vous obtiendrez alors, dans le cadre de résultats, la liste des entités sélectionnées dans le filtre. Dans l'exemple qui suit, je retrouve bien mes entités de type capteur de température à surveiller.

Importer le blueprint

Afin de pouvoir ensuite créer une automatisation, il faut tout d'abord importer le blueprint depuis mon repository Github.

Aller dans Paramètres, puis Automatisations et scènes, et enfin cliquer sur l'onglet Blueprint.

Cliquer sur le bouton en bas à droite Importer un blueprint.

Entrer l'adresse du blueprint :

https://github.com/argonaute199/availability-check/blob/main/availability_check_wildcards.yaml

Voilà, le blueprint availability_check_wildcards est importé et vous pouvez maintenant créer des automatisations de surveillance l'utilisant.

Création de l'automatisation

Grace au BluePrint, nous allons pouvoir créer une automatisation qui se déclenche de 1 à 4 fois par jours, vérifie les entités sélectionnées et envoie une notification si une entité n'est pas disponible.

Aller dans Paramètres, puis Automatisations et scènes, et enfin rester sur l'onglet Automatisations.

Cliquer sur le bouton en bas à droite Créer une automatisation. Vous devriez voir le BluePrint Availability check wildcards.

Cliquer dessus. Vous devriez alors avoir accès aux paramètres de l'automatisation.

  • Remplir de 1 à 4 heures d'exécution dans la journée. Laisser à zéro un champ heure si vous ne souhaitez pas l'utiliser. Par exemple ne remplissez que "Heure 1" et "Heure 2" si vous ne souhaitez lancer la surveillance que 2 fois par jour.
    Il ne faut donc pas déclencher l'automatisation à minuit, car les heures à 0 ne sont pas prises en compte...
  • Spécifier le filtre. Recopier la chaine de caractères précédemment créée, permettant de filtrer les entités à exclure.
  • Spécifier les entités à exclure. Si votre filtre retourne des entités que vous ne souhaitez pas surveiller, spécifier les entités à exclure. Cliquer sur Choisir une entité, puis retrouver et sélectionner l'entité...
  • Spécifier la notification à exécuter.
    Cliquer sur Ajouter une action
    Choisir une notification disponible. J'utilise les notifications Telegram (telegram bot: Send Message), mais vous pouvez utiliser les notifications par défaut de Home Assistant (persistante_notification: create).

    Enfin dans le champ message, entrer le code un texte du type "Attention, devices non disponibles :" puis à la ligne {{entities}} qui à l'exécution sera remplacé par la liste des noms des entités non disponibles.
⚠️
Saisie du message de notification
Il semble y avoir un pb qui interdit la rédaction du message complet avec l’UI.
Commencer à créer l’appel à la notification en mode UI avec un message bidon. Puis passer en YAML (voir ci-dessous) pour finaliser la rédaction du message complet.

Enregistrer votre automatisation, elle est créée et prête à être exécutée.

💡
N'hésitez pas à créer 2 ou 3 automatisations différentes, surveillants des groupes d'entités plus ou moins critiques. Les entités critiques seront surveillées 4 fois pas jour. Celles qui le sont moins 1 à 2 fois seulement.

Test de l'automatisation

Votre automatisation étant prête, il est conseillé de la tester. L'automatisation étant en mode édition, cliquer sur les 3 points en haut à droite et sélectionner "exécuter".

L'automatisation va s'exécuter immédiatement. Vous devriez alors avoir une notification avec le message d'avertissement. Si aucune entité n'est indisponible, la liste sera vide lors du test.

⚠️
Attention, lors d'une exécution manuelle depuis l'éditeur d'automatisation, la condition sur le nombre d'entités indisponible n'est pas exécutée : la notification s'affichera avec une liste vide même s'il n'y a pas d'entités non disponibles (pratique pour tester).

Bien entendu, en exécution normale (déclenchement horaire), la condition s'appliquera et il y aura une notification uniquement s'il y a une ou plusieurs entités indisponibles.

Pour test, vous pouvez désactiver un des devices surveillé (une prise connectée, un thermomètre...) et attendre que l'entité associée devienne indisponible. Si vous relancez l'exécution, vous devriez cette fois avoir une notification affichant le nom de l'entité non disponible.

En cas de doutes, toujours dans l'éditeur d'automatisation, vous pouvez cliquer sur "historique des exécutions" pour vérifier comment l'automatisation a été exécutée.

Si vous cliquez sur l'onglet L'onglet "configuration de l'automatisation", vous retrouverez le code complet généré par le blueprint. Enfin l'onglet "configuration du blueprint", vous retournera uniquement le code exécuté (ici la notification).

Affichage dans le dashboard

En bonus, si vous utilisez la méthode 1 (labels), vous pouvez également créer facilement une carte qui affiche dans le dashboard s'il y a des entités non disponibles. Pour information, j'utilise dans l'affichage le terme "device" car on surveille en général une entité par appareil ou "device"...

Voilà le résultat s'il y a plusieurs entités indisponibles :

Et s'il n’y en a pas :

Pour cela, il faut aller dans le dashboard en édition et créer une markdown card.

Copier le code jinja2 suivant dans le champ contenu :

{% set selector = 'check' %}
{% set result = namespace(entities=[]) %}
{% set entity_list = label_entities(selector)%}

{% for item in entity_list %}
  {% for state in states | selectattr('state','match', 'unavailable') | selectattr('entity_id', 'match', item)%}
    {% set result.entities = result.entities + [state.name] %}
  {% endfor %}
{% endfor %}

{% if result.entities | length == 0 %}
  **Aucun device indisponible.**
{% else %}
  {% if result.entities | length == 1 %}
    **Device indisponible :**
  {% else %}
    **Devices indisponibles :**
  {% endif %}
  {{ '\r\n - ' ~ result.entities|unique|join('\r\n - ')}}
{% endif %}

Changer le label dans la première ligne si vous en utilisez un autre (check utilisé dans le code). À chaque visite de la vue, la carte se mettra à jour...

💡
Il est tout à fait possible de s'inspirer de ce code pour la méthode 2 (wildcards), mais je ne l'ai pas fait.

Conclusion

La mise en place d'une ou plusieurs automatisations qui surveillent vos entités va contribuer à rendre votre système domotique bien plus robuste.

Si vous utilisez zigbee2mqtt, il est indispensable de bien contrôler le délai à partir duquel un device et ses entités deviennent indisponibles. Par défaut, zigbee2mqtt ne rend par les entités indisponibles, et gardent leurs anciennes valeurs. N'hésitez pas à consulter notre article à ce sujet :

Zigbee2MQTT : bien gérer les disponibilités de ses devices
L’indisponibilité non détectée d’un périphérique Zigbee peut avoir de graves conséquences pour nos systèmes domotiques. Cet article vous explique comment fiabiliser Zigbee2MQTT en gérant correctement la surveillance des objets connectés.

Enfin, vous pouvez envoyer vos notifications dans Telegram, plutôt que dans les notifications Home Assistant. Cet article vous expliquera comment faire cela.

Home Assistant : dialogue avec Telegram
Cet article présente comment intégrer Telegram à Home Assistant et communiquer avec lui. Il est primordial de recevoir des notifications de son système domotique, et d’y accompagner des images ou des vidéos. Et s’il est possible d’y répondre, c’est encore mieux.

Annexe - conseils pour nommer ses entités

Tout particulièrement si vous choisissez la méthode 2, le nommage de vos entités est important pour pouvoir facilement les retrouver. Home Assistant ne livre pas de bonne pratique à ce sujet.

En complément dans cet article, voici le nommage que j'utilise et vous suggère :

classe.marque_type_localisation_fonction
  • Classe - classe de base de l'entité : binary_sensor, switch, cover.... Vous ne pouvez le modifier.
  • Marque - Aquara ou Oregon dans mon exemple.
    Certains ne mettent pas la marque, mais cela permettra de filtrer et retrouver rapidement ses entités.
  • Type - type d'objet : fenêtre, prise, thermomètre...
  • Fonction - fonctionnalité de l'entité ou info principale retournée : contact (détecteur ouverture), température, onoff (prise), puissance, energie, batterie, etc

Exemples :

  • binary_sensor.oregon_thermometre_chambre_temperature
  • switch.aqara_prise_bureau_onoff
  • sensor.netatmo_annecy_humidity
💡
Bien entendu, vous ne pourrez pas renommer toutes vos entités.
- Ne renommer que celles qui sont significatives (utilisées dans le dashboard, les automatisations...)
- Nommer bien les appareils, ce qui permet de générer des nommages corrects des entités.