ZigDash

Migrar de ZHA a Zigbee2MQTT

ZHA es el Zigbee propio de Home Assistant. ZigDash funciona con Zigbee2MQTT, así que no puede mostrar los dispositivos que están en ZHA. Migrar significa volver a emparejar tus dispositivos con Zigbee2MQTT. Después, Home Assistant los sigue usando a través de su integración MQTT.

Antes de empezar

Dos formas de migrar

Segundo adaptadorMismo adaptador
PrecioUn adaptador nuevo, unos 30–60 € (por ejemplo un Home Assistant Connect ZBT-2, o un SMLIGHT SLZB-06M o SLZB-07)Gratis
Durante la migraciónTodo sigue funcionando: ZHA conserva el adaptador antiguoZigbee queda apagado hasta que cada dispositivo se vuelve a emparejar
RitmoHabitación por habitación, a lo largo de varios días si quieresTodo de una vez
Volver atrásFácil: desconecta el adaptador nuevo; ZHA nunca se detuvoRestaura la copia de seguridad de ZHA (consulta Volver atrás)

Segundo adaptador

  1. Configura Zigbee2MQTT en el adaptador nuevo (con apps o Docker) con su propia red. Elige todo esto antes del primer arranque de Zigbee2MQTT, porque cambiar el canal más tarde puede obligarte a volver a emparejar:
    • deja la clave de red y el PAN ID en GENERATE (el valor predeterminado);
    • elige un canal distinto del de ZHA (lo muestra ⚙ › Network information de ZHA); Home Assistant recomienda 15, 20 o 25.
  2. Mantén los dos adaptadores separados, cada uno con un cable alargador USB.
  3. En Home Assistant OS, al conectar el adaptador nuevo, Home Assistant puede ofrecerte configurarlo para ZHA o Thread. Ignóralo: el adaptador es para Zigbee2MQTT.
  4. Migra una habitación cada vez: empareja primero sus dispositivos conectados a la corriente (bombillas, enchufes, interruptores empotrados: son routers) y después sus dispositivos a pilas.
  5. Cuando hayas migrado todos los dispositivos, deshabilita ZHA (más abajo) y guarda el adaptador antiguo como repuesto.

Mismo adaptador

  1. Descarga la copia de seguridad de ZHA (consulta Antes de empezar) justo antes de empezar.
  2. Deshabilita ZHA: Ajustes › Dispositivos y servicios › Zigbee Home Automation, el ⋮ junto a Zigbee Home Automation › Deshabilitar. No Eliminar.
  3. Configura Zigbee2MQTT en el mismo adaptador (con apps o Docker), dejando la clave de red y el PAN ID en GENERATE.
  4. Apaga tus dispositivos Zigbee conectados a la corriente desde el interruptor de pared o el disyuntor. Si no, siguen buscando la red antigua.
  5. Vuelve a encenderlos uno por uno y empareja cada uno en cuanto se encienda. Después empareja los dispositivos a pilas.

Tu adaptador

Las páginas de adaptadores de Zigbee2MQTT tienen los detalles.

Home Assistant con apps (Home Assistant OS)

  1. En Ajustes › Apps, instala e inicia Mosquitto broker. Después, Home Assistant te ofrece la integración MQTT en Ajustes › Dispositivos y servicios: acéptala.
  2. Añade el repositorio de Zigbee2MQTT (en la tienda de apps, ⋮ › Repositorios: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) y luego instala Zigbee2MQTT.
  3. En su pestaña Configuración, pon el puerto serie y el adaptador según tu adaptador, por ejemplo:
    port: /dev/serial/by-id/usb-...
    adapter: ember
    Para la forma del segundo adaptador, pon también el canal (consulta arriba) antes del primer arranque.
  4. Inicia Zigbee2MQTT y abre su página web desde la página de la app. Después, empareja.

Home Assistant en Docker (sin apps)

Sin apps, Mosquitto y Zigbee2MQTT se ejecutan como contenedores propios junto a Home Assistant. En una carpeta nueva:

1. compose.yaml (pon la ruta de tu adaptador en devices; ls /dev/serial/by-id/ la muestra):

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

Con un adaptador de red, quita devices y la línea de udev.

2. mosquitto/config/mosquitto.conf:

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

Crea el usuario MQTT (pide la contraseña dos veces; el archivo tiene que pertenecer al propio usuario de Mosquitto, o Mosquitto no arrancará):

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 (las líneas del adaptador, según tu adaptador):

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. Para la forma del mismo adaptador, ZHA ya está deshabilitado (consulta arriba). Si el propio contenedor de Home Assistant mapea el adaptador, quita esa línea de su archivo compose o de docker run: solo un contenedor puede usar el adaptador.

5. docker compose up -d y luego abre http://the-machine:8080: la página web de Zigbee2MQTT.

6. En Home Assistant: Ajustes › Dispositivos y servicios › Añadir integración › MQTT. Broker: la dirección IP de la máquina, puerto 1883, usuario zigbee y la contraseña.

Emparejar los dispositivos

  1. En la página web de Zigbee2MQTT, toca Permit join (queda abierto unos cuatro minutos). Para emparejar a través de un router cercano al dispositivo, elige ese router en el menú de Permit join: es útil con Aqara y otros dispositivos exigentes.
  2. Restablece el dispositivo a modo de emparejamiento, como indique su fabricante: una pulsación larga en la mayoría de los sensores, unos cuantos ciclos de encendido y apagado en las bombillas, una serie de pulsaciones del interruptor en algunos interruptores empotrados.
  3. Cuando aparezca, ponle su nombre y su habitación en Zigbee2MQTT. Luego, el siguiente.

Primero los dispositivos conectados a la corriente y después los de pilas, para que la red nueva tenga rutas.

Después de la migración

Volver atrás

Probado: el 17 de noviembre de 2026, con Home Assistant 2026.11 y un Sonoff ZBDongle-E, la red de ZHA volvió exactamente igual (canal, PAN ID y clave de red). Todavía no lo hemos comprobado con dispositivos emparejados, así que guarda el archivo de copia de seguridad.

Conservar la red sin volver a emparejar

Hay una tercera forma: copiar la red de ZHA en Zigbee2MQTT para que los dispositivos no tengan que volver a emparejarse. Zigbee2MQTT no la admite, un valor incorrecto puede borrar la red, y solo tiene sentido en casas grandes (por ejemplo, de más de 60 dispositivos). Si quieres leer sobre ella: la respuesta del mantenedor de Zigbee2MQTT, y experiencias de la comunidad en la discusión 24478 y la discusión 26716.

Cuéntanos cómo te fue. Esta guía es nueva. Si un paso estaba mal o faltaba, escribe a [email protected] o a la comunidad.