--- title: "Cómo instalar Zigbee2MQTT en Ubuntu 24.04 con Mosquitto" description: "Instala Zigbee2MQTT con Node.js y Mosquitto en Ubuntu 24.04, configura el coordinador USB, empareja dispositivos Zigbee y conéctalo con Home Assistant." category: "Automatización del Hogar e IoT" language: es source: https://cubepath.com/es/docs/automatización-del-hogar-e-iot/instalacion-de-zigbee2mqtt-dispositivos-inteligentes updated: 2026-09-25 --- # Cómo instalar Zigbee2MQTT en Ubuntu 24.04 con Mosquitto 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: | Coordinador | Chip | Valor de `adapter` | |---|---|---| | SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-P) | TI CC2652P | `zstack` | | SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-E) | Silicon Labs EFR32MG21 | `ember` | | ConBee II / ConBee III | Dresden Elektronik | `deconz` | > Consejo: conecta el coordinador con un cable alargador USB, lejos de puertos USB 3.0 y discos externos. Sus interferencias en 2,4 GHz son la causa más frecuente de una red Zigbee inestable. ## 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`: ```bash ls -l /dev/serial/by-id/ ``` ```output 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: ```bash 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: ```bash sudo apt update sudo apt install mosquitto mosquitto-clients ``` Crea un usuario para Zigbee2MQTT. El comando pide la contraseña dos veces: ```bash 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: ```bash sudo nano /etc/mosquitto/conf.d/zigbee.conf ``` ```ini 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: ```bash sudo systemctl restart mosquitto mosquitto_pub -h localhost -u z2m -P your_mqtt_password -t prueba -m hola && echo OK ``` ```output 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`: ```bash 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: ```bash 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: ```bash sudo corepack enable node --version pnpm --version ``` ```output 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: ```bash 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: ```bash 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: ```bash 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á: ```yaml 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: ```bash cd /opt/zigbee2mqtt pnpm start ``` ```output [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: ```bash sudo nano /etc/systemd/system/zigbee2mqtt.service ``` Sustituye `your_user` por tu nombre de usuario: ```ini [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: ```bash sudo systemctl daemon-reload sudo systemctl enable --now zigbee2mqtt sudo systemctl status zigbee2mqtt ``` ```output ● 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: ```bash 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: ```bash 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: ```bash journalctl -u zigbee2mqtt -n 20 --no-pager ``` ```output 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: ```bash 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: ```bash mosquitto_sub -h localhost -u z2m -P your_mqtt_password -t 'zigbee2mqtt/salon/#' -v ``` ```output 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`: ```bash nano /opt/zigbee2mqtt/data/configuration.yaml ``` ```yaml homeassistant: enabled: true ``` Reinicia el servicio: ```bash 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: ```bash 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: ```bash 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: ```bash 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.