Dans la série de nos articles sur l'utilisation des modules Yoctopuce avec Home Assistant, nous allons vous montrer comment intégrer les fonctions plus évoluées des modules Yoctopuce, qui ne sont pas directement offertes par la discovery MQTT. Cela vous permettra, par exemple, de piloter depuis Home Assistant un panneau de LEDs RGB Neopixel, d'afficher des informations sur un écran externe Yoctopuce, ou de commander un appareil externe par une liaison RS-485.
La découverte automatique des fonctions Yoctopuce par MQTT dans Home Assistant est limitée aux fonctions de base pour lesquelles le scénario d'utilisation est univoque. Par exemple, lire la valeur d'un capteur ou commuter un relais. Pour d'autres modules, l'interface utilisateur la plus adéquate dans Home Assistant dépend trop de l'application que vous prévoyez d'en faire pour que nous puissions la proposer automatiquement par le mécanisme de discovery MQTT. Mais cela ne veut pas dire que vous ne pouvez pas les intégrer dans votre panneau de contrôle dans Home Assistant, moyennant quelques étapes de configuration manuelles.
Principe
Home Assistant ne permet pas directement de personnaliser ou d'enrichir les entités définies par un device MQTT pour y ajouter des comportements plus évolués. Par contre, il est possible d'ajouter dans l'interface des widgets d'interfaces génériques, et de les lier à des devices MQTT par le biais d'automatisations.
Les deux composantes essentielles d'une automatisation sont le trigger, qui déclenche l'automatisation, et l'action qui est déclenchée. Pour ajouter un widget de commande évolué à un module Yoctopuce, on ajoutera donc une automatisation avec
- un trigger basé sur le changement d'état d'un widget d'interface
- une action qui publiera un ou plusieurs messages MQTT pour déclencher une action sur le module Yoctopuce.
Pour effectuer ce type d'intégration, nous vous recommandons l'utilisation d'un outil du type MQTT Explorer pour vous permettre de voir en temps réel et en détail tous les messages MQTT échangés entre Home Assistant et les modules Yoctopuce.
Ajouter un widget de commande personnalisé
Pour commencer, il faut choisir le widget d'interface pour votre fonction avancée. Pour cela ouvrez la fenêtre de configuration de Home Assistant (Settings), et dans la section Devices & Services choisissez l'onglet Helpers.
Accéder à la page des Helpers
Pressez le bouton Create Helper et choisissez le type de widget de commande que vous désirez:
- Un bouton (Button)
- Un paramètre numérique (Number)
- Un paramètre textuel (Text)
- Un choix multiple (Dropdown)
- Un commutateur on/off (Toggle)
Donnez ensuite un nom correspondant au rôle de ce widget (souvenez-vous en!), et choisissez-lui une icône représentative.
Définition d'un widget à choix multiples
Vous pouvez ensuite ajouter le widget à votre tableau de contrôle en utilisant la fonction Edit Dashboard. En pressant Add Card puis en sélectionnant l'onglet By Entity, vous verrez une liste de toutes les entités définies. Tapez un mot-clé qui se trouve dans le nom que vous avez donné à votre widget, et vous le retrouverez instantanément.
Ajout du widget dans le tableau de contrôle
Lorsque vous confirmez, le nouveau widget apparaît dans votre panneau de contrôle.
Ajouter une action au widget
Maintenant que le widget de contrôle existe, il faut créer l'automatisation qui produira une action lorsque l'utilisateur change ce widget. Pour cela, retournez dans la fenêtre de configuration de Home Assistant (Settings), et ouvrez la section Automations & scenes.
Accéder à la page des Automations
Pressez le bouton Create new automation et choisissez la première option, Start with an empty automation from scratch.
Création manuelle d'une nouvelle automatisation
Nous allons maintenant définir le Trigger qui déclenche l'automatisation et l'action.
Comme mentionné ci-dessus, dans ce cas nous voulons un trigger basé sur le changement d'état d'un widget. Donc pressez Add trigger, et choisissez l'option State. Retrouvez l'entité correspondant à votre widget (en tapant un mot-clé figurant dans le nom du widget), et votre trigger est déjà terminé.
Définition du trigger
L'action consiste à envoyer un message MQTT. Donc pressez Add action et choisissez l'option Call service. Dans le champ de saisie, tapez mqtt et vous verrez apparaître le service MQTT:Publish, que vous pouvez sélectionner.
Les deux paramètres importants sont le destinataire du message MQTT, défini par le topic, et le contenu du message, le payload.
Le topic correspond au chemin complet de la fonction Yoctopuce à laquelle vous voulez envoyer une commande suivit du suffixe "/set/" et de l'attribut que vous voulez changer. Par exemple, pour un module Yocto-RS485-V2 nommé IntelliFlo, le topic permettant de sélectionner un job sur la fonction serialPort sera:
yoctopuce/IntelliFlo/serialPort/set/currentJob
Il est recommandé d'utiliser MQTT Explorer ou un outil similaire pour vérifier le chemin exact sous lequel votre YoctoHub publie et s'attend à recevoir les messages concernant votre module.
Si la valeur que vous voulez configurer est fixe, vous pouvez la mettre directement dans le champ payload. Si vous voulez construire une valeur dynamiquement sur la base d'un ou plusieurs widgets d'interface, vous pouvez utiliser le mécanisme de templates de Home Assistant, en entrant une valeur du genre
{{ states('input_select.current_job') }}.job
Notez que dans ce cas, dès que vous aurez tapé la double-accolade, l'affichage de votre action commutera en mode YAML, le mode de configuration avancé de Home Assistant. N'ayez crainte, ça n'est pas plus compliqué dans ce cas...
Tester le résultat
Il ne vous reste plus qu'à tester votre widget. A nouveau, MQTT Explorer vous sera précieux pour comprendre ce qui se passe dans le cas où votre command serait ignorée...
Quelques autres exemples
Pour activer une séquence d'affichage sur un écran Yoctopuce comme le Yocto-MaxiDisplay, vous pouvez procéder comme décrit ci-dessus, mais à la place d'utiliser l'attribut currentJob, utilisez l'attribut command et mettez comme payload:
S{{ states('input_select.play_seq') }}.seq
Pour lancer une séquence d'animation sur un panneau de leds RGB NeoPixel piloté par un Yocto-Color-V2, utilisez l'attribut command et mettez comme payload SS3 pour lancer la séquence 3 par exemple.
Quasiment toutes les fonctions de haut niveau disponibles dans la librairie Yoctopuce peuvent être exécutées par un message MQTT de ce type. Pour savoir quel attribut doit être utilisé, et éventuellement quelle valeur magique doit être passée à l'attribut command pour déclencher une action particulière, ouvrez par exemple le fichier source de notre librairie Python correspondant à la fonction voulue, et vous y trouverez facilement l'information recherchée. Ou envoyez un mail à support@yoctopuce.com si cela vous semble trop compliqué :-)
