Konfiguration

Verbindungsparameter

Lass den Web-PIN leer, wenn du die Integration nur per Modbus betreiben möchtest. Modbus bleibt der Basispfad und funktioniert ohne PIN. Wenn du einen PIN angibst, kann der Einrichtungsfluss zusätzlich einen eingeschränkten Fallback im reinen Web-Betrieb anbieten, wenn Modbus nicht verfügbar ist.

Der lokale Modbus-Transport verwendet modbus-connection mit tmodbus. Einträge nutzen die gemeinsame Verbindung von Home Assistant, wenn deren Unit-API verfügbar ist. Ein fehlgeschlagener Anspruch fällt auf einen eigenen Socket zurück. Siehe Verbindungsdiagnose.

Optionen

Nach der Eingabe der Verbindungsdaten wählst du eine Tiefe der geführten Einrichtung:

Jede Tiefe bietet denselben Funktionsumfang. Wähle nur die Funktionen aus, die du ändern möchtest; jede ausgewählte Funktion öffnet eine kurze Seite für ihren Schalter sowie die gegebenenfalls benötigten Sensor-, Heizkreis- oder Gruppenzuordnungen. Eine abschließende Bestätigung speichert die Konfiguration und lädt den Eintrag neu. Einstellungen aus einem tieferen Modus bleiben gespeichert, wenn du später einen einfacheren Modus wählst. Du kannst die Tiefe jederzeit über Neu konfigurieren (Drei-Punkte-Menü ⋮ der Eintragszeile) > Funktionen wechseln. Neu konfigurieren > Verbindung ändert Host, Web-Zugriff und Modbus-Proxy. Bestehende Optionen bleiben unverändert, wenn ihre Funktion im Assistenten nicht ausgewählt war.

Wenn Beta-Funktionen neu aktiviert werden, erscheint vor dem Speichern eine zusätzliche Bestätigungsseite. Sie ist getrennt von der Bestätigung der alleinigen Steuerung, die der automatische Warmwasser-Manager und der Komfortzeitplan verlangen.

Differenztemperaturgeregelte Heizkreise

In der aktuellen stabilen Integration verfügbar; die unten beschriebenen Hardware-Grenzen gelten weiterhin.

Wenn das Heizsystem eines Kreises im Navigator bereits auf Differenztemperaturgeregelt steht, kann Home Assistant Speicher- und Referenztemperatur, ihre vorzeichenbehaftete Differenz und den Kreisstatus anzeigen. Das ist beispielsweise für einen Holzofenkreis mit Speicher sinnvoll.

1. Wähle bei der Ersteinrichtung Anlage in der geführten Funktionsauswahl. Für einen bestehenden Eintrag nutze Konfigurieren → Anlage oder Neu konfigurieren → Funktionen → Anlage.
2. Lass den Kreis unter Heizkreise ausgewählt und wähle ihn zusätzlich unter Differenztemperaturgeregelte Heizkreise. Im erweiterten Optionsformular steht dieselbe Auswahl neben den installierten Heizkreisen.
3. Speichere und warte auf das Neuladen. Vergleiche Speicher- und Referenztemperatur mit deinem Regler. Die Differenz ist Referenz minus Speicher, angegeben in K.

Die Auswahl ist standardmäßig leer und funktioniert in beiden Funktionsprofilen. Mit konfiguriertem Web-PIN an einem Navigator 10 werden Differenzkreise automatisch erkannt: jeder Web-Poll wertet den system/overview-Frame des Reglers aus, der auf der reinen Endanwender-Ebene jeden Heizkreis mit seiner Regelart auflistet. Die manuelle Auswahl bleibt maßgeblich — sie deckt Anlagen ohne Web-Supplement ab und überschreibt die Erkennung. Die Auswahl ändert die Darstellung in Home Assistant, nicht das Heizsystem am Regler, und ist vom internen Differenzregelungsmodul des Navigators getrennt.

Normale Heizungsregler und Climate-Entitäten entfallen für ausgewählte Kreise. Prüfe vor dem Speichern darauf zugreifende Dashboards und Automationen. Die beiden Temperatursensoren behalten ihre Entity-IDs. Zurückschalten stellt normale Regler wieder her; Anpassungen entfernter Regler bleiben dabei nicht erhalten. Hysterese, Schwellen und Maximaltemperatur werden wegen unbestätigter Register nicht angeboten. Die Nachprüfung für 0.21.1 fand weder im API-Katalog noch in der verfügbaren Modbus-Tabelle eine bestätigte Parameterzuordnung. Insbesondere ist hc_d_setpoint_flow_constant als Sollwert eines Konstantkreises dokumentiert; ein gleicher Messwert beweist keine Zuordnung zum Differenzschwellwert. Die Zuordnung basiert auf dem Navigator-10-Bericht in Issue #429 und muss noch auf Hardware mit Differenzregelung bestätigt werden. Siehe Entitäten, Statuswerte und Migration.

Funktionsprofil

Das Funktionsprofil steuert optionale IDM-spezifische Entitäten:

Das Smart-Profil ist standardmäßig aktiviert, um das vollständige bestehende Verhalten der Integration zu erhalten. Vanilla ist nützlich, wenn nur die ursprünglichen Reglerwerte und Steuerungen verfügbar gemacht werden sollen. Der Wechsel des Profils lädt den Eintrag neu; optionale Entitäten können entfernt oder neu erstellt werden, während die Kern-Entitäts-IDs unverändert bleiben.

Das Profil schreibt von sich aus keine Energiewerte und verändert die Heizkurve nicht. Externe PV-, Batterie-, Raumtemperatur-, Feuchtigkeits- und Speicher-Weiterleitung bleiben separate Opt-in-Funktionen und sind in ihren eigenen Abschnitten dokumentiert.

Smart stellt außerdem persistente Energie-, COP-, Kosten-, CO₂- und optionale PV-Eigenverbrauchs-Statistiken bereit, wenn die benötigten Leistungsregister verfügbar sind. Strompreis und CO₂-Faktor werden lokal in den Optionen konfiguriert; sie werden von keinem externen Dienst abgerufen.

Wenn die Gerätehierarchie aktiviert ist, werden optionale Entitäten in eigenen logischen Gruppen geführt: iDM Analytics, iDM Health Monitor und iDM Comfort. Bestehende Regler-, Heizkreis-, Warmwasser- und Web-Entitäten bleiben in ihren bisherigen Gruppen und behalten ihre Entitäts-IDs.

Zuordnung und Weiterleitung externer Leistung

Bei ModBridge oder einem anderen Modbus-Proxy müssen Modbus-Host und -Port dessen Listener benennen; der Web-Host bleibt der tatsächliche Navigator. Beispielsweise kann 192.0.2.10:5020 auf einen Navigator unter 192.0.2.20:502 weiterleiten, während das Web-Supplement 192.0.2.20 verwendet. Ein Port wie 5020 ist nicht grundsätzlich falsch; maßgeblich ist die konfigurierte Proxy-Route. Bei Verbindungsfehlern sind diese Route und deren Verfügbarkeit zu prüfen, nicht die Registerfreigabe. Die Schreibwarnung verschwindet nach einem erfolgreichen Schreibvorgang auf ihr Register. Erfolg auf einem anderen Register entfernt sie nicht.

Bestehende externe Leistungsquellen können wieder geleert werden. Entferne die Auswahl und speichere, um die automatische Weiterleitung dieses Registers zu stoppen; andere ausgewählte Quellen bleiben erhalten. Das Entfernen von Batterie- SOC entfernt auch die optionale SOC-Bedingung im HA-Energiemanager. Es wird kein Ersatzwert ins Register geschrieben. SOC mit Nachkommastellen wird akzeptiert und für den ganzzahligen GLT-Eingang gerundet.

Die Kategorie Externe Leistungsweiterleitung ordnet bestehende Home-Assistant-Sensoren PV-Überschuss, PV-Produktion, Hausverbrauch, Batterie Laden/Entladen, Batterie-SOC und Heizstab-Leistung zu. Der Weiterleitungsschalter ist standardmäßig aus. Wenn aktiviert, werden gültige Werte bei Änderungen der Quelle und mit einer nominellen zyklischen Auffrischung alle drei Sekunden in die entsprechenden IDM-GLT-Register geschrieben, auch bei unveränderten Werten. Diese Auffrischung hat Vorrang vor dem einstellbaren Intervall von 30–3600 Sekunden (Standard: 60 Sekunden). Die tatsächlichen Abschlusszeiten hängen von Verbindungslast und Schreibsperrzeiten ab.

Leistungssensoren müssen W, kW oder MW liefern; die Weiterleitung rechnet in kW um. Der Batterie-SOC muss ein endlicher Prozentsatz von 0 bis 100 sein; Nachkommastellen werden für GLT gerundet. Das Batterievorzeichen kann beibehalten oder invertiert werden, um zur Konvention der Quelle zu passen. Ungültige oder außerhalb des Bereichs liegende Werte werden übersprungen; eine nicht verfügbare Quelle schreibt keinen Ersatzwert Null. Leere Felder lassen ihre Register unangetastet. Sorge dafür, dass nicht gleichzeitig ein anderer Energiemanager dasselbe Register beschreibt.

Wenn eine Batterie genutzt wird, zusätzlich Batterie Laden/Entladen zuordnen, damit Register 84 zusammen mit dem Batterie-SOC (Register 86) geschrieben wird. Der IDM-Support hat diese Anforderung bestätigt; nur den SOC zu schreiben reicht nicht (#493).

Die gespeicherte Zuordnung versorgt auch die optionale PV-Schätzung und den automatischen Warmwasser-Manager. Sie können eine bestehende Zuordnung lesen, während die Weiterleitung aus ist. Der aktuelle geführte Assistent zeigt die Zuordnungsseite nur, wenn die Weiterleitung aktiviert ist; eine separate Seite zur Quellenauswahl nur für den Lesezugriff gibt es noch nicht. Siehe Einrichtung der externen Leistungsweiterleitung zur Vorbereitung des Reglers und zu den Feldzuordnungen. Für einen SolarEdge-Wechselrichter mit Batterie und weitere Wechselrichter siehe GLT-Anleitung und Template-Generator.

Optionaler Workaround für PV-Meldung 20300 bei Nullleistung

Einige Navigator-Regler melden nachts oder bei wenig Licht 20300: Photovoltaik nicht verbunden, obwohl gültige Nullwerte wiederholt erfolgreich über GLT geschrieben werden. Eine kontrollierte Versuchsreihe vom 10.11.2026 an einem Navigator 10 mit Firmware T_NAV10_20.24-1580-g02a20b66f hat den Mechanismus geklärt: Der Regler bemängelt einen eingefrorenen pv_production-Wert — nach rund zehn Minuten ohne Registeränderung erscheint Meldung 20300, unabhängig vom Pegel (statisch 10 W, 20 W und 50 W latchten alle), während jede Wertänderung — hoch oder runter, 10 W oder 50 W — sie in Sekunden löscht. Es gibt keinen Watt-Schwellwert; eine konstante Ersatzleistung beliebiger Größe hält die Meldung daher nicht fern.

Öffne bei einer betroffenen Anlage Einstellungen → Geräte & Dienste → IDM Heatpump → Konfigurieren oder Neu konfigurieren → Funktionen. Aktiviere in den geführten Funktionseinstellungen die externe Leistungsweiterleitung und öffne deren Sensorzuordnung. Schalte PV-Nullleistungs-Workaround ein und speichere die restlichen Schritte des Assistenten. Das gleiche Feld ist bei der Ersteinrichtung vorhanden. Es ist standardmäßig ausgeschaltet.

Ist der Workaround aktiv, wird eine gültige PV-Produktionsquelle, die auf die 10-W-Auflösung des Registers rundet — alles unter 5 W, positiv wie ein Dämmerungswert von 3 W oder negativ wie ein kleiner Standby-Wert des Wechselrichters —, als alternierender 10/20-W-Herzschlag übertragen: Der Ersatzwert wechselt jede Minute, damit das Register nie lange genug einfriert, um die Meldung auszulösen (die längste ohne Latch verifizierte eingefrorene Spanne beträgt 127 Sekunden). Sobald die Quelle 5 W oder mehr meldet, werden wieder die Live-Werte mit der üblichen GLT-Rundung übertragen. Nicht verfügbare, ungültige oder nicht zugeordnete Quellen werden nicht ersetzt. PV-Überschuss, Batteriewerte, Hausverbrauchsberechnung und der ursprüngliche HA-Quellsensor bleiben unverändert; der Herzschlag erzeugt kein künstliches Überschusssignal. Die Steuerung und ihre PV-Anzeigen beziehungsweise Statistiken sehen nachts eine künstliche Produktion von im Mittel 15 W. Verdeck damit keine echten Kommunikationsausfälle. Ausschalten stellt die normale Nullwertübertragung wieder her; die Controller-Firmware wird nicht verändert.

Optionaler PV-Energiemanager

Die Option Automatisches Warmwasser-Laden mit PV-Überschuss ist standardmäßig aus. Sie startet nur den bestehenden sicheren Warmwasser-Boost, wenn der ausgewählte PV-Überschuss verfügbar ist. Sie setzt die Zuordnung der externen Leistungsquellen und die ausdrückliche Bestätigung voraus, dass Home Assistant der einzige Warmwasser-Regler ist. Das ist eine Erklärung der alleinigen Steuerung, keine automatische Erkennung von Smartfox, openWB oder einem anderen Regler. Deaktiviere konkurrierende Warmwasser-Steuerung, bevor du sie bestätigst.

Fehlende, nicht verfügbare oder ungültige Quellwerte führen zum sicheren Abschalten (fail closed). Der Manager schreibt keine GLT-Energiregister und verändert weder das normale Heizen noch die Heizkurve oder den Heizstab. Tarif-, Wetter- und Heiz-Vorsteuerungen werden durch diese Option nicht aktiviert. Ein ausgewählter Tarifsensor verändert nur die Kostenrechnung; eine automatische preisbasierte Heizsteuerung ist nicht implementiert. Siehe Smart Energy & Comfort zu Quellenrangfolge, Standardwerten und dem Verhalten eines bereits laufenden Boosts.

Optionaler Komfortzeitplan und Berater

Der Komfortzeitplan ist standardmäßig deaktiviert und erfordert die ausdrückliche Bestätigung, dass nur ein einziger Regler aktiv ist. Er schreibt nur das Raumtemperatur-Soll des ausgewählten Heizkreises innerhalb des konfigurierten Tagesfensters und stellt danach den vorherigen Sollwert wieder her, wenn der aktuelle Wert noch dem geplanten Sollwert entspricht. Eine manuelle Änderung, die während eines aktiven Zeitplans erfolgt, bleibt unangetastet. Der erweiterte Modus bietet bis zu 16 Tagesfenster über alle konfigurierten Heizkreise hinweg, auch über Nacht, in der in Home Assistant konfigurierten Zeitzone. Siehe Zeitplan-Beispiele.

Der Heizkurven-Assistent und der Wetter-Vorheiz-Berater sind schreibgeschützt. Sie veröffentlichen Empfehlungen, ohne ein IDM-Register zu verändern. Der Wetterberater erfordert eine ausgewählte Home-Assistant-weather-Entität. Alle Komfort-Entitäten erscheinen unter iDM Comfort, wenn die Gerätehierarchie aktiviert ist.

Optionaler iDM Health Monitor

Der iDM Health Monitor ist standardmäßig deaktiviert und fügt schreibgeschützte Diagnose-Entitäten hinzu. Er prüft Kommunikationsfehler, die Verdichter-Startfrequenz, einen aktuell niedrigen COP, die Warmwasser-Temperaturabweichung und unplausible Temperaturwerte. Der Sensor iDM health report zeigt ok oder problem und listet aktive Prüfungen in seinen Attributen auf. Er verändert keine Wärmepumpen-Einstellung.

Predictive Advisor

Der Predictive Advisor ist eine strikt schreibgeschützte Analyse- und Empfehlungsebene und mit dem Smart-Profil standardmäßig aktiviert. Er erklärt, warum die Wärmepumpe läuft, erkennt Anomalien gegen die eigenen Baselines der Anlage, bewertet Zustand und Effizienz, lernt eine COP-Karte und ein Gebäudemodell und empfiehlt Heizkurven-Schritte, Warmwasser-Fenster und einen 24-Stunden-Plan. Details: Predictive Advisor.

Der Advisor arbeitet vollständig lokal und deterministisch — ohne KI, Cloud oder LLM. Der Strompreis-Sensor und die Wetter-Entität werden zusätzlich von den Energie-Statistiken bzw. dem Wetter-Hinweis genutzt.

Abfrageintervall

Das Abfrageintervall legt fest, wie oft Register abgefragt werden.

Web-Supplement-Daten

Die Integration kann optional zusätzliche lokale Navigator-Webdaten über idm-heatpump-api lesen. Dies ist schreibgeschützt und additiv. Verwendet wird es für Werte wie die Navigator-Generation, die Softwareversion, ausgewählte Web-UI-Diagnosen und Infosystem-Meldungen des Navigator 10. (Das Wärmepumpenmodell ist, wo die Firmware es meldet, ein Attribut am Sensor Navigator-Version (Web) — siehe Entitäten.)

Wichtiges Verhalten:

• Wenn kein PIN konfiguriert ist, wird kein Web-Client erstellt und die Integration bleibt im reinen Modbus-Betrieb.
• Während Einrichtung, Neukonfiguration und Reparatur wird das Modbus-Modell nur dazu verwendet zu wählen, welches lokale Webprotokoll zuerst versucht wird. Schlägt dieser Versuch fehl, wird auch das andere unterstützte Protokoll getestet. Das tatsächlich erfolgreiche Protokoll wird mit dem Konfigurationseintrag gespeichert.
• Während der normalen Abfrage wird der erfolgreiche, authentifizierte Client wiederverwendet. Läuft seine Sitzung ab oder schlägt die Verbindung fehl, wird der Client geschlossen und dasselbe bekannte Protokoll sofort neu aufgebaut. Die andere Navigator-Generation wird bei der routinemäßigen Laufzeitwiederherstellung nicht geprüft.
• Nach dem Austausch des Navigators, einer Änderung des Web-Endpunkts oder einer Firmware-Änderung, die das lokale Interface verändert, führe Neu konfigurieren → Verbindungseinstellungen ändern aus, damit die Protokollerkennung erneut laufen kann.
• Ist der PIN während Einrichtung oder Neukonfiguration falsch, zeigt das Formular den PIN-Fehler sofort an. Nach einem Modbus-Fehler kann der PIN direkt im Wiederherstellungsformular korrigiert werden, ohne die Einrichtung neu zu starten.
• Ist das Webinterface später nicht erreichbar, läuft die Modbus-Abfrage weiter.
• Die Web-Abfrage läuft separat und startet kurz nach der Modbus-Abfrage, damit nicht beide Protokolle exakt im selben Moment den Regler belasten.
• Modbus-Registerwerte haben immer Vorrang. Web-Sensoren werden nur für zusätzliche Werte oder Werte ohne bestehende Modbus-Entität erstellt. Web-Metadaten zu Modell/Firmware können ein unbekanntes Modbus-Ergebnis ergänzen, ein eindeutiger Familienkonflikt wird aber ignoriert.
• Wird ein Modbus-Proxy verwendet, trage die Proxy-IP als Host und die ursprüngliche Wärmepumpen-IP als Web-Host ein, damit das lokale Navigator-Webinterface weiterhin erreichbar bleibt.

Der Navigator 2.0 verwendet einen lokalen HTTP/CSRF-Login; Navigator 10 und Navigator Pro verwenden die WebSocket-Login-Familie des Navigator 10. Siehe Lokales Navigator-Webinterface für die vollständige Zustandsmaschine aus Erkennung und Wiederherstellung.

Raumtemperatur-Weiterleitung

Die Raumtemperatur-Weiterleitung ist optional und standardmäßig deaktiviert. Wenn aktiviert, kann die Integration ausgewählte Home-Assistant-Temperatursensoren in die externen IDM-Raumtemperatur-Register der aktiven Heizkreise schreiben, zum Beispiel hc_a_ext_room_temp.

Wichtiges Verhalten:

• Werte werden bei Zustandsänderungen des Sensors geschrieben und zusätzlich periodisch aktualisiert.
• Ungültige, nicht verfügbare, nicht numerische oder außerhalb des Bereichs liegende Werte werden übersprungen.
• Ein Heizkreis ohne ausgewählten Sensor bleibt unangetastet.
• Diese Funktion schreibt Modbus-Werte. Verwende Sensoren, die die tatsächliche Raumtemperatur abbilden, die die Wärmepumpe sehen soll.

Externe Feuchtigkeits-Weiterleitung

Die externe Feuchtigkeits-Weiterleitung ist optional und standardmäßig deaktiviert. Wenn aktiviert, leitet die Integration einen ausgewählten Home-Assistant-Feuchtigkeitssensor in das globale IDM-GLT-Feuchtigkeitsregister (ext_humidity) weiter. Anders als die Raumtemperatur hat die Feuchtigkeit kein Register je Heizkreis, daher kann nur ein einziger Sensor ausgewählt werden.

Dieselben Verhaltenshinweise wie bei der Raumtemperatur-Weiterleitung gelten: Werte werden bei Zustandsänderungen geschrieben und periodisch aktualisiert, ungültige oder außerhalb des Bereichs liegende Werte werden übersprungen, und ein leeres Sensorfeld deaktiviert die Weiterleitung.

Externe Speichertemperatur-Weiterleitung

Die externe Speichertemperatur-Weiterleitung ist optional und standardmäßig deaktiviert. Wenn aktiviert, leitet die Integration bis zu vier ausgewählte Home-Assistant-Temperatursensoren in die festen IDM-GLT-Speicherregister weiter: Wärmespeicher (glt_heat_storage_temp), Kältespeicher (glt_cold_storage_temp) sowie Warmwasserspeicher unten/oben (glt_dhw_temp_bottom / glt_dhw_temp_top).

Dieselben Verhaltenshinweise wie bei der Raumtemperatur-Weiterleitung gelten: Werte werden bei Zustandsänderungen geschrieben und periodisch aktualisiert, ungültige oder außerhalb des Bereichs liegende Werte werden übersprungen, und ein leeres Feld eines Registers lässt dieses unangetastet.

Externe Leistungs-Weiterleitung (PV & Stromzähler)

Die externe Leistungs-Weiterleitung ist optional und standardmäßig deaktiviert. Wenn aktiviert, leitet die Integration ausgewählte Home-Assistant-Leistungs- und Batteriesensoren — oder direkt einen Zweirichtungs-Netzstromzähler zusammen mit der PV-Erzeugung — in die IDM-GLT-Leistungsregister (pv_surplus, pv_production, house_consumption, battery_discharge, battery_fill_level) weiter.

Wichtiges Verhalten:

• Wenn ein Netzstromzähler-Sensor und ein PV-Erzeugungs-Sensor ausgewählt sind, berechnet die Integration automatisch den PV-Überschuss (pv_surplus) und den Hausverbrauch (house_consumption), sofern deren direkte Sensorfelder leer gelassen werden (#519).
• Wenn eine Batterie genutzt wird, Batterie Laden/Entladen und Batterie-SOC zuordnen, damit Register 84 zusammen mit Register 86 geschrieben wird. Der IDM-Support verlangt diesen Schreibzugriff; siehe Einrichtung der externen Leistungsweiterleitung und #493.
• Die weitergeleiteten Werte werden in die GLT-Eingangsregister des Reglers geschrieben (z. B. Register 74 pv_surplus und Register 82 house_consumption). In Home Assistant sind diese beschreibbaren GLT-Eingangsregister als number-Entitäten mit dem Zusatz (Vorgabe) angelegt (z. B. Hausverbrauch (Vorgabe), standardmäßig in der Entitätsregistrierung deaktiviert), während die gleichnamigen sensor-Entitäten ohne diesen Zusatz (z. B. Hausverbrauch) den vom Regler zurückgemeldeten Messwert anzeigen. Um den exakt per Weiterleitung geschriebenen GLT-Wert in Home Assistant zu prüfen, aktiviere die entsprechende number-Entität mit dem Zusatz (Vorgabe).

GLT-Sensoren für externe Leistung werden auch angelegt, wenn ihr erster unterstützter Rücklesewert „nicht gesetzt“ meldet. Sie bleiben bis zu einem gültigen Rücklesewert nicht verfügbar und erholen sich dann ohne Neuladen. Die beschreibbare Number bleibt bei einem nicht gesetzten Wert mit unbekanntem Zustand bedienbar. Dies gilt unabhängig von der automatischen Weiterleitung. Fehlende oder nicht unterstützte Register bleiben ausgefiltert. Das Abschalten der Weiterleitung beendet Schreibzugriffe; es setzt den Reglereingang nicht zurück und garantiert keine Aufbewahrungsdauer.

KNX-Bridge

Die KNX-Bridge ist optional und standardmäßig deaktiviert. Wenn aktiviert, veröffentlicht die Integration die IDM-KNX-Kommunikationsobjekte auf einem KNX-Bus und nimmt Befehle von ihm entgegen — sie ersetzt das Weinzierl-KNX-IP-BAOS-Gateway-Modul, das IDM für den Navigator vertreibt. Sie steuert die Home-Assistant-KNX-Integration an, die eingerichtet sein muss: Gateway, Tunnelling und KNX Secure kommen von dort.

Gruppenadressen werden als Basisadresse + IDM-Objektnummer abgeleitet; mit der Standardbasis landet Objekt 1 (Außentemperatur) auf 8/0/1 und Objekt 222 (Modus Heizkreis A) auf 8/0/222. Der gesamte Katalog passt in eine Hauptgruppe. Verwende idm_heatpump.export_knx_group_addresses, um die vollständige Tabelle für deinen Regler zu erhalten.

Alle Details, einschließlich der Objektgruppen und Datenpunkttypen, stehen in KNX-Bridge.

Heizkreise

Wähle die aktiven Heizkreise (A bis G). Nur aktivierte Heizkreise erzeugen Entitäten in Home Assistant.

Zonen

Gib die Anzahl der Zonenmodule (0–10) und die aktiven Räume je Modul an. Die Integration unterstützt bis zu 8 Räume je Zone; 6 ist der API-Standard für die aktuelle Navigator-10-Hardware. Konfiguriere nur physisch vorhandene Räume, um unnötigen Validierungsverkehr für einzelne Raummodi zu vermeiden.

Raumnamen

Für jeden Raum in jeder Zone kannst du einen eigenen Namen vergeben. Diese Namen werden als Entitätsnamen in Home Assistant verwendet.

Neukonfiguration

Wo diese Punkte zu finden sind: Aktuelle Home-Assistant-Versionen zeigen keinen beschrifteten Button „Konfigurieren“ mehr — das Optionsfenster öffnet das Zahnrad-Symbol (⚙) am rechten Ende der Zeile deines Anlagen-Eintrags unter Einstellungen → Geräte & Dienste → IDM Wärmepumpe. Der beschriftete Punkt Neu konfigurieren liegt im Drei-Punkte-Menü (⋮) derselben Zeile und öffnet den Verbindungs-Assistenten; dessen Aktion Funktionen konfigurieren führt zu denselben Optionen. Solange der Eintrag einen Fehlerzustand anzeigt, ist das Zahnrad ausgeblendet — benutze in dem Fall den Weg über Neu konfigurieren.

1. Öffne Einstellungen → Geräte & Dienste
2. Klicke auf IDM Heatpump
3. Öffne das Drei-Punkte-Menü (⋮) deiner Eintragszeile und klicke auf Neu konfigurieren
4. Wähle die benötigte Aktion:
   • Funktionen öffnet die Standard-, Erweitert- oder Experte-Einrichtung, um Einstellungen ausgewählter Funktionen zu ändern, ohne nicht ausgewählte Kategorien anzutasten.
   • Verbindungseinstellungen ändern aktualisiert nach Prüfung Host, Port, Slave-ID, lokalen Web-PIN und Proxy-Einstellungen.
   • Aktuelle Verbindung testen führt eine schreibgeschützte Prüfung mit den gespeicherten Einstellungen durch. Es wird nichts gespeichert und niemals in Modbus-Register geschrieben.

flowchart TD
    reconf["IDM Heatpump → Neu konfigurieren<br/>(Verbindung und Diagnose)"] --> choice{"Aktion wählen"}
    choice -- "Verbindungseinstellungen ändern" --> conn["Host, Port, Slave-ID, Web-PIN,<br/>Proxy — Prüfung beim Absenden"]
    conn --> ctest{"Prüfung"}
    ctest -- "Modbus schlägt fehl,<br/>Web-PIN gültig" --> wofallback{"Web-only-Fallback angeboten"}
    wofallback -- "annehmen" --> webonly["Web-only-Modus; bestehende Heizkreise, Zonen<br/>und Optionen bleiben erhalten"]
    wofallback -- "Modbus erneut versuchen" --> conn
    ctest -- "ok" --> applied["Eintrag mit den neuen<br/>Einstellungen neu geladen"]
    webonly --> applied
    choice -- "Funktionen konfigurieren" --> guided["Geführter Funktions-Editor — dieselben Schritte<br/>wie bei der Einrichtung, ohne die Verbindung anzutasten"]
    guided --> applied
    choice -- "Aktuelle Verbindung testen" --> diag["Schreibgeschützte Diagnose: DNS/TCP,<br/>ein bekanntes IDM-Register, optionaler Web-Endpunkt.<br/>Es wird nichts gespeichert oder geschrieben"]
    diag --> result{"Ergebnis"}
    result -- "ok" --> okmsg["Erfolg bestätigt"]
    result -- "Fehler" --> errmsg["Genannte Ursache + Empfehlungen;<br/>Formular erneut absenden, um den Test zu wiederholen"]
    result -.-> diag

Der Test liest ein bekanntes IDM-Modbus-Register. Schlägt das fehl, grenzt eine kurze DNS/TCP-Prüfung den Netzwerkfehler genauer ein. Ist ein lokaler Web-PIN konfiguriert, prüft er zusätzlich den Navigator-Web-Endpunkt und die Anmeldung. Das Ergebnis unterscheidet Hostname, abgelehnte Verbindung, Timeout, nicht erreichbaren Endpunkt, fehlende Modbus-Antwort, ungültigen PIN und Webinterface-Fehler. Sende das Ergebnisformular erneut ab, um den Test zu wiederholen.

Ein falscher Web-PIN wird beim Ändern der Verbindung direkt abgelehnt. Bleibt das Feld leer, bleibt der Eintrag im reinen Modbus-Betrieb.

Schlägt Modbus fehl, während ein gültiger Web-PIN vorliegt, bietet der Fluss den reinen Web-Betrieb an und listet dessen Einschränkungen klar auf. Modbus-Verbindung erneut versuchen führt zurück zum richtigen Neukonfigurationsformular; das Zurückschalten aus dem reinen Web-Betrieb löscht die Fallback-Kennzeichnung nach einer erfolgreichen Modbus-Prüfung. Bestehende Heizkreis-, Zonen- und erweiterte Modbus-Optionen bleiben erhalten, während der reine Web-Betrieb aktiv ist, und stehen nach der Wiederherstellung von Modbus wieder zur Verfügung.

Verwende Konfigurieren (das Zahnrad-Symbol in der Eintragszeile) oder Neu konfigurieren → Funktionen konfigurieren, um das vollständige Optionsformular zu bearbeiten, einschließlich Abfrageintervall, Heizkreisen, Zonen, Smart Energy & Comfort, Gesundheitsüberwachung, Weiterleitungen und automatischen Steuerungen. Das Speichern lädt die Integration neu, sodass optionale Entitäten den ausgewählten Einstellungen folgen. Neu aktivierte Beta-Funktionen erfordern vor dem Speichern eine ausdrückliche Bestätigung.

Erweiterte Modbus-Optionen

Der eingeklappte Abschnitt Erweiterte Modbus-Einstellungen bietet zusätzlich zu Timeout- und Wiederholungseinstellungen auch Steuerung für fortgeschrittene Nutzer:

• Pause zwischen Anforderungen (0–0.5 Sekunden) ist der minimale Abstand, den die Verbindung zwischen zwei Modbus-Anforderungen einhält, gemessen vom Ende einer Anforderung bis zum Beginn der nächsten. 0 s (Standard) sendet Anforderungen unmittelbar hintereinander, wie jede Version vor dieser Option. Erhöhe sie, wenn der Regler oder ein Modbus-Gateway mit „device busy" antwortet, Anforderungen verwirft oder unter einer dichten Anforderungsfolge in einen Timeout läuft. Die Pause gilt für jede Anforderung, sodass ein vollständiger Abfragezyklus entsprechend länger dauert: bei rund 40 Batches verlängert 0.1 s einen Zyklus um etwa 4 Sekunden. Beginne bei 0.05 s.
• Pause nach dem Verbinden (0–5 Sekunden) wird einmal nach dem Aufbau der Verbindung abgewartet, bevor die erste Anforderung gesendet wird — beim ersten Verbinden und bei jedem Wiederverbinden, nicht je Anforderung. 0 s (Standard) sendet sofort. Erhöhe sie für Gateways, die eine Verbindung annehmen, bevor sie antworten können.
• Abfrage-Jitter (0–20%) fügt jeder Abfrage eine zufällige Verzögerung von bis zum ausgewählten Prozentsatz des Abfrageintervalls hinzu. Das verteilt Netzwerk- und Reglerlast, wenn mehrere Wärmepumpen gleichzeitig mit der Abfrage beginnen. 0% deaktiviert den Jitter.
• Erweiterte Kommunikationsdiagnose erstellt Diagnose-Entitäten für die letzte erfolgreiche Abfrage, die Abfragedauer, aufeinanderfolgende Fehlschläge und die Anzahl aktiver Register. Abfragen und Fehlschläge insgesamt sind als Attribute und in der heruntergeladenen Diagnose enthalten.
• Schreib-Cooldown (0–600 Sekunden) gilt je Register. Eine zweite Schreiboperation auf dasselbe Register innerhalb des konfigurierten Intervalls wird abgelehnt, ohne etwas an die Wärmepumpe zu senden; Home Assistant meldet die verbleibende Wartezeit. 0 deaktiviert diesen Schutz vollständig; eine Änderung geschieht auf eigenes Risiko. Unterschiedliche Registeradressen blockieren einander nicht.

Der allgemeine Schreib-Cooldown ist unabhängig vom EEPROM-Schutz der API. EEPROM-sensitive Register unterliegen daher weiterhin dem separat konfigurierten EEPROM-Intervall und seinen Sicherheitsregeln.

Verbindungsmodus

Das erste Feld des erweiterten Abschnitts wählt, welche Datenpfade der Eintrag nutzen darf:

• Automatisch (empfohlen) behält das bisherige Verhalten: Modbus für Register und alle Schreibvorgänge, die lokale Web-Ergänzung für zusätzliche Werte, wenn eine Web-PIN konfiguriert ist, und den Web-only-Fallback beim Einrichten, wenn Modbus nicht erreichbar ist, aber eine gültige PIN vorliegt.
• Modbus + Web-Ergänzung legt beide Pfade fest und deaktiviert den Web-only-Fallback beim Einrichten: Eine scheiternde Modbus-Verbindung wird erneut versucht, statt auf Web-only zurückzufallen.
• Nur Web betreibt den Eintrag vollständig über die lokale Web-Oberfläche — beim Einrichten wird keine Modbus-Verbindung aufgebaut. Auf einem Navigator 10 werden Betriebsart und Störungsquittierung über die Web-Oberfläche gesteuert (gleiche Numerierung wie Modbus, vor dem Senden validiert); Sollwerte und weitere Steuermöglichkeiten erfordern weiterhin Modbus. Er benötigt eine konfigurierte Web-PIN und ist mit den Web-Oberflächen von Navigator 10/Pro (WebSocket) und Navigator 2.0 (HTTP) verfügbar — die Web-Steuerung braucht die WebSocket-Variante.
• Nur Modbus kontaktiert niemals die Web-Oberfläche, auch nicht mit konfigurierter PIN; die Web-Entitäten werden für diesen Eintrag nicht erstellt.

Die Auswahl bleibt über Neuladen hinweg bestehen. Ein expliziter Modus übersteuert den alten Web-only-Schalter, den der Einrichtungs-Fallback einstmals gesetzt hat — Modbus + Web-Ergänzung stellt auf einem solchen Eintrag also den vollen Modbus-Betrieb wieder her. Der Diagnose-Export berichtet den aktiven Modus im Block connection zusammen mit der erkannten Controller-Familie, der Firmware-Version und ob eine Web-PIN konfiguriert ist (nur die Angabe, nie die PIN selbst).

Laufzeit- und API-Versionen

IDM Heatpump ist eine benutzerdefinierte Home-Assistant-Integration und kein Add-on. Die Integration erstellt einen Diagnosesensor mit dem Namen IDM-Heatpump-API-Version (Englisch: IDM Heatpump API version). Sein Zustand ist die tatsächlich installierte Version der idm-heatpump-api-Distribution. Die Sensor-Attribute zeigen außerdem:

• integration_version: installierte Version der benutzerdefinierten Integration
• modbus_connection_version: installierte Version der Verbindungsbibliothek
• tmodbus_version: installierte Version des direkten Socket-Backends
• home_assistant_version: installierte Home-Assistant-Core-Version
• python_version: Version der Python-Laufzeit

Dieselbe Versionsmenge ist in der heruntergeladenen Diagnose enthalten. Die Integration und die Versionen ihrer direkten Abhängigkeiten werden beim Start des Eintrags zusätzlich protokolliert. Das ist der maßgebliche Weg, die Laufzeit zu prüfen; die in custom_components/idm_heatpump/manifest.json gepinnte Version beschreibt, was installiert sein sollte, während der Sensor zeigt, was tatsächlich geladen ist.

Versionspaarung von Integration und API

Dieses Projekt hat zwei unabhängig versionierte Pakete:

Das Manifest listet die getestete Laufzeit in dieser Reihenfolge: modbus-connection>=4.12.7, tmodbus[async-serial]>=0.6.2 und idm-heatpump-api[web]==2.16.2. Die ersten beiden Pakete besitzen den direkten Socket. idm-heatpump-api bleibt für die IDM-spezifische Gerätelogik verantwortlich und besitzt ihre eigene Ausnahmehierarchie; die Integration installiert kein pymodbus mehr. 4.12.7 ist die Version von modbus-connection, keine Version der IDM-Integration. Der Transport wurde erstmals mit der IDM-Integrations-Beta 0.11.0-beta.1 ausgeliefert.

Der Adapter ist implementiert, durch automatisierte Tests abgedeckt und auf einem Navigator 10 live verifiziert. Seine geschwärzte Diagnose meldet die aktive Transportquelle. Ab Home Assistant 2026.10 beansprucht jeder Konfigurationseintrag die zentrale geteilte Modbus-Verbindung von Home Assistant: Die Diagnose meldet dann source: homeassistant.modbus, owns_socket: false und supports_shared_connection: true, mehrere Einträge an einem Regler teilen sich ein einziges Socket, und der konfigurierte Modbus-Timeout wird auf die geteilte Verbindung verhandelt. Auf älteren Releases — und immer dann, wenn der geteilte Anspruch nicht zustande kommt — meldet die Diagnose source: modbus_connection.tmodbus, owns_socket: true und supports_shared_connection: false, was ein privates Socket pro Konfigurationseintrag bedeutet. Die Abdeckung für Navigator 2.0/Pro und ein absichtlicher Verbindungstrennungs-/Wiederverbindungstest stehen noch aus; Schreibzugriffe auf echter Hardware bleiben außerhalb des Umfangs, sofern nicht ausdrücklich autorisiert. IDM Heatpump ist eine benutzerdefinierte Integration, kein Home-Assistant-Add-on.

Assist (Text und Sprache)

Die Integration bringt einen lokalen Assist-Agenten mit (Entität Assistent unter dem Wärmepumpen-Gerät). Wähle ihn unter Einstellungen → Geräte & Dienste → Assist als bevorzugten Agenten — oder sprich ihn gezielt an — und frage auf Deutsch oder Englisch:

• „Warum läuft die Wärmepumpe gerade?" — beantwortet vom Betriebsgrund- Erklärer: Betriebsmodus, Leistungsaufnahme, Temperaturen und der eigene Anforderungsgrund des Reglers, wenn das Web-Supplement ihn liefert.
• „Welche Empfehlung gibt es?" — die obersten nur-lesenden Empfehlungen des predictive Advisors.
• „Wie ist der Warmwasserzustand?", „Wie sind die Temperaturen?", „Wie ist der Verbrauch?", „Wie ist der Status?".

Jede Antwort wird lokal aus dem aktuellen Coordinator-Snapshot per deterministischem Keyword-Routing erzeugt. Keine Anfrage verlässt die Instanz, kein Sprachmodell ist beteiligt.

Gemeinsame Evidenz in Assist

Zusätzlich beantwortet der lokale Agent Fragen wie „Was hat sich geändert?“, „Ist der Verbrauch gestiegen?“, „Wie hat sich das Takten entwickelt?“, „Welche Nachweise fehlen?“ oder „Hat die Änderung geholfen?“ anhand derselben begrenzten Historie wie Berichte und Predictive Advisor. Fehlende oder nicht vergleichbare Daten werden benannt. Beobachtete Zusammenhänge sind kein Nachweis für Ursache oder Einsparung. Siehe Evidenz und Optimierungsbeobachtung.

Debug-Protokollierung

Aktiviere erweiterte Protokollierung für die Fehlerbehebung:

logger:
  default: info
  logs:
    custom_components.idm_heatpump: debug

EEPROM-Hinweis

Bestimmte Register sind EEPROM-sensitiv (insgesamt 88). Diese Register werden beim Schreiben im EEPROM gespeichert und haben eine begrenzte Anzahl Schreibzyklen. Die Integration warnt vor übermäßigem Schreiben dieser Register.

Zyklisches GLT-Schreiben

Die Register 1696 und 1698 (GLT-Temperaturanforderungen) müssen zyklisch alle 10 Minuten geschrieben werden, um aktiv zu bleiben. Die Schalter-Entitäten für GLT-Anforderungen erledigen das automatisch.

Experimenteller KI-Anlagenberater

Der optionale, nur lesende Berater erstellt tägliche und wöchentliche Berichte sowie Anlagen- und Effizienzprüfungen. Standardmäßig entstehen lokale Messdatenberichte ohne Modellaufruf. Freiformulierte Erklärungen über Ollama, eine HA-AI-Task-Entität oder einen separat bestätigten Cloud-Anbieter sind zusätzlich aktivierbar. Kein Bericht steuert die Anlage. Siehe Einrichtung, Aktionen, Datenabdeckung und Grenzen.