Cómo conectar dispositivos Zigbee: ZHA o Zigbee2MQTT

7 min
Iniciación

Conectar dispositivos Zigbee a Home Assistant requiere un coordinador de radio y un software que gestione la red.

Para crear esta red mallada, conectaremos un coordinador como el Sonoff Zigbee 3.0 o el Home Assistant Connect ZBT-2 a nuestro Mini PC o Raspberry Pi. Conviene separarlo del servidor con el cable incluido o un alargador USB para reducir interferencias.

Pero el hardware por sí solo no hace nada. Necesitamos un software que actúe como “driver”, que sepa comunicarse por el puerto serie (UART) con el chip del Dongle, interpretar las tramas del protocolo Zigbee y convertirlas en Entidades dentro de Home Assistant.

Aquí nos enfrentamos a la gran decisión técnica de la comunidad maker. Existen dos caminos principales para gestionar nuestra red: ZHA (Zigbee Home Automation) y Zigbee2MQTT. Vamos a analizar en profundidad la arquitectura de ambos para decidir cuál implementar.

ZHA: la vía integrada

ZHA es la integración oficial de Home Assistant para redes Zigbee. Viene incluida en el núcleo, por lo que no requiere instalar ningún contenedor ni aplicación adicional.

Arquitectura de ZHA

A nivel de arquitectura de software, ZHA es un componente de Python que se ejecuta directamente dentro del mismo proceso de Home Assistant.

El flujo de datos es directo y monolítico:

ZHA abre una conexión por el puerto serie (ej. /dev/ttyUSB0) con el Dongle.
Escucha los eventos Zigbee (ej. “Sensor de puerta abierto”).
Transforma ese evento directamente en un cambio de estado en la máquina de estados de Home Assistant (binary_sensor.puerta pasa a on).

Simplicidad extrema (Plug & Play): Al conectar el Dongle USB, Home Assistant lo detecta automáticamente por la interfaz gráfica. Haces un par de clics y ya estás emparejando bombillas.
Integración visual: Toda la gestión de la red (mapa topológico, actualizaciones OTA, configuración de dispositivos) se hace directamente desde los menús nativos de Ajustes de Home Assistant.
Menos puntos de fallo: Al no depender de servicios externos ni intermediarios, hay menos piezas de software que puedan fallar o desconfigurarse.

Acoplamiento con Home Assistant: Al estar integrado en el Core, ZHA deja de procesar eventos mientras Home Assistant se reinicia. Los enlaces directos entre dispositivos compatibles pueden seguir funcionando, pero las automatizaciones que dependen de Home Assistant quedan pausadas.
Soporte de dispositivos nuevos: Cuando un fabricante se aparta del estándar, ZHA puede necesitar reglas específicas llamadas quirks. Su disponibilidad depende de que alguien añada y pruebe el modelo, así que conviene consultar la compatibilidad antes de comprar.

Zigbee2MQTT: una arquitectura independiente

En el otro extremo tenemos Zigbee2MQTT, un proyecto independiente de código abierto y mantenido por la comunidad, que se ha convertido en la herramienta preferida por los usuarios avanzados y los integradores de sistemas.

Arquitectura de Zigbee2MQTT

Z2M es un software independiente, generalmente ejecutado mediante una aplicación de HAOS o en su propio contenedor. Su arquitectura está desacoplada de Home Assistant.

El concepto técnico es muy sólido y se basa en el uso de un Broker MQTT (como Mosquitto):

Z2M toma el control exclusivo del Dongle USB por el puerto serie.
Z2M traduce las tramas Zigbee complejas a un formato de texto universal (cargas útiles o payloads en JSON).
Z2M publica esos JSON en un servidor MQTT.
Home Assistant, mediante su integración MQTT, lee esos mensajes y actualiza sus Entidades.

Si no estás familiarizado con MQTT, no te preocupes. Es el protocolo de mensajería estándar en la industria IoT. Dedicaremos un artículo completo a entender cómo funciona un Broker MQTT más adelante en el nivel Maker.

Desacoplamiento: Como Z2M es un servicio independiente, puede seguir gestionando la radio mientras Home Assistant se reinicia. Las automatizaciones de Home Assistant no se ejecutarán durante ese intervalo, pero Z2M y el broker continúan recibiendo mensajes.
Catálogo amplio: Zigbee2MQTT soporta miles de modelos y publica una lista detallada de dispositivos. El soporte de un equipo nuevo depende de que exista un convertidor compatible, por lo que también debemos comprobarlo antes de comprar.
Topología distribuida: Gracias a usar MQTT, puedes tener Home Assistant instalado en un servidor en el sótano, y tener una Raspberry Pi con Z2M y el Dongle USB en el centro del salón. Se comunicarán por la red Ethernet/WiFi de tu casa.
Interfaz de administración avanzada: Z2M incluye un panel de control web propio (accesible desde el menú lateral de HA) que ofrece herramientas de diagnóstico muy potentes, mapas de red detallados y control exhaustivo de las actualizaciones de firmware (OTA) de los dispositivos.

Curva de aprendizaje inicial: Requiere configurar tres piezas distintas: Instalar el Add-on del Broker MQTT (Mosquitto), instalar el Add-on de Zigbee2MQTT, y configurar la Integración MQTT en Home Assistant para que hablen entre ellos.
Mayor consumo de recursos: Al ejecutar servicios en contenedores separados, consume ligeramente más memoria RAM que ZHA (nada preocupante en un Mini PC, pero a tener en cuenta en una Raspberry Pi muy antigua).

Qué opción elegir

Ambas opciones son excepcionales y completamente funcionales. La decisión depende estrictamente de tu perfil técnico y tus objetivos a largo plazo:

Si quieres domótica fácil, rápida y sin complicaciones: Usa ZHA. Es el camino de menor resistencia, funciona muy bien para el 90% de los hogares y está soportado oficialmente.
Si eres un usuario técnico, tienes una casa grande o planeas integrar decenas de sensores raros de AliExpress: Ve directamente a por Zigbee2MQTT. El tiempo extra que inviertas en configurar MQTT te lo ahorrarás con creces en estabilidad y compatibilidad futura.

Por nuestra preferencia por arquitecturas desacopladas, vamos a utilizar Zigbee2MQTT. Aprender a manejar MQTT nos abrirá además las puertas a integrar nuestros propios sistemas más adelante en el curso.

No conviene ir cambiando alegremente entre ZHA y Zigbee2MQTT una vez que la casa ya está montada. Migrar una red Zigbee no es como cambiar el tema oscuro de una aplicación. A veces implica reemparejar dispositivos, reconstruir nombres de entidades y revisar automatizaciones. Mejor elegir bien al principio.

Y un detalle importante: un mismo dongle Zigbee solo puede estar controlado por un software cada vez. No podéis tener ZHA y Zigbee2MQTT usando simultáneamente el mismo coordinador USB.

El proceso de emparejamiento

Independientemente del software que elijas, el proceso físico para añadir dispositivos a la red es idéntico:

Activas el modo “Permitir unirse” (Permit join) en la interfaz de ZHA o Z2M. Esto abre temporalmente la red (generalmente durante 5 minutos).
Pones el dispositivo físico en modo emparejamiento (normalmente manteniendo pulsado un botón durante 5 segundos hasta que parpadea un LED).
El Coordinador y el dispositivo negocian las claves de seguridad por el aire.
El dispositivo aparece en la pantalla y se generan sus Entidades en Home Assistant.

Emparejad los dispositivos en su ubicación final siempre que podáis. Si emparejáis todos los sensores al lado del coordinador y luego los repartís por la casa, algunos se quedarán asociados a rutas poco óptimas hasta que la malla se recalcule. Funciona, sí, pero a veces da guerra.

Una vez que tenemos nuestros sensores WiFi (Shelly, Sonoff) y nuestra malla Zigbee reportando datos en tiempo real al servidor, la base de datos de Home Assistant empieza a llenarse de información útil.