Zigbee2MQTT con broker en la nube: controla dispositivos Zigbee desde cualquier lugar con TLS

Usar Zigbee2MQTT con un broker en la nube te permite leer sensores y conmutar dispositivos Zigbee desde cualquier lugar, sin redirección de puertos ni VPN en la red de casa. En esta guía apuntarás una instalación existente de Zigbee2MQTT a un broker protegido con TLS en el puerto 8883, la probarás primero en el servidor MQTT público gratuito y después pasarás a credenciales privadas para el uso diario.

¿Por qué usar Zigbee2MQTT con un broker en la nube?

La mayoría de las instalaciones de Zigbee2MQTT hablan con un contenedor Mosquitto en la misma Raspberry Pi. Eso funciona bien hasta que quieres que algo fuera de casa vea los datos: una app móvil con datos móviles, un panel en la oficina, una segunda sede como una casa de vacaciones o un servicio backend que registre el consumo de energía. Exponer un broker local a internet implica redirección de puertos, DNS dinámico y certificados, y cada uno de ellos es una nueva forma de equivocarse.

Un broker en la nube invierte el sentido de la conexión. Zigbee2MQTT abre una conexión TLS saliente hacia el broker, igual que un navegador que abre un sitio web, así que no hay que cambiar nada en el router. Cualquier cliente autorizado, esté donde esté, puede suscribirse entonces a los mismos topics. Si el papel del broker en este esquema es nuevo para ti, la breve explicación de qué hace un broker MQTT es una buena introducción.

El inconveniente, dicho con honestidad: los estados de tus dispositivos pasan ahora por un servicio en internet, así que el cifrado y las credenciales privadas no son opcionales. El resto de esta guía los trata como lo predeterminado.

Qué necesitas

• Una instalación de Zigbee2MQTT funcional (1.x o 2.x) con un coordinador emparejado. Si empiezas desde cero, sigue primero la guía para configurar Zigbee2MQTT y vuelve aquí.
• Acceso al configuration.yaml de Zigbee2MQTT (en la carpeta data, o en la página de configuración del complemento en Home Assistant).
• Para las pruebas: nada más, porque el servidor público acepta conexiones anónimas.
• Para producción: un broker con su propio usuario, contraseña y client ID, por ejemplo un broker MQTT gestionado de ConnectMQ creado desde el portal.

Paso 1: probar en el servidor MQTT público gratuito

Antes de tocar credenciales, comprueba que Zigbee2MQTT puede llegar a internet y publicar con TLS. El servidor MQTT público gratuito en broker.connectmq.com acepta clientes anónimos con cualquier client ID no vacío y único. Todo lo que se publica allí puede leerlo cualquiera, así que usa un prefijo de topic aleatorio y solo dispositivos de prueba inofensivos.

Edita la sección mqtt de configuration.yaml:

mqtt:
  base_topic: connectmq/demo/z2m-7f3k9q/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  client_id: z2m-7f3k9q
  version: 5
  keepalive: 60
  reject_unauthorized: true

Algunas notas sobre estos valores:

• mqtts:// y el puerto 8883 activan TLS. El broker usa un certificado de Let's Encrypt, en el que Node.js ya confía, así que no necesitas una entrada ca.
• base_topic con tu ID aleatorio mantiene tus mensajes separados de los de los demás. Zigbee2MQTT añade el nombre descriptivo del dispositivo y sufijos como /set, así que aquí el topic completo tiene seis niveles, dentro del límite de ocho del servidor público.
• version: 5 selecciona MQTT 5. La versión 4 (MQTT 3.1.1) también funciona.
• reject_unauthorized: true es el valor por defecto; déjalo activado. Desactivarlo acepta cualquier certificado y anula el sentido de TLS.

Reinicia Zigbee2MQTT y busca en el log una línea similar a Connected to MQTT server. Después suscríbete desde cualquier equipo:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i watcher-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/#' -v

Deberías ver bridge/state, bridge/info, bridge/devices y un topic por dispositivo. Conmuta una lámpara desde el otro lado:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i sender-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/living_lamp/set' \
  -m '{"state":"TOGGLE"}'

En Windows o macOS, sustituye --capath /etc/ssl/certs por --cafile apuntando a un paquete de CA que contenga ISRG Root X1.

Límites del servidor público que debes tener en cuenta

El área pública admite 64 KB por mensaje y 10 mensajes por segundo por cliente. Una red Zigbee grande puede alcanzar ambos: bridge/devices enumera cada dispositivo con su definición completa y puede superar los 64 KB en una malla grande, y una ráfaga de informes de sensores puede superar el límite de frecuencia. Para una prueba con unos pocos dispositivos no es un problema, pero es otra razón para pasar a un broker privado en la instalación real.

Paso 2: pasar a un broker privado en la nube para Zigbee2MQTT

Cuando la prueba funcione, crea un broker privado. En ConnectMQ eliges un plan, creas un broker y recibes un usuario, una contraseña y un client ID generados. Los client ID están vinculados a las credenciales emitidas, así que usa exactamente el client ID del portal.

Mantén los secretos fuera del archivo principal con la sintaxis !secret de Zigbee2MQTT. Crea secret.yaml junto a configuration.yaml:

mqtt_user: YOUR_USERNAME
mqtt_password: YOUR_PASSWORD
mqtt_client_id: YOUR_CLIENT_ID

Después haz referencia a él:

mqtt:
  base_topic: home/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: '!secret mqtt_user'
  password: '!secret mqtt_password'
  client_id: '!secret mqtt_client_id'
  version: 5
  keepalive: 60
  reject_unauthorized: true
  include_device_information: false

frontend:
  enabled: true
  port: 8080

advanced:
  last_seen: ISO_8601

Sustituye el host por el que aparece para tu broker en el portal si es distinto. Reinicia y confirma la conexión en el log y en el explorador de topics en directo del portal, donde home/zigbee2mqtt/bridge/state debería aparecer en cuanto arranque Zigbee2MQTT.

last_seen añade una marca de tiempo a cada mensaje de dispositivo, lo que facilita mucho detectar un sensor que ha dejado de informar cuando miras los datos en remoto. Deja include_device_information desactivado salvo que algún consumidor lo necesite, porque añade un bloque de metadatos a cada payload.

Paso 3: controlar dispositivos Zigbee en remoto

Con Zigbee2MQTT en un broker en la nube, cualquier cliente MQTT con credenciales puede actuar sobre tus dispositivos. El contrato de topics es el mismo que en un broker local:

El topic bridge/state se retiene y está configurado como Last Will, de modo que un panel remoto puede distinguir entre "la lámpara está apagada" y "todo el gateway Zigbee está fuera de línea". Usa eso en tu interfaz en lugar de confiar indefinidamente en el último estado del dispositivo.

Un controlador remoto mínimo en Python, con paho-mqtt 2.x, tiene este aspecto:

import json
import paho.mqtt.client as mqtt

BASE = "home/zigbee2mqtt"

def on_connect(client, userdata, flags, reason_code, properties):
    print("connected:", reason_code)
    client.subscribe(f"{BASE}/bridge/state")
    client.subscribe(f"{BASE}/living_lamp")
    client.publish(f"{BASE}/living_lamp/set", json.dumps({"state": "ON", "brightness": 120}))

def on_message(client, userdata, msg):
    print(msg.topic, msg.payload.decode())

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 8883, keepalive=60)
client.loop_forever()

Ten en cuenta que este script necesita su propio client ID. Ejecutarlo con el mismo ID que Zigbee2MQTT desconectaría el gateway cada vez que el script se conecte, porque un broker solo permite una sesión por client ID. Da a cada aplicación sus propias credenciales.

Home Assistant y otros consumidores

Si Home Assistant debe descubrir los dispositivos Zigbee, activa homeassistant: enabled: true en Zigbee2MQTT y apunta la integración MQTT de Home Assistant al mismo broker con las mismas credenciales. La versión paso a paso, incluidos los ajustes TLS en la interfaz de Home Assistant, está en la guía para usar Home Assistant con un broker MQTT externo. Los mensajes de descubrimiento se retienen, así que llegan aunque Home Assistant arranque después de Zigbee2MQTT.

Otros sistemas se integran del mismo modo: Node-RED, Telegraf o un pequeño script se conecta como cliente MQTT, se suscribe a home/zigbee2mqtt/# y escribe en el almacenamiento que uses. El broker solo enruta mensajes, lo que mantiene la arquitectura sencilla y sustituible.

Lista de comprobación para la resolución de problemas

1. Connection refused: Not authorized - comprueba el usuario y la contraseña, y que client_id coincida exactamente con el emitido para esas credenciales.
2. El gateway se reconecta cada pocos segundos - otro cliente está usando el mismo client ID. Revisa tus scripts, flujos de Node-RED y contenedores antiguos.
3. self signed certificate o unable to verify - estás detrás de un proxy que intercepta TLS o el reloj del sistema es incorrecto. Corrige el reloj (algo habitual en una Pi sin hora de red) antes que cualquier otra cosa.
4. No llega nada al suscriptor - confirma que base_topic está escrito exactamente igual en ambos lados; los topics MQTT distinguen entre mayúsculas y minúsculas.
5. Falta bridge/devices en el servidor público - probablemente el mensaje supera el límite público de 64 KB. Prueba con menos dispositivos o pasa a un broker privado, donde el plan Free admite 256 KB.
6. Se ha alcanzado el límite de conexiones - cada instancia de Zigbee2MQTT, panel y script cuenta como una conexión. El plan Free admite hasta 25.

Para una revisión más amplia de TLS, credenciales y diseño de topics, consulta la guía de buenas prácticas de seguridad MQTT.

Cómo elegir un broker alojado para Zigbee2MQTT

Zigbee2MQTT no exige mucho a un broker: MQTT 3.1.1 o 5, TLS, mensajes retenidos y un Last Will. Lo que más importa en una instalación remota es que el broker sea accesible, esté cifrado y aislado de otros clientes. Un broker MQTT gestionado como ConnectMQ se ocupa de los certificados, la disponibilidad y las actualizaciones para que tu Raspberry Pi solo tenga que ejecutar Zigbee2MQTT. Los brokers Serverless gratuitos admiten QoS 0 y 1, lo que cubre sin cambios la publicación con QoS 0 que Zigbee2MQTT usa por defecto. Para una visión más amplia de las opciones de alojamiento, lee la guía del broker MQTT en la nube, y para más proyectos de automatización sobre el mismo broker, explora la guía de automatización IoT.

Lleva tu red Zigbee a ConnectMQ

Crea un broker Serverless gratuito en app.connectmq.com (sin tarjeta de crédito), pega las credenciales generadas en secret.yaml y observa cómo aparecen tus dispositivos Zigbee en el explorador de topics en directo en menos de un minuto tras reiniciar Zigbee2MQTT.

Preguntas frecuentes

¿Puede Zigbee2MQTT conectarse a un broker en la nube con TLS?

Sí. Establece server en mqtts://host:8883 en la sección mqtt de configuration.yaml. Con brokers que usan certificados de confianza pública, como los de Let's Encrypt, no hace falta ningún archivo de CA adicional.

¿Es seguro usar un broker público para Zigbee2MQTT?

Solo para pruebas breves con dispositivos inofensivos. Cualquiera puede leer y publicar en los topics de un broker público, así que nunca debe conectarse de esa forma una cerradura o una alarma; usa credenciales privadas para cualquier cosa real.

¿Sigo necesitando un broker Mosquitto local?

No. Zigbee2MQTT puede publicar directamente en el broker en la nube. Algunas personas mantienen un broker local para automatizaciones exclusivamente locales que deben funcionar durante un corte de internet, lo cual es una decisión de diseño válida.

¿Por qué se desconecta mi gateway Zigbee2MQTT cuando abro otra aplicación?

Es casi seguro que la otra aplicación usa el mismo client ID. Un broker mantiene una sesión por client ID y descarta la conexión más antigua, así que da a cada cliente su propio ID y sus propias credenciales.