Firmware-Migration (v2.x → v3.x)

🏊 Smart Swimming Pool: Migration vom alten Homie 3.0-Format zum neuen MQTT-Discovery-Format

Wenn Sie den Pool Controller v2.x (oder älter) betreiben und auf v3.x upgraden möchten, erklärt dieser Leitfaden, was sich ändert und wie Sie Ihre Smart-Home-Integration aktualisieren müssen.

💡 Neuling? Wenn Sie den Pool Controller zum ersten Mal installieren, folgen Sie stattdessen der Erste Schritte-Anleitung. Diese Anleitung ist nur relevant, wenn Sie bereits ein Homie 3.0-Setup haben.

Übersicht

Warum die Änderung?

Der Wechsel von Homie 3.0 zu Home Assistant MQTT Discovery hatte zwei Ziele:

1. Null-Konfiguration für Home Assistant-Nutzer — HA erkennt alle Entitäten automatisch, keine manuelle Konfiguration nötig
2. Standardisierung — HA Discovery ist der De-facto-Standard für MQTT-basierte IoT-Geräte, während Homie 3.0 nie breite Akzeptanz fand

openHAB wird weiterhin vollständig über manuelle MQTT-Konfiguration unterstützt.

Firmware-Upgrade

Schritt 1: v3.x flashen

Folgen Sie der Standard-Flash-Prozedur in der Erste Schritte-Anleitung:

# In VS Code mit PlatformIO:
# 1. Firmware hochladen
# 2. Dateisystem-Image (LittleFS/Webinterface) hochladen

⚠️ Wichtig: Nach dem Flashen von v3.x ist das Webinterface komplett neu geschrieben. Einstellungen aus dem alten Web-UI werden nicht übernommen. Sie müssen WiFi und MQTT über den Setup-AP (Pool-Controller-Setup) neu konfigurieren.

Schritt 2: WiFi und MQTT neu konfigurieren

1. Nach dem Flashen startet der ESP32 im AP-Modus (Pool-Controller-Setup)
2. Verbinden Sie sich damit und konfigurieren Sie Ihr WLAN unter http://192.168.4.1
3. Nach dem Neustart konfigurieren Sie MQTT über Konfiguration → MQTT

Schritt 3: Konfigurationsparameter erneut einstellen

Nach der Migration konfigurieren Sie diese Parameter im Webinterface (oder über Home Assistant) neu:

• Maximale Pooltemperatur
• Minimale Solartemperatur
• Hysterese
• Timer Start / Ende
• Sensor-Adressen (DS18B20)

Migration nach Smart-Home-Plattform

Home Assistant-Nutzer

Sie sind nach Schritt 2 fertig. Die v3.x-Firmware erkennt sich automatisch über MQTT Discovery.

1. Gehen Sie zu Einstellungen → Geräte & Dienste
2. Das Gerät Pool Controller sollte automatisch erscheinen
3. Siehe Home Assistant Integrations-Guide für die vollständige Entity-Referenz

Hinweis: Wenn Sie manuell MQTT-Sensoren in Home Assistant für die Homie-Topics konfiguriert hatten, werden diese nach dem Upgrade als nicht verfügbar angezeigt. Entfernen Sie sie manuell — die automatisch erkannten Entitäten ersetzen sie.

openHAB-Nutzer

openHAB erfordert manuelle MQTT-Konfiguration. Der openHAB Integrations-Guide zeigt die vollständige Einrichtung.

Was sich ändern muss

Topic-Mapping-Referenz

Wichtige Werte-Änderungen

Breaking Changes

1. Timer-Entities umstrukturiert

v2.x: 4 separate number-Entities für Timer-Start/Ende (Stunden + Minuten einzeln)

homie/<mac>/operation-mode/timer-start-h
homie/<mac>/operation-mode/timer-start-min
homie/<mac>/operation-mode/timer-end-h
homie/<mac>/operation-mode/timer-end-min

v3.x: 2 time-Entities im HH:MM:SS-Format

homeassistant/time/pool-controller/timer-start
homeassistant/time/pool-controller/timer-end

Die alten Entitäten werden automatisch aus Home Assistant entfernt, wenn v3.x startet (leere retained-Payloads werden auf ihre Config-Topics veröffentlicht).

2. Timezone-Entity geändert

v2.x: number-Entity mit Zeitzonen-Index (z.B. 0, 1, …)

v3.x: select-Entity mit lesbaren Zeitzonen-Labels (z.B. Europe/Berlin, America/New_York)

3. Temperaturbasierte Zirkulation (neu in v3.3+)

v3.3 fügte drei neue Konfigurationsparameter für temperaturgesteuerte Zirkulation hinzu:

• temp-circ-threshold — minimale Temperaturdifferenz für Zirkulation
• temp-circ-factor — Laufzeit-Multiplikator pro Grad über Schwelle
• temp-circ-max-runtime — maximale Zirkulationslaufzeit

Diese gab es in v2.x nicht und haben kein Homie-Äquivalent.

4. Geräte-ID ist jetzt konfigurierbar

In v2.x war die Geräte-ID immer die MAC-Adresse (5ccf7fb97572). In v3.x ist die Standard-ID pool-controller, aber Sie können sie im Webinterface unter Konfiguration → MQTT → Geräte-ID ändern.

Wenn Sie sie ändern, aktualisieren Sie alle Topic-Pfade entsprechend.

5. Kein Homie-Kompatibilitätsmodus

Die v3.x-Firmware unterstützt nur Home Assistant MQTT Discovery. Es gibt keinen Rückwärtskompatibilitätsmodus für Homie 3.0. Wenn Sie Homie für benutzerdefinierte Integrationen benötigen, bleiben Sie bei v2.x.

Rollback

Falls Sie zu v2.x zurückkehren müssen:

1. Flashen Sie die v2.x-Firmware mit PlatformIO
2. Konfigurieren Sie WiFi und MQTT neu (v2.x verwendet ebenfalls den Setup-AP)
3. Die alten Homie-Topics werden wieder aktiv
4. openHAB oder Home Assistant verbinden sich automatisch neu

Hinweis: Das Flashen von v3.x löscht die LittleFS-Dateisystempartition. v2.x speichert die Konfiguration möglicherweise anders. Planen Sie ein, nach dem Downgrade alle Einstellungen neu zu konfigurieren.

Ältere Firmware-Versionen