Cómo Migrar a un Nuevo Coordinador Zigbee sin Re-emparejar Dispositivos

Desde el lanzamiento del Home Assistant Connect ZBT-2, un coordinador Zigbee y Thread, muchos se han preguntado qué se necesita realmente para migrar de un adaptador a otro. ¿Qué se requiere, qué riesgos existen y es posible hacerlo sin tener que re-emparejar todos los dispositivos? Porque, seamos sinceros, ¿quién quiere recorrer toda la casa restableciendo un centenar de dispositivos Zigbee para agregarlos a un nuevo coordinador? Nadie.

Este artículo cubre todas las preguntas que puedas tener sobre cómo trasladar tu red Zigbee existente a un nuevo coordinador. Describe claramente los riesgos, los requisitos que deben cumplirse y te guía a través del proceso paso a paso.

¿Por Qué Migrar y Para Quién es Esto?

Migrar tu red Zigbee puede parecer desalentador, especialmente si dependes de ella para luces, sensores, interruptores y automatizaciones en toda tu casa. La buena noticia es que cambiar a un nuevo coordinador no tiene por qué significar empezar de cero. Ahora bien, ¿por qué migrar?

• Deseas actualizar un coordinador Zigbee antiguo a un modelo más nuevo y capaz.
• Buscas un mayor alcance, estabilidad o un límite superior de dispositivos.
• Tu adaptador actual tiene problemas de hardware, interferencias o firmware obsoleto.
• Estás cambiando de ZHA a Zigbee2MQTT o viceversa.
• Estás reconstruyendo tu configuración de Home Assistant y quieres mantener todos los dispositivos Zigbee emparejados.
• Quieres evitar re-emparejar docenas o incluso cientos de dispositivos en tu hogar.

Esta guía se centra exclusivamente en la migración a un nuevo coordinador sin necesidad de re-emparejar dispositivos. Si fuera necesario re-emparejar, el proceso es sencillo y requiere poca explicación: actualiza la ruta del coordinador en tu configuración y comienza a añadir dispositivos uno por uno.

Coordinadores y Chips Zigbee Compatibles

Cuando tanto tu antiguo como tu nuevo coordinador utilizan un chip que soporta copia de seguridad y restauración en Zigbee2MQTT, la migración es relativamente sencilla. Actualmente, la copia de seguridad y restauración completa solo es compatible oficialmente con coordinadores basados en <strong>zstack</strong> (Texas Instruments) y <strong>ember</strong> (Silicon Labs). Esto incluye la migración entre diferentes modelos dentro de la misma familia, como de <strong>EFR32MG21</strong> a <strong>EFR32MG24</strong> o de <strong>CC2538</strong> a <strong>CC2652P</strong>.

Al migrar entre diferentes familias de chips, como de <strong>zstack</strong> a <strong>ember</strong> o de <strong>ember</strong> a <strong>zstack</strong>, el proceso no está oficialmente soportado, pero aún así puedes (y probablemente tendrás) éxito. En la mayoría de los casos, los dispositivos se unen a la nueva red sin re-emparejamiento y funcionan sin problemas. Incluso si algunos necesitan ser re-emparejados, la mayoría de los dispositivos se migran con éxito.

La migración mediante copia de seguridad y restauración no es compatible con otros tipos de adaptadores en Zigbee2MQTT, incluyendo <strong>conbee</strong>, <strong>ezsp</strong>, <strong>zboss</strong> y <strong>zigate</strong>. Estos adaptadores no pueden importar ni restaurar archivos de copia de seguridad del coordinador, por lo que Zigbee2MQTT no puede realizar una migración real con ellos. Aún podrías tener éxito utilizando este método, pero no hay garantías.

Por lo tanto, esta guía para Zigbee2MQTT se centra únicamente en la migración de adaptadores compatibles, incluyendo <strong>ember</strong> > <strong>ember</strong>, <strong>ember</strong> > <strong>zstack</strong>, <strong>zstack</strong> > <strong>zstack</strong> y <strong>zstack</strong> > <strong>ember</strong>. ZHA admite la migración entre todos los tipos de radio oficialmente compatibles, lo que te permite trasladar tu red existente de un adaptador a otro siempre que ambos adaptadores sean compatibles con ZHA.

Para que quede perfectamente claro, aquí tienes una tabla de varios coordinadores Zigbee y los chips que utilizan:

Nota: <strong>ezsp</strong> es el controlador heredado para adaptadores Silicon Labs. Si actualmente estás utilizando <strong>ezsp</strong>, idealmente deberías migrar tu configuración para usar el controlador <strong>ember</strong> más nuevo primero, para tratarlo simplemente como una migración de Ember a Ember, lo cual funciona a pesar de la etiqueta oficial de “no soportado”.

Migrar Zigbee2MQTT a un Nuevo Coordinador

Al cambiar a un nuevo coordinador con función de copia de seguridad compatible, Zigbee2MQTT puede restaurar la red completa sin re-emparejamiento. Algunos dispositivos buscan el coordinador por su dirección IEEE, lo que falla cuando la dirección del coordinador cambia. Por lo tanto, la dirección IEEE existente debe ser copiada al nuevo coordinador. Tanto los adaptadores <strong>zstack</strong> como <strong>ember</strong> soportan copia de seguridad y restauración completas, lo que te permite trasladar la dirección IEEE, la clave de red y la tabla de enrutamiento directamente al nuevo hardware.

Sigue este proceso para migrar Zigbee2MQTT a un nuevo coordinador:

1. Actualiza Zigbee2MQTT a la última versión
   La migración requiere una versión actual de Z2M para garantizar la compatibilidad total de copia de seguridad.

2. Crea una copia de seguridad completa de Zigbee2MQTT por si acaso
   Haz una copia de seguridad de los siguientes archivos de tu directorio de datos de Zigbee2MQTT:
   <strong>coordinator_backup.json</strong> <strong>database.db</strong>, <strong>configuration.yaml</strong>

3. Detén Zigbee2MQTT completamente
   Esto evita escrituras mientras se exporta la copia de seguridad o se copia la dirección IEEE.

4. Copia la dirección IEEE del antiguo al nuevo adaptador (LEER ABAJO)
   NO TE SALTES ESTE PASO: Esto asegura que tu red identifique el nuevo hardware como el mismo coordinador.

5. Conecta tu nuevo coordinador a tu servidor
   Si es un coordinador USB, conéctalo de nuevo al servidor. Si es un coordinador de red, asegúrate de que esté en funcionamiento con una dirección IP estática. Si ejecutas Home Assistant o Zigbee2MQTT en una Máquina Virtual (Proxmox, ESXi) o Docker, debes actualizar la configuración de Passthrough de USB o el mapeo de volumen.

6. Actualiza tu configuración de Zigbee2MQTT
   Asegúrate de que el <strong>pan_id</strong> y el <strong>ext_pan_id</strong> en tu archivo de configuración coincidan exactamente con lo que tenías antes. Si estás copiando datos a una instalación nueva, estos valores a veces se restablecen a los predeterminados, lo que impedirá que los dispositivos se conecten. Finalmente, actualiza la sección <strong>serial</strong> para que coincida con tu nuevo coordinador:

   yaml
   serial:
   port: /dev/ttyUSB_NUEVO_COORDINADOR # Ajusta la ruta y establece el tipo de adaptador

7. Inicia Zigbee2MQTT

8. ¡Listo!

Con la nueva dirección coincidiendo con la antigua, tu red Zigbee se iniciará de nuevo utilizando el nuevo coordinador. Tardará tiempo en estabilizarse y verás datos LQI (Indicador de Calidad de Enlace) inexactos reportados. Ten paciencia, dale 24 horas para que re-enrute y listo. Para acelerar el proceso, camina por la casa y despierta manualmente tus dispositivos alimentados por batería (presiona el botón físico del sensor una vez). Esto los obliga a enviar una ‘Solicitud de Datos’ inmediatamente, ayudándoles a darse cuenta de que la ruta de la red ha cambiado sin esperar su comprobación programada.

Copiar la Dirección IEEE al Nuevo Coordinador

Abre Zigbee2MQTT y navega a Configuración > Acerca de y busca en la sección Coordinador y guarda el valor, por ejemplo, <strong>0xf074bffffe091703</strong>. Alternativamente, navega a la carpeta <strong>zigbee2mqtt</strong> y abre el archivo <strong>database.db</strong>. La dirección del coordinador se encuentra en la primera línea, justo después de "ieeeAddr". Aquí tienes una captura de pantalla de la nueva interfaz de usuario de Zigbee2MQTT:

Ahora, la mayoría de los coordinadores de red permiten cambiar la dirección IEEE directamente desde el panel web. Por ejemplo, los coordinadores SMLight PoE tienen una configuración que se encuentra en el menú Z2M y ZHA, bajo Avanzado: Configuración de Cambio de IEEE del Adaptador. Simplemente pega la nueva y presiona Escribir Dirección IEEE. Asegúrate de que el coordinador no esté en uso mientras haces esto y que Zigbee2MQTT/ZHA estén completamente apagados.

Si tienes un coordinador solo USB, necesitarás usar una herramienta de flasheo de firmware. Dependiendo del fabricante de tu chip (Texas Instruments o Silicon Labs), tienes varias herramientas a tu disposición para cambiar la dirección IEEE. Para chips Silicon Labs, me gusta usar el Universal Silicon Labs Flasher. Para chips Texas Instruments, recomiendo el ZigStar Multi Tool. Así es como se cambia la dirección IEEE con cada uno:

Universal Silicon Labs Flasher

1. Instala la herramienta Universal Silicon Labs Flasher
   Instala a través de la terminal o PowerShell:

   bash
   $ pip install universal-silabs-flasher

2. Conecta tu nuevo adaptador a tu PC
   Encuentra el puerto serie correcto, por ejemplo:

   • Linux: <strong>/dev/ttyACM0</strong>, <strong>/dev/ttyUSB0</strong>, etc.
   • macOS: <strong>/dev/tty.usbmodemXXXX</strong> o <strong>/dev/tty.usbserialXXXX</strong>
   • Windows: <strong>COM3</strong>, <strong>COM4</strong>, etc.

3. Ejecuta el siguiente comando, reemplazando la dirección IEEE y el puerto serie:

   • Reemplaza <strong>/dev/ttyACM0</strong> con la ruta a tu nuevo coordinador.
   • Reemplaza <strong>f074bffffe091703</strong> con la dirección IEEE de tu coordinador.
     IMPORTANTE: Elimina el prefijo hexadecimal <strong>(0x)</strong> y los dos puntos <strong>(:)</strong> de tu dirección IEEE.

   bash
   universal-silabs-flasher –device /dev/ttyACM0 write-ieee –ieee f074bffffe091703

   Si el proceso falla, intenta añadir <strong>--force</strong> al final del comando. Monitoriza los registros para una confirmación exitosa. Si la dirección IEEE del dispositivo actual ya coincide con la nueva, el comando no la escribirá innecesariamente. ¡Listo!

Zigstar Multitool

1. Descarga y lanza ZigStar Multitool
   Instala la aplicación para tu sistema operativo y ábrela.
2. Conecta tu adaptador e introduce el modo Bootloader (BSL)
   Consulta el manual de tu adaptador, ya que el método varía según el modelo.
3. Haz clic en el icono de refrescar y selecciona tu adaptador
   La herramienta debería detectar el dispositivo serie una vez que esté en modo BSL.
4. Introduce la dirección IEEE del coordinador antiguo
   Rellena el campo “IEEE” con la dirección IEEE de tu antiguo coordinador.
   El prefijo <strong>0x</strong> inicial es opcional y no se deben usar dos puntos.
5. Habilita “Write IEEE” y escribe la dirección
   Marca la casilla “Write IEEE” y haz clic en Write IEEE para flashear la dirección.
6. Vuelve a flashear el firmware después
   Este paso es necesario. El coordinador no utilizará la nueva dirección IEEE hasta que se escriba el firmware correcto de nuevo en el adaptador. Usa la misma herramienta para volver a flashear el firmware o consulta la herramienta de flasheo del fabricante, por ejemplo, Sonoff.

Si ZigStar Multitool no detecta tu adaptador, verifica que esté correctamente en modo BSL y que ningún otro software (como Zigbee2MQTT o Home Assistant) esté utilizando actualmente el mismo puerto serie. Intenta desconectar y reconectar el adaptador, luego haz clic en el icono de refrescar nuevamente. Si la operación de escritura IEEE falla, reinicia la herramienta y repite el proceso, asegurándote de que se selecciona la ruta COM o USB correcta.

Migrar ZHA a un Nuevo Coordinador

ZHA incluye un asistente de migración incorporado que hace que trasladar tu red Zigbee existente a un nuevo coordinador sea muy sencillo. El asistente crea automáticamente una copia de seguridad de los datos de tu red actual, transfiere la clave de red Zigbee, conserva los emparejamientos de dispositivos y, cuando es necesario, escribe la dirección IEEE del antiguo coordinador en el nuevo adaptador.

En el proceso, también restaura metadatos esenciales de la red para que tus dispositivos puedan unirse a la red sin ser re-emparejados. En ZHA, este proceso funciona tanto para migraciones de chips idénticos como, en la mayoría de los casos, entre diferentes fabricantes de chips, siempre que el nuevo adaptador sea totalmente compatible con ZHA. Ten en cuenta que al migrar ZHA entre diferentes chips, no hay garantías absolutas y es posible que necesites re-emparejar algunos dispositivos.

Sigue este proceso para migrar ZHA a un nuevo coordinador:

1. Verifica los prerrequisitos y haz una copia de seguridad
   Crea una copia de seguridad completa de Home Assistant antes de migrar.
   Asegúrate de que el antiguo adaptador sea utilizado actualmente solo por ZHA.
2. Conecta el nuevo coordinador a tu servidor HA
   Conecta el nuevo adaptador Zigbee utilizando un cable de extensión USB para reducir la interferencia. Si utilizas un coordinador de red, configura una dirección IP estática en tu router.
3. Ve a Configuración > Dispositivos y Servicios, abre ZHA y haz clic en Configurar (Rueda dentada)
4. Dentro de Configuración de red, selecciona Migrar adaptador.
   ZHA crea automáticamente una copia de seguridad de tu red Zigbee.
5. Selecciona Migrar a un nuevo adaptador.
6. Selecciona el nuevo adaptador Zigbee de la lista de puertos serie.
   Para adaptadores de red, selecciona Introducir manualmente e introduce la dirección TCP y el puerto correctos.
7. Selecciona Migrar automáticamente para restaurar tu copia de seguridad.
   ZHA restaurará la copia de seguridad y escribirá la dirección IEEE del antiguo coordinador en el nuevo adaptador cuando sea compatible.
   En el raro caso de que el nuevo coordinador requiera sobrescribir la dirección IEEE, verás un aviso para Sobrescribir la dirección IEEE de la radio. Introduce la nueva dirección IEEE, marca la casilla Reemplazar permanentemente la dirección IEEE de la radio y haz clic en Enviar.
8. Espera a que los dispositivos se reúnan
   Los dispositivos se unirán automáticamente a la red con el tiempo, lo que puede tardar hasta una hora.
9. Elimina el antiguo coordinador
10. ¡Listo!

Una vez que la red vuelva a estar en línea, deberás darle tiempo para que arranque y se estabilice. Los dispositivos se unirán automáticamente después de un tiempo. Puedes forzar este proceso reiniciando la alimentación de tus routers Zigbee alimentados por red eléctrica.

Conclusión

Migrar una red Zigbee puede parecer abrumador al principio, pero con la preparación adecuada y una comprensión clara de la familia de chips y las capacidades de tu coordinador, el proceso es mucho más manejable de lo que la mayoría espera. Ya sea que uses Zigbee2MQTT o ZHA, ambas plataformas proporcionan mecanismos fiables para trasladar tu red existente a un nuevo adaptador sin tener que recorrer tu casa re-emparejando cada dispositivo.

Para Zigbee2MQTT, la migración exitosa depende completamente del uso de adaptadores basados en familias de chips compatibles como <strong>zstack</strong> de Texas Instruments o <strong>ember</strong> de Silicon Labs. Cuando estas condiciones se cumplen, copiar la dirección IEEE y restaurar la copia de seguridad de la red es suficiente para continuar operando sin problemas la misma malla Zigbee en un nuevo hardware. ZHA ofrece aún más flexibilidad, proporcionando un asistente de migración incorporado que maneja automáticamente la copia de seguridad, restauración, transferencias IEEE y reconstrucción de la red, incluso al cambiar entre diferentes fabricantes de chips, siempre que ambos adaptadores sean totalmente compatibles.

Dicho esto, ningún método de migración está garantizado para ser perfecto. Las redes Zigbee varían ampliamente en tamaño, tipos de dispositivos, patrones de enrutamiento y calidad del firmware. Incluso con procedimientos correctos, es posible que aún necesites re-emparejar un puñado de dispositivos, especialmente sensores alimentados por batería, dispositivos antiguos o cualquier cosa que ya fuera inestable antes de la migración. También es posible que ciertos dispositivos desaparezcan temporalmente, no se reúnan limpiamente o requieran un reinicio manual.