Zigbee2MQTT Update-Guide: Was ist neu (Frontend/Features) + Upgrade-Best-Practices

Zigbee2MQTT ist bei vielen Setups der “Zigbee-Motor” im Hintergrund – und genau deswegen tun Updates manchmal weh: neue Defaults, geänderte Entities, andere Frontend-URLs… und plötzlich ist irgendwas “weg”. In diesem Artikel zeige ich dir die wichtigsten Neuerungen (Stand: Zigbee2MQTT 2.7.1) und eine Upgrade-Routine, die sich in der Praxis bewährt hat. GitHub

Was ist neu?

1) Windfront-Frontend: jetzt Standard (und Legacy wird nicht mehr wachsen)

Die größte sichtbare Änderung: Windfront ist inzwischen das Default-Frontend. Wenn du nichts Spezielles konfiguriert hast, landest du automatisch dort. Das alte Frontend bleibt nutzbar, bekommt aber keine neuen Features mehr. GitHub+1

Du kannst das Frontend-Paket explizit setzen:

frontend:
  enabled: true
  package: zigbee2mqtt-windfront   # oder: zigbee2mqtt-frontend (legacy)

Außerdem praktisch: Du kannst das UI-Serving abschalten (nur WebSocket), wenn du ein eigenes/standalone UI hostest:

frontend:
  enabled: true
  disable_ui_serving: true

Alle Optionen (inkl. Auth-Token, base_url, notification_filter) stehen in der Frontend-Doku. Zigbee2MQTT+1

Wichtig beim Umstieg: In den Release Notes wird explizit erwähnt, dass sich einige URLs in Windfront geänderthaben → Bookmarks ggf. anpassen. GitHub

2) “Health”: Netzwerkzustand & Diagnosen werden besser

Seit 2.5.0 gab’s einen großen Sprung bei “Health”: neue Health-Extension + zusätzliche Infos in bridge/info – und Windfront hat dafür passende UI-Unterstützung bekommen. GitHub
Wenn du ein größeres Mesh hast, ist das Gold wert, um Router-Kandidaten, schwache Links und “zickige” Endgeräte schneller zu finden.

3) Neue Features in 2.7.0: Actions-Bridge + bessere Bind/Reporting/Map-Tools

Mit 2.7.0 kamen u.a.:

action bridge/request API (z.B. Hue-Geräte anhand der Seriennummer resetten) GitHub
Neue Bind-/Reporting-/Map-Features (sprich: mehr Komfort und Möglichkeiten rund um Bindings/Reporting/Netzwerkansichten) GitHub

4) 2.7.1 Hotfix: Crash durch exzessive Disk Writes

2.7.1 ist ein Hotfix, der einen Crash-Fall behebt, der durch zu viele Schreibzugriffe auf die Disk getriggert wurde. Wenn du gerade updatest: das ist ein ziemlich gutes Argument, direkt auf 2.7.1 zu gehen. GitHub

Upgrade-Best-Practices: so update ich Zigbee2MQTT ohne Drama

Schritt 1: Vor dem Update kurz “Hygiene” checken (besonders bei Sprung 1.x → 2.x)

Zigbee2MQTT 2.0 hat alte Legacy-Features konsequent abgeräumt. Empfehlung vom Maintainer: Legacy-Optionen explizit deaktivieren, um beim Upgrade weniger Überraschungen zu erleben: GitHub

advanced:
  homeassistant_legacy_entity_attributes: false
  homeassistant_legacy_triggers: false
  legacy_api: false
  legacy_availability_payload: false
device_options:
  legacy: false

Und: serial.adapter explizit setzen wird empfohlen (Adapter-Discovery hat sich geändert). GitHub

Schritt 2: Backup – aber richtig

Ja, Zigbee2MQTT hat seit 2.0 ein automatisches Migrationssystem, das sogar ein Backup deiner data/configuration.yaml anlegt (z.B. data/configuration_backup_v1.yaml) und Migrations-Logs schreibt. Zigbee2MQTT
Trotzdem mein Standard:

Home Assistant Add-on: Vollbackup/Snapshot vor dem Update
Zusätzlich (egal welche Installation): kompletten data/-Ordner sichern (nicht nur configuration.yaml)

Wichtig: Werte aus der HA-Add-on-Konfigseite oder per Environment Variables landen nicht zwingend in configuration.yaml und werden daher nicht automatisch “mitmigriert”. Zigbee2MQTT

Schritt 3: Changelog/Breaking Changes scannen (5 Minuten, spart 2 Stunden)

Bei 2.0 gab’s u.a. Änderungen bei:

Adapter-Erkennung / Default-Adapter (zstack nicht mehr Default) GitHub
Home Assistant Entities (z.B. entfernte/ersetzte Update-Entities, Trigger-/Click-Sensor-Themen) GitHub
Status Topic: standardmäßig homeassistant/status statt hass/status (falls nicht gesetzt) GitHub

Wenn du Automationen hast, die noch auf alten “Click-/Action-Sensoren” basieren, ist genau hier der Klassiker, warum “nach dem Update nichts mehr passiert”.

Schritt 4: Update durchführen (je nach Installationsart)

A) Home Assistant Add-on (typischer Weg)

Snapshot / Backup
Add-on stoppen
Update installieren
Add-on starten → Logs prüfen
Frontend öffnen → Geräte/Groups/OTA/Map einmal querchecken

B) Docker

Container stoppen
Image pullen
Container mit gleichem Volume (/app/data) starten
Logs prüfen + UI-Check

C) Bare Metal / Git
Bei 2.0 gab’s u.a. Änderungen rund ums Update-Verhalten und pnpm statt npm in Git-Installationen. Wenn du so unterwegs bist, lies die 2.0 Hinweise wirklich einmal durch. GitHub

Schritt 5: Nach dem Update – kurze Checkliste

Log auf WARN/ERROR scannen
Pairing aus (Permit join), wenn du’s nicht brauchst
HA Entities/Automationen spot-checken (besonders Trigger, die früher auf legacy click/action liefen) GitHub
Windfront: Bookmarks/Ingress-Links prüfen (URLs können anders sein) GitHub
Wenn’s “komisch” wird: Migration-Log lesen (data/migration-*-to-*.log) Zigbee2MQTT

Mini-Tipp: Windfront bewusst aktiv setzen (damit Updates dich nicht “überholen”)

Auch wenn Windfront mittlerweile Default ist: ich setze es trotzdem explizit in die Config. Dann weißt du später beim Debuggen immer genau, was du erwartest:

frontend:
  enabled: true
  package: zigbee2mqtt-windfront

Zigbee2MQTT