Zigbee2MQTT es un puente de código abierto que habla directamente con dispositivos Zigbee (sensores, bombillas, enchufes, interruptores) a través de un coordinador USB y publica su estado en un broker MQTT. Así puedes usar dispositivos de muchos fabricantes sin sus pasarelas propietarias. En este tutorial instalarás Mosquitto y Zigbee2MQTT en Ubuntu 24.04, lo ejecutarás como servicio de systemd, emparejarás un dispositivo y lo integrarás con Home Assistant.

Requisitos previos

Para seguir esta guía necesitas:

  • Un equipo con Ubuntu 24.04 LTS (o Debian 12) al alcance de la radio de tus dispositivos: un mini PC, un Raspberry Pi 4/5 o un servidor doméstico. El coordinador se conecta por USB, así que un servidor en un centro de datos no sirve para esta parte.
  • Un usuario no root con privilegios sudo.
  • Un coordinador Zigbee compatible. Los más habituales son:
CoordinadorChipValor de adapter
SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-P)TI CC2652Pzstack
SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-E)Silicon Labs EFR32MG21ember
ConBee II / ConBee IIIDresden Elektronikdeconz

Paso 1: Identificar el coordinador

Conecta el coordinador y localiza su ruta estable en /dev/serial/by-id/. Esta ruta no cambia entre reinicios, a diferencia de /dev/ttyUSB0 o /dev/ttyACM0:

ls -l /dev/serial/by-id/

lrwxrwxrwx 1 root root 13 Sep 25 10:12 usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_4c2f1a7b-if00-port0 -> ../../ttyUSB0

Copia la ruta completa; la usarás en el paso 5. El dispositivo pertenece al grupo dialout, así que añade tu usuario a ese grupo para que Zigbee2MQTT pueda abrirlo:

sudo usermod -aG dialout $USER

Cierra la sesión SSH y vuelve a entrar para que el cambio de grupo tenga efecto. Compruébalo con groups; dialout debe aparecer en la lista.

Paso 2: Instalar y configurar Mosquitto

Zigbee2MQTT publica el estado de los dispositivos y recibe órdenes a través de MQTT. Instala el broker Mosquitto y sus clientes:

sudo apt update
sudo apt install mosquitto mosquitto-clients

Crea un usuario para Zigbee2MQTT. El comando pide la contraseña dos veces:

sudo mosquitto_passwd -c /etc/mosquitto/passwd z2m
sudo chown mosquitto:mosquitto /etc/mosquitto/passwd
sudo chmod 600 /etc/mosquitto/passwd

Si más adelante conectas Home Assistant, crea otro usuario para él con el mismo comando pero sin -c, que sobrescribiría el fichero.

Activa la autenticación y un listener en el puerto 1883:

sudo nano /etc/mosquitto/conf.d/zigbee.conf

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Reinicia Mosquitto y comprueba que acepta al usuario. Sustituye your_mqtt_password por la contraseña que acabas de crear:

sudo systemctl restart mosquitto
mosquitto_pub -h localhost -u z2m -P your_mqtt_password -t prueba -m hola && echo OK

OK

Paso 3: Instalar Node.js 22 y dependencias de compilación

Zigbee2MQTT 2.x necesita Node.js 20 o superior, y Ubuntu 24.04 trae la 18. Añade el repositorio de NodeSource para la rama 22 LTS con su clave en /etc/apt/keyrings:

sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

Instala Node.js junto con git y las herramientas que necesitan algunos módulos nativos:

sudo apt update
sudo apt install nodejs git make g++ gcc libsystemd-dev

Zigbee2MQTT usa pnpm como gestor de paquetes. Node.js 22 incluye Corepack, que lo proporciona:

sudo corepack enable
node --version
pnpm --version

v22.19.0
10.15.1

La primera llamada a pnpm puede pedir confirmación para descargarlo; responde Y.

Paso 4: Descargar Zigbee2MQTT

Crea el directorio de instalación, dáselo a tu usuario y clona la rama estable:

sudo mkdir /opt/zigbee2mqtt
sudo chown -R $USER: /opt/zigbee2mqtt
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

Instala las dependencias exactas del fichero de bloqueo:

cd /opt/zigbee2mqtt
pnpm install --frozen-lockfile

La instalación tarda unos minutos en un Raspberry Pi. Termina sin errores con un resumen de paquetes añadidos.

Paso 5: Configurar Zigbee2MQTT

Parte del fichero de ejemplo que incluye el repositorio:

cp /opt/zigbee2mqtt/data/configuration.example.yaml /opt/zigbee2mqtt/data/configuration.yaml
nano /opt/zigbee2mqtt/data/configuration.yaml

Ajusta estas secciones y deja el resto del fichero (incluida la clave version) como está:

homeassistant:
  enabled: false

frontend:
  enabled: true
  port: 8080

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883
  user: z2m
  password: your_mqtt_password

serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_4c2f1a7b-if00-port0
  adapter: zstack

advanced:
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE
  log_level: info
  • serial.port es la ruta del paso 1 y adapter el valor de la tabla de requisitos.
  • GENERATE hace que Zigbee2MQTT cree una clave de red y unos identificadores aleatorios en el primer arranque y los guarde en este fichero. No los cambies después: todos los dispositivos emparejados dependen de ellos.

Haz una primera ejecución manual para ver los mensajes de arranque:

cd /opt/zigbee2mqtt
pnpm start

[2026-09-25 10:25:31] info:  z2m: Starting Zigbee2MQTT version 2.6.1
[2026-09-25 10:25:33] info:  z2m: Coordinator firmware version: '{"meta":{...},"type":"zStack3x0"}'
[2026-09-25 10:25:34] info:  z2m: Connected to MQTT server
[2026-09-25 10:25:34] info:  z2m: Started frontend on port 8080
[2026-09-25 10:25:34] info:  z2m: Zigbee2MQTT started!

La primera vez compila el código antes de arrancar, así que tarda algo más. Cuando veas Zigbee2MQTT started!, detenlo con Ctrl+C.

Paso 6: Ejecutar Zigbee2MQTT como servicio

Crea una unidad de systemd para que arranque con el sistema y se reinicie si falla:

sudo nano /etc/systemd/system/zigbee2mqtt.service

Sustituye your_user por tu nombre de usuario:

[Unit]
Description=Zigbee2MQTT
After=network.target mosquitto.service

[Service]
Environment=NODE_ENV=production
ExecStart=/usr/bin/node index.js
WorkingDirectory=/opt/zigbee2mqtt
User=your_user
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

Recarga systemd y activa el servicio:

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

● zigbee2mqtt.service - Zigbee2MQTT
     Loaded: loaded (/etc/systemd/system/zigbee2mqtt.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-09-25 10:31:02 CEST; 6s ago

Los mensajes del servicio se consultan con journalctl -u zigbee2mqtt -f.

Paso 7: Emparejar un dispositivo

La interfaz web escucha en el puerto 8080. Si solo vas a usarla desde tu red local, ábrela para esa red; sustituye 192.168.1.0/24 por tu rango:

sudo ufw allow from 192.168.1.0/24 to any port 8080 proto tcp

Abre http://your_server_ip:8080 en el navegador y pulsa Permit join (All). La red acepta dispositivos nuevos durante unos minutos. Pon el dispositivo en modo de emparejamiento según su manual (normalmente mantener pulsado el botón unos segundos o encender y apagar una bombilla varias veces).

También puedes abrir el emparejamiento por MQTT durante 180 segundos:

mosquitto_pub -h localhost -u z2m -P your_mqtt_password -t zigbee2mqtt/bridge/request/permit_join -m '{"time": 180}'

Cuando el dispositivo se una, el registro lo confirma:

journalctl -u zigbee2mqtt -n 20 --no-pager

info:  z2m: Device '0x00158d0001a2b3c4' joined
info:  z2m: Successfully interviewed '0x00158d0001a2b3c4', device has successfully been paired

Dale un nombre descriptivo. Puedes hacerlo desde la interfaz web o por MQTT:

mosquitto_pub -h localhost -u z2m -P your_mqtt_password -t zigbee2mqtt/bridge/request/device/rename -m '{"from": "0x00158d0001a2b3c4", "to": "salon/sensor_temperatura"}'

Comprueba que el dispositivo publica su estado en el nuevo topic:

mosquitto_sub -h localhost -u z2m -P your_mqtt_password -t 'zigbee2mqtt/salon/#' -v

zigbee2mqtt/salon/sensor_temperatura {"battery":100,"humidity":52.3,"linkquality":120,"temperature":21.8,"voltage":3005}

Pulsa Ctrl+C para salir.

Paso 8: Integrar con Home Assistant

Zigbee2MQTT anuncia cada dispositivo a Home Assistant mediante MQTT Discovery, de modo que aparecen solos con sus entidades. Activa la integración en configuration.yaml:

nano /opt/zigbee2mqtt/data/configuration.yaml

homeassistant:
  enabled: true

Reinicia el servicio:

sudo systemctl restart zigbee2mqtt

En Home Assistant ve a Ajustes > Dispositivos y servicios > Añadir integración > MQTT e indica la IP de este equipo, el puerto 1883 y un usuario de Mosquitto. Si Home Assistant está en otra máquina, permite su IP en el cortafuegos:

sudo ufw allow from 192.168.1.50 to any port 1883 proto tcp

Tras unos segundos, los dispositivos de Zigbee2MQTT aparecen en la integración MQTT con sus sensores y controles.

Paso 9: Actualizar firmware de dispositivos (OTA)

Muchos dispositivos admiten actualizaciones de firmware por el aire. La forma más sencilla es la pestaña OTA de la interfaz web, que busca y aplica actualizaciones por dispositivo. Por MQTT, primero comprueba si hay una disponible:

mosquitto_pub -h localhost -u z2m -P your_mqtt_password -t zigbee2mqtt/bridge/request/device/ota_update/check -m '{"id": "salon/sensor_temperatura"}'

Si la hay, lanza la actualización:

mosquitto_pub -h localhost -u z2m -P your_mqtt_password -t zigbee2mqtt/bridge/request/device/ota_update/update -m '{"id": "salon/sensor_temperatura"}'

La actualización puede tardar más de 30 minutos en dispositivos a batería; el progreso aparece en el registro del servicio.

Solución de problemas

Error: Failed to connect to the adapter o Permission denied al abrir el puerto. Comprueba que la ruta de serial.port existe con ls -l /dev/serial/by-id/, que tu usuario está en dialout y que el valor de adapter corresponde al chip del coordinador.

Not authorized al conectar con MQTT. El usuario o la contraseña de la sección mqtt no coinciden con los de Mosquitto. Pruébalos con mosquitto_sub -h localhost -u z2m -P your_mqtt_password -t prueba.

Los dispositivos se desconectan o no se emparejan. Aleja el coordinador de puertos USB 3.0 con un alargador y añade dispositivos alimentados por red (enchufes, bombillas) entre el coordinador y los sensores lejanos: actúan como repetidores. La pestaña Map de la interfaz web muestra la calidad de cada enlace.

Conclusión

Tienes Zigbee2MQTT funcionando como servicio, con Mosquitto protegido por contraseña, un dispositivo emparejado con nombre propio e integración automática con Home Assistant. Como siguientes pasos, puedes proteger la interfaz web con frontend.auth_token, hacer copias de seguridad periódicas del directorio /opt/zigbee2mqtt/data (contiene la clave de red y la base de datos de dispositivos) y actualizar Zigbee2MQTT con git pull seguido de pnpm install --frozen-lockfile y un reinicio del servicio.