Saltar a contenido

Failure mode: Z2M coordinator perdido / muerto

Tercera entrada del catálogo. El stick coordinator falla (USB desconectado, hardware muerto, firmware corrupto). Toda la red Zigbee se cae instantáneamente — devices no son alcanzables hasta restore. Recovery requiere coordinator backup off-site (coordinator_backup.json + database.db) y hardware compatible disponible.

Cómo se manifiesta

  • HA UI muestra Z2M integration en estado "unavailable" o todos los devices Zigbee en "unknown".
  • Z2M logs: Error: failed to open serial port o Coordinator failed to start.
  • lsusb (en HA Container) o el log del Yellow no muestra el USB device del stick.
  • A nivel UX: luces Zigbee dejan de responder, sensores Zigbee no actualizan, automations basadas en Zigbee no disparan.

Cómo se detecta proactivamente

  • Gatus check: HTTP GET al Z2M API health endpoint (/bridge/state). Si devuelve != "online", alertar.
  • Prometheus metric: zigbee2mqtt_bridge_online (si Z2M exporta) o derivar de número de devices _available.
  • LogQL alert: pattern matching en Loki por coordinator failed o serial port.

Cómo se recupera

Caso A — Stick desconectado (más común)

  1. Verificar conexión USB física.
  2. Reconectar.
  3. ha addon restart core_zigbee2mqtt (HAOS) o docker compose restart zigbee2mqtt (Container).
  4. Verificar logs vuelven a Coordinator started successfully.
  5. Confirmar devices se re-asocian (puede tomar 5-15 min para que sleepy devices reporten).

Caso B — Stick hardware muerto

  1. Tener otro stick compatible en stock (recomendación: comprar 2 al inicio del setup).
  2. Apagar Z2M / HA.
  3. Reemplazar stick físico.
  4. Restaurar coordinator_backup.json desde el último backup off-site al directorio de Z2M.
  5. Editar configuration.yaml del Z2M con el nuevo serial path del stick.
  6. Iniciar Z2M.
  7. IMPORTANTE: el coordinator_backup preserva las network keys y los devices NO necesitan re-pair. Si no tenés el backup, sí hay re-pair masivo.

Caso C — Stick firmware corrupto

  1. Re-flashear firmware del stick vía herramientas vendor (SONOFF Tool, etc.).
  2. Restore coordinator backup post-flash.
  3. Restart Z2M.

Cómo se previene

Prevención canónica: backup off-site automatizado

Cron en mini-PC o script en Yellow que cada noche:

# en HAOS Yellow vía SSH addon:
cp /addon_configs/.../coordinator_backup.json /backup/zigbee/$(date +%Y%m%d).json
cp /addon_configs/.../database.db /backup/zigbee/$(date +%Y%m%d).db

# rsync off-site al NAS o S3
rsync -av /backup/zigbee/ nas:/backup/smart-home/zigbee/

Retention: 30 días local + 90 días NAS.

Hardware redundante

  • Tener 1 stick de repuesto en cajón (~$30 SONOFF Dongle-E). Tipo "spare tire".
  • NO hardware exotic: usar el mismo modelo del coordinator productivo para que el restore sea drop-in.

Tests periódicos

  • Mensual: verificar que el último coordinator_backup.json es restorable montándolo en un Z2M ephemeral.
  • Documentar el procedimiento de restore en docs/runbooks/zigbee-coordinator-recovery.md.

Lo que el agente AI hace (perímetro autónomo recomendado)

Acción ¿Autónomo? Razón
Restart de Z2M cuando detecta "coordinator failed" Sí (mes 2+) Caso A, low-risk
Alertar al humano si restart no resuelve en 5 min Sí Escalation
Re-flash firmware del stick No, pide approval Operación destructiva potencial
Restore desde backup No, pide approval Operación destructiva potencial
Re-pair masivo de devices Nunca Catastrófico si se hace por error

Relaciones

Abierto / gaps

  • Documentar el patrón exacto del cron de backup off-site como techniques/coordinator-backup-automated (gap).
  • ¿Cómo se hace el test mensual del backup automáticamente? Idea: ephemeral container Z2M que monta el backup, levanta, hace query, mata.
  • ¿Hay backups incrementales o cada noche es full? database.db es chiquito así que cada noche full sirve.