La domotique, ou l’art de rendre sa maison intelligente, repose sur une communication fiable et efficace entre une multitude d’appareils. Au cœur de cet écosystème, le protocole Zigbee s’est imposé comme un standard de fait pour de nombreux capteurs et actionneurs. Cependant, pour s’affranchir des passerelles propriétaires des fabricants et gagner en flexibilité, des solutions ouvertes comme Zigbee2mqtt ont vu le jour. Coupler cette application avec la puissance de la virtualisation offerte par Proxmox et la légèreté des conteneurs LXC représente une approche à la fois robuste, performante et économe en ressources. Ce guide détaillé explore la méthode d’installation de Zigbee2mqtt au sein d’un conteneur LXC sur un serveur Proxmox, une solution plébiscitée par les amateurs de domotique avancée pour sa stabilité et son évolutivité.
Introduction à Zigbee2mqtt et Proxmox
Qu’est-ce que Zigbee2mqtt ?
Zigbee2mqtt est un projet open source qui fait le pont entre vos appareils Zigbee et un broker MQTT. En termes simples, il permet à des appareils de marques différentes de communiquer entre eux via un langage commun, le MQTT, sans avoir besoin de leurs passerelles respectives. L’un des principaux avantages de cette solution est sa compatibilité étendue, prenant en charge des milliers d’appareils issus de centaines de fabricants. Pour fonctionner, Zigbee2mqtt requiert un coordinateur Zigbee, qui se présente généralement sous la forme d’une clé USB. Cet élément matériel est indispensable pour créer et gérer le réseau maillé Zigbee.
- Indépendance : Vous n’êtes plus dépendant des écosystèmes fermés des fabricants.
- Contrôle local : Toutes les communications restent sur votre réseau local, sans passer par des serveurs externes, ce qui renforce la sécurité et la confidentialité.
- Flexibilité : Intégration aisée avec la plupart des logiciels de domotique comme Home Assistant, Jeedom ou Domoticz.
Le choix du coordinateur est crucial pour la performance et la stabilité de votre réseau. Il existe de nombreux modèles sur le marché, chacun avec ses spécificités.
-
SONOFF ZigBee 3.0 USB Dongle Plus, EFR32MG21 Coordinator, Universelle USB ZigBee Hub, Passerelle ZigBee pour Home Assistant -
SONOFF Zigbee 3.0 & Thread Dongle Lite (EFR32MG21) | Coordinateur de clé USB pour Home Assistant & Zigbee2MQTT | Passerelle compacte avec Fonction Flash Simple firmware et rallonge -
Phoscon ConBee II - passerelle USB Universelle Zigbee 3.0, y Compris Application deCONZ & Phoscon, domotique, Assistant Domestique, ioBroker, Zigbee2MQTT
L’écosystème Proxmox et les conteneurs LXC
Proxmox Virtual Environment (VE) est une plateforme de virtualisation de serveurs, également open source, qui permet de gérer des machines virtuelles (VM) et des conteneurs. Alors qu’une VM émule un ordinateur complet avec son propre noyau de système d’exploitation, un conteneur LXC (Linux Containers) est beaucoup plus léger. Les conteneurs partagent le noyau du système d’exploitation de l’hôte Proxmox, ce qui se traduit par une consommation de ressources (CPU, RAM) nettement inférieure et un démarrage quasi instantané.
Pourquoi combiner ces deux technologies ?
L’association de Zigbee2mqtt et d’un conteneur LXC sur Proxmox offre le meilleur des deux mondes. Vous bénéficiez d’un service isolé, facile à gérer, à sauvegarder et à migrer, tout en consommant un minimum de ressources sur votre serveur. Cette approche permet de dédier un environnement propre et optimisé à votre passerelle Zigbee, garantissant ainsi une stabilité maximale pour un élément aussi critique de votre installation domotique. La gestion centralisée via l’interface web de Proxmox simplifie grandement l’administration au quotidien.
Maintenant que les concepts et les avantages de cette architecture sont clairs, la première étape pratique consiste à préparer l’environnement qui accueillera notre application, c’est-à-dire le conteneur LXC lui-même.
Préparation du conteneur LXC sur Proxmox
Création du conteneur LXC
La création du conteneur se fait directement depuis l’interface web de Proxmox. Il est recommandé d’utiliser un template de système d’exploitation récent et stable, comme Debian 12 ou Ubuntu 22.04. Lors du processus de création, plusieurs paramètres sont à définir. Il est conseillé de leur attribuer des valeurs raisonnables qui pourront être ajustées plus tard si nécessaire.
| Paramètre | Valeur recommandée | Description |
|---|---|---|
| Hostname | zigbee2mqtt | Nom du conteneur sur le réseau. |
| Template | Debian 12 (Standard) | Système d’exploitation de base. |
| Disque | 4 Go | Espace de stockage suffisant pour l’application et ses logs. |
| CPU Cores | 1 | Zigbee2mqtt est peu gourmand en puissance de calcul. |
| Mémoire (RAM) | 512 Mo | Largement suffisant pour la plupart des installations. |
| Réseau | DHCP ou IP statique | Une IP statique est recommandée pour un accès fiable. |
Une fois ces paramètres définis, Proxmox créera le conteneur en quelques secondes. Ne démarrez pas le conteneur immédiatement, une étape cruciale de configuration matérielle doit être réalisée au préalable.
Configuration du « passthrough » USB
Pour que Zigbee2mqtt puisse communiquer avec le coordinateur Zigbee, le conteneur LXC doit avoir un accès direct au port USB sur lequel la clé est branchée. Cette opération est appelée passthrough. Elle se configure en modifiant le fichier de configuration du conteneur sur le nœud Proxmox. D’abord, identifiez le périphérique USB depuis le shell de Proxmox avec la commande lsusb. Ensuite, éditez le fichier /etc/pve/lxc/ID_DU_CONTENEUR.conf et ajoutez les lignes suivantes à la fin du fichier, en adaptant les valeurs si nécessaire :
lxc.cgroup2.devices.allow: c 188:* rwm lxc.mount.entry: /dev/bus/usb/001/002 dev/bus/usb/001/002 none bind,optional,create=file
Ces lignes autorisent le conteneur à accéder au périphérique USB spécifié. Le chemin exact peut varier en fonction de votre configuration matérielle.
Premiers pas dans le conteneur
Vous pouvez maintenant démarrer votre conteneur depuis l’interface Proxmox et ouvrir une console. La première chose à faire est de mettre à jour le système d’exploitation. Pour un système basé sur Debian ou Ubuntu, les commandes sont les suivantes :
apt update apt upgrade -y
Cette étape garantit que tous les paquets sont à jour et que les dépendances nécessaires à l’installation de Zigbee2mqtt seront disponibles dans leurs versions les plus récentes et sécurisées.
Avec un conteneur vierge, à jour et correctement configuré pour accéder au matériel nécessaire, nous disposons d’une base saine pour procéder à l’installation de l’application elle-même.
Installation de Zigbee2mqtt dans le conteneur LXC
Installation des dépendances nécessaires
Zigbee2mqtt repose sur l’environnement d’exécution JavaScript Node.js. Il nécessite également d’autres outils comme Git pour récupérer le code source et des paquets de compilation. L’installation de toutes ces dépendances se fait simplement via le gestionnaire de paquets :
- Node.js et npm : Le moteur d’exécution et son gestionnaire de paquets.
- Git : Pour cloner le dépôt officiel de Zigbee2mqtt.
- make, g++, gcc : Outils de compilation requis pour certaines dépendances de Node.js.
Exécutez la commande suivante pour installer l’ensemble de ces prérequis : apt install -y nodejs npm git make g++ gcc
Clonage du dépôt et installation
L’installation recommandée consiste à cloner le projet depuis son dépôt GitHub dans le répertoire /opt, qui est la convention pour les logiciels tiers sur Linux. Suivez ces étapes :
- Se placer dans le bon répertoire : cd /opt
- Cloner le projet : git clone https://github.com/Koenkk/zigbee2mqtt.git Zigbee2MQTT
- Changer le propriétaire du répertoire : chown -R VOTRE_UTILISATEUR:VOTRE_UTILISATEUR /opt/Zigbee2MQTT
- Se déplacer dans le répertoire du projet : cd Zigbee2MQTT
- Installer les dépendances du projet : npm ci
La commande npm ci lit le fichier package-lock.json pour installer les versions exactes des dépendances, assurant une installation reproductible et stable.
Mise en place du service systemd
Pour que Zigbee2mqtt se lance automatiquement au démarrage du conteneur et soit géré comme un service système, il est indispensable de créer un fichier de service pour systemd. Créez le fichier /etc/systemd/system/zigbee2mqtt.service et insérez-y le contenu suivant :
[Unit] Description=zigbee2mqtt After=network.target [Service] ExecStart=/usr/bin/npm start WorkingDirectory=/opt/Zigbee2MQTT StandardOutput=inherit StandardError=inherit Restart=always User=VOTRE_UTILISATEUR [Install] WantedBy=multi-user.target
N’oubliez pas de remplacer VOTRE_UTILISATEUR par l’utilisateur qui exécutera le service. Ensuite, activez et démarrez le service avec les commandes :
systemctl enable zigbee2mqtt.service systemctl start zigbee2mqtt.service
Le logiciel est désormais installé et configuré pour fonctionner en continu. L’étape suivante consiste à le paramétrer pour qu’il communique correctement avec votre matériel et votre serveur MQTT.
Configuration et personnalisation de Zigbee2mqtt
Le fichier de configuration principal : configuration.yaml
Toute la configuration de Zigbee2mqtt est centralisée dans un unique fichier : /opt/Zigbee2MQTT/data/configuration.yaml. Ce fichier est créé au premier lancement de l’application. Il est écrit au format YAML, qui est sensible à l’indentation. Une attention particulière doit donc être portée à la structure du fichier lors de sa modification. Les sections principales à configurer concernent la connexion au broker MQTT, le port série du coordinateur Zigbee et l’activation de l’interface web.
Configuration du port série et du broker MQTT
Cette section est la plus critique. Vous devez indiquer à Zigbee2mqtt où trouver le coordinateur USB et comment se connecter à votre broker MQTT.
| Paramètre | Exemple de valeur | Description |
|---|---|---|
| homeassistant | true | Active la découverte automatique pour Home Assistant. |
| permit_join | false | Par défaut, l’appairage est désactivé pour des raisons de sécurité. |
| mqtt: base_topic | zigbee2mqtt | Le sujet de base pour tous les messages MQTT. |
| mqtt: server | ‘mqtt://192.168.1.10:1883’ | L’adresse de votre broker MQTT. |
| mqtt: user | mqtt_user | Le nom d’utilisateur pour la connexion MQTT. |
| mqtt: password | ‘votre_mot_de_passe’ | Le mot de passe pour la connexion MQTT. |
| serial: port | ‘/dev/ttyACM0’ | Le chemin vers votre coordinateur Zigbee. |
Après chaque modification de ce fichier, il est impératif de redémarrer le service pour que les changements soient pris en compte : systemctl restart zigbee2mqtt.
Activation de l’interface web (frontend)
Zigbee2mqtt propose une interface web très pratique pour visualiser le réseau, gérer les appareils et lancer l’appairage. Pour l’activer, ajoutez ou modifiez la section frontend dans votre fichier configuration.yaml :
frontend: port: 8080
Une fois le service redémarré, l’interface sera accessible à l’adresse http://IP_DU_CONTENEUR:8080. Cette interface graphique simplifie considérablement l’administration quotidienne de votre réseau Zigbee.
Une fois l’application installée et configurée, il est primordial de s’assurer que tout fonctionne comme prévu et de savoir comment diagnostiquer les éventuels problèmes.
Vérification et mise à jour de la configuration
Démarrage et consultation des journaux
La première source d’information pour vérifier le bon fonctionnement de Zigbee2mqtt est ses journaux (logs). Vous pouvez les consulter en temps réel avec la commande suivante :
journalctl -u zigbee2mqtt.service -f
Les messages importants à rechercher sont la connexion réussie au broker MQTT et la détection correcte du coordinateur Zigbee. Toute erreur dans le fichier de configuration ou problème de communication avec le matériel sera clairement indiquée ici. C’est le premier réflexe à avoir en cas de dysfonctionnement.
Appairage du premier appareil Zigbee
Le test ultime consiste à appairer un appareil. Pour ce faire, activez le mode appairage (permit join) via l’interface web ou en publiant un message MQTT sur le topic zigbee2mqtt/bridge/request/permit_join avec le payload true. Ensuite, mettez votre appareil Zigbee, comme une ampoule connectée ou un capteur de température, en mode appairage en suivant les instructions du fabricant. Vous devriez voir apparaître des messages dans les logs indiquant la détection et l’interview de l’appareil, qui sera ensuite visible dans l’interface web.
-
NOUS P3Z Ampoule intelligente ZigBee RGB E27, Compatible avec Alexa,Hue Bridge, Google Home, Home Assistant, 16 Millions de Couleurs, Contrôle Vocal et Par Application, 2700-6500K -
NOUS P3Z Ampoule intelligente ZigBee RGB E27, Compatible avec Alexa,Hue Bridge, Google Home, Home Assistant, 16 Millions de Couleurs, Contrôle Vocal et Par Application, 2700-6500K -
Osram Lampe LED SMART A60 forme d'ampoule E27, 9 W ZigBee 3.0, intensité variable 2700 K blanc chaud, contrôle par application, Alexa, Google Assistant
Gestion des erreurs courantes
Quelques problèmes peuvent survenir lors de la première mise en route. Voici les plus fréquents et leurs solutions :
- Erreur de connexion MQTT : Vérifiez l’adresse du serveur, le port, le nom d’utilisateur et le mot de passe dans configuration.yaml. Assurez-vous que le broker MQTT est bien accessible depuis le conteneur LXC.
- Coordinateur non trouvé : L’erreur la plus commune est liée au passthrough USB. Vérifiez que le chemin du port série (/dev/ttyACM0 par exemple) est correct et que les permissions sont bien configurées dans le fichier .conf du conteneur sur Proxmox.
- Interface web inaccessible : Contrôlez que le port défini (par exemple 8080) n’est pas bloqué par un pare-feu et que la section frontend est correctement configurée.
Un système fonctionnel est une excellente chose, mais pour garantir sa pérennité et sa sécurité, il est nécessaire de le maintenir à jour et de prévoir des stratégies de sauvegarde.
Maintenance et mise à jour de Zigbee2mqtt
Procédure de mise à jour sécurisée
Les développeurs de Zigbee2mqtt publient très régulièrement des mises à jour qui ajoutent le support de nouveaux appareils et corrigent des bugs. La procédure de mise à jour est simple et sécurisée. Elle s’effectue directement depuis le shell du conteneur :
- Arrêter le service Zigbee2mqtt : systemctl stop zigbee2mqtt
- Se déplacer dans le répertoire de l’application : cd /opt/Zigbee2MQTT
- Télécharger les dernières modifications : git pull
- Mettre à jour les dépendances : npm ci
- Redémarrer le service : systemctl start zigbee2mqtt
Il est conseillé de consulter les notes de version (release notes) avant chaque mise à jour pour être informé des changements importants.
Sauvegarde de la configuration et des données
La sauvegarde est un élément non négociable de toute installation informatique critique. Pour Zigbee2mqtt, les données les plus importantes se trouvent dans le répertoire /opt/Zigbee2MQTT/data. Ce dossier contient :
- configuration.yaml : Votre fichier de configuration.
- database.db : La base de données de tous vos appareils appairés.
- state.json : L’état actuel des appareils.
La perte de ces fichiers signifierait devoir ré-appairer tous vos appareils. Heureusement, Proxmox intègre une fonctionnalité de sauvegarde très performante. Il suffit de programmer des sauvegardes régulières de votre conteneur LXC pour être à l’abri. Ces sauvegardes peuvent être stockées sur un serveur de fichiers distant pour plus de sécurité.
-
UGREEN NASync DH2300 NAS Bureau 2 Baies, 4Go RAM, Connexion NFC One-Touch, LAN 1GbE, Album Photo IA, Système NAS Facile pour Débutants, Serveur NAS Maison (sans Disque) -
UGREEN NASync DH4300 Plus NAS de Bureau 4 Baies, Port LAN 2,5 GbE, 8 Go RAM, Connexion NFC One-Touch, Album Familial/Bébé AI, Cloud Personnel pour Maison/Bureau (sans Disques) -
UGREEN NASync DXP4800 Plus, NAS 4 Baies, Intel Pentium Gold 8505 (5 cœurs), 8Go DDR5, 128Go SSD, 10GbE + 2,5GbE, 2 emplacements M.2 NVMe, HDMI 4K (sans Disque (DXP4800 Plus)
Bonnes pratiques pour la stabilité du système
Pour assurer la longévité et la fiabilité de votre installation, quelques bonnes pratiques sont à observer. Pensez à mettre à jour régulièrement le système d’exploitation du conteneur avec apt update && apt upgrade. Surveillez l’espace disque utilisé, notamment par les fichiers de log. Enfin, documentez votre configuration, en particulier les choix d’adresses IP et les modifications apportées aux fichiers de configuration. Une bonne documentation vous fera gagner un temps précieux lors de futures interventions.
Mettre en place Zigbee2mqtt sur Proxmox via un conteneur LXC est une démarche qui allie performance, isolation et efficacité des ressources. En suivant les étapes de préparation du conteneur avec le passthrough USB, l’installation de l’application et sa configuration minutieuse, vous obtenez une passerelle Zigbee universelle, puissante et entièrement sous votre contrôle. Cette architecture offre une base solide pour construire un écosystème domotique ouvert, fiable et évolutif, libéré des contraintes des solutions propriétaires.
