Après les résultats encourageants de notre intégration des capteurs Yoctopuce dans Home Assistant via la passerelle MQTT, nous n'avons pas résisté à la tentation d'y intégrer aussi nos modules de commande. Mais pour cela, il a fallu commencer par enrichir notre support MQTT pour permettre d'envoyer des ordres aux modules. Voici donc une présentation de ces améliorations.
Jusqu'à présent, VirtualHub et les interfaces réseau de Yoctopuce (YoctoHub-Ethernet, YoctoHub-Wireless-n, etc.) se contentaient de publier les principaux changements d'état des capteurs et actuateurs connectés vers le broker MQTT. Pour permettre une utilisation plus extensive, ils sont désormais capables de:
- recevoir des messages de commande (par exemple pour commuter un relais)
- recevoir des messages de configuration
- publier toute leur configuration lorsqu'un paramètre est changé
- publier les changements de disponibilité (connecté/déconnecté)
Les messages MQTT correspondants sont décrits ci-dessous.
Partie commune
Le topic de tous les messages commence par une partie commune, qui identifie le module Yoctopuce et la fonction particulière de ce module concernée par le message. Elle a la structure suivante:
root_topic/deviceName/functionName
Le root_topic peut être configuré librement, par exemple à la valeur yoctopuce. Si vous connectez plusieurs hubs au même broker MQTT, vous pouvez soit utiliser le même root_topic pour tous, soit un topic différent par hub. L'utilisation d'un root_topic séparé est recommandée si vous envoyez beaucoup de commandes à un hub par MQTT.
Le deviceName correspond au nom logique que vous avez donné au module Yoctopuce concerné. Si aucun nom logique n'a été configuré, le numéro de série du module est utilisé à la place du nom logique (par exemple METEOMK2-012345).
Le functionName correspond au nom logique que vous avez donné à la fonction concernée. Si aucun nom logique n'a été configuré, l'identifiant de la fonction est utilisé (par exemple genericSensor1).
Le fait d'utiliser les noms logique plutôt que les noms matériels dans la racine du topic a l'avantage de permettre d'identifier les modules et les fonctions par leur rôle et de ne pas devoir indiquer explicitement l'identifiant matériel de chaque module au client MQTT qui devra interagir avec ces modules. Le désavantage est que si vous décidez de changer le nom logique de vos modules ou de vos fonctions sans y penser, les topics MQTT utilisés changeront en conséquence.
Topic /api: état complet de la fonction
Sous root_topic/deviceName/functionName/api, chaque fonction publie une structure JSON décrivant l'état complet de la fonction, tous attributs compris. Dans cet encodage JSON,
- les booléens sont représentés par 0 et 1
- les types énumérés sont représentés par des constantes numériques
- les nombres réels tels que les mesures sont représentés sous forme d'entiers, après multiplication par 65536. Il faut donc les diviser par 65536.0 pour obtenir la valeur réelle.
Ce message est publié lorsque l'une des conditions suivante se produit:
- à l'établissement de la connexion du hub avec le broker MQTT
- toutes les cinq minutes
- après un changement de configuration du module
- en réponse à la réception d'une commande par cette fonction
- pour la fonction module, en cas d'activation ou de désactivation de la balise (beacon)
Topic de base: état instantané
Sous root_topic/deviceName/functionName, chaque fonction publie un résumé textuel de son état. Il ne s'agit pas de JSON mais d'une simple chaîne de caractères, correspondant à la valeur de l'attribut advertisedValue de la fonction. Par exemple, pour un capteur, il correspond à la valeur instantanée du capteur, alors que pour un relais il correspond à la lettre A ou B en fonction de l'état de commutation.
Ce message est publié lorsque l'une des conditions suivantes se produit:
- à l'établissement de la connexion du hub avec le broker MQTT
- toutes les cinq minutes
- à chaque changement de l'attribut advertisedValue
Pour éviter de surcharger le broker MQTT avec les changements de valeurs instantanée des capteurs, il est possible de désactiver globalement l'envoi des messages de valeurs instantanées pour les capteurs uniquement, dans la configuration MQTT.
Topics /avg, /min, /max: valeurs moyenne et extrêmes
Sous root_topic/deviceName/functionName/avg, les fonctions de type capteur (sous-classes de Sensor) publient périodiquement la valeur moyenne observée durant l'intervalle de temps précédent, directement sous forme de nombre réel.
Sous root_topic/deviceName/functionName/min, la valeur minimale observée durant l'intervalle de temps précédent.
Sous root_topic/deviceName/functionName/max, la valeur maximale observée durant l'intervalle de temps précédent.
Ces messages sont l'équivalent direct des timed reports documentés dans le manuel de ces modules. L'intervalle de temps doit avoir été configuré préalablement dans l'attribut reportFrequency. Dans le cas contraire, ces messages ne sont pas envoyés.
Topics /set/attributeName: envoi de commande et configuration
Sous root_topic/deviceName/functionName/set/attributeName, il est possible d'envoyer des message pour modifier les attributs des fonctions, dans le but de modifier leur état ou leur configuration. La valeur du message correspond à la nouvelle valeur désirée, telle quelle. Le format est identique à celui utilisé pour l'API REST disponible dans tous les modules Yoctopuce.
Par exemple, on pourrait commuter un relais en envoyant un message au topic
yoctopuce/RelaisPompe/relay1/set/state
avec la valeur 1.
On pourrait aussi déclancher une impulsion de 1500ms sur le même relais en envoyant un message au topic
yoctopuce/RelaisPompe/relay1/set/pulseTimer
avec la valeur 1500.
La réception de commandes et de changements de configuration par MQTT doit avoir été activée explicitement dans la configuration MQTT sur le hub Yoctopuce. Par sécurité, le comportement de base du mode MQTT reste le mode en lecture seule.
Topic /rdy: état de connectivité
Sous root_topic/deviceName/module/rdy, la fonction module publie une indication binaire de l'état de disponibilité du module. La valeur est à 1 lorsque le module est en ligne, et à 0 lorsqu'il est hors ligne.
Ce message est publié par le hub pour son propre module lorsque l'une des conditions suivantes se produit:
- à l'établissement de la connexion du hub avec le broker MQTT
- à la déconnexion du hub du broker MQTT
Ce message est publié pour les modules autres que le hub lorsque l'une des conditions suivantes se produit:
- à l'établissement de la connexion du hub avec le broker MQTT
- au branchement d'un module sur le hub
- au débranchement d'un module du hub
Pour déterminer si un module est réellement atteignable, il faut donc vérifier son propre topic /rdy, pour savoir si il a été déconnecté, et le topic /rdy du hub, pour savoir si la connexion MQTT est active.
MQTT discovery
De plus, des messages particuliers sont publiés sous le topic homeassistant/ juste après l'établissement de la connexion du hub avec le broker MQTT, et répétés toutes les 5 minutes, pour permettre la détection automatique des fonctionnalités offertes, grâce au mécanisme MQTT discovery supporté par Home Assistant et openHab.
Conclusion
Ce support MQTT étendu ouvre de nombreuses possibilités que nous aurons l'occasion d'explorer lors de prochains articles. D'ici là, n'hésitez pas à contacter le support Yoctopuce si vous avez des questions sur son utilisation...