Instalación de Zigbee2MQTT para Dispositivos Inteligentes

Zigbee2MQTT es una solución de código abierto que permite gestionar dispositivos Zigbee sin depender de puentes propietarios, usando MQTT como protocolo de comunicación. Con soporte para más de 3000 dispositivos de distintos fabricantes, puedes integrar sensores, bombillas, enchufes y más directamente con Home Assistant u otras plataformas de automatización del hogar.

Requisitos Previos

  • Servidor Linux (Ubuntu 20.04+, Debian 11+, o CentOS 8+)
  • Coordinador Zigbee USB (CC2652, SONOFF Zigbee 3.0 USB Dongle, etc.)
  • Node.js 18 o superior
  • Broker MQTT (Mosquitto)
  • Acceso root o sudo

Hardware Coordinador Zigbee

El coordinador es el componente más importante. Los más recomendados:

  • SONOFF Zigbee 3.0 USB Dongle Plus - basado en CC2652P, excelente cobertura
  • CC2652RB / CC2652P - amplio soporte de dispositivos
  • Conbee II (Dresden Elektronik) - alternativa compatible

Identifica el puerto USB del coordinador:

# Listar dispositivos USB conectados
ls -la /dev/ttyUSB* /dev/ttyACM*

# Ver detalles del dispositivo
dmesg | tail -20 | grep -i usb

Instalación del Broker MQTT

Zigbee2MQTT necesita un broker MQTT para comunicarse. Instala Mosquitto:

# Ubuntu/Debian
sudo apt update && sudo apt install -y mosquitto mosquitto-clients

# CentOS/Rocky
sudo dnf install -y mosquitto

# Habilitar y arrancar el servicio
sudo systemctl enable --now mosquitto

# Verificar que está escuchando
sudo ss -tlnp | grep 1883

Configura autenticación básica:

# Crear usuario para Zigbee2MQTT
sudo mosquitto_passwd -c /etc/mosquitto/passwd z2muser

# Crear configuración con autenticación
sudo tee /etc/mosquitto/conf.d/default.conf << 'EOF'
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd
EOF

sudo systemctl restart mosquitto

Instalación de Zigbee2MQTT

# Instalar Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Crear directorio de instalación
sudo mkdir -p /opt/zigbee2mqtt
sudo chown $USER:$USER /opt/zigbee2mqtt

# Clonar el repositorio
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

# Instalar dependencias
cd /opt/zigbee2mqtt
npm ci

# Verificar la instalación
node_modules/.bin/zigbee2mqtt --version

Configuración Básica

Crea el fichero de configuración principal:

sudo nano /opt/zigbee2mqtt/data/configuration.yaml

Contenido del fichero:

# Configuración del coordinador Zigbee
serial:
  port: /dev/ttyUSB0  # Ajusta según tu puerto
  adapter: deconz     # Usa 'zstack' para CC2652, 'deconz' para ConBee

# Configuración MQTT
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost
  user: z2muser
  password: TU_CONTRASEÑA_AQUI

# Interfaz web de administración
frontend:
  port: 8080
  host: 0.0.0.0

# Permitir nuevos dispositivos al inicio
permit_join: false

# Almacenamiento de dispositivos
homeassistant: false  # Cambiar a true si usas HA

advanced:
  log_level: info
  network_key: GENERATE  # Genera una clave de red aleatoria la primera vez

Crea el servicio systemd:

sudo tee /etc/systemd/system/zigbee2mqtt.service << 'EOF'
[Unit]
Description=Zigbee2MQTT
After=network.target mosquitto.service

[Service]
Type=simple
User=pi
ExecStart=/usr/bin/node /opt/zigbee2mqtt/index.js
WorkingDirectory=/opt/zigbee2mqtt
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now zigbee2mqtt

# Comprobar los logs
sudo journalctl -u zigbee2mqtt -f

Emparejamiento de Dispositivos

Para añadir nuevos dispositivos Zigbee:

# Activar modo de emparejamiento por 3 minutos vía MQTT
mosquitto_pub -h localhost -u z2muser -P TU_CONTRASEÑA \
  -t zigbee2mqtt/bridge/request/permit_join \
  -m '{"value": true, "time": 180}'

# Escuchar nuevos dispositivos que se unan
mosquitto_sub -h localhost -u z2muser -P TU_CONTRASEÑA \
  -t "zigbee2mqtt/#" -v

También puedes activar el emparejamiento desde la interfaz web en http://TU_IP:8080.

Una vez emparejado un dispositivo, edita data/configuration.yaml para asignarle un nombre amigable:

devices:
  '0x00158d0001234567':
    friendly_name: 'salon/lampara_principal'
  '0x00158d0009876543':
    friendly_name: 'cocina/sensor_temperatura'

Integración con Home Assistant

Para integrar con Home Assistant vía MQTT Discovery:

# En /opt/zigbee2mqtt/data/configuration.yaml
homeassistant: true

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost
  user: z2muser
  password: TU_CONTRASEÑA

En Home Assistant, añade la integración MQTT apuntando al mismo broker. Los dispositivos Zigbee2MQTT aparecerán automáticamente.

Para instalar Zigbee2MQTT como add-on de Home Assistant OS, usa el repositorio oficial: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Actualizaciones OTA

Zigbee2MQTT soporta actualizaciones de firmware Over-The-Air para muchos dispositivos:

# Comprobar actualizaciones disponibles para todos los dispositivos
mosquitto_pub -h localhost -u z2muser -P TU_CONTRASEÑA \
  -t zigbee2mqtt/bridge/request/extension/save \
  -m '{"name":"homeassistant","content":""}'

# Iniciar actualización OTA para un dispositivo específico
mosquitto_pub -h localhost -u z2muser -P TU_CONTRASEÑA \
  -t "zigbee2mqtt/salon/lampara_principal/set" \
  -m '{"update": {"action": "update"}}'

# Monitorizar el progreso de la actualización
mosquitto_sub -h localhost -u z2muser -P TU_CONTRASEÑA \
  -t "zigbee2mqtt/salon/lampara_principal" -v

Habilita las actualizaciones OTA en la configuración:

ota:
  update_check_interval: 1440  # Comprobar actualizaciones cada 24h (en minutos)
  disable_automatic_update_check: false

Solución de Problemas

El coordinador no se detecta:

# Verificar permisos del puerto serie
ls -la /dev/ttyUSB0
sudo usermod -aG dialout $USER
# Necesitas cerrar sesión y volver a entrar para aplicar el cambio

Error "coordinator firmware is not up to date":

# Flashear firmware actualizado con cc2538-bsl
pip3 install cc2538-bsl
python3 -m cc2538-bsl -p /dev/ttyUSB0 --bootloader-sonoff-usb \
  -evw firmware.hex

Dispositivos que no responden:

# Ver log completo con nivel debug
sudo sed -i 's/log_level: info/log_level: debug/' \
  /opt/zigbee2mqtt/data/configuration.yaml
sudo systemctl restart zigbee2mqtt
sudo journalctl -u zigbee2mqtt -f --no-pager

Puerto MQTT rechazado:

# Comprobar que Mosquitto está corriendo
sudo systemctl status mosquitto

# Probar credenciales manualmente
mosquitto_sub -h localhost -u z2muser -P TU_CONTRASEÑA -t "test"

Conclusión

Zigbee2MQTT proporciona una solución robusta y sin dependencias propietarias para gestionar dispositivos Zigbee en tu infraestructura Linux. Con soporte para más de 3000 dispositivos y una integración fluida con Home Assistant, es la base ideal para cualquier instalación de domótica seria. Mantén el firmware del coordinador actualizado y usa la interfaz web para monitorizar el estado de tu red Zigbee.