Configurar Zigbee2MQTT: del coordinador al panel

Configurar Zigbee2MQTT te permite usar sensores, bombillas e interruptores Zigbee de muchas marcas sin sus hubs ni sus nubes, y expone cada dispositivo como topics MQTT sencillos. En esta guía elegirás un coordinador, ejecutarás Zigbee2MQTT en Docker, lo conectarás a un broker, emparejarás y renombrarás dispositivos, los controlarás desde la línea de comandos y verás sus estados en un panel. Todo se prueba primero contra el servidor MQTT público gratuito, pensado para pruebas y no para datos de producción, con un base topic único.

Cómo encaja Zigbee2MQTT

Zigbee2MQTT es un puente. Por un lado, controla un coordinador Zigbee (un stick USB o un adaptador de red) que forma tu malla Zigbee. Por el otro, es un cliente MQTT que publica el estado de cada dispositivo como JSON y escucha comandos. Cualquier cosa que hable MQTT, como Home Assistant, Node-RED, un script en Python o una app móvil, puede entonces usar esos dispositivos.

[Zigbee devices] ~~radio~~ [Coordinator] --USB/TCP-- [Zigbee2MQTT] --MQTT-- [Broker] -- [Dashboards, automations]

El broker se sitúa en el centro y es lo único a lo que se conecta cada consumidor. Si quieres repasar qué hace un broker MQTT, merece la pena leerlo rápidamente antes de empezar.

Cómo elegir un coordinador

El coordinador determina qué valor de adapter usas. Opciones populares y bien soportadas:

Coordinador	Chip	Valor de `adapter`	Notas
Sonoff Zigbee 3.0 USB Dongle Plus (ZBDongle-P)	TI CC2652P	`zstack`	Muy extendido; flashea un firmware Z-Stack reciente
Sonoff ZBDongle-E	Silicon Labs EFR32MG21	`ember`	Usa el firmware EmberZNet actual
Familia SMLIGHT SLZB-06	CC2652P o EFR32	`zstack` o `ember`	Ethernet/PoE, conexión mediante `tcp://IP:6638`
ConBee II / III	Dresden Elektronik	`deconz`	Funciona, pero los adaptadores TI y Silicon Labs son más habituales

Dos consejos prácticos marcan una gran diferencia. Usa un cable alargador USB de aproximadamente medio metro para alejar el stick de los puertos USB 3 y los SSD, cuyas interferencias pueden reducir drásticamente el alcance Zigbee. Y añade pronto algunos routers alimentados por red eléctrica (enchufes o bombillas inteligentes), porque los dispositivos a batería no enrutan y una malla con solo dispositivos finales es frágil.

Instalación de Zigbee2MQTT con Docker

Busca la ruta estable de tu adaptador, que no cambia entre reinicios:

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

Crea una carpeta con un docker-compose.yml:

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXX-if00-port0:/dev/ttyACM0

Sustituye la ruta del dispositivo por la de tu sistema y establece tu zona horaria. Para una instalación permanente, fija la imagen a una versión concreta en lugar de latest, para que las actualizaciones se produzcan cuando tú decidas.

El archivo de configuración de Zigbee2MQTT

Crea data/configuration.yaml antes del primer arranque. Elige un segmento aleatorio para el base topic, porque el servidor público es compartido y cualquiera puede leerlo:

homeassistant:
  enabled: false
frontend:
  enabled: true
  port: 8080
mqtt:
  base_topic: connectmq/demo/z7q4/z2m
  server: mqtt://broker.connectmq.com:1883
  client_id: z2m-z7q4-bridge
serial:
  port: /dev/ttyACM0
  adapter: zstack
availability:
  enabled: true
advanced:
  log_level: info
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

Puntos clave:

base_topic es el prefijo de todo lo que publica Zigbee2MQTT. Aquí tiene cuatro niveles, lo que deja margen dentro del límite de 8 niveles de topic del broker público.
client_id debe ser único y no estar vacío en el broker.
channel no puede cambiarse más tarde sin volver a emparejar todos los dispositivos. Los canales 15, 20 y 25 evitan los solapamientos con Wi-Fi más comunes; comprueba qué canales Wi-Fi están ocupados a tu alrededor.
GENERATE hace que Zigbee2MQTT cree una clave de red y unos ID aleatorios en el primer arranque y los escriba de vuelta en el archivo. Después, haz una copia de seguridad de configuration.yaml y coordinator_backup.json de la carpeta de datos.
availability publica {"state":"online"} u offline por dispositivo, algo muy útil en los paneles.

Arráncalo y sigue el log:

docker compose up -d
docker compose logs -f zigbee2mqtt

Deberías ver la versión del firmware del coordinador y, a continuación, una línea que confirma la conexión con el broker MQTT. Si arrancas sin archivo de configuración, las versiones recientes abren una página de incorporación en el puerto 8080 donde puedes introducir los mismos valores en un formulario.

Emparejar y nombrar dispositivos

Abre el frontend en http://<host>:8080 y haz clic en Permit join (All), o activa el emparejamiento por MQTT durante un máximo de 254 segundos:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/permit_join" -m '{"time": 254}'

Pon el dispositivo en modo de emparejamiento (normalmente con una pulsación larga de su botón o una secuencia de encendidos y apagados en el caso de las bombillas). Aparece con una dirección IEEE como 0x00158d0001abcd12. Renómbralo de inmediato con algo significativo, porque el nombre se convierte en su topic:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/device/rename" \
  -m '{"from": "0x00158d0001abcd12", "to": "living_room_lamp"}'

Detén el emparejamiento con {"time": 0} cuando termines. Dejar la red abierta invita a que los dispositivos de los vecinos se unan por accidente.

Usa guiones bajos en lugar de barras en los nombres descriptivos mientras pruebas en el broker público. Un nombre como living_room/lamp está permitido y crea jerarquías más claras, pero cada barra añade un nivel de topic, y bridge/request/device/rename ya usa los 8 niveles con este base topic.

Leer y controlar dispositivos por MQTT

Suscríbete a todo lo que hay bajo el base topic:

mosquitto_sub -h broker.connectmq.com -p 1883 -i z2m-watch-z7q4 -t "connectmq/demo/z7q4/z2m/#" -v

Un sensor de temperatura publica en connectmq/demo/z7q4/z2m/hallway_sensor:

{"battery": 97, "humidity": 48.2, "linkquality": 116, "temperature": 21.4, "voltage": 2995}

Controla una bombilla publicando en su topic set:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/living_room_lamp/set" \
  -m '{"state": "ON", "brightness": 180, "color_temp": 370, "transition": 2}'

Para pedir a un dispositivo su estado actual, publica {"state": ""} en su topic get. Los topics de dispositivo llevan el estado completo, así que un panel solo necesita una suscripción por dispositivo.

De MQTT a un panel

Como Zigbee2MQTT habla MQTT estándar, tienes varias opciones de panel:

El frontend de Zigbee2MQTT para la gestión: lista de dispositivos, mapa de red, actualizaciones OTA y logs.
Home Assistant mediante su integración MQTT. Establece homeassistant.enabled: true y Zigbee2MQTT publicará mensajes de descubrimiento para que las entidades aparezcan automáticamente; la guía de Home Assistant con MQTT cubre esa parte.
Node-RED Dashboard, suscribiéndose a los topics de dispositivo con un nodo mqtt in y un nodo JSON.
Un panel en el navegador que use MQTT sobre WebSocket, conectándose a wss://broker.connectmq.com:8084/mqtt.

Para comprobaciones rápidas sin construir nada, el explorador de topics en directo del portal de ConnectMQ muestra cada topic de Zigbee2MQTT a medida que se actualiza, algo práctico mientras emparejas y renombras.

Solución de problemas al configurar Zigbee2MQTT

Síntoma	Causa probable	Solución
"Failed to connect to the adapter"	`adapter` o ruta de dispositivo incorrectos	Ajústalo según la tabla anterior; usa la ruta `/dev/serial/by-id`
Los dispositivos se desconectan o se emparejan mal	Interferencias de USB 3, sin routers	Cable alargador, añadir routers alimentados por red eléctrica
Se conecta al broker y luego se desconecta	Client ID duplicado	Un `client_id` único por puente
Mensajes del puente rechazados en el broker público	Payloads grandes de `bridge/devices` o `bridge/definitions` en redes más grandes	Prueba con pocos dispositivos, usa un broker privado para redes completas
El cambio de nombre no tiene efecto	Profundidad de topic superior a los 8 niveles del broker público	Acorta `base_topic` o los nombres

El servidor público también limita cada cliente a 10 mensajes por segundo, algo que una pequeña red de prueba no se acerca a superar pero que una red grande puede superar al arrancar. Es una razón más por la que el área pública es solo para pruebas; el artículo enlazado al principio sobre el servidor MQTT público gratuito enumera todos sus límites.

Paso a un broker privado

Zigbee2MQTT controla cerraduras, luces y alarmas, así que la producción necesita credenciales y TLS. Con un broker MQTT gestionado como ConnectMQ, creas un broker en el portal, copias el usuario, la contraseña y el client ID generados y cambias solo el bloque mqtt:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: YOUR_USERNAME
  password: YOUR_PASSWORD
  client_id: YOUR_CLIENT_ID
  version: 5

El certificado de Let's Encrypt se valida con el paquete de CA del sistema en el contenedor, así que no hacen falta archivos de certificado adicionales. El plan gratuito Serverless permite mensajes de hasta 256 KB, suficiente para los payloads típicos del puente, y los planes de pago lo elevan a 1 MB. La guía de Zigbee2MQTT con un broker en la nube profundiza en el acceso remoto y las instalaciones con varias sedes, y la guía de automatización IoT muestra dónde encaja Zigbee en un sistema doméstico o de edificio más amplio.

Ejecuta Zigbee2MQTT en ConnectMQ

ConnectMQ ofrece a tu puente Zigbee2MQTT un broker MQTT privado con TLS, Secure WebSocket para paneles en el navegador y un portal para ver en directo cada topic de dispositivo. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y apunta a él tu mqtt.server.

Preguntas frecuentes

¿Qué coordinador es mejor para una nueva instalación de Zigbee2MQTT?

Un stick basado en el Texas Instruments CC2652P con el adaptador zstack o un stick Silicon Labs EFR32MG21 con el adaptador ember son las opciones más habituales y mejor soportadas. Los adaptadores conectados a la red son útiles cuando el servidor está lejos de los dispositivos.

¿Puedo cambiar el canal Zigbee más adelante?

Técnicamente sí, pero entonces hay que volver a emparejar la mayoría de los dispositivos. Elige el canal con cuidado antes de emparejar nada.

¿Zigbee2MQTT necesita Home Assistant?

No. Zigbee2MQTT solo necesita un broker MQTT. Home Assistant es un consumidor opcional entre muchos, junto a Node-RED, scripts y paneles.

¿Es seguro ejecutar Zigbee2MQTT en un broker público?

Solo para pruebas. Cualquiera puede leer y publicar en los topics públicos, incluidos tus topics set, así que usa un broker privado con credenciales y TLS para los dispositivos reales.

Guía para configurar Zigbee2MQTT: del coordinador al panel