Installation & Einrichtung

Voraussetzungen

• Home Assistant 2026.11.0 oder neuer
• Marketplace (in Home Assistant eingebaut) oder HACS als Alternative
• IDM Navigator 2.0 / 10 / Pro Wärmepumpe mit aktiviertem Modbus TCP
• Modbus TCP muss im Navigator-Controller aktiviert sein (Port 502, Slave-ID 1)

Installation über Marketplace oder HACS (empfohlen)

Die Integration steht im Standard-Katalog von HACS/Marketplace. Ein benutzerdefiniertes Repository ist nicht nötig, auch kein GitHub-Konto.

Home Assistant Marketplace (empfohlen):

1. Öffne Einstellungen → Marketplace
2. Suche nach "IDM Heatpump"
3. Öffne den Eintrag und klicke auf Herunterladen
4. Starte Home Assistant neu

Alternativ über HACS:

1. Öffne HACS in Home Assistant
2. Gehe zu Integrationen und suche nach "IDM Heatpump"
3. Klicke auf Herunterladen
4. Starte Home Assistant neu

Direktlinks – sie öffnen die Repository-Seite in deinem eigenen Home Assistant:

• IDM Heatpump im Marketplace öffnen (empfohlen)
• IDM Heatpump in HACS öffnen (Alternative)

Beim Upgrade von Home Assistant 2026.10 oder älter auf 2026.11 oder neuer wandert HACS automatisch in den Marketplace über: installierte Downloads und Update-Entitäten bleiben erhalten. Nichts muss neu installiert oder neu konfiguriert werden.

Stable oder Beta wählen

Das letzte stabile Release ist der normale Installationskanal. Die in diesem Wiki beschriebene neue geführte Einrichtung und die Smart-Energy-&-Comfort-Funktionen sind im 0.17.2-b6 Beta verfügbar.

Um die Beta auszuprobieren, öffne den IDM-Heatpump-Eintrag im Marketplace (oder in HACS), nutze deren Versionsauswahl-/Download-Aktion, aktiviere bei Bedarf Vorabversionen und wähle 0.17.2-b6. Sichere Home Assistant vor dem Upgrade und starte Home Assistant nach dem Herunterladen neu. Eine neuere Dokumentationsseite aktualisiert die installierte Integration nicht automatisch. Prüfe die installierte Version in der Diagnose der Integration, bevor du nach den neuen Optionen suchst.

Beta-Fixes haben automatisierte Regressionsabdeckung. Sie sind keine Aussage über eine abgeschlossene Langzeit- oder Hardware-Validierung für alle Modelle. Siehe Stabilität & Release-Reife.

Manuelle Installation

1. Lade das neueste Release herunter (idm_heatpump.zip)
2. Erstelle bei Bedarf das Verzeichnis idm_heatpump unter custom_components/
3. Entpacke den Inhalt des ZIP direkt in dieses Verzeichnis; manifest.json muss unmittelbar darin liegen, ohne ein weiteres verschachteltes idm_heatpump-Verzeichnis:

   <ha-config>/custom_components/idm_heatpump/
   

4. Starte Home Assistant neu

Modbus TCP an der IDM Wärmepumpe aktivieren

Erforderlich: Der volle Betrieb der Integration ist nur möglich, wenn Modbus TCP am IDM Navigator/Controller aktiviert ist. Die Installation der Home-Assistant-Integration kann diese Controller-Einstellung nicht aus der Ferne aktivieren.

Die offizielle iDM-Dokumentation beschreibt die relevante Navigator-Einstellung als Gebäudeleittechnik / Building management system → Modbus TCP → Ein / On. Dieses Menü liegt auf der Installateur-Ebene des Reglers: Lass Modbus TCP von deinem Heizungsinstallateur oder dem iDM-Service aktivieren — die Integration schaltet es nie frei und stellt keinen Zugangscode bereit. Sobald dein Installateur die Aktivierung bestätigt, ist das praktische Vorgehen:

1. Öffne das lokale Display des IDM Navigators/Controllers.
2. Öffne Gebäudeleittechnik (englisch: Building management system) — der Zugriff auf die Ebene erfolgt über deinen Installateur, falls das Menü dies verlangt.
3. Setze Modbus TCP auf Ein / Aktiv (englisch: On / Enabled).
4. Speichere die Einstellung. Starte den Navigator/Controller neu, wenn die Schnittstelle nicht sofort verfügbar wird.
5. Verbinde den Navigator mit dem lokalen Ethernet-Netzwerk und notiere seine IP-Adresse.
6. Verwende in dieser Integration TCP-Port 502 und normalerweise Slave-/Unit-ID 1.

Menünamen und Berechtigungen können sich zwischen Navigator 2.0, Navigator 10, Navigator Pro und Firmware-Versionen unterscheiden. Wenn Gebäudeleittechnik oder Modbus TCP fehlt, nur lesbar oder gesperrt ist, bitte deinen Heizungsinstallateur oder den iDM-Service, die Schnittstelle zu aktivieren. Ändere keine unbeteiligten Heizungs- oder Sicherheitsparameter.

Die erforderliche Einstellung gehört zur IDM Wärmepumpe/dem Navigator. Eine Modbus-TCP-Option an einem PV-Wechselrichter ist eine separate Schnittstelle und aktiviert keinen Home-Assistant-Zugriff auf die Wärmepumpe.

Netzwerk-Checkliste:

• Home Assistant und der Navigator müssen sich lokal gegenseitig erreichen können.
• Bevorzuge kabelgebundenes Ethernet; exponiere Port 502 nicht ins Internet.
• Reserviere die Navigator-IP im Router oder konfiguriere sie konsistent, damit sie sich nicht unerwartet ändert.
• Teste die Adresse aus dem Netzwerk von Home Assistant, nicht nur von einem Telefon in einem anderen WLAN/VLAN.

Quelle: offizielle iDM-Technikdokumentation (PDF), die festlegt, dass Modbus TCP im Menü Gebäudeleittechnik des Navigators auf Ein stehen muss; iDM dokumentiert TCP-Port 502 für die Modbus-Kommunikation des Navigators zusätzlich in der technischen PV-/GLT-Dokumentation.

Einrichtung

1. Öffne Einstellungen → Geräte & Dienste
2. Klicke auf Integration hinzufügen
3. Suche nach "IDM Heatpump"
4. Folge dem Konfigurationsassistenten:
   • Im Flow angezeigte Voraussetzung: Bestätige, dass am Navigator Gebäudeleittechnik → Modbus TCP aktiviert ist
   • Start: Wähle Verbindungsdaten manuell eingeben oder Netzwerk nach der Wärmepumpe durchsuchen. Der Scan fragt jeden Rechner eines Subnetzes einmalig auf dem Modbus-TCP-Port 502 ab — es werden keine Modbus-Daten gesendet oder gelesen — und listet die antwortenden Geräte mit IP-Adresse und, falls auflösbar, Reverse-DNS-Hostnamen; die gewählte Adresse legt das Verbindungsformular vor. Das Subnetz-Feld ist mit dem Netzwerk des Home-Assistant-Hosts vorbelegt
   • Verbindung: Gib einen Namen, die IP/den Hostnamen der Wärmepumpe, Port 502 und Slave-ID 1 ein
   • Automatische Anlagenerkennung: Nach erfolgreichem Verbindungstest liest der Assistent die Anlagenkonfiguration nur-lesend vom Regler (Modell, aktive Heizkreise, Zonenmodule, Kaskade) und zeigt sie im Review-Schritt; die folgenden Schritte öffnen mit diesen Werten statt mit Standardwerten. Eine gescheiterte Erkennung behält stillschweigend die Standardwerte.
   • Optionaler Webzugriff: Gib den lokalen Navigator-Web-PIN ein; bei Verwendung eines Modbus-Proxys aktiviere zusätzlich die Proxy-Option und gib die ursprüngliche Wärmepumpen-Adresse als Web-Host ein
   • Einrichtungstiefe: Wähle Standard, Erweitert oder Experte; diese steuern den Detailgrad, nicht welche Funktionen verfügbar sind
   • Funktionen: Wähle die Kategorien, die du konfigurieren möchtest, z. B. Anlage, Smart-/Vanilla-Profil, Energie, Health Monitor oder Komfort
   • Funktionsseiten: Gib die angeforderten Sensoren, Heizkreis-Zuordnungen und optionalen Einstellungen an; prüfe die Zuständigkeitsbestätigung, bevor du eine automatische Schreibfunktion aktivierst
   • Zonen: Konfiguriere die Anzahl aktiver Räume für jedes ausgewählte Zonenmodul
5. Prüfe und bestätige die Konfiguration zum Abschluss. Wie du die Einrichtungstiefe später änderst, steht in Konfiguration.

Ablauf der Einrichtung

Derselbe Ablauf als Diagramm. Jeder Pfad endet in einem funktionierenden Eintrag — die geführten Stufen verändern nur, wie viel gefragt wird, nie welche Funktionen verfügbar sind:

flowchart TD
    add["Integration hinzufügen → IDM Heatpump"] --> start{"Adresse manuell eingeben<br/>oder Netzwerk durchsuchen?"}
    start -- "manuell" --> prereq{"Modbus TCP am Navigator<br/>aktiviert?"}
    start -- "Netzwerkscan" --> scan["Subnetz-Formular (voreingestellt aus<br/>den Adaptern von Home Assistant)"]
    scan --> scanres["Ergebnisliste: IP plus<br/>Reverse-DNS-Name,<br/>keine Modbus-Daten gesendet"]
    scanres --> prereq
    prereq -- "nein" --> enable["Am Regler aktivieren:<br/>Gebäudeleittechnik → Modbus TCP"]
    enable --> conn
    prereq -- "ja" --> conn["Verbindungsformular: Name, Host, Port 502,<br/>Slave-ID 1, optionaler Web-PIN / Proxy<br/>(Host nach einem Scan vorbelegt)"]
    conn --> validate{"Verbindung geprüft:<br/>DNS/TCP-Check, Modbus-Sonde,<br/>Web-Login bei gesetztem PIN"}
    validate -- "Fehler" --> cause["Fehlerformular nennt die Ursache<br/>(siehe Tabelle unten)"]
    cause --> conn
    validate -- "Modbus nicht erreichbar,<br/>Web-PIN funktioniert" --> fallback{"Web-only-Modus nutzen?"}
    fallback -- "ja" --> webonly["Web-only-Eintrag:<br/>Lesen + begrenzte Steuerung,<br/>Modbus-Optionen bleiben erhalten"]
    fallback -- "Modbus erneut versuchen" --> conn
    validate -- "ok" --> review["Erkennungs-Review: Navigator-Modell bestätigen,<br/>erkannte Anlage (Kreise, Zonen, Kaskade),<br/>Einrichtungstiefe wählen"]
    review -- "Standard / Erweitert / Experte" --> features["Funktionskategorien:<br/>Anlage, Profil, Energie, Health,<br/>Komfort, Weiterleitung, KNX"]
    features --> pages["Funktionsseiten: angeforderte Sensoren,<br/>Heizkreis-Zuordnungen,<br/>Zuständigkeitsbestätigung für Schreibfunktionen"]
    pages --> zones{"Zonenmodule<br/>ausgewählt?"}
    zones -- "ja" --> rooms["Zonen: Anzahl aktiver Räume<br/>pro Zonenmodul"]
    zones -- "nein" --> finish
    rooms --> finish["Eintrag erstellt — Entitäten erscheinen<br/>nach der ersten erfolgreichen Abfrage"]

Lokaler Navigator-Web-PIN (keine Cloud-2FA)

Der optionale Web-PIN ist der lokale Netzwerk-Code, der am Navigator-Display konfiguriert wird. Er ist getrennt vom myIDM-App-/Cloud-Konto, dessen Passwort und der Zwei-Faktor-Authentifizierung.

An einem Navigator 2.0 mit deutschem Display konfigurierst du ihn unter:

Einstellungen → Allgemeine Einstellungen → Netzwerkeinstellungen → Code lokales Netzwerk

Die Menübezeichnungen können je nach Navigator-Generation und Firmware abweichen. Ein leerer Wert oder 0 deaktiviert die lokale Weboberfläche. Cloud-Zugangsdaten oder ein temporärer Zwei-Faktor-Code werden in Home Assistant daher abgelehnt.

Der Navigator 2.0 nutzt einen lokalen HTTP-Login mit CSRF-Token. Navigator 10 und Navigator Pro nutzen die Navigator-10-WebSocket-Login-Familie. Die Einrichtung nutzt das per Modbus erkannte Modell nur zur Wahl des ersten Versuchs, probiert bei Bedarf das andere unterstützte Protokoll und speichert das Protokoll, das tatsächlich funktioniert. Die normale Abfrage bleibt dann auf diesem bekannten Protokoll. Der vollständige Lebenszyklus ist unter Lokale Navigator-Weboberfläche beschrieben.

Einrichtungsprüfung und Fehlermeldungen

Der Einrichtungs- und der Rekonfigurations-Flow lesen ein bekanntes IDM-Register. Schlägt das fehl, trennt eine kurze DNS-/TCP-Prüfung Netzwerkprobleme von einem erreichbaren Endpunkt, der keine nutzbaren Modbus-Daten liefert. So kann Home Assistant eine hilfreichere Ursache nennen, statt einen allgemeinen Verbindungsfehler zu melden:

Das Protokoll enthält Host, Port, Slave-ID, Fehlerklasse und die empfohlenen Prüfungen. PIN-Werte werden niemals ins Protokoll geschrieben.

Die gespeicherte Verbindung später testen

Öffne Einstellungen → Geräte & Dienste → IDM Heatpump → Neu konfigurieren → Aktuelle Verbindung testen. Der Test prüft den gespeicherten Modbus-Endpunkt und, wenn ein lokaler Web-PIN konfiguriert ist, den Web-Endpunkt des Navigators. Er ist rein lesend: Es werden keine Einstellungen gespeichert und keine Wärmepumpen-Register geschrieben. Nach der Korrektur einer Netzwerk- oder Controller-Einstellung kann das Ergebnis erneut abgesendet werden, um den Test zu wiederholen.

Deinstallation

1. Öffne Einstellungen → Geräte & Dienste
2. Finde die Integration IDM Heatpump
3. Klicke auf die drei Punkte → Löschen
4. (Optional) Lösche den Ordner custom_components/idm_heatpump/
5. Starte Home Assistant neu

Aktualisierung

Über den Marketplace (Home Assistant 2026.11+) oder HACS (bis 2026.10): Öffne den IDM-Heatpump-Eintrag und wähle Update, danach Home Assistant neu starten. Neue Versionen erscheinen zusätzlich als Update-Entität im Aktualisierungen-Panel von Home Assistant.

Manuell: Wiederhole die manuelle Installation (überschreibt die alten Dateien).

Automatische externe Leistungsweiterleitung von Home Assistant

Öffne nach der Installation der Integration den IDM-Heatpump-Eintrag und wähle Neu konfigurieren → Funktionen → Externe Leistungsweiterleitung. Beim Aktivieren der Weiterleitung öffnet sich die Sensor-Zuordnungsseite. Jedes Feld bietet eine durchsuchbare Liste vorhandener Home-Assistant-Sensor-Entitäten:

• PV-Überschuss → IDM pv_surplus (Register 74–75)
• PV-Produktion → pv_production (78–79)
• Hausverbrauch → house_consumption (82–83)
• Batterie Laden/Entladen → battery_discharge (84–85)
• Batterie-Ladezustand → battery_soc (86)
• Leistung Elektro-Heizstab → electric_heater_power (76–77)
• Bidirektionaler Netzleistungszähler → leitet pv_surplus (74–75) ab; mit PV-Produktionssensor auch house_consumption (82–83)

Leistungssensoren müssen W, kW oder MW liefern; die Werte werden vor dem Schreiben nach kW umgerechnet. Der Batterie-Ladezustand muss ein endlicher Prozentsatz von 0 bis 100 sein; Nachkommastellen werden gerundet. Ungültiger SOC wird übersprungen und nicht als Ersatzwert weitergeleitet. Nutzt der Energiemanager die openWB-Vorzeichenkonvention (negativ bedeutet Entladen), wähle Quellvorzeichen invertieren. Nicht verfügbare oder ungültige Sensoren werden übersprungen; die Integration schreibt niemals null als Ersatz.

Wenn eine Batterie genutzt wird, verlangt der IDM-Support, dass Register 84 (battery_discharge, Batterie Laden/Entladen) zusammen mit dem Batterie-SOC (Register 86) geschrieben wird. Nur den SOC zuzuordnen reicht nicht und kann dazu führen, dass die Batteriezeilen flackern oder verschwinden; siehe #493. Positive Werte bedeuten Entladen, negative Werte Laden. Bei zwei getrennten Batterien die Summe ihrer vorzeichenbehafteten Leistungswerte in derselben Einheit und Vorzeichenkonvention weiterleiten. Nutzt der Helper positiv für Laden, die Vorzeichenumkehr der Integration aktivieren.

Ein bidirektionaler Netzleistungszähler lässt sich direkt auswählen (#519): Lege seine Vorzeichenkonvention fest (positiv = Netzbezug oder positiv = Einspeisung); die Integration normalisiert das Vorzeichen und leitet den signierten pv_surplus ab, zusammen mit dem PV-Produktionssensor auch den Hausverbrauch einschließlich gemappter Batterieleistung (Laden zählt negativ). Explizit gewählte Überschuss- und Verbrauchssensoren haben Vorrang vor der Ableitung, der Netzleistungszähler allein wird nie als Hausverbrauch geschrieben, und eine Zuordnung, für den keine Ableitung übrig bleibt, wird abgelehnt. Details unter Smart Energy & Comfort.

Wichtige Zuständigkeitsregel

Nur ein System sollte ein bestimmtes IDM-GLT/PV-Register aktiv schreiben. Aktiviere diese Weiterleitung nicht für ein Register, das auch von SMARTFOX, openWB oder einem anderen Energiemanager geschrieben wird. Andernfalls gewinnt der letzte Schreiber, und die Werte können pendeln.

IDM Navigator vorbereiten

1. Öffne am Navigator/Controller die Gebäudeleittechnik (GLT).
2. Aktiviere Modbus TCP und verwende Port 502. Die normale Modbus-Slave-/Unit-ID ist 1.
3. Die vom installierten System benötigten GLT-/Energiemanager-Eingangsregister werden auf der Installateur-Ebene des Reglers freigegeben: Lass die GLT-/PV-Funktion von deinem Heizungsinstallateur aktivieren — die Integration schaltet sie nie frei. Manche Navigator-Generationen zeigen eine separate GLT/PV- oder Energiemanager-Berechtigung; die genaue Bezeichnung und Zugriffsebene hängen von Firmware und Installateur-Einstellungen ab.
4. Speichere die Einstellung und starte den Controller nur neu, wenn der Navigator es verlangt.
5. Konfiguriere die Home-Assistant-Optionen und prüfe die Werte – falls vorhanden – im GLT-/Energiemanager-Monitor des Navigators.

Wenn das Menü fehlt oder gesperrt ist, bitte den Heizungsinstallateur oder den iDM-Service, die GLT-/Modbus-TCP-Funktion zu aktivieren. Die SMARTFOX- und openWB-Dokumentation bestätigt, dass diese Werte für eine Energiemanager-/GLT- Schnittstelle bestimmt sind, der genaue Aktivierungsweg hängt aber von Installation und Firmware ab.