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
- ¿Qué instalación tienes? Si el menú Ajustes de Home Assistant muestra Apps (Complementos en versiones antiguas), tienes Home Assistant OS: consulta con apps. Si no, Home Assistant se ejecuta en Docker (Container): consulta Docker.
- ¿Qué adaptador tienes? Abre Ajustes › Dispositivos y servicios › Zigbee Home Automation. En Hubs, el adaptador aparece con su modelo, por ejemplo SONOFF ZBDongle-E. Luego consulta tu adaptador.
- Haz una copia de seguridad de ZHA. En esa página, toca el ⚙ junto a Zigbee Home Automation y luego Download backup. Guarda el archivo. En la misma página, Network information muestra el canal, el tipo de radio y el puerto serie.
- Qué cambia en Home Assistant. Tus dispositivos vuelven como dispositivos MQTT nuevos, con nuevos ID de entidad. Las automatizaciones, los scripts y los paneles que los usan tienen que apuntar a los nuevos, y su historial empieza de cero. Los grupos y las vinculaciones creados en ZHA se vuelven a crear en Zigbee2MQTT.
- Tiempo. Cada dispositivo se restablece y se vuelve a emparejar, uno por uno. Todavía no tenemos tiempos reales; reserva una tarde para una casa pequeña y más para una grande.
Dos formas de migrar
| Segundo adaptador | Mismo adaptador | |
|---|---|---|
| Precio | Un 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ón | Todo sigue funcionando: ZHA conserva el adaptador antiguo | Zigbee queda apagado hasta que cada dispositivo se vuelve a emparejar |
| Ritmo | Habitación por habitación, a lo largo de varios días si quieres | Todo de una vez |
| Volver atrás | Fácil: desconecta el adaptador nuevo; ZHA nunca se detuvo | Restaura la copia de seguridad de ZHA (consulta Volver atrás) |
Segundo adaptador
- 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.
- deja la clave de red y el PAN ID en
- Mantén los dos adaptadores separados, cada uno con un cable alargador USB.
- 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.
- 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.
- Cuando hayas migrado todos los dispositivos, deshabilita ZHA (más abajo) y guarda el adaptador antiguo como repuesto.
Mismo adaptador
- Descarga la copia de seguridad de ZHA (consulta Antes de empezar) justo antes de empezar.
- Deshabilita ZHA: Ajustes › Dispositivos y servicios › Zigbee Home Automation, el ⋮ junto a Zigbee Home Automation › Deshabilitar. No Eliminar.
- Configura Zigbee2MQTT en el mismo adaptador (con apps o Docker), dejando la clave de red y el PAN ID en
GENERATE. - Apaga tus dispositivos Zigbee conectados a la corriente desde el interruptor de pared o el disyuntor. Si no, siguen buscando la red antigua.
- Vuelve a encenderlos uno por uno y empareja cada uno en cuanto se encienda. Después empareja los dispositivos a pilas.
Tu adaptador
- Silicon Labs (Home Assistant Connect ZBT-1 y ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M y SLZB-07):
adapter: ember. El ZBT-2 además necesitabaudrate: 460800; el ZBDongle-E necesitartscts: false; el SLZB-06M necesita el firmware 20240510 o posterior. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 y SLZB-06P7):
adapter: zstack. - ConBee o RaspBee:
adapter: deconz. - CC2531 o ZiGate: demasiado antiguos o ya sin mantenimiento para una buena red de Zigbee2MQTT. Usa la forma del segundo adaptador con un adaptador nuevo.
- Un adaptador de red (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, serie MR): ZHA lo muestra como
socket://IP:6638; en Zigbee2MQTT estcp://IP:6638, y Docker no necesita la línea de USB. - Multiprotocolo (ZBT-1 o Yellow con Zigbee y Thread a la vez; lo indica la página del hardware en Home Assistant): Zigbee2MQTT no puede usar firmware multiprotocolo. Para la forma del mismo adaptador, desactiva el multiprotocolo mientras sigues en ZHA, con el procedimiento del propio Home Assistant (ZBT-1, Yellow). Los dispositivos Thread que lo usaban dejan de funcionar hasta que otro router de borde Thread se haga cargo de ellos. Para la forma del segundo adaptador, no lo toques y compra el adaptador nuevo solo para Zigbee.
Las páginas de adaptadores de Zigbee2MQTT tienen los detalles.
Home Assistant con apps (Home Assistant OS)
- 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.
- Añade el repositorio de Zigbee2MQTT (en la tienda de apps, ⋮ › Repositorios:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) y luego instala Zigbee2MQTT. - En su pestaña Configuración, pon el puerto serie y el adaptador según tu adaptador, por ejemplo:
Para la forma del segundo adaptador, pon también el canal (consulta arriba) antes del primer arranque.port: /dev/serial/by-id/usb-... adapter: ember - 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
- 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.
- 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.
- 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
- ZigDash: ábrelo y toca Encontrar mi instalación. Encuentra Mosquitto en tu red; inicia sesión con el usuario MQTT. O elige Home Assistant e inicia sesión: ahora también funciona, porque Home Assistant tiene la integración MQTT.
- Nombres y habitaciones: en ZigDash, Ajustes › Importar desde Home Assistant trae los nombres y habitaciones que diste a los dispositivos nuevos en Home Assistant.
- Home Assistant: apunta las automatizaciones, los scripts y los paneles a los dispositivos nuevos. Cuando estés seguro, elimina la integración ZHA.
Volver atrás
- Segundo adaptador: detén Zigbee2MQTT y desconecta el adaptador nuevo. ZHA nunca se detuvo. Los dispositivos que ya migraste tienen que volver a emparejarse con ZHA.
- Mismo adaptador: detén Zigbee2MQTT y luego, en la página de ZHA, toca Habilitar. ZHA dice "Network settings do not match most recent backup" (la configuración de red no coincide con la copia de seguridad más reciente), porque ahora el adaptador tiene la red de Zigbee2MQTT. Abre Ajustes › Reparaciones › "Zigbee network settings have changed" (la configuración de la red Zigbee cambió) y elige Restore backup (recommended). La red de ZHA vuelve tal como estaba. Los dispositivos que habías emparejado con Zigbee2MQTT tienen que volver a emparejarse con ZHA. Si no aparece ninguna reparación, usa ⚙ › Migrate adapter con la copia de seguridad que descargaste.
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.