Zigbee2MQTT Home Assistant: Guía Definitiva de Instalación

Este artículo puede contener enlaces de afiliado. Si compras desde estos enlaces, el precio para ti es el mismo y la tienda me paga una pequeña comisión que ayuda a mantener Tecnoyfoto.

Si buscas una red Zigbee flexible, local y con un soporte muy amplio dentro de Home Assistant, Zigbee2MQTT sigue siendo una de las opciones más completas en 2026. Es compatible con un catálogo enorme de dispositivos, muestra controles muy detallados y ofrece buenas herramientas para administrar y diagnosticar tu red Zigbee.

Actualizado el 16 de junio de 2026

Actualización de junio de 2026: se ha corregido la ruta de acceso a la Tienda de Apps de Home Assistant, se ha sustituido la dirección antigua del repositorio de Zigbee2MQTT y se ha adaptado la instalación al asistente de configuración actual.

Aviso sobre el vídeo: fue grabado con una versión anterior de la interfaz. Para realizar una instalación nueva, sigue los pasos escritos y actualizados de esta guía, especialmente la ruta de la Tienda de Apps, la dirección del repositorio y el asistente inicial de Zigbee2MQTT.

En esta guía veremos el proceso completo: elegir coordinador, instalar Mosquitto, añadir la App oficial de Zigbee2MQTT, completar el asistente inicial, emparejar dispositivos, migrar desde ZHA y resolver los problemas más habituales.

Antes de empezar: el método mediante Apps de Home Assistant explicado aquí está pensado para Home Assistant OS y Home Assistant Supervised. La App actual de Zigbee2MQTT necesita un sistema de 64 bits y se recomienda utilizar una Raspberry Pi 4 o un equipo superior.

Zigbee2MQTT o ZHA: ¿cuál deberías elegir?

ZHA está integrado directamente en Home Assistant y suele ser la opción más sencilla para montar una primera red Zigbee. Zigbee2MQTT necesita un broker MQTT y una aplicación adicional, pero ofrece más visibilidad y más opciones de control para quien quiere profundizar.

Compatibilidad muy amplia: Zigbee2MQTT admite un catálogo enorme y suele incorporar con rapidez dispositivos nuevos o poco habituales.
Control detallado: su interfaz reúne funciones del dispositivo, informes, vinculaciones, grupos, registros, actualizaciones OTA e información de la red.
Flexibilidad mediante MQTT: permite inspeccionar los mensajes con herramientas externas y conectarlo con otras plataformas de automatización compatibles.
Servicio separado: cuando Zigbee2MQTT está instalado como App de Home Assistant, reiniciar Home Assistant Core normalmente no detiene Zigbee2MQTT. Sin embargo, las automatizaciones y los paneles de Home Assistant sí dependen de que Home Assistant esté disponible.

Importante: ZHA y Zigbee2MQTT no pueden controlar el mismo coordinador al mismo tiempo. Puedes utilizar ambos en una misma instalación de Home Assistant, pero cada uno necesita su propio coordinador y su propia red Zigbee.

Elegir un coordinador Zigbee en 2026

El coordinador es la radio central que crea y administra tu red Zigbee. Elegir un modelo fiable, colocarlo bien y construir una malla sólida es más importante que limitarse a escoger entre ZHA o Zigbee2MQTT.

Coordinador	Conexión	Ventajas	Aspectos que debes considerar
SONOFF ZBDongle-P	USB	Chip de Texas Instruments fiable, soporte maduro, precio contenido y una comunidad muy amplia	Conviene usar un alargador USB y alejarlo de puertos USB 3.0, discos SSD, puntos de acceso Wi-Fi y cajas metálicas
SONOFF ZBDongle-E	USB	Chip moderno de Silicon Labs, compatible oficialmente con Zigbee2MQTT y con buen rendimiento	Utiliza el controlador `ember`; conviene mantener su firmware actualizado y usar un alargador USB
SMLIGHT SLZB-06	Ethernet / PoE	Puede colocarse en una zona central, no necesita estar junto al servidor y permite una instalación limpia mediante PoE	Reserva una dirección IP fija y, para la conexión serie por red, es preferible utilizar Ethernet por cable en lugar de Wi-Fi

Mi recomendación práctica: un coordinador USB continúa siendo una opción excelente cuando el servidor de Home Assistant está bien situado. Si el servidor está dentro de un armario, un rack, un sótano o una esquina de la vivienda, un coordinador Zigbee Ethernet te da mucha más libertad para colocar la radio donde realmente tenga sentido.

Paso 1: instalar Mosquitto Broker

Zigbee2MQTT se comunica con Home Assistant mediante MQTT. En Home Assistant OS o Supervised, la opción más sencilla es utilizar la App oficial de Mosquitto Broker.

Ve a Ajustes > Apps.
Pulsa el botón Añadir situado en la esquina inferior derecha para abrir la Tienda de Apps.
Busca Mosquitto broker, instálalo e inícialo.
Activa Iniciar al arrancar y Vigilancia.
Ve a Ajustes > Personas > Usuarios y crea un usuario dedicado para Zigbee2MQTT, por ejemplo mqtt_user. No utilices los nombres reservados homeassistant ni addons.
Si no ves el apartado Usuarios, activa el Modo avanzado en tu perfil de Home Assistant.
Ve a Ajustes > Dispositivos y servicios. Si Home Assistant ha detectado la integración MQTT, configúrala y asegúrate de que el descubrimiento MQTT está habilitado.

Guarda el nombre de usuario y la contraseña de MQTT. Los necesitarás durante el asistente inicial de Zigbee2MQTT.

Paso 2: añadir el repositorio oficial de Zigbee2MQTT

Vuelve a Ajustes > Apps y pulsa Añadir para abrir la Tienda de Apps.
Abre el menú de los tres puntos y selecciona Repositorios.
Añade exactamente esta dirección oficial:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
Cierra la ventana de repositorios y actualiza la Tienda de Apps si fuera necesario.
Instala la App estable Zigbee2MQTT. La versión Edge está pensada para probar versiones de desarrollo y no es la adecuada para la mayoría de las viviendas.

Paso 3: iniciar Zigbee2MQTT y completar el asistente

La App actual de Zigbee2MQTT muestra una página de configuración guiada durante el primer inicio. Este es ahora el método recomendado para ponerlo en marcha.

Inicia la App de Zigbee2MQTT.
Abre su interfaz web. La primera pantalla debería mostrar el asistente inicial.
En la configuración MQTT, utiliza mqtt://core-mosquitto:1883 como servidor e introduce el usuario y la contraseña MQTT que has creado antes.
Selecciona tu coordinador en el apartado de dispositivos encontrados. Zigbee2MQTT normalmente completará de forma automática la ruta y el tipo de adaptador.
Indica el canal Wi-Fi de 2,4 GHz que utilizas cuando el asistente te lo solicite. Esto le ayudará a sugerir un canal Zigbee con menos interferencias.
Comprueba que estén habilitadas la integración con Home Assistant y la interfaz de Zigbee2MQTT.
Guarda la configuración y deja unos segundos para que Zigbee2MQTT termine de arrancar.

Si la página muestra brevemente el error 502 Bad Gateway, espera unos segundos y actualízala. Si continúa sin abrirse después de aproximadamente dos minutos, revisa el registro de la App para ver el error exacto.

Configuración manual del adaptador si no se detecta

La detección automática es la opción más sencilla. Configura el adaptador manualmente solo cuando Zigbee2MQTT no consiga encontrarlo. Estos ejemplos muestran los valores principales.

SONOFF ZBDongle-P:

serial:
  port: /dev/serial/by-id/usb-RUTA_DE_TU_DONGLE
  adapter: zstack

SONOFF ZBDongle-E:

serial:
  port: /dev/serial/by-id/usb-RUTA_DE_TU_DONGLE
  adapter: ember

SMLIGHT SLZB-06 mediante Ethernet:

serial:
  port: tcp://192.168.1.50:6638
  adapter: zstack

Para un coordinador USB, utiliza siempre que sea posible la ruta estable /dev/serial/by-id/... en lugar de una ruta temporal como /dev/ttyUSB0. Puedes localizarla en Ajustes > Sistema > Hardware > Todo el hardware.

La configuración esencial de MQTT y Home Assistant debe ser equivalente a esta:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://core-mosquitto:1883
  user: tu_usuario_mqtt
  password: 'tu_password_mqtt'

homeassistant:
  enabled: true

frontend:
  enabled: true

Nota: la App de Home Assistant y el asistente inicial pueden mostrar estos valores como campos separados, en lugar de un único bloque YAML.

Paso 4: emparejar tus dispositivos Zigbee

Abre la interfaz web de Zigbee2MQTT.
Pulsa Permitir unirse (Todos) en la esquina superior derecha. La red permanecerá abierta durante un tiempo limitado.
Restablece el dispositivo Zigbee a valores de fábrica o ponlo en modo de emparejamiento siguiendo las instrucciones del fabricante.
Espera a que Zigbee2MQTT complete la identificación y configuración del dispositivo.
Asigna al dispositivo un nombre claro y colócalo en el área correspondiente de Home Assistant.
Cierra el permiso de unión cuando hayas terminado de emparejar.

Si el descubrimiento MQTT está activo y homeassistant.enabled está configurado como true, el dispositivo y sus entidades deberían aparecer automáticamente en Home Assistant.

Cómo migrar de ZHA a Zigbee2MQTT

No existe una migración universal con un solo clic desde ZHA a Zigbee2MQTT. En la mayoría de los casos tendrás que restablecer los dispositivos y volver a emparejarlos. Planifica el cambio con cuidado, especialmente cuando tus dispositivos Zigbee forman parte de automatizaciones importantes.

Opción A: reutilizar el mismo coordinador

Esta opción no requiere comprar otro coordinador, pero provoca más tiempo de interrupción porque ZHA y Zigbee2MQTT no pueden utilizar el mismo coordinador simultáneamente.

Crea una copia de seguridad completa de Home Assistant.
Anota todos los dispositivos, áreas, identificadores de entidad, automatizaciones, tarjetas, escenas y scripts que dependan de ZHA.
Desactiva ZHA y comprueba que haya liberado el coordinador antes de iniciar Zigbee2MQTT.
Configura Zigbee2MQTT con ese coordinador.
Restablece y empareja de nuevo los dispositivos, empezando por los routers alimentados por corriente y continuando después con los dispositivos a batería.
En Home Assistant, cambia manualmente los nuevos identificadores de entidad cuando sea necesario. Utilizar el mismo nombre descriptivo en Zigbee2MQTT no garantiza que Home Assistant recupere automáticamente el antiguo entity_id.
Prueba todas las automatizaciones, escenas, scripts y paneles antes de eliminar la configuración antigua de ZHA.

Opción B: utilizar un segundo coordinador

Normalmente es el método de migración más seguro. ZHA y Zigbee2MQTT pueden funcionar a la vez cuando cada uno utiliza un coordinador diferente y una red Zigbee independiente. Así puedes mover los dispositivos poco a poco sin dejar toda la casa fuera de servicio.

Mantén funcionando la red ZHA existente.
Instala un segundo coordinador para Zigbee2MQTT.
Mueve primero los routers alimentados por corriente para crear una base sólida en la nueva malla de Zigbee2MQTT.
Mueve gradualmente los dispositivos a batería y actualiza sus identificadores de entidad y automatizaciones en Home Assistant.
Elimina ZHA únicamente cuando hayas probado por completo la migración.

Configuración avanzada y mantenimiento

Actualizaciones de firmware OTA

Zigbee2MQTT puede ofrecer actualizaciones inalámbricas de firmware para los dispositivos compatibles. La disponibilidad depende del fabricante y del modelo exacto. Antes de instalar una actualización, revisa sus notas y evita actualizar todos los dispositivos al mismo tiempo. Una nueva versión puede solucionar problemas, pero también puede cambiar el comportamiento del dispositivo o introducir incompatibilidades.

Grupos Zigbee

Cuando varias bombillas o interruptores deben reaccionar juntos, puedes crear un grupo Zigbee dentro de Zigbee2MQTT. Un comando de grupo mejora la sincronización y reduce el número de órdenes individuales que envía Home Assistant. No convierte todas las respuestas en literalmente instantáneas, pero normalmente consigue un funcionamiento más uniforme.

Mapa de red y calidad del enlace

El mapa de red sirve para ver qué dispositivos actúan como routers y cómo está conectada la malla, pero solo representa una instantánea. Algunos dispositivos a batería que permanecen dormidos pueden no aparecer aunque estén funcionando correctamente.

No juzgues la salud de la red por un único valor LQI ni por el color de una línea. Distintos fabricantes y chips calculan y muestran LQI y RSSI de manera diferente, por lo que pueden resultar engañosos. Los síntomas reales —órdenes lentas, mensajes fallidos, desconexiones frecuentes o rutas inestables— son más importantes que perseguir una cifra concreta.

Copias de seguridad

Crea copias de seguridad periódicas de Home Assistant y comprueba que incluyan los datos de la App de Zigbee2MQTT. La información de la red Zigbee se guarda tanto en el coordinador como en los archivos de datos de Zigbee2MQTT, por lo que conservar esos datos es esencial cuando mueves o restauras una instalación.

Solución de problemas frecuentes

¿Por qué aparece “502 Bad Gateway” al abrir Zigbee2MQTT?

Un error 502 durante unos segundos justo después de iniciar la App puede ser normal. Espera un poco y actualiza la página. Si continúa durante más de aproximadamente dos minutos, consulta el registro de Zigbee2MQTT. Las causas habituales son una ruta o un tipo de adaptador incorrectos, credenciales MQTT no válidas, otra integración como ZHA utilizando el coordinador o un coordinador Ethernet que no responde.

¿Por qué mis dispositivos se desconectan o dejan de responder?

Las causas más frecuentes son las interferencias, una mala ubicación del coordinador, routers Zigbee poco fiables o una malla débil. Usa un alargador USB, aleja el coordinador de dispositivos USB 3.0, discos SSD, puntos de acceso Wi-Fi y cajas metálicas, y añade buenos routers Zigbee alimentados por corriente que permanezcan siempre encendidos. No cambies el canal Zigbee a la ligera: el canal adecuado depende de tu entorno Wi-Fi y el cambio puede obligar a volver a emparejar algunos dispositivos.

¿Por qué no se empareja mi dispositivo Zigbee?

Comprueba que el permiso de unión esté activo, confirma que el dispositivo se haya restablecido a valores de fábrica y sigue las instrucciones del modelo exacto. Cambia la batería si fuera necesario y prueba a emparejarlo cerca del coordinador o mediante un router adecuado situado cerca de su ubicación definitiva. Comprueba también que el modelo sea compatible con Zigbee2MQTT.

¿Qué significa el error “Adapter disconnected”?

Zigbee2MQTT ha perdido la comunicación con el coordinador. En dispositivos USB, revisa el alargador, el puerto USB, la alimentación, el firmware y la ruta del hardware. En coordinadores Ethernet, comprueba el cable de red, la dirección IP fija, la alimentación y el puerto TCP. Asegúrate también de que ninguna otra aplicación o integración esté intentando utilizar el mismo coordinador.

El dispositivo aparece en Zigbee2MQTT, pero no en Home Assistant. ¿Qué debo revisar?

Comprueba que la integración MQTT esté configurada en Home Assistant, que el descubrimiento MQTT esté activo y que la integración de Home Assistant esté habilitada en Zigbee2MQTT mediante homeassistant.enabled: true. Después revisa los registros de Mosquitto y Zigbee2MQTT para localizar errores de autenticación o descubrimiento.

¿Pueden ZHA y Zigbee2MQTT utilizar el mismo coordinador al mismo tiempo?

No. Cada coordinador debe estar dedicado a una sola aplicación y a una única red Zigbee. Puedes utilizar ZHA y Zigbee2MQTT simultáneamente dentro de Home Assistant únicamente cuando cada uno tiene un coordinador independiente.

¿Te ha servido esta guía? Si todavía tienes problemas para elegir coordinador, conectar Mosquitto o emparejar un dispositivo concreto, deja un comentario indicando el modelo del coordinador y el error exacto que aparece en el registro de Zigbee2MQTT.