Zigbee2MQTT en tu Raspberry Pi: arma una red Zigbee local sin nube con Home Assistant

Tu Raspberry Pi como cerebro Zigbee de la casa

¿Tienes una ampolleta IKEA Trådfri, un sensor Aqara y un enchufe Sonoff y te das cuenta de que cada marca te pide su propio hub, su propia app y su propia cuenta en la nube? Zigbee2MQTT corta ese nudo de raíz. Conectas un solo dongle USB Zigbee a tu Raspberry Pi, dejas que Home Assistant haga de tablero central y todos los dispositivos. de cualquier marca. quedan hablando en la misma red local, sin pasar nunca por internet.

Al terminar este tutorial vas a tener un coordinador Zigbee funcionando en el Raspberry Pi, un broker MQTT corriendo dentro de Home Assistant, el add on de Zigbee2MQTT instalado y configurado, y al menos un dispositivo Zigbee (ampolleta, sensor o enchufe) ya emparejado y visible desde el dashboard. También vas a entender por qué la prolongación USB es obligatoria, qué hacer cuando el adaptador no aparece, y cómo actualizar el firmware del dongle Sonoff sin abrir la carcasa.

Concepto: por qué Zigbee + MQTT + Home Assistant juntos

Zigbee es un protocolo de radio de baja energía, pensado para sensores y actuadores que viven con pila o enchufados, con la gracia de armar una malla: cada dispositivo enchufado a la red eléctrica repite la señal y extiende el alcance. El problema histórico es que cada fabricante usaba su propia capa lógica encima de Zigbee, así que para conversar con un sensor Aqara necesitabas un hub de Aqara, y para una ampolleta Hue, una bridge Philips.

Zigbee2MQTT mete una capa de traducción universal en el medio: un único dongle USB recibe el tráfico Zigbee de cualquier fabricante y lo convierte a mensajes MQTT, que es el bus de mensajería estándar que ya entiende Home Assistant. Resultado: 3.000+ dispositivos compatibles, una sola interfaz, todo local. Si se cae tu internet, igual tus rutinas siguen funcionando.

Hardware necesario antes de empezar

No hace falta una bestia: cualquier Raspberry Pi con Home Assistant OS ya corriendo te sirve. Lo que sí marca diferencia es el dongle y, sobre todo, la prolongación USB.

• Raspberry Pi 3 B+, 4 o 5 con Home Assistant OS instalado y funcionando en tu red.
• Tarjeta microSD 32 GB (o SSD, mejor todavía) para el sistema.
• Fuente USB-C 5 V 3 A para Pi 4 o 5 (microUSB 2.5 A para Pi 3).
• Dongle Zigbee USB (coordinador). El más probado es el Sonoff Zigbee 3.0 USB Dongle Plus.
• Cable de extensión USB de 30 a 50 cm: imprescindible para alejar el dongle del Raspberry Pi.

La razón del cable extensor no es estética: el procesador del Raspberry Pi y los puertos USB 3.0 generan ruido electromagnético en la misma banda de 2.4 GHz que usa Zigbee. Si enchufas el dongle directo al Pi, vas a notar que dispositivos a 5 metros se desconectan o no emparejan. Con 30 cm de separación el problema desaparece. Es el truco más barato y más subestimado de todo este setup.

Paso 1: Mosquitto Broker, el bus de mensajes

Zigbee2MQTT no habla directo con Home Assistant: ambos se conectan a un broker MQTT que actúa como intermediario. La opción estándar es Mosquitto, que viene como add on oficial de Home Assistant.

Dentro de Home Assistant:

1. Ve a Ajustes → Complementos → Tienda de complementos.
2. Busca Mosquitto broker y pulsa Instalar (toma 1 a 2 minutos).
3. Activa Iniciar al arrancar y luego pulsa Iniciar.

Mosquitto reutiliza automáticamente tu usuario y contraseña de Home Assistant, así que no tienes que crear credenciales nuevas. Apenas arranca, Home Assistant detecta la integración MQTT y te muestra un aviso del tipo "Se ha encontrado una nueva integración MQTT": pulsas Configurar y confirmas.

Paso 2: Agregar el repositorio de Zigbee2MQTT

Zigbee2MQTT no viene en el store oficial. Tienes que añadir su repositorio manualmente:

1. Ajustes → Complementos → Tienda de complementos.
2. Arriba a la derecha, menú ⋮ → Repositorios.
3. Pega esta URL y pulsa Añadir:

https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

4. Cierra la ventana, recarga el store y busca Zigbee2MQTT. Elige la versión estable y pulsa Instalar.

Importante: todavía no lo inicies. Antes hay que averiguar el puerto serial del dongle, porque sin ese dato el add on arranca en error.

Paso 3: Identificar el puerto serial del dongle

Enchufa el dongle al Raspberry Pi a través del cable extensor. Después:

1. Ajustes → Sistema → Hardware → System Hardware.
2. Busca tu dongle. En el Sonoff Dongle Plus la línea relevante se ve así:

/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0

Anota la ruta completa. La forma by-id es mucho mejor que /dev/ttyUSB0 porque sobrevive a reinicios: aunque cambies el dongle de puerto USB, el by-id sigue apuntando al mismo dispositivo.

Paso 4: Configurar Zigbee2MQTT

Vuelve a la página del add on Zigbee2MQTT → pestaña Configuración y pega esto (reemplazando el port con la ruta que anotaste):

data_path: /config/zigbee2mqtt
socat:
  enabled: false
zigbee2mqtt_config:
  homeassistant:
    enabled: true
  permit_join: false
  mqtt:
    base_topic: zigbee2mqtt
    server: mqtt://core-mosquitto
  serial:
    port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0

Pulsa Guardar y luego Iniciar. En la pestaña Log deberías ver a los pocos segundos:

Zigbee2MQTT:info Started successfully

Si aparece "Cannot find adapter", lo más probable es que el puerto esté mal copiado o que Mosquitto aún no esté corriendo. Revisa primero esos dos puntos antes de tocar nada más.

Paso 5: Emparejar tu primer dispositivo Zigbee

Zigbee2MQTT agrega un ícono propio a la barra lateral de Home Assistant. Desde ahí:

1. Pulsa en Zigbee2MQTT en la barra lateral.
2. Arriba a la derecha, activa Permit join (queda abierto 255 segundos).
3. Pon el dispositivo en modo de emparejamiento:
   • Sonoff: presiona el botón 5 segundos hasta que parpadee el LED.
   • IKEA Trådfri: 6 segundos el botón pequeño al lado de la ampolleta.
   • Aqara: 3 a 5 pulsaciones rápidas del botón.
4. El dispositivo aparece solo en la lista. Dale un nombre descriptivo ("Sensor living", "Ampolleta cocina").
5. Desactiva Permit join de nuevo para evitar emparejamientos accidentales.

Consejo de oro: cuando emparejes por primera vez, mantén el dispositivo a menos de 2 metros del dongle. Una vez aceptado, lo puedes llevar al otro extremo de la casa.

Gracias a MQTT Discovery, el dispositivo aparece automáticamente en Ajustes → Dispositivos y servicios → MQTT, listo para agregarlo al dashboard.

Solución de problemas habituales

Actualizar firmware del Sonoff Dongle Plus

Actualizar el firmware vale la pena cuando notas dispositivos que emparejan a medias, desconexiones aleatorias, o cuando Zigbee2MQTT te avisa de una nueva versión. Antes de empezar: para Zigbee2MQTT desde Ajustes → Complementos para liberar el dongle.

En el ZBDongle-P (chip CC2652P) se puede flashear sin abrir la carcasa. Primero baja la firmware coordinator del repositorio oficial Z-Stack firmware; el archivo se llama CC1352P2_CC2652P_launchpad_coordinator_*.zip y adentro viene el .hex que necesitas.

Instala cc2538-bsl en tu PC o en el mismo Raspberry Pi:

pip install pyserial intelhex
git clone https://github.com/JelmerT/cc2538-bsl.git

Y luego flashea (ajustando puerto y nombre del .hex):

python3 cc2538-bsl/cc2538_bsl.py -ewv \
  -p /dev/ttyUSB0 \
  --bootloader-sonoff-usb \
  ./CC1352P2_CC2652P_launchpad_coordinator_20230507.hex

El parámetro --bootloader-sonoff-usb activa el modo bootloader desde software, así que no hay que apretar ningún botón ni abrir el case. El flasheo demora 1 a 2 minutos. Después reinicia Zigbee2MQTT.

Para el ZBDongle-E (chip Silicon Labs EFR32MG21) el flasher universal de Python funciona bien:

pip install universal-silabs-flasher
universal-silabs-flasher \
  --device /dev/ttyACM0 \
  flash --firmware firmware.gbl

Las firmwares .gbl están en el repo Sonoff_Zigbee_Dongle_Firmware bajo la carpeta Dongle-E.

Variantes y mejoras

Una vez que tu red Zigbee local quede de pie, hay tres extensiones que valen la pena:

• Coordinador en red, no en USB: si tu Raspberry Pi vive en un lugar con mala cobertura para el resto de la casa, reemplaza el dongle USB por un coordinador Ethernet como el SMLIGHT SLZB-06. Lo pones en el centro físico del hogar, conectado por red, y Zigbee2MQTT se conecta por TCP (tcp://192.168.x.x:6638) en vez de puerto serial. La cobertura mejora muchísimo.
• Tablero de batería y RSSI: agrega al dashboard una tarjeta tipo entities con el nivel de batería de cada sensor y su LQI (Link Quality Indicator). Así detectas al toque cuándo una pila se está acabando o cuándo un dispositivo está demasiado lejos y necesita un repetidor (un enchufe inteligente en el medio resuelve).
• Automatización con Node RED: instala el add on Node RED en Home Assistant y conéctalo al mismo broker Mosquitto. Cada dispositivo Zigbee2MQTT publica en topics tipo zigbee2mqtt/sensor_living, así que puedes armar flujos visuales (sensor de movimiento → ampolleta on por 2 min → off) sin escribir YAML.

Personalización para Chile

En Chile arma este proyecto entero en MechatronicStore con componentes en stock local. Los productos clave para este montaje son:

• Raspberry Pi 5 4GB. la base para correr Home Assistant OS.
• Tarjeta microSD 32GB clase 10. sistema operativo y configuración.
• Cable Ethernet CAT6. recomendado para conectar tu Pi al router por cable (más estable que WiFi para un servidor que va a estar siempre prendido).
• Fuente USB-C 5 V 3 A. alimentación correcta para Pi 5 (con menos voltaje el sistema reinicia solo).
• Cable USB tipo A macho hembra para extensión. para alejar el dongle Zigbee del Raspberry Pi.

El Sonoff Zigbee 3.0 USB Dongle Plus es el modelo más probado de la comunidad Zigbee2MQTT y suele importarse directo; si no está en stock local, una alternativa válida es cualquier coordinator Zigbee compatible (ConBee II/III, SMLIGHT, ZZH). eso sí, no es intercambiable con dongles 433 MHz o LoRa: el protocolo es distinto. Los sensores Aqara e IKEA Trådfri se consiguen en marketplaces internacionales; si recién partes, mejor empieza con un solo dispositivo barato (un botón Aqara WXKG11LM o una ampolleta IKEA E27) para validar el setup antes de invertir más.

Recursos

• Tutorial original (alemán): Zigbee2MQTT einrichten, Schritt-für-Schritt Anleitung mit Home Assistant
• Repositorio Zigbee2MQTT add on: hassio zigbee2mqtt
• Firmware coordinator ZBDongle-P: Z-Stack firmware
• Firmware ZBDongle-E: Sonoff_Zigbee_Dongle_Firmware
• Documentación oficial Zigbee2MQTT: zigbee2mqtt.io

Versión chilena inspirada en el tutorial de raspberry.tips, adaptada con tuteo, contexto local y componentes en stock en MechatronicStore.