Configurar Zigbee2MQTT con Gladys: hub Zigbee local, sin nube
Zigbee2MQTT te permite tener tu propio hub Zigbee local con Gladys: conectas un dongle USB Zigbee a la máquina en la que funciona Gladys y controlas todos tus dispositivos Zigbee directamente desde casa, sin cuenta en la nube y sin el puente del fabricante. Este tutorial te muestra cómo configurarlo, emparejar tu dongle y añadir dispositivos.
Gladys instala y gestiona por ti Zigbee2MQTT y su broker MQTT: consulta Zigbee2MQTT sin Home Assistant. ¿Todavía estás eligiendo un dongle? Lee nuestra guía de compra de dongles Zigbee.
En resumen, vamos a conectar tus dispositivos Zigbee directamente a Gladys, sin necesidad de puentes de terceros (solo con un dongle USB Zigbee y el proyecto Zigbee2Mqtt).
Puedes consultar la lista de dispositivos compatibles aquí.
Antes de empezar, asegúrate de tener un coordinador Zigbee: un dongle USB conectado a la máquina en la que funciona Gladys, o un coordinador de red (consulta Usar un coordinador de red más abajo).
Un dongle USB sencillo y económico que hemos probado con Gladys es el dongle USB Sonoff Zigbee 3.0.
La lista completa de adaptadores compatibles está disponible en la lista de adaptadores compatibles con Zigbee2mqtt.
Configurar el puerto del dongle USB
Conecta tu dongle USB Zigbee a la máquina en la que funciona Gladys (tu Raspberry Pi, tu NAS).

En Gladys, ve a Integraciones / Zigbee2Mqtt y después haz clic en Configuración en el menú.
Gladys muestra los puertos USB de la máquina, cada uno con el nombre del dispositivo conectado, por ejemplo ITead Sonoff Zigbee 3.0 USB Dongle Plus (/dev/ttyUSB0). Los demás puertos serie, los de la propia máquina y los de los HAT GPIO (como la RaspBee), están ocultos: haz clic en Mostrar los demás puertos serie (HAT GPIO, puertos de la máquina) para verlos.

Gladys reconoce los dongles más habituales (SONOFF ZBDongle-P y ZBDongle-E, Home Assistant Connect ZBT-1 y ZBT-2, ConBee II y III, SMLIGHT SLZB-06M y SLZB-07…). Si reconoce tu dongle, su puerto y su modelo ya están seleccionados: no tienes que elegir nada.
Si no, selecciona el puerto y después el modelo de tu dongle en la lista:

El modelo es obligatorio: así Zigbee2mqtt sabe qué configuración debe usar.
Si tienes un dongle basado en EmberZNet (como por ejemplo el Sonoff Zigbee 3.0 ZBDongle-E), te recomendamos actualizar el firmware del dongle. Si no, elige la opción (legacy ezsp) en la lista, aunque Gladys haya seleccionado por ti el modelo de tu dongle.
Si ejecutas Gladys en un disco externo conectado por USB, puedes tener problemas de alimentación, ya que tu Pi puede tener dificultades para suministrar suficiente energía tanto al disco como al dongle USB Zigbee.
Te recomendamos usar un hub USB con alimentación externa.
Puedes leer más al respecto en la web de Zigbee2MQTT: Zigbee2MQTT fails to start
Usar un coordinador de red
Desde Gladys 5, el coordinador ya no tiene que estar conectado a la máquina en la que funciona Gladys. Un coordinador de red (SMLIGHT SLZB-06/SLZB-07, ZigStar…) se conecta por Ethernet o Wi-Fi, así que puedes colocarlo en el centro de tu casa, lejos de tu servidor y de las interferencias. Gladys sigue instalando y gestionando Zigbee2MQTT por ti.
En Integraciones / Zigbee2Mqtt, en la configuración:
- En ¿Cómo está conectado el coordinador Zigbee?, elige Coordinador de red (Ethernet/Wi-Fi).
- Introduce la dirección y el puerto TCP del coordinador, por ejemplo
tcp://192.168.1.20:6638(el prefijotcp://es opcional). Asigna al coordinador una dirección IP fija en tu router. - Selecciona el tipo de adaptador indicado en la documentación de tu coordinador: el SLZB-06 usa
zstack, y el SLZB-06M y el SLZB-07 usanember.
Después, continúa con el siguiente paso para activar Zigbee2MQTT.
Activar Zigbee2Mqtt
Una vez configurado tu dongle, Gladys necesita instalar dos contenedores (MQTT y Zigbee2Mqtt) para usar el dongle y comunicarse con todos tus dispositivos. No te preocupes, todo esto está automatizado.
Ve a la sección Configuración y haz clic en el botón Activar Zigbee2mqtt. Tras unos instantes (el tiempo de espera depende del modelo de tu Raspberry Pi y de tu ancho de banda), deberías ver todos los elementos iniciados y las conexiones entre ellos en verde.

Gladys solo muestra Zigbee2MQTT en verde cuando realmente se ha iniciado y ha respondido a Gladys. Mientras tanto, un mensaje bajo el esquema te indica en qué punto está:
- Zigbee2MQTT se está iniciando: aparece como "Reiniciando". Espera un momento, se pondrá en verde en cuanto responda a Gladys.
- Zigbee2MQTT no consigue iniciarse: Gladys muestra el error encontrado encima del esquema. Consulta Solucionar los errores habituales de Zigbee2MQTT.
- Zigbee2MQTT no responde: Gladys no obtiene respuesta; quizá esté detenido o se bloquee al iniciarse. Consulta la misma sección.
Mientras Zigbee2MQTT no responda, las páginas Descubrir y Dispositivos muestran el aviso "Zigbee2mqtt no responde" y el emparejamiento de dispositivos está desactivado. El aviso desaparece por sí solo en cuanto Zigbee2MQTT está listo.
Permitir el emparejamiento de dispositivos
Para que los dispositivos puedan emparejarse con tu red Zigbee, debes permitir la unión (joining in) en la configuración de Zigbee.
Haz clic en el menú Descubrir y después en el botón Permitir la unión.

⚠️ Una vez emparejados tus dispositivos, tendrás que volver aquí para bloquear el emparejamiento, por seguridad.
Añadir dispositivos
Para que tu dispositivo se una a la red, consulta su manual. En la mayoría de los casos, basta con mantener pulsado el botón físico.
Los dispositivos ya emparejados con tu red Zigbee aparecerán automáticamente en la lista con sus funcionalidades detectadas. Puedes cambiarles el nombre y asignarlos a una habitación con la lista desplegable.

Modificar los dispositivos
Si es necesario, puedes ir al menú Dispositivos para modificar o completar la configuración de tus dispositivos.
Haz clic en el botón Editar de un dispositivo. Podrás cambiar su nombre, la habitación a la que pertenece y el nombre de cada funcionalidad.

Uso
Ahora puedes usar estos dispositivos Zigbee desde el panel de control o automáticamente desde las escenas. Según la funcionalidad de cada dispositivo, tendrás acceso a mediciones, estados o acciones.
Solucionar los errores habituales de Zigbee2MQTT
La mayoría de los problemas de Zigbee2MQTT tienen tres causas: el puerto USB equivocado, el tipo de adaptador equivocado o interferencias en la banda de 2,4 GHz. Estos son los errores que tienes más probabilidades de encontrarte y lo que significan realmente.
Error while starting zigbee-herdsman
Zigbee2MQTT no ha podido comunicarse en absoluto con tu dongle. Comprueba, en este orden:
- El puerto USB seleccionado en
Integraciones / Zigbee2Mqtt / Configuraciónes aquel en el que está conectado tu dongle. Si has cambiado el dongle de puerto, o has reiniciado con un disco conectado, el nombre del puerto puede haber cambiado. - El modelo de dongle seleccionado en los ajustes corresponde a tu hardware. Un dongle Silicon Labs configurado como uno de Texas Instruments (o al revés) falla justo aquí.
- Nada más está usando el dongle. Solo una instancia de Zigbee2MQTT puede ocupar el adaptador.
- El dongle recibe suficiente alimentación. Desconéctalo, vuelve a conectarlo a través de un hub USB alimentado o de un cable alargador USB corto, y reinicia la integración.
Failed to connect to the adapter (SRSP - SYS - ping after 6000ms)
Este error es específico de los coordinadores Texas Instruments (CC2652 / ZBDongle-P): el adaptador está ahí, pero no responde. Casi siempre se debe a un puerto equivocado, a un tipo de adaptador incorrecto en los ajustes o a un dongle que hay que desconectar y volver a conectar físicamente. Si persiste, volver a flashear el firmware del coordinador resuelve los casos restantes.
Adapter EZSP protocol version (8) is not supported by host
Tu dongle EmberZNet (Silicon Labs), normalmente un Sonoff ZBDongle-E, tiene un firmware más antiguo que el que espera la versión actual de Zigbee2MQTT. Tienes dos opciones:
- actualizar el firmware del dongle, que es la opción recomendada, o
- seleccionar la opción
(legacy ezsp)en la lista de modelos de dongle en Gladys, para que Zigbee2MQTT use el protocolo antiguo.
MQTT failed to connect, exiting (connection refused: not authorized)
Zigbee2MQTT se ha iniciado, pero el broker MQTT ha rechazado sus credenciales. En Gladys, ambos contenedores se gestionan por ti, así que rara vez tendrás que tocar un archivo de configuración: vuelve a la sección Configuración, desactiva Zigbee2MQTT y vuelve a activarlo. Gladys recrea ambos contenedores con credenciales coincidentes. Si además usas la integración MQTT con tu propio broker, asegúrate de no haber apuntado Zigbee2MQTT hacia él con un nombre de usuario o una contraseña diferentes.
MAC channel access failure
Es un problema de radio, no de software: el coordinador no consigue un hueco libre en el aire. Las causas y soluciones habituales:
- El dongle está conectado directamente a la máquina, junto a puertos USB 3.0, un SSD o la propia Raspberry Pi. Aléjalo con un cable alargador USB de un metro aproximadamente: es, con diferencia, la solución más eficaz.
- Tu Wi-Fi y tu red Zigbee se solapan en la banda de 2,4 GHz. Cambia el canal de tu Wi-Fi o el de tu red Zigbee para que no coincidan.
- El dispositivo está demasiado lejos del coordinador. Coloca entre ambos un dispositivo Zigbee conectado a la red eléctrica (un enchufe o una bombilla): estos actúan como routers y amplían la malla.
Si tu problema no aparece aquí, la documentación de Zigbee2MQTT trata en detalle los fallos de arranque, y el foro de Gladys es un buen lugar para buscar tu mensaje de error exacto.
Preguntas frecuentes
¿Cómo añado un dispositivo a Zigbee2MQTT en Gladys?
Una vez activado Zigbee2MQTT, abre el menú Descubrir, haz clic en Permitir la unión y pon tu dispositivo en modo de emparejamiento (normalmente manteniendo pulsado su botón). El dispositivo aparece automáticamente en la lista con sus funcionalidades detectadas, donde puedes cambiarle el nombre y asignarlo a una habitación. Recuerda desactivar la unión después, por seguridad.
¿Qué dongle USB Zigbee debo usar con una Raspberry Pi o un NAS?
Funciona cualquier adaptador de la lista de adaptadores compatibles con Zigbee2MQTT. Un dongle económico que hemos probado con Gladys es el dongle USB Sonoff Zigbee 3.0. Conéctalo a la máquina en la que funciona Gladys (tu Raspberry Pi o tu NAS); si arrancas desde un disco USB, usa un hub USB alimentado para que el dongle reciba suficiente energía. Nuestra guía de compra de dongles Zigbee compara los modelos más habituales.
¿Zigbee2MQTT con Gladys funciona sin la nube?
Sí. Zigbee2MQTT se ejecuta en local en tu propio hardware y se comunica con tus dispositivos a través del dongle USB, así que tu red Zigbee sigue funcionando sin conexión a internet y sin cuenta en la nube del fabricante.
¿Qué puerto y qué ajustes debo seleccionar para mi dongle Zigbee?
En Gladys, ve a Integraciones / Zigbee2Mqtt y después a Configuración. Gladys muestra tus puertos USB con el nombre del dispositivo conectado a cada uno y reconoce los dongles más habituales: su puerto y su modelo ya están seleccionados. Si no, eliges el puerto que corresponde a tu dongle y seleccionas el modelo de dongle para que Zigbee2MQTT cargue la configuración adecuada.
¿Por qué no arranca Zigbee2MQTT?
Casi siempre porque Zigbee2MQTT no consigue llegar al coordinador: el puerto USB seleccionado no es el correcto, el modelo de dongle de los ajustes no corresponde a tu hardware, el dongle no recibe suficiente alimentación o su firmware es demasiado antiguo (el error EZSP protocol version is not supported en los dongles Sonoff ZBDongle-E). Comprueba primero el puerto y el modelo en los ajustes de la integración y, después, desconecta y vuelve a conectar el dongle a través de un hub alimentado o de un cable alargador USB.
¿Por qué mis dispositivos Zigbee se desconectan continuamente?
La causa principal son las interferencias en la banda de 2,4 GHz, que aparecen como MAC channel access failure en los logs. Aleja el dongle de la máquina con un cable alargador USB de un metro, mantenlo lejos de los puertos USB 3.0 y de los SSD, asegúrate de que los canales de tu Wi-Fi y de Zigbee no se solapan y añade dispositivos Zigbee conectados a la red eléctrica, que actúan como routers y amplían la malla.