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

Si buscas la forma más robusta, profesional y universal de gestionar tu domótica, instalar Zigbee2MQTT en Home Assistant es la mejor decisión que puedes tomar en 2026. A diferencia de otras integraciones, Zigbee2MQTT te da compatibilidad con miles de dispositivos y un control total sobre tu red, sin depender de la nube y con una estabilidad a prueba de fallos.

Actualizado el 21 de febrero de 2026

En esta guía definitiva, actualizada para que sea tu referencia durante todo el año, vamos a desgranar desde la elección del hardware hasta trucos de configuración avanzada para que tu red Zigbee sea absolutamente infalible.

¿Por qué Zigbee2MQTT frente a ZHA? La Decisión Estratégica

Esta es la eterna duda para cualquiera que empiece con Zigbee en Home Assistant. Mientras que ZHA (Zigbee Home Automation) es la integración nativa y más sencilla de poner en marcha, Zigbee2MQTT es la elección de los expertos por motivos de peso. El debate ZHA vs Zigbee2MQTT se decanta por el segundo cuando buscas el máximo rendimiento:

Compatibilidad Extrema: Soporta un catálogo de dispositivos ligeramente mayor y, lo que es más importante, a menudo ofrece compatibilidad con dispositivos nuevos o «exóticos» antes que ZHA.
Independencia Total: Zigbee2MQTT funciona como un servicio separado. Si necesitas reiniciar Home Assistant por cualquier motivo, tu red Zigbee seguirá activa y funcionando en segundo plano. Los dispositivos seguirán comunicándose entre sí sin interrupción.
Flexibilidad y Depuración: Al usar un intermediario estándar como es un Broker MQTT, puedes utilizar herramientas externas como MQTT Explorer para «escuchar» todo lo que ocurre en tu red, facilitando enormemente la depuración de errores.
Portabilidad: Si en el futuro decides migrar a otra plataforma de domótica que soporte MQTT (como OpenHAB), podrías hacerlo sin tener que volver a emparejar todos tus dispositivos.

Tip para expertos: Si eres de los que no quiere renunciar a nada, he desarrollado un método único para integrar Zigbee2MQTT y ZHA con un solo coordinador, algo que hasta hace poco parecía imposible y que te permite probar lo mejor de ambos mundos.

El Hardware: El Cerebro de tu Red Zigbee en 2026

Para que Zigbee2MQTT funcione, necesitas un dispositivo físico llamado coordinador Zigbee. Este actúa como el cerebro central de la red. En 2026, la elección es más importante que nunca para asegurar la estabilidad y el alcance. Aquí tienes una comparativa de las mejores opciones:

Coordinador	Tipo	Pros	Contras	Precio Estimado (2026)
SONOFF Dongle-P	USB	– Muy fiable y estable (chip CC2652P) – Económico y fácil de encontrar – Gran comunidad de soporte	– Requiere un cable alargador USB para evitar interferencias – La cobertura depende de la ubicación del servidor de Home Assistant	15-25€
SONOFF Dongle-E	USB	– Chip más moderno (EFR32MG21) – Excelente rendimiento – Soporte oficial para Thread/Matter (futurible)	– También necesita alargador USB – Puede requerir actualizaciones de firmware para máxima estabilidad	20-30€
SMLIGHT SLZB-06	Ethernet/PoE	– La mejor cobertura: puedes colocarlo en el centro de la casa, conectado por cable de red – Alimentación por Ethernet (PoE) para una instalación limpia – Inmune a reinicios del servidor HA	– Más caro que las opciones USB – La configuración inicial es ligeramente más compleja (configurar IP)	50-70€

Mi recomendación para 2026: Si estás montando una red nueva y puedes permitírtelo, un coordinador Zigbee Ethernet como el SLZB-06 es la inversión más inteligente a largo plazo por su flexibilidad y cobertura. Para presupuestos más ajustados o instalaciones más pequeñas, el Sonoff Dongle Plus (tanto el modelo P como el E) sigue siendo una elección fantástica y fiable.

Paso 1: Instalar Mosquitto Broker, el Traductor Universal

Zigbee2MQTT no habla directamente con Home Assistant. Utiliza un lenguaje universal llamado MQTT. Para que se entiendan, necesitamos un «traductor» o intermediario, conocido como Broker. El estándar de facto en Home Assistant es Mosquitto.

Ve a Ajustes > Apps > Tienda de Apps en tu Home Assistant.
Busca e instala la App (anteriormente conocido como Add-on) de Mosquitto Broker.
Antes de iniciarlo, ve a la pestaña «Configuración». Deja todo como está, pero ve a Ajustes > Personas > Usuarios en Home Assistant y crea un nuevo usuario específico para MQTT (por ejemplo, `mqtt_user`). Esto es una buena práctica de seguridad.
Vuelve a la configuración de la App de Mosquitto, inicia la App y activa la opción «Vigilancia» para que se reinicie solo si falla.

Paso 2: Instalar la App de Zigbee2MQTT

Ahora que tenemos el traductor, instalemos el protagonista. Como la App oficial no está en la tienda por defecto, debemos añadir su repositorio.

En la Tienda de Apps, haz clic en los tres puntos de la esquina superior derecha y selecciona Repositorios.
Añade la siguiente URL oficial y pulsa «Añadir»:
https://github.com/zigbee2mqtt/hassio-addon
Cierra la ventana, refresca la página y busca Zigbee2MQTT en la lista. Instálalo.
¡MUY IMPORTANTE! No inicies la App todavía. Primero debemos configurarla.

Paso 3: Configurar Zigbee2MQTT (El Paso Crítico)

Este es el punto donde la mayoría de los usuarios fallan. Debemos decirle a Zigbee2MQTT dónde está nuestro coordinador (el pincho USB o el dispositivo de red) y cómo hablar con Mosquitto. Ve a la pestaña Configuración de la App de Zigbee2MQTT.

Ajuste del Puerto Serie

En el editor de configuración (normalmente en modo YAML), busca la sección serial. Aquí es donde indicas la ruta de tu hardware:

serial:
  # Para un Sonoff Dongle USB
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_v2_...

  # Para un coordinador Ethernet como el SLZB-06
  # port: tcp://192.168.1.50:6638

Para encontrar la ruta exacta de tu USB, puedes ir a Ajustes > Sistema > Hardware > Menú de 3 puntos > Todo el hardware y buscarlo en la lista.

Ajuste de la Conexión MQTT

Ahora, busca la sección mqtt y asegúrate de que apunta a Mosquitto y utiliza el usuario que creaste en el paso 1.

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

Guarda la configuración y ahora sí, ¡inicia la App de Zigbee2MQTT!

Paso 4: Emparejar tus Dispositivos

Si todo ha ido bien, la App se iniciará y el registro (Log) mostrará mensajes de conexión exitosa. Ahora viene la parte divertida.

Abre la Interfaz de usuario web de Zigbee2MQTT desde el panel lateral o la página de la App.
En la parte superior, haz clic en el botón «Permitir unirse (Todos)». El contador se pondrá en marcha.
Pon tu dispositivo Zigbee (bombilla, sensor, enchufe) en modo emparejamiento, siguiendo sus instrucciones (normalmente es dejar pulsado un botón o encender y apagar varias veces).
En pocos segundos, el dispositivo aparecerá en la lista de Zigbee2MQTT. Puedes cambiarle el nombre para que sea más amigable.
Automáticamente, una nueva entidad aparecerá en Home Assistant, ¡lista para usar en tus automatizaciones y paneles!

Cómo Migrar de ZHA a Zigbee2MQTT (Paso a Paso)

¿Ya usas ZHA y quieres dar el salto? El proceso requiere paciencia pero te dará una red mucho más potente. No es posible una migración «automática», tendrás que volver a emparejar los dispositivos, pero si lo haces de forma ordenada, minimizarás los problemas.

¡Haz una copia de seguridad! Antes de tocar nada, crea una copia de seguridad completa de tu Home Assistant. Te recomiendo usar la integración de copias en Google Drive.
Documenta tu red actual: Ve a la integración de ZHA y haz capturas de pantalla de todos tus dispositivos, prestando especial atención a los nombres de las entidades (ej: sensor.temperatura_salon).
Detén ZHA: Ve a Ajustes > Dispositivos y Servicios, busca ZHA y, en el menú de tres puntos, selecciona «Desactivar». No la borres todavía. Reinicia Home Assistant.
Instala y configura Zigbee2MQTT: Sigue los pasos 1, 2 y 3 de esta misma guía. Asegúrate de que el puerto serie de tu coordinador está correctamente configurado.
Empareja y renombra: Abre la interfaz de Zigbee2MQTT y empieza a emparejar tus dispositivos uno a uno. A medida que aparezcan, renómbralos con el mismo nombre amigable que tenían en ZHA. Zigbee2MQTT creará entidades con nombres muy parecidos (o idénticos), lo que salvará muchas de tus automatizaciones.
Verifica y elimina: Una vez que todos tus dispositivos estén funcionando en Zigbee2MQTT, puedes volver a la integración de ZHA y, ahora sí, eliminarla.

Configuración Avanzada y Mantenimiento

Una vez que tu red está en marcha, hay varias funciones avanzadas en Zigbee2MQTT que te darán un control aún mayor.

Actualizaciones OTA de Dispositivos

Muchos dispositivos Zigbee (especialmente de marcas como Philips Hue, IKEA o Aqara) reciben actualizaciones de firmware. Desde la interfaz de Zigbee2MQTT, en la pestaña «OTA», puedes comprobar si alguno de tus dispositivos tiene una actualización pendiente e instalarla directamente desde ahí, sin necesidad del hub oficial de la marca.

Grupos y Escenas

Si tienes varias luces en una misma habitación, en lugar de encenderlas una a una desde Home Assistant, puedes crear un grupo directamente en Zigbee2MQTT. Al hacerlo, envías un solo comando a la red Zigbee («encender grupo salón») en lugar de múltiples comandos individuales. Esto reduce la latencia y la congestión de la red, haciendo que la respuesta sea instantánea.

Interpretando el Mapa de Red

La pestaña «Mapa» es una herramienta de diagnóstico increíble. Te muestra cómo están conectados tus dispositivos. Las líneas verdes y con un número alto (LQI > 100) indican una conexión fuerte. Las líneas rojas o con LQI bajo señalan un enlace débil. Usa este mapa para identificar puntos ciegos y decidir dónde colocar un nuevo dispositivo alimentado por corriente (un enchufe, un relé o una bombilla) para que actúe como repetidor y fortalezca la red mesh.

Solución de Errores Comunes (FAQ)

Error 502 Bad Gateway al abrir la interfaz

Es el error más común. Significa que la App de Zigbee2MQTT no ha podido arrancar. Las causas más probables son: 1) Un error en la ruta del `puerto` serie en la configuración. 2) El coordinador USB se ha desconectado. 3) En coordinadores Ethernet, la IP ha cambiado. Revisa siempre la pestaña «Registro» (Log) para ver el mensaje de error exacto.

Mis dispositivos se desconectan o no responden

Esto suele deberse a dos problemas: interferencias o una red mesh débil. Para las interferencias, asegúrate de que tu pincho USB está en un alargador lejos de puertos USB 3.0 y del chasis del PC. También puedes cambiar el canal Zigbee en la configuración (el canal 25 es el que menos solapa con el WiFi de 2.4GHz). Para una red débil, añade más dispositivos que actúen como repetidores (enchufes o bombillas) repartidos por la casa.

Mi dispositivo no se empareja

Primero, asegúrate de que has activado «Permitir unirse» en Zigbee2MQTT. Si sigue sin aparecer, prueba lo siguiente: 1) Acércalo al coordinador para el primer emparejamiento. 2) Asegúrate de que la batería (si la tiene) es nueva. 3) Realiza el proceso de reseteo del dispositivo varias veces; a veces no funciona a la primera. 4) Comprueba en la web de Zigbee2MQTT si el dispositivo es compatible.

Error «Adapter disconnected» en el log

Este error indica un problema de comunicación física con el coordinador. Si es USB, prueba a cambiar el cable alargador o el puerto USB. Si es un coordinador Ethernet, verifica que el cable de red esté bien conectado y que el dispositivo tenga la IP que has configurado en Zigbee2MQTT y no haya cambiado.

¿Te ha servido esta guía definitiva? Si después de seguir estos pasos tienes dudas sobre qué coordinador elegir o te has atascado en la migración desde ZHA, déjame un comentario y te ayudaré. ¡Nos vemos en el próximo nivel de tu hogar inteligente!