Zigbee2MQTT : tous ses appareils Zigbee dans Home Assistant sans cloud

Le protocole Zigbee permet à des dizaines d’appareils domotiques de communiquer entre eux et avec un coordinateur central, sans Wi-Fi, sans cloud, avec une autonomie de pile mesurée en années. Le problème : par défaut, ces appareils sont liés à des applications propriétaires. Zigbee2MQTT coupe ce lien et expose tout à Home Assistant via MQTT.

Ce que fait Zigbee2MQTT

Zigbee2MQTT (Z2M) joue le rôle de passerelle entre le réseau Zigbee physique et l’écosystème domotique. Le coordinateur (la clé USB) parle Zigbee avec les appareils, Z2M traduit ces messages en JSON sur un broker MQTT, et Home Assistant consomme ce flux via l’intégration MQTT.

Les avantages concrets par rapport à une solution cloud :

• Zéro dépendance cloud : les appareils fonctionnent si Internet tombe
• Latence inférieure à 100ms : tout reste en local
• Compatibilité large : Z2M supporte plus de 3000 appareils de marques différentes
• Mises à jour OTA : firmware des appareils géré depuis Z2M
• Réseau maillé : les appareils sur secteur servent de routeurs pour étendre la portée

Pourquoi Docker sur la machine prioritaire

Z2M est un service critique : si il tombe, tous les automatismes Zigbee s’arrêtent. Je le fais tourner en Docker sur ma machine débit prioritaire, celle qui ne s’arrête jamais et qui tourne 24/7. Pas dans la VM Home Assistant, pas dans un add-on HA : un conteneur Docker indépendant avec restart: unless-stopped.

Ça découple aussi le cycle de vie de Z2M de celui de HA : je peux redémarrer Home Assistant sans toucher au service Zigbee, et inversement.

Installation via Docker Compose (Dockge)

Je gère la stack depuis Dockge. Le compose est minimal :

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - /opt/stacks/zigbee2mqtt/data:/app/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 8080:8080
    environment:
      - TZ=Europe/Paris
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXX:/dev/ttyACM0

Le point clé : passer la clé USB via devices avec son identifiant stable (/dev/serial/by-id/) plutôt que /dev/ttyUSB0 qui peut changer au redémarrage. L’identifiant complet est visible avec :

ls /dev/serial/by-id/

Configuration Z2M

Avant le premier démarrage, créer le fichier /opt/stacks/zigbee2mqtt/data/configuration.yaml :

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://IP_BROKER:1883
  user: MQTT_USER
  password: MQTT_PASSWORD

serial:
  port: /dev/ttyACM0

frontend:
  enabled: true
  port: 8080

homeassistant:
  enabled: true

La ligne homeassistant: enabled: true active la découverte automatique dans HA : chaque appareil appairé apparaît directement dans Home Assistant sans configuration manuelle.

Le coordinateur : Sonoff USB Dongle Plus

J’utilise le Sonoff Zigbee 3.0 USB Dongle Plus (CC2652P). C’est le coordinateur le plus courant dans la communauté Z2M : bon support, firmware maintenu, supporte 100+ appareils en réseau maillé.

Limite actuelle : c’est un câble USB relié physiquement à la machine. Je prépare la migration vers un coordinateur Ethernet/PoE (type SLZB-06), ce qui permettra de placer le coordinateur où le signal Zigbee est optimal, indépendamment de l’emplacement du serveur. Z2M supporte nativement les coordinateurs en TCP, la migration se fait en une ligne de config.

Appairage des appareils

L’interface web Z2M (port 8080) centralise tout. Pour ajouter un appareil : ouvrir l’appairage depuis le bouton « Autoriser l’appairage », mettre l’appareil en mode appairage (reset bouton ou procédure selon le modèle), Z2M le détecte et lui assigne un nom convivial.

L’interface montre en temps réel l’activité du réseau : messages entrants, valeurs des capteurs, LQI (qualité du signal) de chaque appareil. Le réseau maillé s’auto-organise : les appareils sur secteur (prises, compteurs) servent de routeurs pour les appareils sur pile.

Les appareils du setup

Sur mon réseau Zigbee actuel :

• ZLinky LiXee (Jennic) : téléinfo EDF, remonte la consommation instantanée et les index dans HA
• Mesure VMC Daikin, cuisine, électricité (Tuya PJ-1203A) : compteurs de courant sur les circuits, suivi de consommation en temps réel
• Fuite Buanderie (IKEA E2202) : détecteur d’inondation, alerte Telegram si présence d’eau
• Porte escalier (SONOFF SNZB-04) : contact d’ouverture/fermeture pour les automatisations

Tous ces appareils remontent leurs états dans Home Assistant automatiquement dès l’appairage. À partir de là : entités disponibles pour les tableaux de bord, les automatisations, les historiques.

Intégration Home Assistant

Dans HA, ajouter l’intégration MQTT (Paramètres > Appareils > Ajouter une intégration > MQTT) avec l’adresse du broker. Grâce à la découverte automatique activée dans Z2M, chaque appareil appairé crée ses entités dans HA sans rien faire de plus. Un compteur d’énergie génère des entités sensor.mesure_cuisine_power, sensor.mesure_cuisine_current, sensor.mesure_cuisine_voltage, toutes exploitables immédiatement dans les automatisations et le tableau de bord Energie.

FAQ

Pour aller plus loin

• Installer Home Assistant sur Proxmox : la VM HA qui consomme les entités Z2M
• Mes automatisations HA préférées : ce qu’on peut faire avec les appareils Zigbee une fois dans HA
• Dockge : la gestion Docker où tourne Z2M
• Mon setup homelab 2026 : vue d’ensemble de la machine prioritaire et de l’architecture