Zigbee2MQTT in Docker: meine Konfiguration und warum Sensoren offline gehen

Mein Zigbee-Netz ist auf rund 80 Geräte angewachsen: Heizkörperthermostate, Temperatur- und Bewegungssensoren, Türkontakte, Steckdosen und jede Menge smarte Lampen. Zigbee2MQTT verbindet sie alle über MQTT mit Home Assistant. Hier ist mein Setup, und das eine Problem, das mich lange beschäftigt hat.

1. Docker Compose

Zigbee2MQTT läuft als einzelner Container. Der USB-Stick wird über seinen by-id-Pfad durchgereicht. So funktioniert er auch dann noch, wenn die USB-Geräte nach einem Neustart in anderer Reihenfolge erkannt werden.

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    environment:
      TZ: Europe/Berlin
      ZIGBEE2MQTT_CONFIG_FRONTEND_ENABLED: "true"
      ZIGBEE2MQTT_CONFIG_FRONTEND_PORT: "8080"
      # das Frontend-Passwort steht in .env, nicht in dieser Datei
      ZIGBEE2MQTT_CONFIG_FRONTEND_AUTH_TOKEN: ${Z2M_AUTH_TOKEN:?set Z2M_AUTH_TOKEN in .env}
    volumes:
      - ./:/app/data
      - /run/udev:/run/udev:ro
    devices:
      # deinen Pfad findest du mit: ls -l /dev/serial/by-id/
      - /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0:/dev/ttyUSB0
    ports:
      # Frontend nur auf dem Host selbst
      - "127.0.0.1:8080:8080"

2. configuration.yaml

Das ist meine Konfiguration ohne Geheimnisse. Bei einer neuen Installation lässt GENERATE Zigbee2MQTT beim ersten Start einen zufälligen Netzwerkschlüssel und zufällige PAN-IDs erzeugen. Übernimm diese Werte nie aus fremden Beispielen.

version: 5
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mqtt-broker:1883
  user: zigbee2mqtt
  password: '!secret mqtt_password'
serial:
  port: /dev/ttyUSB0
  adapter: zstack
  baudrate: 115200
  rtscts: false
advanced:
  channel: 15
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE
  transmit_power: 20
  adapter_delay: 100
  last_seen: ISO_8601
  log_level: error
availability:
  enabled: true
homeassistant:
  enabled: true
frontend:
  enabled: true
  port: 8080

Ein paar Anmerkungen zu den Einstellungen:

• channel: einmal wählen und danach nicht mehr ändern. Ein Kanalwechsel bedeutet, viele Geräte neu anzulernen. Die Zigbee-Kanäle 15, 20 und 25 überschneiden sich am wenigsten mit den üblichen WLAN-Kanälen 1, 6 und 11.
• last_seen: ISO_8601: speichert für jedes Gerät einen Zeitstempel. Den brauchst du, um das Offline-Problem unten zu verstehen.
• availability: zeigt Geräte in Home Assistant als online oder offline an. Nützlich, aber genau das sorgt für die meiste Verwirrung, wie du gleich siehst.
• password: '!secret mqtt_password' liest den Wert aus einer separaten secret.yaml. So kannst du die Konfiguration teilen oder sichern, ohne das Passwort preiszugeben.

3. Sensoren, die immer wieder das Netz verlassen

Das ist der Teil, der mich lange beschäftigt hat. Alle paar Tage werden einige Batteriesensoren, meistens Tür- und Fensterkontakte, in Zigbee2MQTT und Home Assistant als offline angezeigt. Bisher hat immer dasselbe geholfen: die Tür einmal öffnen und schließen, und der Sensor ist sofort wieder online. Kein Neu-Anlernen, kein Batteriewechsel.

Dass einmal Öffnen und Schließen reicht, ist eigentlich ein guter Hinweis. Es gibt zwei wahrscheinliche Erklärungen, und beide können im selben Netz vorkommen.

Grund 1: Der Sensor war nie weg, nur still

Batteriegeräte schlafen fast die ganze Zeit und senden nur etwas, wenn sich ihr Zustand ändert, oder in großen Abständen ein Lebenszeichen. Zigbee2MQTT kann sie nicht fragen: „Bist du noch da?“ Bei eingeschalteter Availability wartet es einfach: Hat ein Batteriegerät 25 Stunden lang (Standardwert) nichts gesendet, wird es als offline markiert. Eine Tür, die einen Tag lang niemand geöffnet hat, sieht genauso aus wie ein toter Sensor. Beim Öffnen sendet er eine Nachricht, und der Sensor ist „wieder da“.

Diesen Fall erkennst du am Zeitpunkt last seen: Ist der Sensor fast genau 25 Stunden nach seiner letzten Meldung offline gegangen, ist es das Zeitlimit und kein echtes Problem. Die Lösung ist ein längeres Zeitlimit für diese Geräte:

availability:
  enabled: true
  active:
    timeout: 10       # Minuten, Geräte mit Netzteil (können angepingt werden)
  passive:
    timeout: 1500     # Minuten, Batteriegeräte (Standard = 25 Stunden)

# oder nur für einzelne Geräte, im Abschnitt devices:
devices:
  '0x00158d0001234567':
    friendly_name: Haustür
    availability:
      timeout: 4320   # 3 Tage

Grund 2: Der Sensor hat seinen Router verloren

Batteriegeräte sprechen nicht direkt mit dem Koordinator. Sie hängen an einem Router in der Nähe, also an einem Gerät mit Netzstrom wie einer Steckdose oder einer smarten Lampe. Verschwindet dieser Router, ist der Sensor verwaist. Das merkt er erst, wenn er etwas senden will, und sucht sich dann einen neuen Router. Deshalb „repariert“ das Öffnen der Tür ihn: Das Öffnen zwingt den Sensor, sich neu zu verbinden.

Typische Gründe, warum ein Router verschwindet oder seine Geräte verliert:

• Smarte Lampen, die am Wandschalter ausgeschaltet werden. Jede Lampe ist ein Router. Schaltest du sie aus, ist jeder Sensor verwaist, der daran hing. Das ist die häufigste Ursache.
• Schwache Router. Viele günstige Lampen und Steckdosen können nur wenige Geräte halten oder verlieren sie nach einem Firmware-Aussetzer.
• Aqara-/Xiaomi-Sensoren. Sie halten sich nicht vollständig an den Zigbee-Standard und bleiben oft nur an bestimmten Routern stabil verbunden. Mit Routern anderer Hersteller fallen sie regelmäßig heraus.

Was ich dagegen tue

1. Bei jedem Sensor, der offline geht, den Zeitpunkt last seen prüfen, um das Zeitlimit von echten Ausfällen zu unterscheiden.
2. Das Availability-Zeitlimit für Tür- und Fensterkontakte erhöhen. Sie müssen sich nicht jeden Tag melden.
3. Lampen, die als Router dienen, dauerhaft mit Strom versorgen und über Zigbee schalten statt über den Wandschalter.
4. Einen eigenen, immer eingeschalteten Router (einen USB-Router-Stick oder eine gute smarte Steckdose) in die Nähe der Sensoren setzen, die am häufigsten ausfallen.
5. In der Netzwerkkarte des Zigbee2MQTT-Frontends nachsehen, an welchem Router jeder Problemsensor hängt.

Was ich gelernt habe

• „Offline“ heißt in Zigbee2MQTT oft nur „hat seit 25 Stunden nichts gesagt“.
• Wie stabil das Netz ist, entscheiden die Router, nicht der Koordinator. Lampen am Wandschalter sind schlechte Router.
• Sichere Netzwerkschlüssel und Koordinator-Backup. Sie machen den Unterschied zwischen einem Stick-Tausch in Minuten und 80 Geräten neu anlernen.

Ich aktualisiere diesen Artikel, sobald ich weiß, welcher der beiden Gründe bei meinen Sensoren zutrifft.