Wie können wir dir helfen?

Dies ist das häufigste Einstiegsproblem und liegt fast immer an einer von zwei Ursachen:

1. Fehlender Treiber: ESP32-Boards nutzen serielle USB-Chips zur Kommunikation. Die zwei gängigsten Chips sind der CH340/CH341 oder der CP2102 (Silicon Labs). Windows 10/11 und macOS benötigen oft eine manuelle Installation des Treibers. Die passenden offiziellen Treiber-Downloads findest du direkt rechts in unserem Download-Bereich.

2. Reines Ladekabel: Viele USB-Kabel (insbesondere solche von Powerbanks oder Ladegeräten) besitzen keine internen Datenleitungen, sondern übertragen nur Strom. Verwende zwingend ein hochwertiges USB-Datenkabel! Teste im Zweifel mehrere Kabel.

3. Port-Kontrolle: Öffne unter Windows den Geräte-Manager. Sobald das Board eingesteckt wird, muss unter „Anschlüsse (COM & LPT)“ ein Eintrag wie „Silicon Labs CP210x...“ oder „USB-SERIAL CH340 (COMx)“ erscheinen. Erscheint dort ein gelbes Warnsymbol, installiere den Treiber neu.

Wenn der Flashvorgang mittendrin abbricht oder gar nicht erst startet, versuche folgende Best Practices:

- Boot-Modus manuell erzwingen: Viele ESP32-Boards benötigen ein manuelles Signal, um in den Flash-Modus zu wechseln. Halte die BOOT-Taste (auf manchen Boards beschriftet mit BOOT oder IO0) auf dem ESP32 gedrückt, während du im Web Flasher auf „Verbinden“ klickst. Sobald im Browser die Verbindung hergestellt wird (Fortschrittsbalken startet), kannst du die Taste loslassen.

- Direkten USB-Port nutzen: Schließe das Board nicht an einen passiven USB-Hub, eine Tastatur oder einen Monitor an. Schließe es direkt an einen USB-Port deines Mainboards (Rückseite des PCs) oder direkt an den Laptop an, um Stromschwankungen auszuschließen.

- Andere serielle Verbindungen trennen: Stelle sicher, dass keine Software im Hintergrund (z. B. Cura, Arduino IDE, Simulatorsoftware) versucht, auf denselben COM-Port zuzugreifen.

Da es verschiedene ESP32-Entwicklerboards gibt, verbauen die Hersteller unterschiedliche serielle USB-Brücken-Chips. Um den richtigen Treiber zu installieren, kannst du deinen Chip ganz einfach identifizieren:

- **1. Optische Prüfung des Boards:**
Schaue dir den kleinen, schwarzen Chip direkt hinter dem USB-Anschluss deines ESP32-Boards an:
- **CP2102 / CP2104 (Silicon Labs):** Dieser Chip ist quadratisch, sehr klein (ca. 5x5 mm) und flach. Meist steht im Laser-Aufdruck sehr klein "SILABS" oder "CP2102" geschrieben.
- **CH340C / CH340G (WCH):** Dieser Chip ist länglich, rechteckig (ca. 10x5 mm) und hat deutlich sichtbare Lötfüßchen an den Längsseiten. Aufgedruckt ist meist "CH340" oder "CH341".

- **2. Manuelle Installation unter macOS (Wichtiger Sicherheitshinweis):**
Seit macOS High Sierra blockiert das System Treiberinstallationen von Drittanbietern standardmäßig.
- **So gibst du ihn frei:** Gehe nach der Treiberinstallation in die **Systemeinstellungen** -> **Sicherheit & Datenschutz** -> **Allgemein**. Klicke ganz unten neben der Meldung *"Die Systemsoftware des Entwicklers [...] wurde blockiert"* auf **„Erlauben“**. Erst danach funktioniert der COM-Port im Browser.

- **3. COM-Port Kontrolle im Windows-Geräte-Manager:**
Schließe das Board an. Wenn ein gelbes Ausrufezeichen unter *"Andere Geräte -> CP2102 USB to UART Bridge Controller"* steht, fehlt der Treiber. Mache einen Rechtsklick auf den Eintrag, wähle *Treiber aktualisieren* -> *Automatisch nach Treibern suchen* oder lade den offiziellen Treiber über unsere Sidebar (rechts) herunter.

ESP32-Mikrocontroller haben ein hochfunktionales, aber empfindliches WLAN-Modul. Achte auf folgende Stolperfallen:

- Nur 2.4 GHz Band unterstützt: Der ESP32 kann physikalisch **kein 5 GHz WLAN** empfangen. Dein Heim-WLAN muss zwingend auf dem 2,4 GHz Frequenzband senden. Falls dein Router beide Frequenzen unter demselben Namen (SSID) ausstrahlt (Band Steering), kann es helfen, dem 2,4 GHz Netz temporär einen eigenen Namen zu geben oder das 5 GHz Netz kurzzeitig zu deaktivieren.

- Keine Sonderzeichen: Manche Firmware-Versionen haben Probleme mit komplexen Sonderzeichen (z. B. &, %, $, !, ?) oder Leerzeichen im WLAN-Namen (SSID) oder im Passwort. Verwende für maximale Kompatibilität nur Buchstaben und Zahlen.

- Keine Client-Isolation im Gastnetz: Wenn du die OpenDTU in einem WLAN-Gastzugang betreibst, muss die option „WLAN-Geräte dürfen untereinander kommunizieren“ im Router aktiv sein, andernfalls blockiert der Router den Zugriff auf das Webinterface.

Wenn du dich mit dem temporären WLAN OpenDTU-OnBattery (Passwort: openDTU42) verbindest und die Einrichtungsseite unter http://192.168.4.1 nicht lädt, liegt das meistens am Smartphone:

- Mobile Daten ausschalten: Da das DTU-WLAN keine Internetverbindung hat, erkennen moderne Smartphones (iOS & Android) dies als „offline“ und leiten alle Anfragen heimlich über dein mobiles Datennetz (LTE/5G) weiter. Schalte während der Einrichtung die **Mobilen Daten deines Smartphones komplett aus**.

- Meldung „Kein Internet“ bestätigen: Dein Smartphone wird dich fragen, ob du mit dem Netzwerk verbunden bleiben willst, obwohl kein Internet verfügbar ist. Bestätige dies unbedingt mit **„Ja“** oder **„Trotzdem verbinden“**.

- Echten Browser nutzen: Vermeide integrierte In-App-Browser (z. B. aus QR-Code-Scannern). Öffne manuell Google Chrome, Microsoft Edge oder Safari und tippe die IP exakt ein.

Da ESP32-Boards standardmäßig nur über eine winzige, auf die Platine gedruckte Keramik- oder Leiterplatten-Antenne verfügen, reagieren sie sehr empfindlich auf Dämpfungen im Heimnetzwerk. So machst du deine Verbindung felsenfest:

- **1. Vorsicht vor Metallgehäusen (Faradayscher Käfig):**
Bringe das ESP32-Board niemals in einem Metallgehäuse oder in der Nähe von großen Metallflächen (z. B. direkt hinter der Aluminium-Unterkonstruktion deiner Solarmodule) unter. Metall schirmt Funkwellen fast zu 100% ab. Nutze zwingend ein **3D-gedrucktes Kunststoff- oder Acrylgehäuse**.

- **2. Statische IP-Adresse vergeben:**
Oft sind Verbindungsabbrüche keine echten Funkabbrüche, sondern Timeouts beim automatischen Beziehen der IP-Adresse (DHCP-Lease) im Router.
- **Lösung:** Vergib in deinem Router (z. B. FritzBox) eine feste IP für das Board oder konfiguriere eine statische IP direkt in den WLAN-Einstellungen des OpenDTU-Webinterfaces. Das beschleunigt auch die Ladezeit des Dashboards drastisch.

- **3. Upgrade auf ESP32 mit externer Antennenbuchse:**
Wenn der Aufstellort (z. B. im Keller oder in der Garage) weit vom Router entfernt ist, greife zu einem **ESP32-WROOM-32U** (oder einem baugleichen Board mit **U.FL- bzw. IPEX-Antennenbuchse**). Dort kannst du eine externe 2.4 GHz Stabantenne mit einem kleinen Pigtail-Adapter anschließen, was die Reichweite und Signalqualität vervielfacht.

Wenn dein Hoymiles-Wechselrichter als offline angezeigt wird oder keine Live-Daten übermittelt, prüfe folgende Punkte:

- Es muss Tageslicht sein: Der interne Mikroprozessor des Hoymiles-Wechselrichters wird ausschließlich durch den **Solarstrom der PV-Module** betrieben. Nachts, in der Dämmerung oder bei starker Schneedecke schaltet sich der Wechselrichter komplett ab. Eine Kommunikation ist dann physikalisch unmöglich. Prüfe das System daher nur bei ausreichendem Tageslicht.

- Wechselrichter-Seriennummer prüfen: Die 12-stellige Seriennummer muss exakt ohne Leerzeichen eingetragen werden. Tippfehler (z. B. Verwechslung von 0 und O) blockieren die Autorisierung.

- Falsches Funkmodul: Hoymiles nutzt zwei Frequenzen. Die **HM-Serie** nutzt das 2,4 GHz Band (erfordert ein **NRF24L01+** Modul). Die neuere **HMS- und HMT-Serie** nutzt das Sub-1-GHz Band (868 MHz, erfordert ein **CMT2300A** Funkmodul). Stelle sicher, dass deine DTU das passende Modul für deinen Inverter-Typ besitzt.

Du kannst im Webinterface der OpenDTU direkt den Hardware-Status des Funkmoduls überprüfen:

- Navigiere im oberen Menü auf **Info** -> **System**.

- Scrolle zum Bereich **Funkmodul** (bzw. Radio Diagnostics). Dort siehst du eine detaillierte Statusanzeige.

- Steht dort ein **grüner Haken** (oder Status *Connected/OK*), kommuniziert das ESP32-Board erfolgreich über die SPI-Datenleitungen mit dem Funkmodul.

- Steht dort ein rotes Kreuz oder *Not Connected*, liegt ein Hardware-Verkabelungsfehler vor. Prüfe die Lötstellen, die Steckkontakte oder ob die Pin-Konfiguration unter **Einstellungen** -> **Pin-Zuordnung** exakt mit deiner Hardware übereinstimmt.

Da Wechselrichter meistens im Freien an der Hauswand oder direkt unter den PV-Modulen befestigt sind, müssen die DTU-Funksignale dicke Außenwände und oft dreifach verglaste Wärmeschutzfenster durchdringen. Mit diesen Hardware- und Software-Tricks maximierst du die Funkreichweite:

- **1. Kondensator-Modding (Der ultimative Bastler-Tipp für NRF24L01+):**
Die NRF24L01+ Funkmodule ziehen während der extrem kurzen Sende-Peaks (Transmit) impulsartig sehr hohe Ströme. Der Spannungsregler des ESP32-Boards ist darauf oft nicht schnell genug vorbereitet, wodurch die Versorgungsspannung kurzzeitig einbricht und das Signal abreißt.
- **Lösung:** Löte einen kleinen **Elektrolytkondensator (Elko) mit einer Kapazität von 10 µF bis 100 µF (mindestens 6.3V)** direkt an die Pins **VCC und GND** auf der Unterseite des NRF24-Funkmoduls. Das stabilisiert die Spannungsversorgung bei Sende-Peaks massiv und behebt 90% aller sporadischen Empfangsprobleme.

- **2. Sendestärke im Webinterface erhöhen:**
Gehe in der OpenDTU auf **Einstellungen** -> **Wechselrichter-Einstellungen**. Dort kannst du die Sendeleistung (TX Power) deines Funkmoduls konfigurieren. Stelle diese auf **„High“** oder **„Max“**. Achtung: Nutze die maximale Leistung nur, wenn ein Modul mit externer Antenne verbaut ist, da platinenbasierte Funkmodule ohne Antenne sonst überhitzen können.

- **3. Verwende ein Funkmodul mit Antenne (PA + LNA):**
Verwende statt des einfachen NRF24-Moduls mit Platinenantenne die Version mit zusätzlichem Leistungsverstärker (PA = Power Amplifier) und Rauschverstärker (LNA = Low Noise Amplifier), die über eine schraubbare externe Stabantenne (SMA) verfügt. Dies erhöht die nutzbare Reichweite im Freifeld auf bis zu 100 Meter.

Der **Dynamic Power Limiter (DPL)** ist das Herzstück der **OpenDTU-OnBattery** Firmware. Er regelt die Leistungsabgabe deines Hoymiles-Wechselrichters in Echtzeit:

- **Das Prinzip:** Ein Smart Meter (z. B. Shelly 3EM, IR-Schreib-Lesekopf) am Hausanschluss misst permanent, ob du Strom aus dem Netz beziehst oder einspeist.

- **Die Regelung:** Der DPL empfängt diesen Wert (z. B. via MQTT aus Home Assistant oder direkt von einem Victron GX-Gerät) und passt das Limit des Wechselrichters dynamisch an. Braucht dein Haus gerade 400W und die Solaranlage könnte 600W liefern, drosselt der DPL den Wechselrichter präzise auf 400W. So verhinderst du, dass wertvoller Solarstrom unvergütet ins öffentliche Netz verschenkt wird (sog. **Nulleinspeisung**).

Ein starkes „Aufschwingen“ oder ständiges Hin- und Herregeln des Wechselrichters zwischen 0W und dem Maximum hat meistens zwei Gründe:

1. **Zu kurze Regelintervalle:** Die Kommunikation zum Hoymiles-Wechselrichter benötigt konstruktionsbedingt ca. 3 bis 5 Sekunden, um ein neues Leistungslimit umzusetzen. Stellst du das Regelintervall im DPL zu kurz ein (z. B. unter 5 Sekunden), schickt die DTU bereits ein neues Limit ab, bevor der Wechselrichter das alte Limit überhaupt physisch umgesetzt hat. **Erhöhe das Regelintervall im DPL auf 5 bis 10 Sekunden.**

2. **Fehlende Hysterese / Dämpfung:** Smart Meter liefern extrem nervöse Echtzeitwerte. Setze im DPL eine angemessene **Hysterese** (z. B. 15W) oder nutze in Home Assistant einen **gleitenden Mittelwert** (Filter-Integration) über 15–30 Sekunden für den Stromzählersensor, bevor der Wert an die DTU übergeben wird. Dies glättet kurze Spitzen (wie z. B. das kurze Einschalten einer Kaffeemaschine) und schont die Funkverbindung.

Ein weit verbreiteter Konfigurationsfehler beim Einrichten des Dynamic Power Limiters. Wenn dein Haus mehr Strom verbraucht, regelt die DTU den Wechselrichter plötzlich ab, und wenn du einspeist, regelt sie ihn hoch. Das System arbeitet genau spiegelverkehrt.

- **Die Ursache:** Es gibt keinen einheitlichen Industriestandard für die Vorzeichen bei Stromzählern. Manche Zähler und Integrationen stellen Netzbezug als *positiven Wert* und Netzeinspeisung als *negativen Wert* dar, andere genau umgekehrt.

- **Die Lösung:** In den DPL-Einstellungen von OpenDTU-OnBattery kannst du das erwartete Vorzeichenverhalten umschalten. Falls du den Wert über Home Assistant einspeist, erstelle einen einfachen **Template-Sensor**, der das Vorzeichen invertiert (Wert multipliziert mit -1), und sende diesen invertierten Wert an das MQTT-Topic der DTU.

Wenn die gemessene Batteriespannung der OpenDTU-OnBattery um einige Zehntel Volt (oder mehr) von den exakten Werten deines Victron SmartShunts oder deines Multimeters abweicht, liegt das meistens an einer von zwei Ursachen:

- **1. Spannungsabfall unter Last (Leitungswiderstand):**
Fließt ein hoher Ladestrom (z. B. 20A bis 40A von deinen Solarmodulen) durch die Zuleitungskabel zur Batterie, fällt über dem internen Widerstand des Kabels eine messbare Spannung ab (Spannungsabfall). Die DTU misst die Spannung nah am Laderegler, während der SmartShunt die reale Spannung direkt an den Batteriepolen misst.
- **Lösung (VE.Smart Networking):** Nutze das offizielle **Victron VE.Smart Network**! Verbinde deinen SmartSolar Laderegler und deinen SmartShunt drahtlos via Bluetooth. Der Laderegler empfängt so den exakten Spannungswert direkt von den Batteriepolen (Spannungssensorik) und regelt den Strom hochpräzise ab. Die DTU liest dann die korrigierten Werte über VE.Direct aus.

- **2. Bauteiltoleranzen & ESP32-ADC-Messfehler:**
Falls du ein DIY-Spannungsteiler-Board nutzt, das die Batteriespannung direkt an einen Analog-Eingang (ADC) des ESP32 übergibt: Der interne Analog-Digital-Wandler des ESP32 ist konstruktionsbedingt relativ ungenau und nicht linear kalibriert. Widerstände auf günstigen Boards besitzen zudem Toleranzen von bis zu 5%.
- **Lösung:** In den Batterie-Einstellungen von OpenDTU-OnBattery kannst du einen **Spannungskalibrierungsfaktor** (Multiplier / Offset) eintragen. Nimm ein zuverlässiges Multimeter, misst die Spannung direkt an den Batteriepolen, und passe den Faktor in der DTU so an, dass der angezeigte Wert exakt mit dem des Multimeters übereinstimmt.

Wenn Werte in Home Assistant zunächst korrekt angezeigt werden, sich dann aber nach Stunden oder Tagen nicht mehr aktualisieren, liegt das meistens an der MQTT-Verbindung:

- **Retain-Flags prüfen:** Stelle sicher, dass in den MQTT-Einstellungen der OpenDTU die Option **Retain** (Speichern) für Statusnachrichten aktiviert ist. Dies sorgt dafür, dass der Broker immer den letzten bekannten Wert speichert und an Home Assistant ausliefert.

- **Verbindungsabbrüche & IP-Lease:** Wenn der ESP32 kurzzeitig das WLAN verliert, vergibt manche FritzBox nach dem Wiederverbinden eine neue IP-Adresse. Dies kann die MQTT-Session blockieren. **Vergebe im Router zwingend eine statische IP (Option „Diesem Gerät immer die gleiche IP-Adresse zuweisen“)** für die OpenDTU.

- **Broker-Auslastung:** Prüfe das Protokoll deines Mosquitto-Brokers in Home Assistant. Falls dort im Sekundentakt An- und Abmeldungen der DTU verzeichnet werden, reduziere das Sendeintervall in den DTU-Einstellungen.

Wenn du MQTT in der OpenDTU konfiguriert hast, aber in Home Assistant unter der MQTT-Integration keine neuen Geräte auftauchen, prüfe folgende Schritte:

1. **Auto-Discovery in OpenDTU aktivieren:** Navigiere im Webinterface der OpenDTU auf *Einstellungen* -> *MQTT* und vergewissere dich, dass das Häkchen bei **„Enable Home Assistant MQTT Auto Discovery“** gesetzt ist. Der standardmäßige Discovery-Präfix sollte auf homeassistant stehen.

2. **MQTT-Verbindung prüfen:** Steht im Webinterface der OpenDTU unter *Info* -> *System* der MQTT-Status auf *Connected*? Falls dort *Disconnected* steht, kontrolliere die IP-Adresse deines Mosquitto Brokers (meist die IP von Home Assistant), den Port (Standard: 1883) sowie Benutzername und Passwort.

3. **Datenstrom im HA-Entwicklerwerkzeug abhören:** Gehe in Home Assistant auf *Entwicklerwerkzeuge* -> *Zustände* oder direkt auf die MQTT-Integration unter *Einstellungen* -> *Geräte & Dienste* -> *MQTT* -> *Konfigurieren*. Tippe unter „Ein Thema abonnieren“ das Zeichen # ein und klicke auf „Hören starten“. Wenn dort keine Daten von der DTU ankommen, blockiert eine Firewall oder falsche Zugangsdaten die Kommunikation.

Das Home Assistant Energie-Dashboard ist sehr wählerisch. Sensoren können dort nur ausgewählt werden, wenn sie exakt definierte Attribute besitzen: device_class: energy, state_class: total_increasing und die Maßeinheit kWh oder Wh.

Manche Versionen von OpenDTU liefern diese Attribute über Auto-Discovery nicht standardmäßig mit. Der sauberste Weg dies zu lösen, ist das Erstellen eines **virtuellen Template-Sensors (Helfers)** direkt in Home Assistant:

1. Gehe in Home Assistant zu **Einstellungen** -> **Geräte & Dienste** -> **Helfer**.
2. Klicke unten rechts auf **+ Helfer erstellen** und wähle **Template** -> **Sensor** aus.
3. Trage folgende Konfiguration ein:
- **Name:** PV Produktion Summe (oder ähnlich)
- **Zustandstemplate:** {{ states('sensor.opendtu_total_yield') | float }} (Ersetze dies durch die exakte Entitäts-ID deines OpenDTU-Summenenergie-Sensors)
- **Maßeinheit:** kWh (bzw. Wh, je nachdem was dein Sensor liefert)
- **Geräteklasse:** *Energy*
- **Zustandsklasse:** *Total increasing* (Extrem wichtig!)

Nach dem Speichern kannst du diesen neu erstellten Template-Sensor sofort im Energie-Dashboard unter „Solarproduktion“ hinzufügen. Es kann bis zu zwei Stunden dauern, bis die ersten Balkendiagramme generiert werden.

Wenn dein Energie-Dashboard plötzlich gigantische Ausschläge (z. B. 12.000 kWh an einem Tag) anzeigt oder der Tagesertrag nachts auf Null fällt und Home Assistant dies als massiven negativen Verbrauch interpretiert, liegt das am Resetverhalten des ESP32:

- **Die Ursache:** Wenn die OpenDTU neu startet (oder der Wechselrichter nachts abschaltet), wird der Zählerstand manchmal kurzzeitig als 0 oder unavailable (nicht verfügbar) an Home Assistant gemeldet. Sobald sich das Gerät wieder fängt und den echten Wert (z. B. 450 kWh Gesamterzeugung) sendet, denkt Home Assistant, die Differenz von 0 auf 450 sei innerhalb einer einzigen Sekunde erzeugt worden. Das führt zu gigantischen Ausschlägen.

- **Die Lösung (Utility Meter / Verbrauchszähler):** Nutze die in Home Assistant integrierte **Verbrauchszähler (Utility Meter)** Integration als robusten Puffer. Gehe auf *Einstellungen* -> *Geräte & Dienste* -> *Helfer* -> *+ Helfer erstellen* -> **Verbrauchszähler**. Wähle deinen OpenDTU-Sensor als Eingangssensor und stelle den Rücksetzungszeitraum auf **Täglich** ein. Diese Integration filtert plötzliche Nullsprünge und Neustarts automatisch heraus und liefert perfekte, fehlerfreie Daten an das Energie-Dashboard.

Dies ist der wichtigste Sicherheitshinweis für die Automatisierung deines Wechselrichters!

Wechselrichter (und auch ESP32-Chips) besitzen Flash-Speicher (EEPROM), der bauartbedingt nur eine begrenzte Anzahl an Schreibzyklen (oft ca. 10.000 bis 100.000 Mal) überlebt. Wenn du ein Limit permanent speicherst und dies über eine Automatisierung alle 10 Sekunden tust, ist der Speicher deines Wechselrichters **nach wenigen Wochen dauerhaft zerstört (Hardware-Defekt)**.

- **Die Lösung:** Nutze für alle automatisierten Regelungen (wie z. B. Nulleinspeisung) **ausschließlich die non-persistenten (flüchtigen) MQTT-Topics**! Diese schreiben die Werte direkt in den RAM-Arbeitsspeicher, was unendlich oft und verschleißfrei möglich ist. Sie werden beim Abschalten des Wechselrichters nachts wieder vergessen.

- **Die korrekten Topics:**
- **Absolut in Watt:** [deine_dtu_topic]/[inverter_name]/cmd/limit_nonpersistent_absolute
- **Relativ in Prozent:** [deine_dtu_topic]/[inverter_name]/cmd/limit_nonpersistent_relative

- **WICHTIG:** Sende MQTT-Nachrichten an diese Topics **niemals mit gesetztem Retain-Flag** (Option „behalten“ in HA-Automatisierungen deaktivieren), da dies zu unerwarteten Regelschleifen führen kann.

Wenn du die Nulleinspeisung lieber direkt in Home Assistant statt auf der DTU regeln möchtest (z. B. weil dein Smart Meter nicht direkt mit der DTU gekoppelt werden kann), kannst du vorgefertigte Automatisierungsvorlagen (Blueprints) nutzen:

- **Der Klassiker:** Das beliebteste Community-Blueprint ist der **„OpenDTU Solar Export Limiter“**. Dieser liest deinen Stromzähler-Sensor aus und steuert das Limit des Wechselrichters per MQTT an.

- **So importierst du es:** Navigiere in Home Assistant zu *Einstellungen* -> *Automatisierungen & Szenen* -> *Blueprints*. Klicke auf **„Blueprint importieren“** und füge die URL des offiziellen GitHub-Repositories der OpenDTU-Community ein.

- **Der Vorteil:** Ein Blueprint in Home Assistant bietet dir eine grafische Oberfläche, auf der du Mindestgrenzen (z. B. Wechselrichter nie unter 50W drosseln, da sonst der Standby-Verbrauch steigt) und Sicherheitsabschaltungen bei Netzausfall extrem einfach einstellen kannst.

Wenn du versuchst, eine Entität (z. B. einen selbst erstellten MQTT- oder Template-Sensor) über die Benutzeroberfläche umzubenennen, einem Raum zuzuweisen oder das Symbol zu ändern, drosselt Home Assistant dies manchmal mit dem Hinweis, dass keine eindeutige ID (Unique ID) vorhanden ist.

- **Die Ursache:** Eine Unique ID ist ein permanenter, unveränderlicher Bezeichner (z. B. eine UUID oder eine Seriennummer), der für die interne Datenbank von HA benötigt wird. Wenn du Sensoren manuell per YAML-Code anlegst oder manche Drittanbieter-Integrationen nutzt, wird diese ID nicht automatisch generiert. Ohne Unique ID kann Home Assistant Änderungen aus der UI heraus nicht in seiner internen Registrierungsdatenbank speichern.

- **Die Lösung (YAML konfigurieren):** Du kannst für fast alle in YAML definierten Entitäten (wie z. B. template oder mqtt) manuell eine Unique ID vergeben. Füge einfach das Attribut unique_id: mit einem beliebigen, einzigartigen Textschlüssel in den Code deiner Konfiguration ein:

template:
  - sensor:
      - name: "Mein PV Tagesertrag"
        state: "{{ states('sensor.opendtu_total_yield') | float }}"
        unit_of_measurement: "kWh"
        device_class: energy
        state_class: total_increasing
        unique_id: "opendtu_tagesertrag_unique_12345" # Hier deine ID eintragen!

Nach einem Reload der Template-Entitäten kannst du den Sensor in der Home Assistant UI vollumfänglich anpassen, umbenennen und Räumen zuweisen.

Wenn nach einem Home Assistant Update, dem Installieren neuer Custom Cards über HACS oder dem Ändern von Dashboard-Styles plötzlich Buttons nicht reagieren, Elemente verschoben sind oder die Login-Seite endlos lädt, liegt das fast immer an einem veralteten Browser-Cache.

Home Assistant nutzt sehr aggressives Caching, um Ladezeiten der Benutzeroberfläche zu minimieren. Bei Änderungen am System versucht der Browser oft weiterhin, alte, nicht mehr kompatible CSS- oder JavaScript-Dateien zu laden.

- **Lösung 1 (Hard Refresh im Webbrowser):**
- **Windows / Linux:** Drücke Strg + F5 oder Strg + Shift + R.
- **macOS:** Drücke Cmd + Shift + R.

- **Lösung 2 (Cache erzwungen leeren):**
- **Chrome/Edge/Brave:** Drücke F12, um die Entwicklertools zu öffnen. Mache einen Rechtsklick auf den kreisförmigen Refresh-Button deines Browsers und wähle **„Cache leeren und schwere Aktualisierung“**.
- **Safari:** Gehe in die Safari-Einstellungen -> *Datenschutz* -> *Webseitendaten verwalten*, suche nach deiner Home Assistant IP/Domain und lösche diese gezielt.

- **Lösung 3 (Home Assistant Companion App):**
Wenn die offizielle App auf deinem Smartphone spinnt, wische von ganz oben nach unten, um einen Reload zu erzwingen. Hilft das nicht, gehe in der App auf *Einstellungen* -> *Companion App* -> *Debugging* -> **„Frontend-Cache zurücksetzen“**.

Ein häufiges Problem bei Home Assistant OS: Du klickst im Add-on (z. B. Mosquitto MQTT Broker, Zigbee2MQTT, InfluxDB) auf „Starten“, der Kreis dreht sich, blinkt kurz rot und das Add-on stoppt wieder.

- **Schritt 1: Das Protokoll (Log) lesen!**
Navigiere im betroffenen Add-on ganz oben auf den Reiter **„Protokoll“** (Log). Dort steht in den letzten 5 Zeilen die exakte Fehlermeldung, warum das Add-on abgebrochen ist. Ignoriere diese Meldungen nicht – sie enthalten die direkte Lösung.

- **Die häufigsten Ursachen & Lösungen:**

1. **Port belegt (Address already in use):** Ein anderes Add-on oder eine Integration nutzt bereits denselben Netzwerkport. Beispiel: Wenn du den Mosquitto Broker startest, darf kein anderes Tool auf Port 1883 lauschen. Kontrolliere unter *Einstellungen* -> *System* -> *Netzwerk*, ob Doppelbelegungen vorliegen.

2. **Fehlende / fehlerhafte Konfiguration (Missing options):** Viele Add-ons starten aus Sicherheitsgründen nicht mit Werkseinstellungen. Beim Mosquitto Broker muss z. B. in den Add-on-Einstellungen (Reiter *Konfiguration*) oft ein Benutzername und Passwort hinterlegt werden, falls kein integrierter Home Assistant User genutzt wird.

3. **Hardware nicht erreichbar:** Add-ons wie Zigbee2MQTT benötigen physischen Zugriff auf deinen USB-Stick. Wenn der USB-Port des Raspberry Pi oder deiner VM umgesteckt wurde, stimmt der Pfad (z. B. /dev/ttyUSB0 oder /dev/serial/by-id/...) nicht mehr und das Add-on bricht mit einem Verbindungsfehler ab. Prüfe den Pfad unter *Einstellungen* -> *System* -> *Hardware* -> *Gesamte Hardware*.

Dieser Fehler tritt auf, wenn du manuelle Konfigurationen in deiner configuration.yaml oder anderen YAML-Dateien vornimmst und Home Assistant die Datei nicht mehr einlesen kann. Das System verweigert dann oft den Neustart.

- **Die Ursache:** Das YAML-Dateiformat besitzt eine extrem strikte Syntax für Strukturierungen und Einrückungen. Es erlaubt **kategorisch keine Tabulator-Zeichen (Tabulator-Taste / `\t`)**! Jede Einrückungsebene darf ausschließlich aus regulären Leerzeichen (Spaces) bestehen (üblicherweise 2 oder 4 Leerzeichen pro Ebene). Befindet sich auch nur ein einziger Tabulator im Code, bricht der Parser mit dieser Fehlermeldung ab.

- **Die Lösung:**
1. **Tabs durch Spaces ersetzen:** Wenn du den *Studio Code Server* oder *FileEditor* in Home Assistant nutzt, markiere den Text. Tabulatoren werden oft als kleine rote Symbole oder Pfeile markiert. Ersetze sie durch Leerzeichen.
2. **VS Code Einstellung:** In VS Code kannst du unten rechts in der Statusleiste auf „Tabulator-Größe“ klicken und die Option **„Einrückung in Leerzeichen konvertieren“** wählen.
3. **Vor Neustart prüfen:** Gehe vor jedem Home Assistant Neustart zwingend auf *Entwicklerwerkzeuge* -> *YAML* und klicke auf **„Konfiguration prüfen“**. Nur wenn dort ein grünes Häkchen erscheint, ist dein YAML-Code syntaktisch fehlerfrei und sicher für einen Systemstart.

Dieser Fehler tritt meistens auf, wenn du ein Core-Update oder ein Add-on-Update in Home Assistant startest. Der Ladebalken bricht nach einigen Minuten ab und wirft diese unübersichtliche Fehlermeldung aus.

- **Die Ursache:** Der zugrundeliegende Docker-Dienst (der die Add-ons und Home Assistant selbst in isolierten Containern ausführt) kann das neue Image nicht herunterladen, weil **kein freier Speicherplatz auf der Festplatte (SSD/SD-Karte) mehr verfügbar ist**.

- **Die Lösung (Speicherplatz freigeben):**

1. **Speicher prüfen:** Navigiere zu *Einstellungen* -> *System* und schaue dir oben die Auslastung deines Speichers an. Liegt diese über 90%, drosselt das System Downloads.

2. **Alte Backups löschen:** Backups sind die größten Speicherfresser. Gehe auf *Einstellungen* -> *System* -> *Backups*. Lade wichtige Backups herunter und lösche ältere, nicht mehr benötigte Sicherungen aus Home Assistant.

3. **Recorder-Datenbank reduzieren:** Die Home Assistant Datenbank (home-assistant_v2.db) speichert jeden Sensorwert standardmäßig 10 Tage lang. Bei vielen Sensoren wächst die Datei auf dutzende Gigabyte an. Füge in deiner configuration.yaml folgende Zeilen hinzu, um Daten nach 7 Tagen automatisch zu löschen (Purge) und unnötige Entitäten vom Recording auszuschließen:

recorder:
  purge_keep_days: 7
  auto_purge: true

4. **VM-Festplattengröße erhöhen:** Falls du Home Assistant in einer virtuellen Maschine (z. B. Proxmox, VirtualBox, Hyper-V) betreibst, ist die Standard-Zuweisung oft nur 6 bis 12 GB groß. Erhöhe die virtuelle Festplatte in deinem Hypervisor auf mindestens 32 GB. Home Assistant OS erweitert die Partition beim nächsten Systemstart automatisch.

Einsteiger stehen oft vor der Frage, welche Installationsmethode für Home Assistant die beste ist. Die beiden gängigsten Varianten unterscheiden sich grundlegend im Funktionsumfang und Wartungsaufwand:

- **Home Assistant Operating System (HAOS) – Empfohlen für 95% aller User:**
HAOS ist ein minimalistisches, vorkonfiguriertes Betriebssystem, das exklusiv für Home Assistant entwickelt wurde (z. B. für Raspberry Pi, Home Assistant Green oder dedizierte Mini-PCs).
- **Vorteile:** Voller Funktionsumfang inklusive **Supervisor**, integriertem **Add-on Store** (Installation von MQTT-Brokern, Node-RED, InfluxDB etc. mit nur einem Klick direkt in der UI) und automatischen Backups sowie einfachen OS-Updates über die Weboberfläche.

- **Home Assistant Container (Docker) – Für erfahrene Linux-Nutzer:**
Hierbei läuft Home Assistant als isolierter Container auf einem bestehenden Betriebssystem deiner Wahl (z. B. Debian, Ubuntu, Synology DSM).
- **Vorteile:** Extrem ressourcenschonend, lässt sich perfekt auf bestehenden Heimservern betreiben, auf denen bereits andere Docker-Dienste laufen.
- **Nachteile:** Es gibt **keinen Supervisor** und **keine Add-ons** direkt in der Benutzeroberfläche! Wenn du beispielsweise MQTT nutzen möchtest, musst du manuell einen separaten Docker-Container (z. B. Mosquitto Broker) auf deinem Server starten und konfigurieren. Auch Backups und System-Updates müssen manuell über Docker-Befehle verwaltet werden.

Ja, absolut! Eines der Kernversprechen und wichtigsten Alleinstellungsmerkmale von Home Assistant ist die kompromisslose **lokale Kontrolle** (Local Control) über dein Smart Home.

- **Was läuft komplett offline weiter?**
Da Home Assistant lokal auf deiner Hardware (z. B. Raspberry Pi oder Mini-PC) läuft, funktionieren dein gesamtes Dashboard, alle deine Automationen, Skripte und Szenen völlig autark weiter – selbst wenn dein Internetanbieter eine Störung hat.
Alle Geräte, die über lokale Netzwerkprotokolle angebunden sind, arbeiten störungsfrei:
- **Zigbee & Z-Wave:** Werden lokal über deinen USB-Funkstick gesteuert.
- **Matter & Thread:** Lokale, herstellerübergreifende Funk- und Netzwerkprotokolle.
- **ESPHome:** Deine selbst gebauten ESP32-Steuerungen (wie OpenDTU) kommunizieren direkt im WLAN mit Home Assistant, ohne Umweg über das Internet.

- **Was fällt bei einem Internetausfall weg?**
- Integrationen, die zwingend die Cloud des Herstellers benötigen (z. B. Ecoflow-Cloud, Zendure-Cloud oder manche smarte Steckdosen von TP-Link/Tupo).
- Der Fernzugriff von unterwegs (sofern du kein lokales VPN oder Nabu Casa nutzt).
- Wettervorhersagen oder Web-Dienste.
- Push-Nachrichten auf dein Smartphone (diese benötigen die Apple- oder Google-Push-Server).

**Tipp:** Achte beim Kauf neuer Hardware auf das offizielle Siegel **„Works with Home Assistant – Local Control“**, um maximale Unabhängigkeit von Internet und Hersteller-Servern zu garantieren.

Ja, und das wird im professionellen Dauerbetrieb **dringend empfohlen**! Da Home Assistant permanent Sensorwerte in eine Datenbank schreibt, sind herkömmliche microSD-Karten oft nach 6 bis 18 Monaten durch die extrem hohe Zahl an Schreibzyklen physisch abgenutzt und gehen kaputt.

Es gibt zwei Wege, eine USB-SSD an einem Raspberry Pi 4 zu nutzen:

- **Methode A: Die Daten-Festplatte (Data Disk) – Empfohlen & Sicher:**
Dies ist die modernste, stabilste und von den Entwicklern empfohlene Methode. Hierbei bleibt eine einfache, günstige SD-Karte im Pi stecken, um das reine Betriebssystem (HAOS) unkompliziert zu booten. Alle Schreibvorgänge und Daten werden jedoch auf die angeschlossene USB-SSD verschoben.
- **So geht's:** Schließe die SSD an einen der blauen USB 3.0 Ports des Pi 4 an. Gehe in Home Assistant auf *Einstellungen* -> *System* -> *Speicher*. Klicke unten auf das Drei-Punkte-Menü und wähle **„Daten-Festplatte verschieben“**. Wähle deine SSD aus und bestätige. Das System startet neu und verschiebt alle Protokolle, Datenbanken und Backups dauerhaft auf die SSD.

- **Methode B: Kompletter Boot von USB-SSD (ohne SD-Karte):**
Du kannst das Home-Assistant-OS-Image direkt mit dem BalenaEtcher auf die USB-SSD flashen und den Pi komplett von USB booten lassen (dafür muss der Bootloader des Pi 4 auf USB-Boot konfiguriert sein).
- **Achtung:** Viele günstige USB-zu-SATA-Adapter-Kabel verwenden Controller-Chips (z. B. JMicron), die in Kombination mit dem Raspberry Pi 4 im U-Boot-Bootloader abstürzen oder instabile Verbindungen verursachen. Verwende daher primär Methode A oder achte beim Kauf auf einen USB-Adapter mit ASMedia- oder Realtek-Chipsatz.

Dank Home Assistant musst du dich nicht auf ein einziges Sprachassistenten-Ökosystem festlegen. Du kannst alle in Home Assistant integrierten Geräte problemlos für Apple Home (Siri), Amazon Alexa und Google Assistant freigeben:

- **1. Sprachsteuerung mit Apple Siri (100% kostenlos & lokal):**
Home Assistant verfügt über eine extrem leistungsstarke, integrierte **Apple HomeKit-Bridge**. Diese simuliert eine HomeKit-Zentrale.
- **So geht's:** Gehe auf *Einstellungen* -> *Geräte & Dienste* -> *Integration hinzufügen* und suche nach **„Apple HomeKit-Bridge“**. Wähle die Geräteklassen aus, die du steuern möchtest. Home Assistant zeigt dir einen QR-Code an. Scanne diesen einfach mit der „Home“-App auf deinem iPhone oder iPad. Alle Geräte (auch solche, die Apple nativ gar nicht unterstützt) tauchen sofort in Apple Home auf und können per Siri gesteuert werden.

- **2. Sprachsteuerung mit Alexa & Google Assistant:**
Hierfür gibt es zwei Wege:
- **Weg A (Komfortabel per Home Assistant Cloud / Nabu Casa):** Dies ist der einfachste Weg. Für ca. 6,50 € im Monat (Nabu Casa Cloud) verbindest du Alexa oder Google Home mit nur einem Klick. Es ist keine Portfreigabe oder DynDNS-Konfiguration nötig. Das Beste: 100% der Einnahmen fließen direkt in die Vollzeit-Entwickler von Home Assistant, um das Projekt werbefrei und unabhängig zu halten.
- **Weg B (Manuell & Kostenlos für Entwickler):** Du kannst über die Amazon Developer Console bzw. Google Actions Console eigene Skills erstellen. Dies erfordert jedoch fortgeschrittene Kenntnisse, einen extern erreichbaren HTTPS-Zugang (z. B. via DuckDNS & Let's Encrypt Portfreigabe 443) sowie die manuelle Einrichtung von AWS Lambda-Funktionen.

Wenn du eine neue Integration oder ein Custom Component (oft über den Community Store HACS) installiert hast, und diese danach unter *Einstellungen* -> *Geräte & Dienste* -> *Integration hinzufügen* nicht in der Suche erscheint, liegt das meist an einem übersprungenen Initialisierungsschritt:

- **Schritt 1: Home Assistant zwingend neu starten!**
Drittanbieter-Integrationen (aus dem Verzeichnis custom_components) werden erst beim Systemstart von Home Assistant in den Speicher geladen. Nach der Installation in HACS musst du das System unter *Entwicklerwerkzeuge* -> *YAML* -> **„Neu starten“** einmal komplett booten.

- **Schritt 2: Browser-Cache leeren (Wichtig!)**
Manchmal ist die Integration bereits geladen, aber dein Webbrowser hat die Liste der UI-Komponenten im Cache zwischengespeichert. Drücke Strg + F5 (Windows) bzw. Cmd + Shift + R (macOS), um die Ansicht komplett neu zu laden.

- **Schritt 3: Fehler im Fehlerprotokoll (Logs) suchen:**
Wenn die Integration nach dem Neustart immer noch fehlt, konnte sie aufgrund eines Ladefehlers oder inkompatibler Abhängigkeiten nicht gestartet werden. Gehe zu *Einstellungen* -> *System* -> *Protokolle* und suche nach Fehlern mit roter Markierung. Häufige Ursachen sind Versionskonflikte, wenn ein Custom Component nicht für die aktuell installierte Home Assistant Version aktualisiert wurde.

- **Schritt 4: YAML-Integrationen prüfen:**
Manche ältere Integrationen können nicht über die UI hinzugefügt werden, sondern erfordern Einträge in der configuration.yaml. Stelle sicher, dass die Schreibweise exakt stimmt und führe vor dem Neustart immer eine Überprüfung aus (*Entwicklerwerkzeuge* -> *YAML* -> *Konfiguration prüfen*).

VE.Direct ist eine serielle Schnittstelle von Victron Energy, die extrem empfindlich auf elektromagnetische Störungen reagiert. Bei sporadischen Abbrüchen helfen diese Profilösungen:

- **Galvanische Trennung (Optokoppler):** Dies ist die wichtigste Empfehlung! Da der Victron SmartSolar Laderegler hohe Ströme schaltet und der ESP32 oft über ein anderes USB-Netzteil betrieben wird, entstehen Potenzialunterschiede auf der Masseleitung (GND). Dies stört die serielle Datenübertragung und kann im schlimmsten Fall das ESP32-Board zerstören. **Nutze zwingend ein VE.Direct Kabel mit integrierter galvanischer Trennung (Optokoppler-Modul).**

- **Kabellänge reduzieren:** Das serielle VE.Direct-Kabel sollte so kurz wie möglich gehalten werden (maximal 1,5 Meter) und darf nicht parallel zu stromführenden Batteriekabeln oder Solarkabeln verlegt werden, um Induktionen zu vermeiden.

Ja! Sowohl OpenDTU als auch OpenDTU-OnBattery unterstützen I2C-basierte OLED-Displays (meist 0.96 Zoll SSD1306 oder 1.3 Zoll SH1106):

- **Verkabelung:** Verbinde die Pins des Displays wie folgt:
- VCC an 3.3V (oder 5V, je nach Display-Spezifikation)
- GND an GND
- SCL an den konfigurierten I2C-SCL Pin des ESP32 (z. B. GPIO 22)
- SDA an den konfigicherten I2C-SDA Pin des ESP32 (z. B. GPIO 21)

- **Aktivierung:** Gehe im Webinterface auf **Einstellungen** -> **Display-Einstellungen**. Aktiviere das Häkchen für das Display, wähle den passenden chip-Typ (SSD1306 oder SH1106) aus und trage die korrekten GPIO-Pins für SDA und SCL ein. Nach einem Neustart des ESP32 zeigt das Display automatisch Live-Daten, WLAN-Status und IP-Adresse an.

Nein, das ist physikalisch und softwareseitig ausgeschlossen.

Das ESP32-Board verfügt über einen unveränderlichen, im Silizium eingebrannten Bootloader (ROM). Selbst wenn die USB-Verbindung während des Flashvorgangs getrennt wird, der Strom ausfällt oder eine völlig fehlerhafte Firmware geflasht wird, bleibt dieser Bootloader immer intakt.

Du kannst das Board jederzeit wieder anschließen, den Web Flasher erneut starten, gegebenenfalls die BOOT-Taste gedrückt halten und den Flashvorgang neu anstoßen. Die Hardware kann durch Software-Modifikationen nicht beschädigt werden.