Zigbee2MQTT avec Home Assistant en 2026: guide complet

Dans ce tutoriel, nous allons déployer Zigbee2MQTT avec Home Assistant sur un serveur auto-hébergé en utilisant Docker. Cela vous permettra d’intégrer vos appareils Zigbee tels que des ampoules intelligentes et des capteurs de température à votre écosystème domotique existant. Vous apprendrez comment installer le dongle Zigbee, configurer l’application Zigbee2MQTT et créer des automatisations dans Home Assistant pour contrôler vos appareils en toute autonomie.

Prérequis

OS : Ubuntu 24.04 LTS
Mini-PC ou NAS avec suffisamment de ressources (CPU, RAM)
Dongle Zigbee compatible (par exemple Energenie EDZB1943W)
Accès à un nom de domaine ou IP statique
Ports 8123 et 1883 ouverts

Installation pas à pas

Étape 1 : Installer Docker et Docker Compose

Installez Docker sur votre serveur en utilisant les commandes suivantes :

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER

Puis installez Docker Compose via la commande :

sudo apt-get install docker-compose

Étape 2 : Cloner le répertoire Zigbee2MQTT

Clonez le dépôt officiel de Zigbee2MQTT à l’aide de la commande suivante :

git clone https://github.com/Koenkk/zigbee2mqtt.git ~/zigbee2mqtt

Étape 3 : Configurer Zigbee2MQTT

Créez un fichier configuration.yaml dans le répertoire ~/zigbee2mqtt en ajoutant les paramètres requis pour votre serveur et votre dongle. Par exemple, voici une configuration basique :

bridge:
 port: 1883
 mqtt:
 base_topic: zigbee2mqtt
 server: 'tcp://localhost:1883'
devices:
 - name: "Energenie EDZB1943W"
 friendly_name: "Dongle Zigbee"
zigbee:
 channel: 25 # Choisissez un canal non utilisé

Étape 4 : Créer le fichier docker-compose.yml

Créez un nouveau fichier docker-compose.yml dans le répertoire de travail pour Docker Compose. Utilisez la configuration suivante :

docker-compose:
version: '3'
services:
 zigbee2mqtt:
 container_name: zigbee2mqtt
 image: koenkk/zigbee2mqtt
 restart: always
 volumes:
 - /path/to/your/configuration:/app/data/configuration.yaml
 environment:
 - TZ=Europe/Paris # Ajustez selon votre fuseau horaire

Étape 5 : Lancer Zigbee2MQTT via Docker Compose

Lancez le service Zigbee2MQTT en utilisant la commande suivante :

docker-compose up -d

Étape 6 : Appairage d’appareils Zigbee

Connectez votre dongle Zigbee au serveur et accédez à l’interface web de Zigbee2MQTT via http://localhost:8081. Suivez les instructions pour apparer vos appareils Zigbee. Vérifiez que chaque appareil est correctement répertorié dans la liste des appareils.

Étape 7 : Intégrer Zigbee2MQTT à Home Assistant

Dans l’interface de configuration de Home Assistant, ajoutez un nouveau service MQTT sous ‘Configuration > Services’. Configurez les paramètres d’accès pour votre serveur Zigbee2MQTT. Ensuite, créez des automatisations dans Home Assistant en utilisant la fonctionnalité intégrée MQTT.

Vérifications

Vérifiez le bon fonctionnement de l’installation avec ces commandes :

docker ps # Vérifie que Zigbee2MQTT est en cours d'exécution

Accédez à http://localhost:8081 et vérifiez la liste des appareils appairés. Utilisez l’interface Home Assistant pour tester les automatisations MQTT.

Sécurité et bonnes pratiques

Pour sécuriser votre installation, activez HTTPS sur le serveur via Caddy ou Let’s Encrypt. Assurez-vous d’utiliser des mots de passe forts et de configurer la deuxième authentification à facteur (2FA) si possible. Mettez régulièrement à jour les logiciels pour prévenir les vulnérabilités.

Dépannage : erreurs courantes

Symptôme : Zigbee2MQTT ne démarre pas
Cause : Configuration docker-compose incorrecte ou erreur de chemin vers le fichier YAML.
Correctif : Vérifiez la configuration docker-compose.yml et les droits d’accès au répertoire.
Symptôme : Appairage échoué
Cause : Canal Zigbee saturé ou appareil non compatible.
Correctif : Essayez un autre canal ou une autre version du firmware de l’appareil.
Symptôme : Home Assistant ne détecte pas les messages MQTT
Cause : Configuration incorrecte du service MQTT dans Home Assistant.
Correctif : Vérifiez le nom d’hôte et le port du serveur Zigbee2MQTT.

FAQ

La configuration YAML est-elle obligatoire ?

Non, elle n’est pas nécessaire si vous préférez configurer manuellement l’application. Cependant, elle facilite la gestion des paramètres.

Quels sont les appareils Zigbee pris en charge ?

Vérifiez le répertoire devices du dépôt GitHub officiel de Zigbee2MQTT pour une liste complète et à jour des appareils compatibles.

Comment configurer la mise à jour automatique de Home Assistant ?

Utilisez l’intégration ‘HACS’ (Home Assistant Community Store) pour installer et gérer les mises à jour d’applications tierces.

A lire aussi

Heberger ce service

Pas envie de gerer le materiel ni la maintenance ? Ce type de service s’auto-heberge sur un VPS manage, pret en quelques minutes. Voir les offres PlanetHoster