Wenn sich eine ESPHome-Konfiguration anders verhält als erwartet, ist der Issue-Tracker meist schnell gefunden. Schwieriger ist es, das Problem so klar zu beschreiben, dass du weißt, wohin damit. Funktioniert etwas nicht so wie dokumentiert? Fehlt eine Funktion, oder ist noch unklar, was genau gebraucht wird? Könnte ein Detail der Konfiguration, der Hardware oder des Netzwerks das Ergebnis erklären?
Diese Unterscheidung ist wichtig. Ein Issue lässt sich leichter untersuchen, wenn es einen Fehler beschreibt, den andere nachstellen können. Ein Feature-Wunsch braucht einen klaren Anwendungsfall und einen realistischen Umfang. Die Hinweise zur Mitarbeit bei ESPHome verweisen auf GitHub Issues und für Feature-Wünsche auf die Discussions der Organisation. Die aktuelle Einstiegsanleitung beschreibt die üblichen Schritte zur Installation und Konfiguration, die du vor einer Problemmeldung durchgehen solltest. ESPHome: Hinweise zur Mitarbeit ESPHome: Erste Schritte
Dieser Leitfaden hilft dir mit wenigen Schritten bei der Entscheidung, wenn du eine eigene Installation betreibst oder verwaltest. Jedes Projekt entscheidet selbst, wie es Meldungen einordnet. Die Maintainer können deine Meldung anders kategorisieren, schließen oder an eine andere Stelle verweisen. Ziel ist, ihnen konkrete Angaben zu liefern, die diese Entscheidung erleichtern.
Ein beobachtbares Ergebnis
Beschreibe zuerst, was passiert ist, und wähle dann eine Kategorie. Halte in einem Satz fest, was du erwartet und was du tatsächlich beobachtet hast:
Mit dieser Konfiguration und diesem Gerät habe ich X erwartet. Stattdessen habe ich nach Y Folgendes beobachtet: Z.
Zum Beispiel: „Die dokumentierte Einstellung mac_address wird akzeptiert, aber nach einem Neustart meldet die Ethernet-Schnittstelle eine andere Adresse.“ Das lässt sich überprüfen. „MAC-Adressen sind verwirrend“ ist eine wichtige Rückmeldung, beschreibt aber noch keinen Fehler und keine Änderung, die ein Maintainer nachstellen kann.
Notiere die genaue Komponente, Plattform, ESPHome-Version und Hardware beziehungsweise das Board. Falls relevant, gehört auch die Home-Assistant-Version dazu. Bei Netzwerkproblemen können außerdem Router, Switch, Access Point, DHCP-Server oder die ab Werk einprogrammierte Adresse des Geräts das Ergebnis beeinflussen. Was auf einem Board passiert, muss nicht für alle Boards derselben Familie gelten.
Wenn deine Erwartung auf der Dokumentation beruht, verlinke die genaue Seite und beschreibe das Verhalten mit eigenen Worten. Falls eine ältere Konfiguration funktioniert hat, notiere die letzte bekanntermaßen funktionierende Version und die erste Version, in der sich das Verhalten geändert hat. Eine Meldung zu einer Regression ist etwas anderes als der Wunsch nach einem neuen Verhalten.
Die Prüfung auf einen Fehler
Ein Bug-Report ist meist der richtige Einstieg, wenn alle folgenden Punkte zutreffen:
- Das Projekt dokumentiert das benötigte Verhalten oder hat es bereits implementiert.
- Mit einer unterstützten Konfiguration lässt sich zeigen, dass das tatsächliche Ergebnis davon abweicht.
- Andere könnten den Test mit denselben wesentlichen Voraussetzungen wiederholen.
Du musst die eigentliche Ursache nicht nachweisen. Behaupte nur nicht ohne Belege, sie zu kennen. Eine Konfiguration, die bei der Validierung scheitert, kann auf einen Fehler hindeuten. Dasselbe gilt für erzeugte Firmware, die dokumentierte Einstellungen nicht beachtet, oder für eine kürzlich eingeführte Änderung, durch die eine bisher funktionierende, unterstützte Konfiguration nicht mehr läuft.
Reduziere die Konfiguration, bevor du die Meldung abschickst. Kopiere die Datei und entferne Sensoren und Automationen, die nichts mit dem Problem zu tun haben. Übrig bleiben nur die Plattform, die Netzwerkkomponente und die Einstellung, die du zum Vorführen des Problems brauchst. Veröffentliche niemals WLAN-Passwörter, API-Schlüssel, Zugangsdaten für den Broker, öffentliche IP-Adressen oder eine vollständige Übersicht deines Heimnetzes. Ersetze diese Werte durch eindeutige Platzhalter und gib an, welche Angaben du entfernt hast.
ESPHome bietet Befehle und Aktionen im Device Builder, mit denen du Konfigurationen validieren und Logs ansehen kannst. Laut Dokumentation kannst du Build-Dateien gefahrlos bereinigen; das kann Kompilierungsfehler beheben. Notiere, ob du das ausprobiert hast, bevor du ein Build-Ergebnis als Fehler meldest. ESPHome: Erste Schritte
Feature-Wünsche
Ein Feature-Wunsch passt besser, wenn das aktuelle Verhalten der Dokumentation entspricht, es aber keinen unterstützten Weg gibt, deine berechtigte Anforderung umzusetzen. Er kann auch sinnvoll sein, wenn eine Einstellung wie vorgesehen funktioniert, aber einen neuen Modus, eine zusätzliche Eingabe oder eine weitere Anbindung braucht.
Beschreibe zuerst das Problem aus Anwendersicht, bevor du eine Lösung vorschlägst. „Bei der Inbetriebnahme mehrerer ähnlicher Geräte braucht jedes Gerät eine eigene Netzwerkidentität“ beschreibt ein Problem. „Fügt diesem YAML-Schlüssel eine Lambda-Funktion hinzu“ ist eine mögliche Lösung. Wenn du beides getrennt hältst, können Maintainer auf einen bestehenden Ansatz hinweisen oder eine Einschränkung erklären. Außerdem können sie eine Umsetzung wählen, die keinen Sonderfall für ein einzelnes Board schafft.
Erkläre den Umfang und die nötigen Abwägungen. Geht es um ein einzelnes Testgerät, einen wiederholbaren Aufbau für einen Workshop oder eine ganze Geräteflotte? Muss die Funktion schon vor der ersten Netzwerkverbindung greifen? Hängt sie mit lokal administrierten MAC-Adressen, DHCP-Reservierungen, mDNS-Namen, OTA-Updates oder in der Hardware einprogrammierten Adressen zusammen? Ein kurzes, konkretes Szenario sagt Maintainern mehr als der allgemeine Hinweis, dass die Funktion praktisch wäre.
Die aktuelle Datei mit den Hinweisen zur Mitarbeit bei ESPHome unterscheidet ausdrücklich zwischen Issues und Feature-Wünschen und verweist für Feature-Wünsche auf den GitHub-Discussions-Bereich des Projekts. GitHub beschreibt Discussions als Ort für Fragen, Informationsaustausch und Gespräche. Dort lässt sich also eine noch unklare Anforderung gemeinsam klären. Für einen konkreten, reproduzierbaren Fehler ist eine Fehlermeldung passend. ESPHome: Hinweise zur Mitarbeit GitHub: Informationen zu Discussions
Fragen zu unklarem Verhalten
Manchmal passt noch keine der beiden Kategorien. Ein Begriff kann mehrere Bedeutungen haben, zwei Seiten können sich scheinbar widersprechen oder eine gültige Konfiguration lässt offen, in welcher Reihenfolge die Abläufe stattfinden. Stelle zunächst eine konkrete Frage im Community-Kanal oder Diskussionsbereich, den das Projekt dafür nennt. Füge eine minimale Konfiguration und den tatsächlichen Log-Auszug bei und frage, welches Verhalten unterstützt wird.
Wenn deine Erwartung nicht dokumentiert ist, nutze einen Bug-Report nicht als Support-Ticket. Die Frage ist trotzdem relevant. Der sinnvolle erste Schritt kann aber sein, das Verhalten zu klären, die Dokumentation zu verbessern oder eine Einschränkung zu bestätigen. Sobald du weißt, dass dokumentiertes Verhalten nicht funktioniert oder eine Funktion fehlt, kannst du leichter entscheiden, wohin die Meldung gehört.
Suche zuerst nach einem bestehenden Issue oder einer Diskussion. Verwende dafür den Komponentennamen, das Board oder die Chipfamilie, die Fehlermeldung und die entscheidende Konfigurationsoption. Ergänze einen bestehenden Bericht nur dann um Details, wenn sie dasselbe Verhalten nachvollziehbar machen. Ähnliche Symptome können unterschiedliche Ursachen haben, besonders bei WLAN, Ethernet, DHCP und dem zeitlichen Ablauf beim Start.
Kompakte Belege ohne sensible Daten
Bereite für ein Issue oder einen Feature-Wunsch dieselben kompakten Angaben vor:
- ESPHome-Version und Installationsmethode.
- Board- oder Hardwarebezeichnung und die relevante Netzwerkschnittstelle.
- Eine minimale YAML-Konfiguration, aus der sensible Angaben entfernt wurden.
- Das genaue Ergebnis der Validierung oder den Log-Auszug, einschließlich Zeitstempeln, wenn die Reihenfolge wichtig ist.
- Die Schritte vom Neustart oder einem sauberen Build bis zum beobachteten Ergebnis.
- Erwartetes Ergebnis, tatsächliches Ergebnis und bisherige Lösungsversuche.
Gib bei Fragen zur Netzwerkidentität genau an, welche Adresse du meinst: eine ab Werk vergebene Adresse, eine von der Firmware konfigurierte, eine lokal administrierte oder eine, die ein Router nach DHCP anzeigt. Diese Angaben sind nicht automatisch austauschbar. Die Client-Bezeichnung im Router oder ein mDNS-Hostname beweist nicht, welche Adresse die Firmware beim Start verwendet hat.
Teste so, dass du alle Änderungen rückgängig machen kannst. Wenn du die Netzwerkidentität änderst, nutze ein Ersatzgerät oder teste in einem Wartungsfenster. Ein Adresskonflikt kann auch die Verbindung anderer Geräte stören. Wenn du für einen Test DHCP-Reservierungen oder Zugriffsregeln änderst, erwähne das in der Meldung. So können andere die Umgebung nachvollziehen, ohne dass du dein ganzes Netzwerk offenlegst.
Ein klarer nächster Schritt
Prüfe vor dem Absenden, welche Beschreibung passt:
- Dokumentiertes oder zuvor funktionierendes Verhalten schlägt auch mit einem minimalen Beispiel fehl: Erstelle einen Bug-Report im Issue-Tracker des Projekts.
- Für einen klar beschriebenen Bedarf gibt es keinen dokumentierten, unterstützten Weg: Reiche einen Feature-Wunsch über den aktuell vom Projekt genannten Weg ein.
- Du kannst das erwartete Verhalten noch nicht benennen oder deine Beobachtung nicht reproduzieren: Stelle zuerst eine gezielte Frage und sammle weitere Belege.
Erstelle für jedes zugrunde liegende Problem eine eigene Meldung. Verlinke zugehörige Belege, statt parallel an mehreren Stellen Meldungen zu eröffnen. Sei bereit, eine von den Maintainern vorgeschlagene Änderung zu testen. Versprich aber keinen Hardwarezugang und keine Reaktionszeiten, die du nicht einhalten kannst.
Eine klar eingegrenzte Meldung garantiert weder eine Fehlerbehebung noch eine neue Funktion. Sie gibt dem Projekt einen Ausgangspunkt, um einen Fehler nachzustellen, einen Wunsch zu bewerten oder eine Einschränkung zu dokumentieren. Das hilft mehr als ein langer Thread, in dem sich deine Wünsche, deine Beobachtungen und deine Vorstellungen zur Umsetzung vermischen.