Article publié le 06/06/2022
Mis à jour le 07/06/2022
On trouve pas mal de tutos pour installer MQTT sur Home Assistant lorsque celui-ci tourne sur un raspberry ou sur une distrib linux classique, contrairement aux installations sur Docker. Il y a pas mal de doc mais souvent en anglais. J’ai un peu galéré pour arriver à un résultat fonctionnel (et d’ailleurs mon installation est certainement perfectible), j’ai donc résumé ici les quelques étapes de la configuration des différents éléments.
Je ne vais pas m’étendre sur Docker ou Portainer, d’une part parce que je n’en ai pas les compétences et d’autre part parce qu’il y a suffisamment de doc sur le web pour ça, google is your friend.
Principe de fonctionnement
Par défaut j’utilisais (comme beaucoup de monde au départ je pense) l’intégration ZHA disponible nativement dans Home Assistant. Ne pouvant pas utiliser d’addons (l’installation d’HA via container docker ne permet pas l’accès aux addons) c’est la solution la plus simple à mettre en œuvre.
Le principe avec ZHA est le suivant:
Home Assistant <> intégration ZHA <> périphériques
HA communique avec ZHA qui se charge de gérer le protocole Zigbee pour communiquer avec les périphériques.
Avec MQTT c’est légèrement différent puisqu’on rajoute des intermédiaires:
Home Assistant <> intégration MQTT <> Mosquitto <> zigbee2mqtt <> périphériques
HA communique via l’intégration MQTT avec le broker (Mosquitto). Ce dernier fait ensuite le lien avec les différents périphériques. Dans mon cas j’utilise des périphériques zigbee donc il faut transposer les commandes du protocole MQTT au protocole Zigbee et inversement, donc on rajoute un intermédiaire: zigbee2mqtt.
Pourquoi autant de couches alors que l’intégration ZHA fait le job nativement dans Home Assistant? Simplement parce que zigbee2mqtt prend en charge plus de périphériques que ZHA, offre l’accès à plus de paramètres sur ces derniers. Le protocole MQTT étant conçu pour être léger l’installation ne s’en trouve pas ralentie globalement (c’est toujours instantané entre l’appui sur un bouton et l’activation du périphérique par exemple).
Le réseau bridge Docker
Afin d’isoler les différents éléments domotique de mes autres containers j’ai créé un réseau en mode bridge que j’ai nommé « domotique ». Les différents containers peuvent ainsi communiquer entre eux sans problème mais sans pouvoir communiquer avec les autres containers tournant sur Docker. Le docker Home Assistant est inclus dans ce réseau. Les containers visibles en bas de page s’ajouteront à mesure qu’ils seront configurés.
Nota bene: après coup j’ai fixé l’ip de Mosquitto dans la conf du container. En effet une mise à jour de Docker m’a mis le bordel: lorsque Docker a redémarré les containers se sont vus réattribuer une ip et il se trouve que celle de Mosquitto avait changé, le rendant injoignable par Home Assistant et Zigbee2MQTT.
Le broker: Mosquitto
Ça faisait un moment que j’avais installé Mosquitto mais sans aller plus loin. J’étais dans la découverte des possibilités offertes par Home Assistant encore à l’époque, ce qui fait que j’avais laissé ça de côté. De mémoire je n’ai pas rencontré de difficulté particulière. J’ai utilisé l’image officielle dispo sur Docker Hub, à savoir l’image eclipse-mosquitto. Les éléments tels que les volumes pour les dossiers config, data, et log et PUID / PGID sont à adapter en fonction de votre configuration.
zigbee2mqtt
Lien vers le dépôt officiel sur docker hub: https://hub.docker.com/r/koenkk/zigbee2mqtt
La configuration du container est relativement simple si on suit la doc ( https://www.zigbee2mqtt.io/guide/installation/02_docker.html ). Je mets une capture d’écran de ma config sur portainer ci-dessous. Tout n’est pas à recopier, là aussi par exemple les valeurs PUID et PGID dans les variables d’environnement sont propres à mon installation. De même pour le chemin du dossier /app/data, il faut adapter à votre environnement.
Déployer ensuite le container (bien penser à désactiver ZHA dans les intégrations Home Assistant si ce n’est pas déjà fait sinon z2m n’arrivera pas à configurer le dongle Zigbee). Une interface graphique doit être disponible sur l’ip du serveur sur le port exposé (pour ma part le 8082 parce que les 8080 et 8081 sont déjà utilisés). À partir de là on peut commencer à ajouter les périphériques Zigbee. Lors de chaque démarrage / redémarrage zigbee2mqtt est en mode appairage. Les périphériques découverts seront automatiquement ajoutés (il faut les réinitialiser s’ils étaient appairés auparavant) et peuvent être renommés via l’interface graphique de z2m.
Une étape qui m’a bien fait galérer et que je n’ai pas vue dans la doc de z2m. Dans le fichier de configuration (/app/data/configuration.yaml) par défaut la ligne homeassistant: est à false. Il faut la passer à true comme ci-dessous:
homeassistant: trueCette modif permet simplement à z2m de faire le lien avec l’intégration MQTT de Home Assistant, sans ça les périphériques détectés par z2m resteront invisibles dans HA.
Intégration MQTT
Normalement, une fois le broker installé (ici Mosquitto) et configuré sur le bon réseau, Home Assistant le détecte et propose de configurer l’intégration MQTT. Si ce n’est pas le cas il suffit de l’ajouter à la main (bouton en bas à droite de l’interface) ou de passer par le site home-assistant.io :
La configuration se fait sans problème, il suffit d’y renseigner l’ip de votre broker ainsi que le port:
Pour le reste la configuration par défaut fait le job.
Conclusion
Cet article a été écrit pour partie de mémoire (lors d’une installation il y a quelques temps) et en finissant l’installation et la configuration de certains éléments. J’ai rencontré quelques difficultés lors des installations et configurations. Il se peut donc qu’il y ait quelques manques ou erreur, même si après relecture je pense y avoir mis l’essentiel. Quoi qu’il en soit il y a certainement des choses à corriger ou des optimisations à apporter. N’hésitez pas à me faire remonter vos remarques sur vos difficultés ou vos suggestions d’améliorations en commentaire ou via la fiche contact.