Skip to content
Zigbee

Actualizar Zigbee2MQTT 2.0.0: Guía Completa y Solución a Problemas

Con la reciente actualización de Zigbee2MQTT a la versión 2.0.0, muchos usuarios, incluido yo, hemos enfrentado ciertos problemas para adaptarnos a los cambios importantes. En este artículo, te guiaré paso a paso sobre cómo actualizar correctamente tu instalación de zigbee2mqtt. Además, gracias a mi experiéncia, te contaré cómo solucionar posibles problemas que yo mismo he enfrentado. Esta versión trae mejoras significativas, pero también cambios que pueden requerir ajustes en tu configuración.

Índice de contenido

    Cambios importantes en Zigbee2MQTT 2.0.0

    Antes de proceder con la actualización, es crucial entender los principales cambios que trae esta nueva versión. Aquí están los más destacados:

    1. Mejoras en la detección de adaptadores USB
      Ahora Zigbee2MQTT identifica los adaptadores de manera más estricta. Esto puede causar errores como USB adapter discovery error si la configuración no es correcta.
    2. Eliminación de funciones obsoletas
      Muchas configuraciones heredadas han sido eliminadas, como:
      • Sensores de clic (*_click) y acción (*_action).
      • Entidades duplicadas en Home Assistant (por ejemplo, sensor vs number).
      • Configuraciones como legacy_api y availability_timeout.
    3. Cambios específicos para dispositivos
      Algunos dispositivos han recibido actualizaciones importantes, como renombrar atributos o eliminar configuraciones. Por ejemplo:
      • Los dispositivos Tuya ZY-M100-24G ahora usan «presencia» en lugar de «ocupación».
      • Algunos dispositivos Aqara y IKEA han cambiado nombres o eliminado atributos.
    4. Migración de configuraciones
      Zigbee2MQTT elimina automáticamente configuraciones obsoletas. Es importante revisar el archivo migration-1-to-2.log después de la primera ejecución para detectar cambios.

    Cómo actualizar Zigbee2MQTT a la versión 2.0.0

    Actualizar Zigbee2MQTT puede parecer intimidante, pero siguiendo estos pasos, será un proceso sencillo:

    1. Hacer una copia de seguridad

    Antes de tocar nada, asegúrate de hacer una copia de seguridad completa de tu sistema y del archivo configuration.yaml de Zigbee2MQTT. Esto te permitirá volver a la versión anterior si algo sale mal.

    2. Preparar el archivo configuration.yaml de Zigbee2mqtt

    Localiza dónde tienes especificado el coordinador y añade la línea de adapter según se muestra aquí

    serial:
  port: /dev/serial/by-id/usb-Silicon_Labs_Sonoff_Zigbee_3.0_USB_Dongle_Plus_0001-if00-port0
  adapter: zstack

    El port puede que lo tengas diferente ya que dependerá de tu coordinador.

    Asegúrate de que las configuraciones heredadas ya estén desactivadas. Agrega o verifica las siguientes líneas en tu archivo configuration.yaml de zigbee2mqtt:

    advanced:
  homeassistant_legacy_entity_attributes: false
  homeassistant_legacy_triggers: false
  legacy_api: false
  legacy_availability_payload: false
device_options:
  legacy: false

    Esto minimizará los cambios drásticos al actualizar.

    3. Actualizar Zigbee2MQTT

    Si usas Home Assistant y Zigbee2MQTT como complemento:

    1. Ve a la sección Supervisor > Zigbee2MQTT.
    2. Haz clic en Actualizar.

    Para instalaciones manuales:

    1. Detén Zigbee2MQTT.
    2. Ejecuta los siguientes comandos:
    npm install -g pnpm
./update.sh

    4. Verificar el estado

    Reinicia Zigbee2MQTT y revisa los registros para detectar posibles errores. Si todo funciona correctamente, ¡enhorabuena! Has actualizado con éxito.

    Problemas comunes y soluciones en Zigbee2MQTT 2.0.0

    A pesar de los preparativos, pueden surgir problemas después de la actualización. Aquí tienes una lista de los más comunes y cómo resolverlos:

    1. Error: USB adapter discovery error

    Si Zigbee2MQTT no detecta tu adaptador:

    • Asegúrate de que el puerto y adaptador estén correctamente configurados en configuration.yaml de zigbee2mqtt. Por ejemplo:
    serial:
  port: /dev/serial/by-id/usb-Silicon_Labs_Sonoff_Zigbee_3.0_USB_Dongle_Plus_0001-if00-port0
  adapter: zstack
    • Si usas ezsp y no funciona, puedes intentar cambiar el adaptador a ember y reinicia Zigbee2MQTT.

    2. Cambios en Home Assistant

    Algunas entidades pueden desaparecer o cambiar. Por ejemplo:

    • Las entidades de bloqueo infantil ahora son interruptores.
    • Se eliminaron atributos de entidad heredados. Usa exposes para personalizarlas.

    3. Problemas con dispositivos específicos

    Consulta la documentación del dispositivo en la web de Zigbee2MQTT para ver si ha habido cambios en nombres o atributos.

    4. Configuraciones eliminadas automáticamente

    Si ves configuraciones eliminadas en migration-1-to-2.log, revísalas y actualízalas según sea necesario.

    5. Si nada de esto funciona: actualizar el firmware del dispositivo

    Si después de verificar la configuración, los adaptadores y otros pasos no logras que Zigbee2MQTT funcione correctamente, es posible que el firmware de tu dongle Zigbee necesite una actualización. La versión 2.0.0 introduce cambios que podrían no ser compatibles con firmware más antiguo. En este otro artículo, te explico cómo actualizar el ZBDongle P y E de Sonoff.

    Opinión personal

    Desde mi experiencia, actualizar a Zigbee2MQTT 2.0.0 puede requerir tiempo y paciencia, pero vale la pena. Esta guía intenta ayudarte a minimizar los posibles problemas que te puedan salir. Esta versión ofrece una gestión más eficiente y elimina configuraciones obsoletas, lo que mejora el rendimiento y la seguridad de nuestra red Zigbee. Si sigues estos pasos, te aseguro que el proceso será mucho más fluido.

    Sígueme a YouTube

    Actualizar Zigbee2MQTT 2.0.0

    Ajustes