ZigDash

Passer de ZHA à Zigbee2MQTT

ZHA est le Zigbee intégré à Home Assistant. ZigDash fonctionne avec Zigbee2MQTT, il ne peut donc pas afficher les appareils qui sont dans ZHA. Passer à Zigbee2MQTT veut dire appairer à nouveau vos appareils avec Zigbee2MQTT. Home Assistant continue ensuite à les utiliser, via son intégration MQTT.

Avant de commencer

Deux façons de migrer

Second adaptateurMême adaptateur
CoûtUn nouvel adaptateur, environ 30–60 € (par exemple un Home Assistant Connect ZBT-2, ou un SMLIGHT SLZB-06M ou SLZB-07)Gratuit
Pendant la migrationTout continue de fonctionner : ZHA garde l'ancien adaptateurLe Zigbee est coupé jusqu'à ce que chaque appareil soit appairé à nouveau
RythmePièce par pièce, sur plusieurs jours si vous le souhaitezTout d'un coup
Retour en arrièreFacile : débranchez le nouvel adaptateur, ZHA ne s'est jamais arrêtéRestaurez la sauvegarde ZHA (voir Revenir en arrière)

Second adaptateur

  1. Installez Zigbee2MQTT sur le nouvel adaptateur (avec apps ou Docker), avec son propre réseau. Choisissez tout cela avant le premier démarrage de Zigbee2MQTT, car changer de canal plus tard peut obliger à tout appairer à nouveau :
    • laissez la clé réseau et le PAN ID sur GENERATE (la valeur par défaut) ;
    • choisissez un canal différent de celui de ZHA (le ⚙ de ZHA › Network information l'indique) ; Home Assistant conseille 15, 20 ou 25.
  2. Éloignez les deux adaptateurs l'un de l'autre, chacun sur une rallonge USB.
  3. Sous Home Assistant OS, quand vous branchez le nouvel adaptateur, Home Assistant peut proposer de le configurer pour ZHA ou Thread. Ignorez cette proposition : l'adaptateur est pour Zigbee2MQTT.
  4. Migrez une pièce à la fois : appairez d'abord ses appareils sur secteur (ampoules, prises, interrupteurs encastrés : ce sont des routeurs), puis ses appareils sur pile.
  5. Quand tous les appareils sont migrés, désactivez ZHA (voir plus bas) et gardez l'ancien adaptateur en réserve.

Même adaptateur

  1. Téléchargez la sauvegarde ZHA (voir Avant de commencer), juste avant de commencer.
  2. Désactivez ZHA : Paramètres › Appareils et services › Zigbee Home Automation, le ⋮ à côté de Zigbee Home Automation › Désactiver. Pas Supprimer.
  3. Installez Zigbee2MQTT sur le même adaptateur (avec apps ou Docker), en laissant la clé réseau et le PAN ID sur GENERATE.
  4. Coupez vos appareils Zigbee sur secteur, à l'interrupteur ou au disjoncteur. Sinon, ils continuent à chercher l'ancien réseau.
  5. Rallumez-les un par un, et appairez chacun dès qu'il est allumé. Appairez ensuite les appareils sur pile.

Votre adaptateur

Les pages sur les adaptateurs de Zigbee2MQTT donnent les détails.

Home Assistant avec apps (Home Assistant OS)

  1. Dans Paramètres › Apps, installez et démarrez Mosquitto broker. Home Assistant propose alors l'intégration MQTT dans Paramètres › Appareils et services : acceptez-la.
  2. Ajoutez le dépôt Zigbee2MQTT (dans la boutique d'apps, ⋮ › Dépôts : https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), puis installez Zigbee2MQTT.
  3. Dans son onglet Configuration, renseignez le port série et l'adaptateur d'après votre adaptateur, par exemple :
    port: /dev/serial/by-id/usb-...
    adapter: ember
    Pour la méthode du second adaptateur, réglez aussi le canal (voir plus haut) avant le premier démarrage.
  4. Démarrez Zigbee2MQTT et ouvrez sa page web depuis la page de l'app. Ensuite, appairez.

Home Assistant dans Docker (sans apps)

Sans apps, Mosquitto et Zigbee2MQTT tournent dans leurs propres conteneurs, à côté de Home Assistant. Dans un nouveau dossier :

1. compose.yaml (mettez le chemin de votre adaptateur dans devices ; ls /dev/serial/by-id/ l'affiche) :

services:
  mosquitto:
    image: eclipse-mosquitto:2
    restart: unless-stopped
    ports:
      - 1883:1883
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto
    ports:
      - 8080:8080
    volumes:
      - ./zigbee2mqtt:/app/data
      - /run/udev:/run/udev:ro
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-...:/dev/ttyACM0

Avec un adaptateur réseau, retirez devices et la ligne udev.

2. mosquitto/config/mosquitto.conf :

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/

Créez l'utilisateur MQTT (le mot de passe est demandé deux fois ; le fichier doit appartenir à l'utilisateur de Mosquitto, sinon Mosquitto ne démarre pas) :

docker run -it --rm -v "$PWD/mosquitto/config:/mosquitto/config" eclipse-mosquitto:2 \
  sh -c "mosquitto_passwd -c /mosquitto/config/passwd zigbee && chown mosquitto:mosquitto /mosquitto/config/passwd"

3. zigbee2mqtt/configuration.yaml (les lignes de l'adaptateur d'après votre adaptateur) :

homeassistant:
  enabled: true
frontend:
  enabled: true
  port: 8080
mqtt:
  server: mqtt://mosquitto:1883
  user: zigbee
  password: your-password
serial:
  port: /dev/ttyACM0          # a network adapter: tcp://IP:6638
  adapter: ember
advanced:
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE
  channel: 20                 # second adapter: not ZHA's channel

4. Pour la méthode du même adaptateur, ZHA est maintenant désactivé (voir plus haut). Si le conteneur de Home Assistant lui-même donne accès à l'adaptateur, retirez cette ligne de son fichier compose ou de sa commande docker run : un seul conteneur peut utiliser l'adaptateur.

5. docker compose up -d, puis ouvrez http://the-machine:8080 : c'est la page web de Zigbee2MQTT.

6. Dans Home Assistant : Paramètres › Appareils et services › Ajouter une intégration › MQTT. Broker : l'adresse IP de la machine, port 1883, utilisateur zigbee et le mot de passe.

Appairer les appareils

  1. Sur la page web de Zigbee2MQTT, touchez Permit join (ouvert pendant environ quatre minutes). Pour appairer via un routeur proche de l'appareil, choisissez ce routeur dans le menu de Permit join : utile pour Aqara et d'autres appareils difficiles.
  2. Mettez l'appareil en mode appairage, comme l'indique son fabricant : un appui long pour la plupart des capteurs, quelques cycles allumé/éteint pour les ampoules, une série de basculements pour certains interrupteurs encastrés.
  3. Quand il apparaît, donnez-lui son nom et sa pièce dans Zigbee2MQTT. Puis passez au suivant.

D'abord les appareils sur secteur, ensuite les appareils sur pile, pour que le nouveau réseau ait des routes.

Après la migration

Revenir en arrière

Testé : le 17 novembre 2026, avec Home Assistant 2026.11 et un Sonoff ZBDongle-E, le réseau de ZHA est revenu à l'identique (canal, PAN ID et clé réseau). Nous ne l'avons pas encore vérifié avec des appareils appairés, alors gardez le fichier de sauvegarde.

Garder le réseau sans appairer à nouveau

Il existe une troisième méthode : copier le réseau de ZHA dans Zigbee2MQTT pour que les appareils n'aient pas besoin d'être appairés à nouveau. Zigbee2MQTT ne la prend pas en charge, une mauvaise valeur peut effacer le réseau, et elle n'a de sens que pour les grands logements (disons plus de 60 appareils). Si vous voulez en savoir plus : la réponse du mainteneur de Zigbee2MQTT, et des retours de la communauté dans la discussion 24478 et la discussion 26716.

Dites-nous comment ça s'est passé. Ce guide est nouveau. Si une étape était fausse ou manquante, écrivez à [email protected] ou à la communauté.