38.1 Les modèles dans Home Assistant

Les modèles sont un mécanisme qui permet d'obtenir une valeur à partir d'autres valeurs avec possibilité d'opérations mathématiques, de tests conditionnels, etc.

On peut les comparer à de petits bouts de programmes qui ont accès notamment aux valeurs :

• des capteurs virtuels que vous pourrez ajuster dans l'onglet Aperçu
• des capteurs réels
• de toute autre entité

Grâce à eux, les scripts et les automatisations bénéficient de plus de possibilités. 

Dans cette fiche :

• Éditeur de modèles
• Valeur principale d'un capteur
• Capteur avec attributs
• Retrouver un attribut particulier
• Conditions
• Travailler avec des valeurs numériques
• Variables dans un modèle
• Boucles dans un modèle
• Commentaires dans un modèle
• Identifiants d'objets non conformes
• Résumé des syntaxes

Éditeur de modèles

Le code d'un modèle doit répondre aux règles énoncées ici : https://www.home-assistant.io/docs/configuration/templating/.

Le langage utilisé pour définir un modèle est Jinja2. Sa syntaxe ressemble à celle de Python.

Pour vous aider à valider le code d'un modèle, rendez-vous dans Outils de développement / Modèle (en anglais : Template).

Effacez le contenu de l'éditeur de modèles et remplacez-le par celui que vous désirez tester. Le résultat apparaîtra immédiatement à droite.

Valeur principale d'un capteur

Dans sa forme la plus simple, le modèle pourra retrouver la valeur principale d'un capteur.

Pour travailler avec les valeurs des capteurs, il faut utiliser les objets de type state.

Ici, on utilisera la fonction states() et on lui fournira en paramètre l'identifiant de l'entité, le tout entre doubles accolades.

Le même résultat est obtenu avec ceci :

ou encore avec :

Cependant, selon la documentation officielle de Home Assistant¹:

Avoid using states.sensor.temperature.state, instead use states('sensor.temperature'). It is strongly advised to use the states(), is_state(), state_attr() and is_state_attr() as much as possible, to avoid errors and error message when the entity isn’t ready yet (e.g., during Home Assistant startup).

Capteur avec attributs

Certains capteurs ont plusieurs attributs.

Pour le savoir, utilisez un modèle qui constiste en le mot states suivi d'un point puis de l'identifiant du capteur.

Cette syntaxe ne doit pas être utilisée dans une automatisation mais elle est utile dans les outils de développement.

ou, si vous préférez travailler avec OpenWeatherMap :

On voit d'un coup tous les attributs disponibles.

Il est possible de demander à voir seulement les attributs.

Retrouver un attribut particulier

Pour travailler avec un attribut particulier :

Conditions

La fonction is_state() retourne true si un capteur correspond à la valeur passée en paramètre :

Avec is_state_attr(), on peut vérifier si un attribut a une valeur donnée :

Le test conditionnel combiné à states(), state_attr(), is_state() ou is_state_attr() offre des possibilités intéressantes :

Travailler avec des valeurs numériques

Dans le cas où le modèle doit effectuer un test entre une valeur retrournée par states() et une valeur numérique (int ou float),  les bonnes pratiques veulent que le modèle utilise un filtre pour assurer que la valeur est du bon type.

Il s'agit d'ajouter une pipe (|) suivie du type.

Parfois, ce n'est pas une question de bonnes pratiques mais bien une question de bon fonctionnement.

Par exemple, si vous tentez de comparer la valeur d'un capteur avec une valeur numérique, vous pourriez obtenir une erreur du genre « TypeError: '<' not supported between instances of 'str' and 'int' ».

Le message est alors clair : il n'est pas possible de comparer une chaîne et un entier.

La conversion de type est alors une obligation en plus d'être une bonne pratique :

Variables dans un modèle

Afin de rendre le code plus facile à lire, vous pouvez créer des variables que vous réutiliserez plus loin dans le modèle.

Boucles dans un modèle

Un modèle peut effectuer une boucle pour réaliser une opération un nombre défini de fois ou encore pour effectuer une opération sur chaque entité qui répond à un critère.

Par exemple, pour effectuer une opération sur chacun des capteurs virtuels booléens (ici, on ne fait qu'afficher l'identifiant) :

Pour boucler un nombre défini de fois (ici, on ne fait qu'afficher l'index) :

Commentaires dans un modèle

J'aime bien conserver dans l'éditeur de modèles de Home Assistant une série de tests que je réalise.

Pour mieux m'y retrouver, j'y ajoute des commentaires.

Les commentaires dans les modèles sont entourés de {# et de #}.

Identifiants d'objets non conformes

Si, lorsque vous testez un tel modèle dans l'éditeur, vous obtenez un message du genre « TemplateSyntaxError: expected token 'end of print statement', got '... », c'est peut-être parce que l'identifiant de l'objet (ce qui suit le point dans l'identifiant de l'entité) débute par un caractère non autorisé, par exemple un chiffre.

Pour régler ce problème, vous pouvez utiliser cette syntaxe (remplacez sensor par le domaine et identifiant_objet_problematique par l'identifiant de l'objet) :

Remarquez les différentes syntaxes et leur résultat. Dans cet exemple, j'ai utilisé un identifiant d'objet qui ne pose pas de problème.

Les deux premiers modèles donnent le même résultat mais pas le troisième.

Dans tous les cas, il est conseillé de travailler avec states() plutôt qu'avec states..

Résumé des syntaxes

Source

1. « Templating ». Home Assistant. https://www.home-assistant.io/docs/configuration/templating/