Moin zusammen.
Da hier in letzter Zeit immer wieder Beiträge auftauchen bei denen User Schwierigkeiten bei der Ersteinrichtung von Z2M mit dem Z2M Onboarding-Prozess haben und dann z.T. auch “komische” Ratschläge von anderen Usern kommen, wie z.B. das man bei einem Sonoff Dongle-P doch mal ember als adapter: probieren sollte, 
oder auch das man die Z2M configuration.yaml manuell erstellen müsste/sollte, 
habe ich den Z2M Installationsprozess per Z2M Onboarding eben mal durchgespielt. Dafür hier jetzt mal eine (Kurz)Anleitung. 
Vorab: Ich habe das bei mir mit einem Proxmox Host gemacht, unter dem dann eine Test HA VM läuft. Aber das funktioniert in der Form natürlich auch bei einer HA bare metal Installation.
Zum Einsatz kamen:
Proxmox + HA VM
Sonoff Dongle-P
HA Core 2025.10
Mosquitto broker 6.5.0
Z2M 2.6.3-1
Vorausgesetzt wird das das Mosquitto broker Addon gem. Doku unter HA bereits installiert und gestartet wurde und das das Z2M Addon Repo bei den HA Addons bereits vorhanden ist. Auch sollte man für die weiter unten erwähnten “Nacharbeiten” das File Editor Addon bereits unter HA installiert haben.
Ebenfalls vorausgesetzt ist das ZHA nicht auch noch installiert und aktiviert und für den gleichen Coordinator eingerichtet ist. Das funktioniert nicht. Ein Zigbee Coordinator kann bekanntlich immer nur von Z2M oder ZHA benutzt werden. Bevor man Z2M installiert muss also ZHA deinstalliert werden und wenn ZHA sich nach einem Reboot von HA dann ggf. wieder “meldet” und den Coordinator wieder für ZHA einrichten will, muss man ZHA ignorieren und darf es nicht wieder einrichten.
Los geht’s.
Falls man wie ich den USB-Dongle (hier ein Sonoff Dongle-P) an einem Proxmox Host angeschlossen hat hier noch die Schritte die man dort machen kann bzw. muss.
- USB-Dongle per USB-Kabel (Länge sollte mind. 0,5 Meter sein) an den Proxmox Host anschließen.
- Per
lsusbnachschauen ob der Dongle von dem Proxmox Host auch erkannt wird.
- Den USB-Dongle bei der HA VM über Hardware —> Add —> USB-Device hinzufügen.
Anm.: Ich habe dafür schon immer Use USB Port genutzt, aber eine Einbindung perUse USB Vendor/Device IDfunktioniert ebenfalls und was dann von beiden der ggf. bessere oder sinnvollere Weg ist soll hier nicht Thema sein. - Damit ist das Thema anschließen des USB-Dongle an den Proxmox Host und durchreichen an die HA VM erledigt.
Kommen wir nun zu HA und der Einrichtung von Z2M.
- Bei HA über Einstellungen —> System —> Hardware —> Gesamte Hardware nachschauen ob dort der USB-Dongle auftaucht. Das sollte dann z.B. so aussehen:
- Den dort vorhandenen Eintrag hinter ID kopieren. Dieser wird später noch einmal gebraucht.
- Bei den HA Addons das Z2M Addon aufrufen und es per Installieren-Button installieren.
- Nachdem es installiert wurde sieht die Oberfläche dann so aus und man aktiviert dort die drei Optionen.
Anschließend klickt man auf den Starten-Button und es erscheint diese Oberfläche.
auf der man dann auf den Benutzerfläche öffnen Button klickt. - Jetzt öffnet sich die Onboarding-Seite von Z2M die dann so aussieht.
Dort muss man per Select a device den USB-Dongle auswählen. Hier in dem Beispiel also den Sonoff Dongle-P, der unter /dev/ttyUSB0 vorhanden ist. Wenn der Dongle von Z2M richtig erkannt wurde wird auch gleich automatisch der passende Driver für ihn ausgewählt und eingetragen. Hier bei einem Sonoff Dongle-P alsozstack. Anm.: Bei einem Sonoff Dongle-E sollte dortemberstehen. Außer dann bei dem Wifi-Kanal noch zu schauen ob man den dort vorausgewählten übernehmen oder ggf. ändern will, brauchen bei der Z2M Onboarding-Seite keine weiteren Einstellungen gemacht werden und man kann unten auf der Seite auf den Submit-Button klicken. - Wenn man auf den Submit-Button geklickt hat und man ggf. auch keinen Fehler gemacht hat, sollte als nächstes automatisch folgende Seite erscheinen
und die Z2M Einrichtung per Z2M Onboarding-Seite wurde erfolgreich abgeschlossen. Dann kommt der Punkt an dem hier wohl schon der ein oder andere User gescheitet ist,
nämlich: Was genau heißt “You can close this page”. Lösung: Einfach oben auf den Pfeil klicken und man bekommt direkt die Z2M Oberfläche zu Gesicht. Sollte man zumindest wenn man nichts falsch gemacht hat.
- Die grundsätzlich Z2M Einrichtung per Z2M Onboarding-Seite ist abgeschlossen und Z2M sollte ab dem Zeitpunkt laufen und funktionieren.
Kommen wir noch zu ein paar “Nacharbeiten”, die zwar nicht unbedingt notwendig sind, aber die man durchaus machen könnte/sollte.
Per HA File Editor Addon öffnet man die Z2M configuration.yaml unter dem Pfad: /homeassistant/zigbee2mqtt/configuration.yaml Die sieht dann z.B. so aus.
Wie man sehen kann steht in der aktuell unter serial: als port: noch port: /dev/ttyUSB0, was so zwar grundsätzlich auch funktioniert, aber besser ist es dort die ID des USB Dongle einzutragen. Jetzt kommt der Eintrag zum tragen den man sich vorher über Einstellungen —> System —> Hardware —> Gesamte Hardware kopiert hatte. In dem Beispiel hier lautet der ID-Pfad bei mir:
/dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge_Controller_ceb3673b3793eb118f9b194f3d98b6d1-if00-port0
Diesen Pfad trägt man jetzt bei serial: ein und ersetzt dort alten …/ttyUSB0 Pfad. Das sieht dann so aus.
Anschließend die Änderung per Icon oben rechts speichern.
Zum Schluss sollte man HA einmal kompl. neu booten.
Nach dem Reboot von HA sollte Z2M laufen und funktionieren und man kann mal einen Blick in das HA Z2M Protokoll werfen, was dann so in der Art aussehen sollte.
[08:40:00] INFO: Socat not enabled
[08:40:01] INFO: Starting Zigbee2MQTT...
Starting Zigbee2MQTT without watchdog.
[2025-11-03 08:40:02] info: z2m: Logging to console, file (filename: log.log)
[2025-11-03 08:40:02] info: z2m: Starting Zigbee2MQTT version 2.6.3 (commit #unknown)
[2025-11-03 08:40:02] info: z2m: Starting zigbee-herdsman (6.3.2)
[2025-11-03 08:40:02] info: zh:zstack:znp: Opening SerialPort with {"path":"/dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge_Controller_ceb3673b3793eb118f9b194f3d98b6d1-if00-port0","baudRate":115200,"rtscts":false,"autoOpen":false}
[2025-11-03 08:40:02] info: zh:zstack:znp: Serialport opened
[2025-11-03 08:40:02] info: z2m: zigbee-herdsman started (resumed)
[2025-11-03 08:40:02] info: z2m: Coordinator firmware version: '{"meta":{"maintrel":1,"majorrel":2,"minorrel":7,"product":1,"revision":20230507,"transportrev":2},"type":"ZStack3x0"}'
[2025-11-03 08:40:02] info: z2m: Currently 0 devices are joined.
[2025-11-03 08:40:02] info: z2m: Connecting to MQTT server at mqtt://core-mosquitto:1883
[2025-11-03 08:40:03] info: z2m: Connected to MQTT server
[2025-11-03 08:40:03] info: z2m:mqtt: MQTT publish: topic 'zigbee2mqtt/bridge/state', payload '{"state":"online"}'
[2025-11-03 08:40:03] info: z2m: Started frontend on port 8099
[2025-11-03 08:40:03] info: z2m: Zigbee2MQTT started!
Anm.: Sollte es ggf. doch ein Problem bei der Z2M Installation gegeben haben und man möchte noch einmal kompl. bei Null anfangen, reicht es nicht aus das Z2M Addon einfach nur zu deinstallieren. Dadurch verbleiben nämlich noch “Reste” in dem Z2M Ordner unter HA. Stattdessen muss man aus dem Z2M Ordner unter /homeassistant/zigbee2mqtt die darin noch vorhandenen Dateien per File Editor Addon löschen. D.h. die Datein die man hier sieht.
Anm.: Den log-Ordner muss man nicht unbedingt löschen.
Nach dem löschen der Dateien sollte man HA sicherheitshalber noch einmal kompl. booten.
So das soll es dann auch gewesen sein. Ich hoffe das User mit dieser Anleitung etwas anfangen können und das das Thema Z2M Onboarding-Prozess und der Ablauf dabei, dadurch auch geklärt, bzw. klarer wurde.
Anm.: Ja es gibt auch noch ein paar Feinheiten die man ggf. anders machen könnte, aber mir ging es hier in erster Linie darum den Z2M Onboarding-Prozess zu zeigen und nicht darum was man ggf. alles noch irgendwie anders machen könnte.
VG Jim
