Was du in diesem Video lernst

• Eine einfache Checkliste / Entscheidungsbaum, um ESPHome-Projekte systematisch zu debuggen (statt wild rumzuprobieren)

• Erster Basis-Check: Hat dein ESP überhaupt Strom? (LED, Netzteil, USB-Kabel)

• Typischer Klassiker: USB-Kabel liefert Strom, aber keine Daten → ESP wird am PC nicht erkannt

• Wi-Fi Debugging über Router/Access-Point: Gerät online? IP? überhaupt verbunden?

• Captive Portal / AP-Fallback: Wie du dich direkt mit dem ESP-Hotspot verbindest, wenn WLAN nicht klappt

• Logs als wichtigste Quelle: ESPHome Logs lesen und aus Fehlermeldungen ableiten, was wirklich kaputt ist

• Häufige WLAN-Ursachen: 2,4 GHz, getrennte SSIDs für 2,4/5 GHz, falsches Passwort, Auth-Timeout

• OTA vs. Kabel: Wann OTA-Update nicht geht und du manuell flashen musst (Factory .bin)

• Boot/Flash-Modus: Warum manchmal Reset/Boot-Tasten nötig sind (je nach Board)

• Sensor zeigt „unknown“: Übergang von Online-Status → Sensorwerte → Sensor-Kommunikation

• I²C Debugging: „No device found“ → Pins prüfen → Bus-Scan → I²C-Adresse korrekt setzen

• Warum der richtige Board-Typ in ESPHome entscheidend ist (Pin-Layout/Mapping je Board unterschiedlich)

• Häufiger Verdrahtungsfehler: SDA/SCL vertauscht (21/22)

• Sensor-spezifische Konfiguration: z. B. AHT20/21 braucht „variant“

• Konzept Pull-Up / Pull-Down und wie du (erstmal) den internen Pull-Up aktivierst (SDA/SCL pullup)

Debugging Schritt für Schritt

Schritt 1 – Stromversorgung prüfen (immer zuerst)

1. Schau: Leuchtet eine Status-LED am Board?

2. Wenn nein:

   • anderes USB-Kabel testen

   • anderes Netzteil/USB-Port testen

3. Merke: Manche Kabel/Netzteile liefern „irgendwie“ Strom, aber instabil oder zu wenig.

Schritt 2 – WLAN/Erreichbarkeit prüfen

1. Öffne deinen Router (UniFi, Fritz!Box o. ä.) und suche das Gerät (Hostname wie TempSensorSHT31...).

2. Prüfe:

   • Hat das Gerät eine Wi-Fi-Verbindung?

   • Hat es eine IP?

3. Wenn keine Verbindung:

   • Nutze AP-Fallback / Captive Portal (wenn aktiviert)

   • Verbinde dich mit dem vom ESP erstellten Hotspot (SSID z. B. TempSensorSHT31)

   • Öffne die Captive-Portal-Seite → dort siehst du „keine Netzwerkverbindung“ und kannst handeln

WLAN-Grundregeln aus dem Video:

• ESPs brauchen praktisch immer 2,4 GHz

• kann helfen: 2,4 GHz und 5 GHz getrennte Namen geben (nicht gleiche SSID)

Schritt 3 – Entscheiden: OTA oder Kabel?

Wenn WLAN kaputt ist, geht OTA oft nicht zuverlässig. Dann:

1. ESP physisch an den PC holen

2. Über web.esphome.io (oder deine ESPHome-Umgebung) eine Verbindung per USB herstellen

3. Wenn ESP am PC nicht erkannt wird:

   • anderen USB-Port testen

   • anderes USB-Kabel testen
     Merke: Es gibt Kabel, die laden nur (Strom), aber können keine Daten.

Schritt 4 – Logs lesen (dein wichtigstes Diagnose-Tool)

1. In ESPHome: Logs öffnen

2. Wenn keine Logs kommen:

   • „Reset device“ in ESPHome / oder Board kurz resetten

   • Achte auf die Boot-Tabelle (Start-Ausgaben). Wenn die nicht kommt, stimmt etwas Grundsätzliches nicht.

Schritt 5 – WLAN-Fehler aus Logs ableiten (Beispiel im Video)

Du siehst Meldungen wie:

• Authentifizierung abgelaufen / failed to connect / retry loop

• Gerät findet Netzwerk mit gutem Empfang, verbindet aber nicht

falsches Wi-Fi-Passwort gesetzt → ESP fällt in AP-Fallback.

Fix:

1. In ESPHome-Konfig das korrekte Wi-Fi-Passwort setzen (idealerweise aus secrets.yaml)

2. Installieren:

   • „Wirelessly“ probieren (wenn Gerät erreichbar)

   • wenn nicht erreichbar: Manual download → Factory .bin → per web.esphome.io flashen

Schritt 6 – Flashen/Installieren, wenn’s hakt

1. Wenn „fail to analyze“ o. ä. kommt:

   • bei vielen Boards reicht kurz Reset/Boot drücken

   • bei manchen: Boot gedrückt halten + Reset kurz drücken, Boot noch halten (abhängig vom Board)

Schritt 7 – Gerät ist online, aber Sensorwerte fehlen (nächste Debug-Stufe)

Wenn Home Assistant zeigt:

• Gerät online (nicht ausgegraut), aber Entitäten unknown oder ohne Werte

Dann gehst du wieder in die Logs und suchst den nächsten Fehler.

Schritt 8 – I²C „No device found“ → Verkabelung & Pins prüfen

• I²C auf bestimmten Pins gestartet, dann: „no device found“

Vorgehen:

1. Verkabelung checken (SDA/SCL/Power/GND)

2. Pins im Code prüfen: Stimmen SDA/SCL im YAML mit deiner Verdrahtung überein?

3. Wenn du unterschiedliche Boards nutzt: Board-Typ in ESPHome korrekt setzen, weil Pin-Layouts variieren.

Video-Fehler: Code war auf GPIO18/19, Verdrahtung aber 21/22 (oder umgekehrt).
→ Fix: im YAML SDA/SCL passend setzen (empfohlen: beim ESP32 oft 21/22).

Schritt 9 – SDA/SCL vertauscht erkennen und korrigieren

Nach dem ersten Fix kommt:

• Bus scan findet Gerät-Adresse, aber Kommunikation schlägt trotzdem fehl

Im Video wird entdeckt:

• SDA und SCL sind vertauscht (Kabelfarben / Reihenfolge am Sensor)

Fix:

• SDA ↔ SCL tauschen 

• Logs erneut öffnen → du solltest sehen:

  • „Bus recovery successful“

  • „Found device at address 0x44“ (Beispiel SHT31)

Schritt 10 – I²C-Adresse korrekt setzen (SHT31 Beispiel)

Wenn der Bus-Scan z. B. 0x44 findet, aber dein YAML nutzt 0x34, kommt:

• „Communication … failed“

Fix:

1. In der ESPHome Doku der Komponente prüfen, welche Adressen möglich sind

2. Im YAML address: 0x44 setzen (oder passende Adresse)

3. OTA installieren → danach erscheinen Sensorwerte

Schritt 11 – Sensor-spezifische Pflicht-Parameter (AHT20/21 Hinweis)

Manche Sensoren funktionieren nur, wenn du eine Variante angibst (z. B. AHT20 vs. AHT21).
Wenn Werte fehlen trotz korrekter Verdrahtung:

• Doku checken, ob zusätzliche config keys nötig sind (z. B. variant:).

Schritt 12 – Wenn’s immer noch spinnt: Pull-Up / Pull-Down (I²C)

Manchmal braucht die Datenleitung einen definierten Pegel:

• Pull-Up: Leitung wird im Leerlauf auf „High“ (3,3 V) gezogen

• Pull-Down: Leitung wird im Leerlauf auf „Low“ (GND) gezogen

Ein einfacher Start : internen Pull-Up aktivieren:

• sda_pullup: true

• scl_pullup: true

Praxis-Tipps

• Immer nur 1 ESP am PC gleichzeitig – sonst wird’s beim Port/Device-Auswählen schnell chaotisch.

• Markiere dir an jedem Sensor SDA/SCL (z. B. Schrumpfschlauch/Farbcode), damit du nicht jedes Mal rätselst.

• Wenn OTA nicht geht: Nicht stundenlang kämpfen – Kabel dran, Factory-Bin flashen, weiter.

• Router-Check ist Gold wert: Wenn der ESP keine IP hat, ist Home Assistant nicht das Problem.

• Wenn „No device found“: 80% der Fälle sind Pins falsch / SDA-SCL vertauscht / GND fehlt.

• Nimm die offizielle ESPHome-Doku als „Single Source of Truth“ für Adressen, Varianten, Pflichtfelder.

• Board-Typ korrekt setzen (esp32dev vs. C3/C6 etc.). Gleiche Optik ≠ gleiche Pins.

Fazit

Du debugst ESPHome-Projekte am schnellsten, wenn du nicht „irgendwas“ probierst, sondern strikt nach Reihenfolge vorgehst: Strom → WLAN → Logs → Verkabelung/Pins → Sensor-Doku (Adresse/Variante) → Pull-Ups. Genau diese Routine macht deine Builds robust – und du findest Fehler reproduzierbar, statt zufällig.