Zigbee2MQTT availability: timeout y payload retained explicados
Última revisión: 24/09/2026
Cuando un sensor Zigbee se cae de la red, Zigbee2MQTT no lo adivina: espera un tiempo sin recibir ningún mensaje y entonces lo marca como offline. Ese estado viaja por MQTT en un topic concreto y, si está bien montado, no tienes que esperar al siguiente ping para ver el último estado: el broker lo retiene y se lo entrega a cada suscriptor nuevo. Aquí están el topic, el payload, el timeout y el YAML.
El mensaje retained es lo que te salva los arranques
La disponibilidad se publica en este topic:
zigbee2mqtt/[FRIENDLY_NAME]/availabilityEl payload que llega es:
{"state":"online"}o bien:
{"state":"offline"}Lo importante es que este mensaje se publica con la bandera retained de MQTT activada. En la práctica eso significa que el broker guarda el último estado y se lo envía automáticamente a cualquier cliente que se suscriba después. Si Home Assistant arranca cuando un sensor lleva media hora sin dar señales, no tiene que esperar a que Zigbee2MQTT decida publicar de nuevo: recibe el estado `offline` al primer latido de la suscripción.
Por qué un sensor tarda en aparecer como offline
Zigbee2MQTT no consulta constantemente cada dispositivo. Para no castigar la batería de los sensores de pila, escucha los mensajes que el propio dispositivo emite y compara el tiempo transcurrido con el parámetro availability_timeout. Si no recibe nada en ese margen, publica offline. No es un fallo: es la forma menos agresiva de detectar dispositivos muertos.
El valor se configura en el arranque de Zigbee2MQTT:
advanced:
availability_timeout: 25En cuanto reinicies Zigbee2MQTT, los dispositivos que lleven más de ese tiempo sin hablar pasarán a offline al primer chequear. Subir el timeout solo retrasa esa marca; no arregla un dispositivo que ya no responde.
Leer la disponibilidad en Home Assistant
La integración MQTT expone el estado de availability como un sensor. Puedes usarlo en una plantilla para no encender luces cuando un sensor de presencia está caído:
condition:
- condition: state
entity_id: sensor.nombre_amigable_availability
state: "online"Si no ves la entidad, revisa que el dispositivo esté emparejado en Zigbee2MQTT y que Home Assistant reciba su discovery MQTT. La entidad de availability no se crea a mano: llega con el mensaje de configuración del dispositivo.
| Parámetro | Qué controla | Qué pasa si lo subes mucho |
|---|---|---|
| availability_timeout | Minutos sin mensaje antes de publicar offline | Detectas el fallo más tarde |
| retain (Mensaje availability) | Que el broker conserve el último estado para suscriptores nuevos | No depende del timeout; siempre conviene que esté |
| availability en Home Assistant | Sensor expuesto para usar en conditions | Puedes automatizar sobre el estado sin tocar el dispositivo |
Lo que no debes concluir de un estado offline
Un sensor a pila puede tardar una hora en volver a emitir solo porque no ha detectado cambios. `offline` significa "no he recibido nada en el margen configurado", no "el sensor está roto". Antes de reemplazar nada, da un empujón: pulsa el botón del dispositivo o cámbialo de canal para forzar un mensaje. Si con eso vuelve a `online`, el problema no era la radio, era el timeout de reporte elegido.
Cambios de esta revisión: publicado el artículo con los datos de la doc oficial de Zigbee2MQTT y el flujo retained confirmado por el repo de Zigbee2MQTT. Añadido SVG y tabla de parámetros.