Comment installer Zigbee2MQTT LXC sous Proxmox ?

Nous avons probablement vu toutes les manières différentes d’installer Zigbee2MQTT sur le blog, sauf une. Et dans la continuité de notre série Proxmox, je me devais de vous proposer un guide pour le déployer sous un conteneur LXC Proxmox de sorte à compléter l’offre de virtualisation domotique.

J’annonce tout de suite, installer et gérer Zigbee2MQTT sous conteneur Proxmox n’est pas la manière la plus simple. Plus technique, elle n’est pas forcément plus complexe en soit, mais nécessite tout de même quelques compétences en informatique, ou à minima, une volonté à se confronter à la ligne de commande Linux, ses petits caprices et au debug.

Bien que je vous livre un guide pas à pas évitant les différentes erreurs, même si gérer Zigbee2MQTT sous un conteneur LXC est une excellente manière de le gérer dans un environnement domotique safe et structuré, il est important de signaler cela en préambule.

Si vous nous vous sentez pas à l’aise avec la ligne de commande ou ne voulez pas vous embêter avec de la maintenance par la suite, optez plutôt pour une installation sous VM Home Assitant à l’aide de notre guide All inclusive.

Si en revanche vous avez l’esprit technique, suivez moi, nous allons déployer Z2M sous LXC pour gérer le réseau Zigbee sous Proxmox.

Les prérequis nécessaires à Zigbee2MQTT

Avant de passer à l’installation de Z2M sur votre Proxmox, il faut commencer par vérifier que vous remplissez bien les conditions. Qui dit “Zigbee” 2 “MQTT”, dit nécessité de disposer d’un contrôleur Zigbee (dongle), ainsi que d’un broker MQTT sur lequel raccorder Z2M. On vous explique comment le faire dans le guide ci-dessous, là aussi dans un conteneur LXC.

---

Le contrôleur Zigbee

Plusieurs options, la plus commune est l’utilisation d’un Dongle USB, Conbee II, Sonoff ZBDongle ou encore Skyconnect sont les plus connus.

Puis il y a le contrôleur Zigbee sur le réseau local, c’est personnellement le choix que j’ai fait, plus flexible et plus performant, il ne coûte pas plus cher en plus. Le SLZB-06 est un excellent choix, disponible dans deux versions selon votre préference.

Le broker MQTT

Concernant le broker, étant dans une logique d’implémentation sous Proxmox, je vous recommande chaudement d’envisager de déployer aussi votre broker MQTT sous Proxmox. Nous avons un guide pas à pas à suivre pour y parvenir.

Déploiement de Zigbee2MQTT sous conteneur LXC Proxmox en une commande

Pour lancer l’installation de Z2M sous Proxmox, rendez-vous sur le noeud principal de votre hyperviseur Proxmox, puis sous le menu Shell pour y lancer la commande ci-dessous.

bash -c "$(wget -qLO - https://github.com/tteck/Proxmox/raw/main/ct/zigbee2mqtt.sh)"

L’assistant d’installation s’affiche alors à l’écran, vous n’avez qu’à simplement répondre Yes pour toutes les questions proposées.

Le script d’installation se charge d’appliquer la meilleure configuration pour le conteneur avec les paramètres par défaut, donc laissez simplement faire l’assistant qui allouera 2 vCPU, 1Go de mémoire RAM et 4Gb d’espace disque au conteneur.

Le script déroule les différentes étapes de l’installation pour vous, il n’y a qu’à patienter quelques instants.

À la fin de l’installation, le script vous demande si vous désirez configurer Z2M sur la branche de production “EDGE” ou de développement, répondez “N” pour assurer d’utiliser la bonne version stable du système.

C’est terminé ! Pour l’installation, car il y a maintenant un peu de paramétrage à effectuer.

Edition de la configuration de Zigbee2MQTT

Maintenant que l’installation de Zigbee2MQTT est effective sous un conteneur, LXC, il faut passer à la configuration. La configuration de Z2M se base sur un unique fichier de config, c’est assez simple, la difficulté réside surtout dans les types de paramètres à utiliser selon votre installation.

Pour ouvrir le fichier de configuration, utiliser la commande suivante, toujours sous la section Shell du conteneur.

nano /opt/zigbee2mqtt/data/configuration.yaml

Par défaut, le fichier de configuration de Zigbee2MQTT ressemble à cela :

Voyons maintenant les différents paramètres à ajouter à ce fichier suivant votre configuration.

Configurer MQTT

Comme son nom l’indique, ZéM utilise un broker MQTT pour transmettre les états et actions au système domotique. Il faut donc pour cela indiquer les paramètres de connexion vers le serveur MQTT de votre réseau local, que vous aurez au préalable mis en service sur un autre conteneur LXC comme on vous l’explique dans un précédent guide.

Pour cela vous allez simplement éditer la partie mqtt du fichier de configuration avec les lignes suivantes, en veillant à modifier l’adresse IP, l’identifiant et le mot de passe avec les informations propres à votre broker MQTT.

mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://192.168.86.224:1883'
  user: usr
  password: pwd
  keepalive: 60
  reject_unauthorized: true

Configurer le port du contrôleur suivant le contrôleur USB

Si vous utilisez un contrôleur Zigbee local de type USB connecté au PC qui fait tourner votre Proxmox, vous devrez indiquer le port utilisé ainsi que le type de contrôleur dans la section serial de la configuration, plus particulièrement le type de contrôleur utilisé pour utiliser le bon pilote.

serial:
  port: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
  #adapter: deconz	#(decommenter pour ConBee II)
  #adapter: ezsp    #(decommenter pour Sonoff Zigbee 3.0 USB Dongle Plus V2 model "ZBDongle-E version")
  #adapter: ember    #(decommenter pour Skyconnect / ZBDongle-E)

Notez que le pilot ezsp sera décommissionné dans la prochaine version de Z2M au profit de ember pour les contrôleurs à base de puce EFR32.

Bon à savoir

Pour déterminer l’adresse du port à indiquer vous pouvez utiliser la commande dmesg toujours dans la partie Shell du conteneur Proxmox. Il existe deux manières de joindre un port USB sous Linux. Dans la mesure du possible, vous devez utiliser le chemin absolu du port de type /dev/serial/by-id/ au lieu de l’adresse virtuelle de type /dev/tty*.

En effet, le port de type /dev/tty* peut changer après un redémarrage et conduire à une défaillance de Z2M. Par exemple, /dev/ttyACM0 peut devenir /dev/ttyACM1 après un simple redémarrage puis revenir plus tard à /dev/ttyACM0.

Si ce n’est pas dramatique en soit, cela va conduire à des défaillances au redémarrage de Zigbee2MQTT, vous obligeant à investiguer pour identifier le nom du nouveau port et le corriger dans le fichier de configuration .En revanche, le chemin de type /dev/serial/by-id/ ne changera pas.

Configuration du port dans le cas du contrôleur Ethernet

Nous l’avons vu dernièrement, il y a mieux que le contrôleur USB, il y a le contrôleur sur le réseau local, en PoE même comme le SLZB-06, celui que j’utilise dans mon installation. Dans le cas où vous utilisez ce type de contrôleur Zigbee sur réseau local, vous devrez configurer la section serial du fichier de configuration comme cela :

serial:
  port: tcp://192.168.1.167:6638
  baudrate: 115200
  adapter: zstack

On vient simplement indiquer l’adresse IP du contrôleur et son port et indiquer le débit de travail et le type d’adapter “zstack” pour là encore indiquer à Z2M le pilote à utiliser pour communiquer avec le contrôleur.

Activation de l’interface web

Autre point important, vous devez ajouter le code suivant dans le fichier de configuration pour activer l’interface web (frontend) pour gérer Zigbee2MQTT plus simplement depuis votre navigateur.

frontend:
  port: 8081

Vous n’aurez alors qu’à utiliser votre navigateur web habituel pour gérer votre réseau domotique Zigbee via l’URL http://ipdezigbee2MQTT:8081. Ce qui est toujours plus simple que via la ligne de commande.

Activation de la découverte auto Home Assistant

Enfin, si votre objectif est d’utiliser Zigbee2MQTT avec la domotique Home Assistant, passez à true la premier section du fichier de configuration.

homeassistant: true

Démarrage de Zigbee2MQTT

Maintenant que notre serveur Zigbee2MQTT est configuré, il est temps de le démarrer pour en valider le fonctionnement. Pour cela, toujours sous la ligne de commande Shell, jouez simplement la commande suivante :

cd /opt/zigbee2mqtt && npm start

Si vous n’avez aucune erreur et que la ligne de commande affiche Zigbee2MQTT started ! Votre système est prêt.

Problèmes et solutions

Mais bien souvent, il y a quelques petits ajustements à faire. Je vous le disais en introduction, ce n’est pas la méthode la plus simple de déployer Zigbee2MQTT, même si c’est une des meilleures qui une fois configurée vous assure un système simple, fiable et indépendant. Encore plus sous Proxmox avec la virtualisation, les snapshots et sauvegardes qui assurent une restauration éclair en cas de problème.

Mais le premier démarrage n’est pas toujours immédiat et parfois, il faut chercher un peu. Voici les erreurs que j’ai rencontrées de mon côté et les paramètres/actions pour corriger ces erreurs.

Problème d’indentation dans le fichier de configuration

Tout comme sous la configuration de la domotique Home Assistant, l’indentation à une grande importance. Et vous n’êtes pas à l’abri d’une erreur “bête” au démarrage de Zigbee2MQTT si vous avez glissé un espace de trop dans le fichier de configuration.

Les problèmes d’indentation sont assez simples, puisque l’erreur est affiché à l’écran en retour du démarrage défaillant. Allez simplement corriger cette erreur dans le fichier et relancer la commande de démarrage pour confirmer que c’est OK.

Problème de configuration du contrôleur Zigbee sur le réseau local

J’ai reçu deux erreurs sur le démarrage de mon Zigbee2MQTT à la première mise en service. La première était que j’avais indiqué le nom DNS (http://slzb-06-2.local) mais cela empêchait Zigbee2MQTT de démarrer.

Indiquez plutôt l’adresse IP que le nom, DNS a corrigé la première erreur.

serial:
  port: tcp://192.168.1.167:6638

Après cela, il n’y avait plus d’erreur au niveau du démarrage de la partie Zigbee-herdsman, mais un peu plus loin.

Pour corriger le dernier problème, j’ai simplement ajouté dans le fichier de configuration l’instruction de génération pour pan_id ainsi que la clé réseau et un numéro de channel. Ajoutez simplement une section advanced à votre fichier comme ci-dessous :

advanced:
  pan_id: GENERATE
  network_key: GENERATE
  channel: 20

Lancez enfin une nouvelle tentative de démarrage et cela devrait être OK.

Confirmez cela via votre navigateur web en accédant à la page d’administration qui n’est accessible que quand Z2M est correctement démarré et opérationnel, vous visualisez la page, votre Zigbee2MQTT est fin prêt.

Conclusion

Avant de passer à la configuration de vos premiers périphériques Zigbee, je vous conseille vivement de mettre en place une sauvegarde de votre conteneur en suivant notre guide pas à pas. Vous aurez alors un Zigbee2MQTT pleinement opérationnel et surtout sécurisé.

---