Créez vos premiers composants Home Assistant

Dans un billet précédent, nous vous avons expliqué comment mettre en place Home Assistant pour contrôler et orchestrer votre installation. Home Assistant est une solution puissante et clé en main. Aujourd’hui, nous allons mettre les mains dans le cambouis et comprendre comment pousser sa personnalisation en créant nos propres composants.

Les composants permettent d’étendre les possibilités d’Home Assistant, ils peuvent écouter et déclencher des événements (changement de température, changement de coordonnées GPS), offrir des services pour contrôler un appareil (ouvrir les volets, baisser le volume) et conserver ces états (la lampe est allumé, une vidéo est en cours de lecture, etc.).

Pour suivre cet article, des connaissances basiques en programmation Python seront nécessaires. Je vous conseille les tutoriels de apprendre-pythonopenclassrooms ou encore learnpython pour les anglophones.

Vous êtes prêts ? C’est parti.

Notre premier composant Home Assistant

Home Assistant fourni un ensemble de composants clé en main mais il est possible de créer des composants personnalisés.  En quelques lignes de code, nous allons créer le notre. Celui-ci va nous permettre d’afficher un état simple dans Home Assistant.

Premièrement, nous devons créer un fichier qui va décrire le comportement de notre composant. Afin que Home Assistant le prenne en compte, il devra être placé dans le dossier custom_components.

# On crée le dossier custom_components
mkdir ~/.homeassistant/custom_components
# On édite le fichier python qui va décrire le comportement de notre composant
vi ~/.homeassistant/custom_components/hello_devotics.py

Nous allons maintenant décrire le comportement de notre composant en ajoutant les lignes suivantes au fichier hello_devotics.py.

"""Notre premier composant"""
# Le nom du composant -- identique au nom du fichier pour permettre à Home Assistant de le trouver
DOMAIN = 'hello_devotics'

def setup(hass, config):
    """
    Home Assistant va appeler cette fonction pour initialiser le composant.
    Il va définir l'état 'devotics.author'
    et lui assigner la valeur 'Antoine'
    """
    hass.states.set('devotics.author', 'Antoine')
    return True

Il ne nous reste plus qu’à indiquer à Home Assistant qu’il doit charger le composant en ajoutant la ligne suivant au fichier configuration.yaml :

hello_devotics:

Notre premier composant est déjà prêt !

Il ne reste plus qu’à relancer Home Assistant. Dans la partie “States”, nous pouvons voir notre état.

Composant Home Assistant simple

La partie “History” permet de contrôler les changements de valeur de notre état.

Voir l'état du composant depuis l'historique Home Assistant

Nous pouvons également changer l’état manuellement en allant dans la partie “Developer Tools States”

Modifier un état depuis Home Assistant

Configurer notre composant Home Assistant

Notre premier composant est très simple et manque un peu de modularité : certaines personnes ne s’appellent pas Antoine. Dans cette partie, nous allons voir comment rendre notre composant configurable, nous pourrons alors le partager et chacun pourra le personnaliser selon ses envies.

Pour ce faire, nous allons modifier le fichier hello_devotics.py de la façon suivante :

DOMAIN = 'hello_devotics'

def setup(hass, config):
    # On récupère la configuration définie dans configuration.yaml
    # Si elle n'est pas présente, on utilisera '¯\_(ツ)_/¯'
    author = config[DOMAIN].get('author', '¯\_(ツ)_/¯')
    hass.states.set('devotics.author', author)
    return True

Avec ces quelques changements, notre composant devient configurable. Si nous rechargeons Home Assistant, nous devrions voir la valeur par défaut “¯\_(ツ)_/¯” s’afficher.
Nous pouvons changer la valeur de l’état en modifiant le fichier configuration.yaml :

hello_devotics:
  author: John Travolta

Un composant plus complexe

Nous avons vu les bases sur les états de Home Assistant. Nous allons maintenant créer un composant un peu plus complexe.

Ici, j’ai choisi de créer un composant qui nous permettra d’afficher l’auteur et le texte du dernier SMS reçu. Pour cela, nous aurons besoin de créer un service qui nous permettra de mettre à jour les détails du SMS.
Créons d’abord un nouveau fichier devotics_sms.py pour décrire notre composant :

DOMAIN = 'devotics_sms'

# Les noms des états qui stockeront le nom du contact et le message
STATE_CONTACT_NAME = 'sms.contact_name'
STATE_TEXT = 'sms.text'
# Les noms des l'attributs cherchés dans la configuration et le service pour le nom du contact et le message
ATTR_CONTACT_NAME = 'contact_name'
ATTR_TEXT = 'text'
# Les valeurs par défaut
DEFAULT_CONTACT_NAME = '¯\_(ツ)_/¯'
DEFAULT_TEXT = 'Please text me...'
# Le nom de notre service pour mettre à jour les états
SERVICE_UPDATE_SMS = 'update_sms'

def setup(hass, config):
    # On récupère les valeurs par défaut depuis notre configuration...
    contact_name = config[DOMAIN].get(ATTR_CONTACT_NAME, DEFAULT_CONTACT_NAME)
    text = config[DOMAIN].get(ATTR_TEXT, DEFAULT_TEXT)
    # ...et on modifie les états avec ces valeurs
    hass.states.set(STATE_CONTACT_NAME, contact_name)
    hass.states.set(STATE_TEXT, text)

    # Notre service pour modifier l'état
    def handle_update_sms(call):
        # On récupère les nouvelles valeurs
        contact_name = call.data.get(ATTR_CONTACT_NAME, DEFAULT_CONTACT_NAME)
        text = call.data.get(ATTR_TEXT, DEFAULT_TEXT)
        # ...et on met à jour les états
        hass.states.set(STATE_CONTACT_NAME, contact_name)
        hass.states.set(STATE_TEXT, text)

    # On enregistre notre service permettant de changer l'état auprès d'Home Assistant
    hass.services.register(DOMAIN, SERVICE_UPDATE_SMS, handle_update_sms)

    return True

Comme avec notre premier composant, ce composant va stocker des états : le nom du contact et le texte du message. Nous ajoutons cependant une nouveauté, nous enregistrons un service auprès de Home Assistant. Celui-ci nous permet de récupérer les nouvelles valeurs et de mettre à jour les états. Pour pouvoir tester notre composant, nous allons le référencer dans le fichier configuration.yaml :

devotics_sms:
  contact_name: Nicolas S.
  text: Double ration de frites pour tout le monde

En redémarrant Home Assistant, nous pouvons voir notre composant s’afficher sur la page d’accueil avec nos deux états.

Composant SMS

Tester notre composant avec Home Assistant

Pour vérifier que notre service fonctionne bien, nous pouvons l’appeler manuellement en allant dans la partie “Developer Tools Services”. Nous y retrouvons le service que nous avons enregistré et pouvons l’appeler avec le JSON suivant pour changer notre état :

{"contact_name": "John Doe", "text": "Hello services"}

Appeler un service depuis Home Assistant

Les états devraient se mettre à jour et afficher les nouvelles valeurs.

Tout fonctionne ? Nous pouvons continuer.

Automatiser l’appel au service Home Assistant

Home assistant expose tous les services enregistrés via une API HTTP. Cela signifie que notre service est disponible depuis n’importe où et peut être appelé depuis d’autres applications d’automatisation comme IFTTT.
Pour faire fonctionner notre composant, j’ai créé un petit scénario IFTTT : si je reçois un SMS, alors j’appelle notre service avec le nom du contact et le contenu du message.
J’ai utilisé Maker pour effectuer l’appel du service avec la configuration suivante :

Configuration Maker IFTTT pour Home Assistant

L’URL à utiliser est de ce format : <url-home-assistant>/api/services/devotics_sms/update_sms?api_password=<password-home-assistant>, l’URL d’Home Assistant est celle que vous avez configurée pour pouvoir accéder à Home Assistant en dehors de chez vous et le mot de passe est celui configuré dans le fichier configuration.yaml.

Vous pouvez tester le fonctionnement en attendant un message de votre grand-mère ou en vous envoyant un message à vous-même.

Conclusion

J’espère que cet article vous a permis d’un peu mieux comprendre les bases des composants Home Assistant et quelques possibilités que ceux-ci peuvent offrir. Nous verrons dans un prochain article des fonctionnalités plus complexes de ceux-ci. D’ici là, je vous laisse vous amusez à créer vos composants personnalisés.

JavaScript and Progressive Web Apps enthusiast ☕ Coffee lover ☕ Home automation newbie
Tu aimes cet article ? Alors partage le Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInPin on PinterestShare on RedditShare on Tumblr

1 réponse

  1. Etienne dit :

    Merci pour cet article 🙂 bien utile pour appréhender la création de composants.

Laisser un commentaire