Connecter des appareils Zigbee à Home Assistant avec Zigbee2MQTT et Mosquitto

Article de la série « Mon ordinateur Ubuntu » 
Actions et articles créés avec l’aide de Claude.ai et 100% testé et ajusté par moi.

Tu veux piloter une ampoule, une télécommande ou un capteur Zigbee depuis Home Assistant ? Ce tutoriel te guide pas à pas pour mettre en place la chaîne complète : Mosquitto comme broker MQTT, Zigbee2MQTT comme passerelle, et Home Assistant comme cerveau de ta domotique.

Ce que tu vas mettre en place

Les appareils Zigbee ne parlent pas directement à Home Assistant. Il faut une chaîne de traduction :

1. Le dongle Zigbee reçoit les messages de tes appareils Zigbee
2. Zigbee2MQTT traduit ces messages en MQTT
3. Mosquitto joue le rôle de boîte aux lettres : il reçoit et redistribue les messages MQTT
4. Home Assistant lit ces messages et crée automatiquement les entités correspondantes

Chaque composant est installé comme un container Docker, selon le même protocole que les autres services de ta stack.

Prérequis

• Home Assistant installé et accessible (voir les autres articles de la série)
• Docker et Portainer en place
• Le dongle Sonoff Zigbee 3.0 USB Dongle Lite MG21 branché sur ton PC Linux
• Un appareil Zigbee à appairer (ampoule, télécommande, capteur…)
• un système pour sauvegarder le contenu entier de /home/USER/docker/ , sous-répertoire inclus. Voir en particulier Sauvegarder ses containers Docker automatiquement avec Rclone.

Étape 1 – Identifier le port USB du dongle

Branche le dongle Sonoff MG21, puis lance cette commande :

ls /dev/serial/by-id/

Tu obtiens quelque chose comme :

usb-SONOFF_SONOFF_Dongle_Lite_MG21_c85bc664b7a3ef1188de4cbd61ce3355-if00-port0

Note ce nom exact, tu en auras besoin à l’étape 3.

Étape 2 – Identifier un port disponible pour Zigbee2MQTT

Zigbee2MQTT expose une interface web. Par défaut il utilise le port 8080, mais ce port est peut-être déjà pris par un autre container. Vérifie avec :

bash

sudo docker ps --format "table {{.Names}}\t{{.Ports}}"

Si le port 8080 est occupé (par Stirling-PDF par exemple), utilise le port 8081. Retiens le port disponible, tu en auras besoin à l’étape 3.

Étape 3 – Installer Mosquitto

Créer les répertoires

sudo mkdir -p /home/USER/docker/mosquitto/config
sudo mkdir -p /home/USER/docker/mosquitto/data
sudo mkdir -p /home/USER/docker/mosquitto/log

Créer le fichier de configuration

sudo nano /home/USER/docker/mosquitto/config/mosquitto.conf

Colle exactement ce contenu, sans rien d’autre avant ni après :

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

allow_anonymous true permet la connexion sans authentification. Ce n’est pas un problème car le port 1883 n’est pas exposé vers l’extérieur – il reste confiné au réseau local.

Créer la stack dans Portainer

Dans Portainer, crée une stack « mosquitto » avec ce YAML :

services:
  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:latest
    volumes:
      - /home/USER/docker/mosquitto/config:/mosquitto/config
      - /home/USER/docker/mosquitto/data:/mosquitto/data
      - /home/USER/docker/mosquitto/log:/mosquitto/log
    ports:
      - "1883:1883"
    restart: unless-stopped
    environment:
      TZ: Europe/Paris

Corriger les permissions du dossier log

Le container Mosquitto tourne avec l’utilisateur interne mosquitto (UID 1883). Sans cette correction, il ne peut pas écrire ses logs :

sudo chown -R 1883:1883 /home/USER/docker/mosquitto/log

Redémarre le container depuis Portainer. Vérifie les logs avec :

sudo docker logs mosquitto

Tu dois voir Restored 0 base messages et aucune erreur.

Sauvegarder le YAML

sudo nano /home/USER/docker/mosquitto/docker-compose.yml
# coller le YAML
sudo chown USER:USER /home/USER/docker/mosquitto/docker-compose.yml

Étape 4 – Installer Zigbee2MQTT

Créer le répertoire

sudo mkdir -p /home/USER/docker/zigbee2mqtt/data

Créer la stack dans Portainer

Dans Portainer, crée une stack « zigbee2mqtt » avec ce YAML. Remplace IDENTIFIANT_DU_DONGLE par le nom exact récupéré à l’étape 1, et PORT_EXTERNE par le port disponible identifié à l’étape 2 (8080 ou 8081) :

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt:latest
    volumes:
      - /home/USER/docker/zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "PORT_EXTERNE:8080"
    environment:
      TZ: Europe/Paris
    devices:
      - /dev/serial/by-id/IDENTIFIANT_DU_DONGLE:/dev/ttyACM0
    restart: unless-stopped

Point critique : la ligne devices: doit contenir le chemin exact du dongle. C’est le point le plus sensible de l’installation.

Sauvegarder le YAML

sudo nano /home/USER/docker/zigbee2mqtt/docker-compose.yml
# coller le YAML
sudo chown USER:USER/home/ald/docker/zigbee2mqtt/docker-compose.yml

Après démarrage, Zigbee2MQTT est accessible via http://IP_DU_PC:PORT_EXTERNE. Une page d’onboarding s’affiche – c’est normal, c’est le premier démarrage.

Compléter l’onboarding

Sur la page d’onboarding, sélectionne ton dongle dans la liste « Devices found » et clique sur Submit sans modifier les autres valeurs. Zigbee2MQTT génère alors automatiquement sa configuration.

Modifier le fichier de configuration

Après l’onboarding, modifie le fichier de configuration généré :

sudo nano /home/USER/docker/zigbee2mqtt/data/configuration.yaml

Apporte ces modifications, sans toucher au reste (network_key, pan_id, channel…) :

Redémarre le container depuis Portainer. Vérifie les logs :

sudo docker logs zigbee2mqtt

Tu dois voir Zigbee2MQTT started! et Connected to MQTT server.

Étape 5 – Connecter Home Assistant à MQTT

Dans Home Assistant : Paramètres > Appareils et services > Ajouter une intégration > MQTT

Remplis les champs :

• Broker : IP_DU_PC
• Port : 1883
• Nom d’utilisateur et mot de passe : laisser vides

Clique sur Valider. Si la connexion réussit, l’intégration MQTT apparaît dans ta liste de services.

Zigbee2MQTT et Home Assistant se découvrent alors automatiquement via MQTT Discovery.

Étape 6 – Appairer un premier appareil pour vérifier

C’est le test de tout ce qui précède ! Dans l’interface Zigbee2MQTT (http://IP_DU_PC:PORT_EXTERNE) :

1. Clique sur Autoriser l’appairage – le mode appairage est actif pendant 3 minutes
2. Mets ton appareil en mode appairage selon la procédure du fabricant (pour une ampoule Lidl : allumer et éteindre rapidement 3 fois)
3. L’appareil apparaît dans Zigbee2MQTT

Va ensuite dans Home Assistant : Paramètres > Appareils et services > MQTT. Ton appareil doit être visible et contrôlable.

Note sur les ampoules Zigbee : une ampoule Zigbee doit rester alimentée en permanence pour rester joignable sur le réseau. Si tu coupes le courant via l’interrupteur mural, elle disparaît du réseau. La bonne pratique est de ne plus utiliser l’interrupteur physique et de contrôler l’ampoule uniquement via Home Assistant ou une télécommande Zigbee.

Ce que tu as maintenant

• Un broker MQTT (Mosquitto) qui tourne en container Docker
• Une passerelle Zigbee (Zigbee2MQTT) connectée à ton dongle et à Mosquitto
• Home Assistant qui découvre automatiquement tous tes appareils Zigbee
• Une base solide pour ajouter d’autres appareils : capteurs de température, détecteurs d’ouverture, interrupteurs Zigbee…

La prochaine étape : créer des automatisations pour que tes appareils Zigbee travaillent ensemble.