Saltar a contenido

Zigbee2MQTT (Z2M)

Implementation FOSS standalone para correr una red Zigbee y exponerla vía MQTT. Soporta 3,400+ devices en 2026, el ecosistema más amplio del mercado. Más maintenance que ZHA pero más flexible y con mejor diagnostics. Probable opción actual del usuario.

Contexto

Para la pregunta de cómo sostener Zigbee en el setup del usuario, Z2M es la elección dominante hoy si tiene >20 devices o ecosistema mixto. La razón pragmática de no migrar a ZHA: re-pair cuesta horas y el upside (un componente menos) no compensa con la meta "no tinkering".

Contenido

Stack

  • Daemon standalone (Node.js) que corre fuera o dentro de HA.
  • Habla MQTT con HA (vía Mosquitto u otro broker).
  • En HA OS: instalable como add-on oficial (one-click).
  • En HA Container: corre como container separado + Mosquitto container.

Características relevantes

  • 3,400+ devices soportados (2026).
  • OTA firmware updates de Aqara, IKEA, Tuya, Sonoff, etc.
  • Network diagnostics: map detallado, LQI por device, packet logs.
  • Converters system: extensible para devices no soportados (más accesible que el "quirks" system de ZHA).

Failure modes específicos

  • Mosquitto broker down: toda la red Z2M deja de actualizar HA.
  • Z2M process crash: misma cosa.
  • Updates de Z2M ocasionalmente breaking: requiere release notes check + manual testing post-upgrade.
  • Coordinator perdido / cambiado: requiere backup procedure (database.db + coordinator_backup.json).

Recovery procedures (a documentar como gaps)

  1. Mosquitto broker down: container restart o ha addon restart core_mosquitto.
  2. Z2M crash post-upgrade: rollback a versión anterior; reportar issue al repo si reproducible.
  3. Coordinator died: restore con coordinator_backup.json + database.db en hardware nuevo.

Por qué la default en este wiki

  • El HA Yellow probablemente lo trae preconfigurado vía add-on.
  • Ecosistema mixto (Aqara + Sonoff + IKEA + cualquier otro brand mencionado por el usuario) lo justifica.
  • Diagnostics permiten al agente AI (Q10) entender la red mejor.

Relaciones

Citas / evidencia

Abierto / gaps

  • Documentar el procedimiento canónico de coordinator backup off-site automatizado (script que copia database.db a NAS cada noche).
  • Cuándo se promueve un fix de Z2M al perímetro autónomo del agente (Q10) — ¿restart automático? ¿solo notificar?
  • Cross-check del dato "3,400+ devices" contra https://www.zigbee2mqtt.io/supported-devices/.