ESPAltherma Teil 2: Firmware flashen und in Home Assistant einbinden

von

Im ersten Teil dieser Serie ging es um die Architektur und die Hardware-Seite: ESP32 an den X10A-Port der Daikin Altherma anschließen. Mit der Verkabelung steht jetzt die Frage im Raum, wie aus diesem passiven Lauscher tatsächlich Daten in Home Assistant werden. Dieser Teil deckt beides ab: das Flashen der Firmware mit VSCode und PlatformIO, und die anschließende Integration in Home Assistant über MQTT – inklusive der eigenen Template-Sensoren, mit denen ich aus den Rohdaten sinnvolle Entitäten baue.

Vorbereitung: VSCode und PlatformIO installieren

ESPAltherma wird nicht über die Arduino IDE geflasht, sondern über Visual Studio Code mit der PlatformIO-IDE-Extension. Der Grund: PlatformIO verwaltet Bibliotheken, Board-Definitionen und Build-Umgebungen deutlich sauberer als die klassische Arduino-IDE, was bei einem Projekt mit mehreren unterstützten Boards (ESP32, ESP8266, M5StickC, M5StickC Plus) und vielen wählbaren Wärmepumpen-Definitionsdateien spürbar Zeit spart.

  1. VSCode installieren (falls noch nicht vorhanden)
  2. In VSCode über die Extensions-Ansicht nach „PlatformIO IDE“ suchen und installieren
  3. Nach der Installation erscheint links eine neue PlatformIO-Ameisen-Kopf-Ikone in der Seitenleiste

Anschließend das ESPAltherma-Repository von GitHub herunterladen (per „Code → Download ZIP“ oder per Git-Klon) und den entpackten Ordner in VSCode über „Datei → Ordner öffnen“ laden. PlatformIO erkennt automatisch die enthaltene platformio.ini und bietet die passenden Build-Umgebungen an.

Die richtige Build-Umgebung wählen

Unten in der VSCode-Statusleiste findet sich ein Feld, über das sich die aktive PlatformIO-Umgebung umschalten lässt. Für einen gewöhnlichen ESP32 (wie ich ihn selbst einsetze) bleibt die Standard-ESP32-Umgebung aktiv, es muss nichts umgestellt werden. Wer stattdessen ein M5StickC oder M5StickC Plus verwendet, muss hier explizit env:M5StickC bzw. die passende Plus-Variante auswählen – wird das vergessen, kommt es laut Projektdokumentation zu Konflikten zwischen dem PSRAM des M5-Boards und der Standard-Serial-Portbelegung, was sich in einem unresponsive Gerät oder fehlschlagenden Uploads äußert. Für ESP8266 ist entsprechend die nodemcuv2-Umgebung zu wählen.

Das von mir verwendete ESP32-Board: ESP32 NodeMCU Development Board mit WROOM-32 bei Amazon ansehen*

* Affiliate-Link: Wenn du über einen entsprechend gekennzeichneten Link etwas kaufst, erhalte ich möglicherweise eine Provision. Für dich ändert sich der Preis dadurch nicht. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen.

Konfiguration in setup.h

Die zentrale Konfigurationsdatei liegt unter src/setup.h. Hier werden folgende Punkte eingetragen:

  • WLAN-Zugangsdaten (SSID/Passwort)
  • MQTT-Broker-Adresse, Port, ggf. Zugangsdaten
  • Die GPIO-Pins für RX/TX, über die der ESP32 mit dem X10A-Port kommuniziert

Beim ESP32 ist hier Vorsicht geboten: Der Chip hat mehrere UARTs, aber Serial0 (die Standard-USB-Verbindung zum PC) darf nicht für die Altherma-Kommunikation zweckentfremdet werden, weil ESPAltherma genau darüber seine eigenen Debug-Logs ausgibt. Stattdessen kommt Serial2 zum Einsatz, in der Praxis meist GPIO16 (RX2) und GPIO17 (TX2) – exakt die Pins, die ich auch selbst in meiner Verkabelung aus Teil 1 verwendet habe. Beim ESP8266 sieht die Sache anders aus: Der Chip hat nur eine „anderthalbe“ Hardware-Serial-Schnittstelle, weshalb ESPAltherma hier auf eine Software-Serial-Implementierung zurückgreift. Empfohlen werden GPIO4 und GPIO5 (D2/D1 auf einem NodeMCU-Board), wobei nicht jeder GPIO gleich gut geeignet ist – manche blockieren beim Booten die Konsolenausgabe.

Die passende Definitionsdatei für das eigene Wärmepumpenmodell

ESPAltherma bringt für zahlreiche Daikin-/Rotex-/Hoval-Modelle vorgefertigte Definitionsdateien mit, die festlegen, welche Register überhaupt abgefragt und wie ihre Rohwerte in sinnvolle Einheiten umgerechnet werden. Ausgewählt wird die passende Datei über eine #include-Zeile in setup.h:

...
//#include "def/ALTHERMA(HPSU6_ULTRA).h"
#include "def/ALTHERMA(HYBRID).h" //<-- diese Zeile wird verwendet
//#include "def/ALTHERMA(LT-D7_E_BML).h"
...Code-Sprache: PHP (php)

Praktisch: Es gibt inzwischen auch lokalisierte Definitionsdateien, unter anderem auf Deutsch. Dazu wird die Sprache einfach in den Pfad mit aufgenommen:

#include "def/German/ALTHERMA(HYBRID).h"Code-Sprache: PHP (php)

Ist unklar, welche Definitionsdatei zum eigenen Modell passt, empfiehlt die Projektdokumentation, die naheliegendste zu wählen oder notfalls die Default.h zu verwenden – im schlimmsten Fall fehlen dann einzelne Werte oder liefern null, was sich im Nachgang leicht über die Community-Wiki zu den Registerwerten nachschlagen und korrigieren lässt.

Werte gezielt freischalten

In der gewählten Definitionsdatei folgt eine lange Liste einzelner Werte, die standardmäßig größtenteils auskommentiert sind:

LabelDef labelDefs[] = {
//  {0x00,0,801,0,-1,"*Refrigerant type"},
{0x60,0,304,1,-1,"Data Enable/Disable"}, //<-- wird abgefragt und gemeldet
// {0x60,1,152,1,-1,"Indoor Unit Address"},
{0x60,2,315,1,-1,"I/U operation mode"}, //<-- wird abgefragt und gemeldet
{0x60,2,303,1,-1,"Thermostat ON/OFF"}, //<-- wird abgefragt und gemeldet
// {0x60,2,302,1,-1,"Freeze Protection"},
{0x60,2,301,1,-1,"Silent Mode"}, //<-- wird abgefragt und gemeldet
...Code-Sprache: JavaScript (javascript)

Hier gilt: nicht einfach alles auskommentieren. Je mehr Werte aktiv sind, desto größer wird die einzelne MQTT-Nachricht, die ESPAltherma periodisch verschickt – bei zu vielen Werten kann das zu Problemen bei der MQTT-Übertragung führen. Das ist mir selbst so passiert: Ich hatte anfangs deutlich zu viele Werte gleichzeitig aktiviert, mit dem Ergebnis, dass die MQTT-Nachricht schlicht zu groß wurde und dadurch immer wieder gar nicht oder nur unvollständig bei Home Assistant ankam – ohne dass das auf den ersten Blick als „zu große Nachricht“-Problem erkennbar war, es sah eher nach einer allgemein wackligen Verbindung aus. Sinnvoller ist es, gezielt die Werte zu aktivieren, die tatsächlich gebraucht werden, und bei Bedarf später weitere hinzuzufügen. In meinem eigenen Setup sind das vor allem die Werte rund um Drücke, Temperaturen im Kältekreis und die Inverter-Frequenz – dazu gleich mehr im Abschnitt zu den Template-Sensoren.

Nach der Konfiguration wird die Firmware ganz regulär über PlatformIO hochgeladen (Upload-Button oder F1 → PlatformIO: Upload).

Troubleshooting nach dem ersten Flash

Zwei Fehlerbilder tauchen in der Praxis besonders häufig auf:

  • „Timeout on register“ bzw. Fehler 0x15 0xEA: Das ist die Antwort der Wärmepumpe darauf, dass sie das verwendete Protokoll nicht versteht. Betroffen sind meist ältere Altherma-Generationen (etwa Baujahr 2010 oder früher), die noch das ältere „S“-Protokoll statt des neueren „I“-Protokolls sprechen. Abhilfe: am Ende von setup.h die Zeile #define PROTOCOL 'I' auf #define PROTOCOL 'S' ändern und die passende PROTOCOL_S– bzw. PROTOCOL_S_ROTEX-Definitionsdatei wählen.
  • „Time out! Check connection“ bzw. falsche CRC-Prüfsummen: Das deutet fast immer auf ein Verkabelungsproblem hin. Die mit Abstand häufigste Ursache – wie schon in Teil 1 erwähnt – ist eine fehlende oder wacklige GND-Verbindung zwischen ESP32 und X10A-Port. Zweithäufigste Ursache sind schlicht minderwertige oder lose sitzende Dupont-Kabel.

Zur Fehlersuche loggt ESPAltherma sowohl über die serielle USB-Verbindung (im PlatformIO Serial Monitor sichtbar) als auch über MQTT auf dem Topic espaltherma/log – Letzteres lässt sich direkt in Home Assistant über die MQTT-Integration („Konfigurieren → Ein Topic abhören“) mitverfolgen, ganz ohne zusätzliches Tool.

Integration in Home Assistant über MQTT-Discovery

Läuft die Firmware und ist die WLAN-/MQTT-Verbindung hergestellt, meldet sich ESPAltherma automatisch über MQTT-Discovery bei Home Assistant an. Dabei entstehen zwei Geräte:

  • „Daikin Altherma via ESPAltherma“ – enthält alle in der Definitionsdatei aktivierten Sensoren als eigene Entitäten
  • „ESPAltherma“ – enthält zwei technische Basis-Entitäten: sensor.althermasensors (hält sämtliche Werte zusätzlich als Attribute) und switch.altherma (aktiviert das optionale Relais für den externen Ein/Aus-Thermostat, siehe unten)

Eigene Template-Sensoren aus den Rohwerten bauen

Auch wenn die Auto-Discovery bereits einzelne Sensor-Entitäten anlegt, lohnt es sich, für Werte, die man in eigenen Diagrammen, Gauges oder Automationen verwenden möchte, zusätzliche Template-Sensoren zu bauen, die direkt auf die Attribute von sensor.althermasensors zugreifen. Das gibt volle Kontrolle über Einheiten, Gerätklassen und Namensgebung. So sieht bei mir zum Beispiel der Template-Sensor für die Inverter-Frequenz des Kompressors aus:

template:
  - sensor:
      - name: "HP INV Frequenz"
        unique_id: hp_inv_frequenz
        state: "{{ state_attr('sensor.althermasensors','INV frequency (rps)') | float(0) }}"
        unit_of_measurement: "Hz"
        state_class: measurementCode-Sprache: JavaScript (javascript)

Nach demselben Muster habe ich mir eine ganze Reihe weiterer Template-Sensoren gebaut, die sich direkt aus den ESPAltherma-Attributen speisen: Hochdruck und Niederdruck im Kältekreis, Sauggas- und Heißgastemperatur, die Temperatur am Kompressoraustritt sowie am Kompressorport, und die Differenz zwischen Vor- und Rücklauftemperatur. Genau diese Werte sind es auch, die in Teil 3 als Basis für das fertige Dashboard dienen – insbesondere die Inverter-Frequenz, die als Trigger für eine kleine Automation dient, die jeden Kompressorstart mitzählt (Details dazu ebenfalls in Teil 3).

Wichtige Klarstellung: ESPAltherma kann nur lesen

So detailliert die ausgelesenen Werte auch sind – ESPAltherma kann die Konfigurationsregister der Wärmepumpe nicht direkt verändern. Die einzige Ausnahme betrifft die bereits erwähnte switch.altherma-Entität: Sie steuert ein Relais, das als externer Ein/Aus-Thermostat fungiert und damit die Heizfunktion grob ein- oder ausschalten kann – mehr nicht. Sollwerte für Vorlauftemperatur, Warmwasser oder Betriebsmodus lassen sich darüber nicht setzen.

Für die eigentliche Steuerung nutze ich deshalb, wie in Teil 1 beschrieben, die Daikin-Cloud-Integration (Onecta). Perspektivisch plane ich, diese Cloud-Abhängigkeit für die Steuerung durch eine selbstgebaute, rein lokale P1P2MQTT-Bridge zu ersetzen – dazu aber mehr, sobald dieses Projekt bei mir selbst über die Planungsphase hinaus ist.

Exkurs: Was der Home Hub über Modbus zusätzlich kann

Wie in Teil 1 angerissen, nutze ich aktuell zusätzlich den Daikin Home Hub über Modbus TCP – technisch über eine HACS-Integration, die intern auf den Baustein EKRHH zugreift. Anders als ESPAltherma kann diese Integration nicht nur lesen, sondern auch direkt schreiben: Vorlauftemperatur-Sollwerte für Heizen und Kühlen, Warmwasser-Nachheiz-Sollwert, Leistungsgrenzen, Betriebsmodus, sogar der Smart-Grid-Zustand lassen sich per Service-Call setzen. Der Home Hub selbst wird dafür über die P1/P2-Klemmen (Pin 11/12, beschriftet als „USER INTERFACE“) an der Hydrobox angeschlossen.

Das klingt zunächst nach der eleganteren Lösung gegenüber der Cloud-Integration – ich nutze es aktuell auch übergangsweise genau dafür. Der Haken, den ich bereits in Teil 1 erwähnt habe, bleibt aber bestehen: Der Home Hub kann nur einen Modus gleichzeitig sprechen, und die anstehende EEBus-Pflicht für den Netzbetreiber im Rahmen der §14a-Regelung wird mich zwingen, umzuschalten. Danach steht mir Modbus nicht mehr zur Verfügung, es sei denn, ich betreibe zusätzlich eine zweite Home-Hub-Box ausschließlich für Modbus. Wer aktuell noch nicht von dieser Umstellungspflicht betroffen ist, für den bleibt der Modbus-Weg über den Home Hub bis auf Weiteres eine vollwertige, sehr mächtige Alternative zur Cloud-Integration.

Ausblick auf Teil 3

Damit stehen jetzt alle Rohdaten sauber in Home Assistant zur Verfügung. Im letzten Teil der Serie geht es um die praktische Steuerung im Alltag – Zusammenspiel von Cloud-Integration und SG-Ready-Kontakten – sowie um das fertige Dashboard: History-Karten für Temperaturverläufe, die Automation zum Mitzählen der Kompressorstarts, eine COP-Berechnung und die Einbindung in die bestehende Amortisations-Serie. Weiter geht es hier mit ESPAltherma Teil 3: Wärmepumpe steuern und im Dashboard überwachen.

Schreibe einen Kommentar