ESPHome-Logs lesen: Fehler über Netzwerk und USB eingrenzen

Dein ESP32 taucht nach dem Start nicht in Home Assistant auf? Öffne zuerst das Log des Geräts. Ist es im Netzwerk erreichbar, versuch es über seine IP-Adresse. Scheitert es schon beim Start oder beim Verbindungsaufbau, lies die Meldungen über den seriellen Anschluss.

1. Den passenden Log-Zugang wählen

Über das Netzwerk: Wenn das Gerät erreichbar und Netzwerk-Logging eingerichtet ist, gib die Geräte-IP mit --device an.

esphome logs geraet.yaml --device 192.168.1.100

Ersetze den Dateinamen und die Beispiel-IP durch deine Werte. ESPHome prüft die YAML-Konfiguration, bevor es die Logs anzeigt. Meldet die CLI schon bei der Konfiguration einen Fehler, behebe zuerst diesen Fehler.

Über USB oder UART: Wenn das Gerät beim Start hängen bleibt oder nie ins Netz kommt, wähle den seriellen Anschluss. Das Board muss dafür eine nutzbare serielle Schnittstelle bereitstellen.

esphome logs geraet.yaml --device COM3

Ersetze COM3 durch den tatsächlichen Port. Unter Linux kann er zum Beispiel /dev/ttyACM1 heißen. Wenn du den Start untersuchst, öffne den seriellen Logstream vor dem Neustart. So kannst du auch frühe Meldungen erfassen.

2. Die erste relevante Meldung suchen

1. Fehler gezielt auslösen. Wiederhole den Schritt, bei dem das Problem auftritt. Achte darauf, wann das erwartete Verhalten zum ersten Mal ausbleibt.
2. Ein paar Zeilen zurückgehen. Lies die Meldungen vor dem Abbruch mit. WARN und ERROR helfen beim Filtern. Welche Meldung zur Ursache gehört, entscheidet der Zusammenhang.
3. Nur eine Änderung testen. Wiederhole danach denselben Schritt. Notiere, ob die erste auffällige Meldung verschwindet oder nur der Folgefehler anders aussieht.

Beispielsituation: Die Netzwerklogs brechen beim Neustart ab und kommen danach nicht zurück. Wechsle auf die serielle Ausgabe und wiederhole den Neustart. Prüfe dort, ob das Gerät weiter startet, in einer Neustartschleife steckt oder erst beim Netzwerkaufbau hängen bleibt.

3. Einen brauchbaren Ausschnitt festhalten

Notiere Board, Firmware-Version, den Auslöser des Fehlers und die erste auffällige Meldung mit einigen Zeilen davor und danach. Entferne WLAN-Zugangsdaten, Schlüssel und andere private Angaben, bevor du den Ausschnitt teilst.

Wenn du den Messwert in Home Assistant siehst, aber die Aktion ausbleibt, geht es mit dem Leitfaden zur Fehlersuche weiter.

Quellen

• ESPHome CLI: logs und –device
• ESPHome-Entwicklerdokumentation: Netzwerk- und serielle Logs
• ESPHome Logger: Logstufen

Zum Weiterlesen: ESPHome startet nicht: Boot-Logs über USB mitschneiden.