Intégrations, appareils, entités : qui parle à qui

Quand une lampe ne répond plus, la moitié des gens cherchent au mauvais endroit, parce qu'ils ne savent pas quelle pièce du puzzle a lâché. Home Assistant range tout ce qu'il connaît en trois étages. Les connaître, c'est savoir où regarder.

Cette leçon suppose que vous avez déjà installé Home Assistant et rattaché un premier appareil, comme le montre le guide Premiers pas avec Home Assistant.

L'intégration : le traducteur

Une intégration relie Home Assistant à une marque, un protocole ou un service. Il y en a une pour les ampoules d'une marque donnée, une pour la météo, une pour une antenne Zigbee. Elle parle la langue de l'appareil d'un côté, et celle de Home Assistant de l'autre.

C'est l'étage qui tombe quand tous les appareils d'une même marque deviennent indisponibles en même temps : le mot de passe du compte de la marque a changé, ou son service en ligne est en panne.

L'appareil : l'objet physique

Un appareil représente un objet réel : une prise connectée, un thermostat, un capteur de porte. Il appartient à une intégration, et il regroupe ce que l'objet sait faire. On lui donne une pièce, un nom lisible, et c'est par lui qu'on retrouve un objet dans l'interface.

L'entité : ce qu'on lit et ce qu'on pilote

Une entité est une seule fonction d'un appareil : l'interrupteur de la prise, sa consommation, sa température interne. Une prise connectée peut ainsi porter trois ou quatre entités. Ce sont les entités qu'on affiche sur un tableau de bord et qu'on utilise dans une automatisation, jamais l'appareil entier.

Chaque entité a un état, une seule valeur à la fois (« on », « 21,5 », « ouvert »), et des attributs qui précisent cet état : la luminosité d'une lampe allumée, l'unité d'une mesure.

flowchart LR
    I["Intégration<br/>(la marque, le protocole)"] --> A1["Appareil<br/>prise du salon"]
    I --> A2["Appareil<br/>prise de la cuisine"]
    A1 --> E1["Entité : interrupteur<br/>état on / off"]
    A1 --> E2["Entité : consommation<br/>état 42 W"]
    A2 --> E3["Entité : interrupteur"]

Cas concret

Le capteur de la porte d'entrée ne déclenche plus l'éclairage du couloir. Trois questions, dans l'ordre des étages. L'intégration est-elle en erreur ? Non, les autres capteurs de la même marque fonctionnent. L'appareil est-il joignable ? Sa fiche indique une pile à 2 %. Inutile de toucher à l'automatisation : la panne est sous l'entité, dans l'objet lui-même.

Erreurs fréquentes

• Utiliser l'appareil là où il faut l'entité. Une automatisation se déclenche sur l'état d'une entité précise, pas sur « la prise ».
• Garder les noms techniques. « switch_3_zigbee » dans une automatisation devient illisible six mois plus tard.
• Supprimer une intégration pour « repartir de zéro ». Elle emporte tous ses appareils et entités, et les automatisations qui s'en servaient.

À retenir

• Trois étages : l'intégration traduit, l'appareil représente l'objet, l'entité porte une fonction et son état.
• Une panne qui touche toute une marque vient de l'intégration ; une panne isolée vient de l'appareil.
• On affiche et on automatise des entités.

Mini-exercice

Ouvrez la fiche d'un de vos appareils et comptez ses entités. Pour chacune, notez son état actuel, puis cherchez lequel de ses attributs vous seriez susceptible d'utiliser un jour.