Installation & Setup

Requirements

• Home Assistant 2026.8.1 or newer
• HACS (Installation guide)
• IDM Navigator 2.0 / 10 / Pro heat pump with Modbus TCP enabled
• Modbus TCP must be enabled in the Navigator controller (Port 502, Slave ID 1)

Installation via HACS (recommended)

1. Open HACS in Home Assistant
2. Go to Integrations
3. Click ⋮ (Three Dots) → Custom Repositories
4. Enter the URL: https://github.com/Xerolux/idm-heatpump-hass
5. Select Category: Integration
6. Click Add
7. Search for "IDM Heatpump"
8. Click Download
9. Restart Home Assistant

Choosing stable or beta

The latest stable release is the normal installation channel. The new guided setup and Smart Energy & Comfort features described in this wiki are available in 0.17.2-b6 beta.

To try the beta, open the IDM Heatpump repository in HACS, use its version selection/download action, enable prerelease versions if needed and select 0.17.2-b6. Back up Home Assistant before upgrading and restart Home Assistant after downloading. A newer documentation page does not update the installed integration automatically. Confirm the installed version in the integration's diagnostics before looking for the new options.

Beta fixes have automated regression coverage. They are not a claim of completed long-term or all-model hardware validation. See Stability & Release Readiness.

Manual Installation

1. Download the latest release (idm_heatpump.zip)
2. Create the idm_heatpump directory under custom_components/ if needed
3. Extract the ZIP contents directly into that directory; manifest.json must be immediately inside it, without another nested idm_heatpump directory:

   <ha-config>/custom_components/idm_heatpump/
   

4. Restart Home Assistant

Enable Modbus TCP on the IDM heat pump

Required: Full integration operation is only possible when Modbus TCP is enabled on the IDM Navigator/controller. Installing the Home Assistant integration cannot enable this controller setting remotely.

The official iDM documentation describes the relevant Navigator setting as Building management system / Gebäudeleittechnik → Modbus TCP → On / Ein. A practical setup sequence is:

1. Open the local IDM Navigator/controller display.
2. Sign in to installer/technician level if the controller requires it.
3. Open Building management system (German: Gebäudeleittechnik).
4. Set Modbus TCP to On / Enabled (German: Ein / Aktiv).
5. Save the setting. Restart the Navigator/controller if the interface does not become available immediately.
6. Connect the Navigator to the local Ethernet network and note its IP address.
7. Use TCP port 502 and normally slave/unit ID 1 in this integration.

Menu names and permissions can differ between Navigator 2.0, Navigator 10, Navigator Pro and firmware versions. If Gebäudeleittechnik or Modbus TCP is missing, read-only, or locked, ask your heating installer or iDM service to enable the interface. Do not change unrelated heating or safety parameters.

The required setting belongs to the IDM heat pump/Navigator. A Modbus TCP option on a PV inverter is a separate interface and does not enable Home Assistant access to the heat pump.

Network checklist:

• Home Assistant and the Navigator must be able to reach each other locally.
• Prefer wired Ethernet; do not expose port 502 to the internet.
• Reserve the Navigator IP in the router or configure it consistently so it does not unexpectedly change.
• Test the address from Home Assistant's network, not only from a phone on a different Wi-Fi/VLAN.

Source: official iDM technical documentation (PDF), which specifies that Modbus TCP must be On in the Navigator's Gebäudeleittechnik menu; iDM also documents TCP port 502 for Navigator Modbus communication in its technical PV/GLT documentation.

Setup

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for "IDM Heatpump"
4. Follow the configuration wizard:
   • Prerequisite shown in the flow: Confirm that Navigator Building management system → Modbus TCP is enabled
   • Connection: Enter a name, the heat pump IP/hostname, port 502, and slave ID 1
   • Optional web access: Enter the local Navigator web PIN; when using a Modbus proxy, also enable the proxy option and enter the original heat pump address as web host
   • Setup depth: Choose Standard, Advanced or Expert; these control detail, not which features are available
   • Features: Select the categories you want to configure, such as plant, Smart/Vanilla profile, energy, Health Monitor or comfort
   • Feature pages: Supply the requested sensors, circuit mappings and optional settings; review the ownership confirmation before enabling an automatic write feature
   • Zones: Configure the number of active rooms for each selected zone module
5. Review and confirm the configuration to finish. See Configuration for changing the setup depth later.

Local Navigator web PIN (not cloud 2FA)

The optional web PIN is the local network code configured on the Navigator display. It is separate from the myIDM app/cloud account, its password and two-factor authentication.

On a German Navigator 2.0 display, configure it under:

Einstellungen → Allgemeine Einstellungen → Netzwerkeinstellungen → Code lokales Netzwerk

Menu wording can vary by Navigator generation and firmware. An empty value or 0 disables the local web interface. Entering cloud credentials or a temporary two-factor code in Home Assistant will therefore be rejected.

Navigator 2.0 uses a local HTTP login with a CSRF token. Navigator 10 and Navigator Pro use the Navigator-10 WebSocket login family. Setup uses the Modbus-detected model only to choose the first attempt, tries the other supported protocol if necessary and stores the protocol that actually works. Normal polling then stays on that known protocol. See Local Navigator Web Interface for the complete lifecycle.

Setup validation and error messages

The setup and reconfigure flows read a known IDM register. If that fails, a short DNS/TCP check separates network failures from a reachable endpoint that does not provide usable Modbus data. This allows Home Assistant to provide a more useful cause instead of a generic connection error:

The logs include host, port, slave ID, error class, and the recommended checks. PIN values are never written to the log.

Test the saved connection later

Open Settings → Devices & Services → IDM Heatpump → Reconfigure → Test current connection. The test checks the saved Modbus endpoint and, when a local web PIN is configured, the Navigator web endpoint. It is read-only: no settings are saved and no heat-pump registers are written. The result can be submitted again to repeat the test after correcting a network or controller setting.

Uninstallation

1. Go to Settings → Devices & Services
2. Find the IDM Heatpump integration
3. Click the three dots → Delete
4. (Optional) Delete the custom_components/idm_heatpump/ folder
5. Restart Home Assistant

Upgrade

Via HACS: Go to HACS → Integrations → IDM Heatpump → "Update" → Restart HA.

Manually: Repeat the manual installation (overwrites the old files).

Automatic external power forwarding from Home Assistant

After the integration is installed, open the IDM Heatpump entry and choose Reconfigure → Features → External power forwarding. Enabling forwarding opens the sensor mapping page. Each field offers a searchable list of existing Home Assistant sensor entities:

• PV surplus → IDM pv_surplus (registers 74–75)
• PV production → pv_production (78–79)
• House consumption → house_consumption (82–83)
• Battery charge/discharge → battery_discharge (84–85)
• Battery state of charge → battery_soc (86)
• Electric heater power → electric_heater_power (76–77)

Power sensors must expose W or kW; values are converted to kW before writing. Battery SOC is a whole percentage from 0 to 100; -1 means no battery. If the energy manager uses the openWB sign convention (negative means discharge), choose Invert source sign. Unavailable or invalid sensors are skipped; the integration never writes zero as a fallback.

Important ownership rule

Only one system should actively write a given IDM GLT/PV register. Do not enable this forwarding for a register that is also written by SMARTFOX, openWB or another energy manager. Otherwise the last writer wins and values can oscillate.

IDM Navigator preparation

1. On the Navigator/controller, open BMS / Gebäudeleittechnik.
2. Enable Modbus TCP and use port 502. The normal Modbus slave/unit ID is 1.
3. Enable or release the GLT/energy-management input registers required by the installed system. Some Navigator generations show a separate GLT/PV or energy-manager permission; the exact wording and access level depend on firmware and installer settings.
4. Save the setting and restart the controller only if the Navigator requests it.
5. Configure the Home Assistant options and verify the values in the Navigator GLT/energy-manager monitor, if available.

If the menu is missing or locked, ask the heating installer or iDM service to enable the GLT/Modbus-TCP function. SMARTFOX and openWB documentation confirms that these values are intended for an energy-manager/GLT interface, but the exact activation path is installation- and firmware-dependent.