Configuration

Connection Parameters

Leave the web PIN empty if you want Modbus-only operation. Modbus remains the baseline path and works without a PIN. Providing a PIN also enables the setup flow to offer a limited web-only fallback when Modbus is unavailable.

The local Modbus transport uses modbus-connection with the tmodbus backend. Entries use Home Assistant's shared connection when its unit API is available; a failed shared claim falls back to a private socket. See connection diagnostics.

Options

After entering the connection details, choose a guided setup depth:

Each depth offers the same set of functions. Select only the functions you want to change; each selected function opens a short page for its switch and any needed sensor, circuit or group mapping. A final confirmation saves the configuration and reloads the entry. Settings from a deeper mode remain saved when you later choose a simpler mode. You can switch depth at any time through Reconfigure (in the row's ⋮ menu) > Features. Reconfigure > Connection changes the host, web access and Modbus proxy. Existing options remain in place if their function was not selected in the wizard.

When newly enabling beta features, an additional acknowledgement page appears before saving. It is separate from the ownership confirmation required by the automatic DHW manager and comfort schedule.

Differential-temperature controlled circuits

Available in the current stable integration; hardware-specific limits below still apply.

For a circuit whose heating system is already set to Differential temperature control in the Navigator, Home Assistant can display storage and reference temperatures, their signed difference and the circuit status. This is useful for installations such as a wood-stove circuit connected to a storage tank.

1. In initial setup, select Plant in the guided feature selection. For an existing entry, use Configure → Plant or Reconfigure → Features → Plant.
2. Keep the circuit selected under Heating circuits, then also select it under Differential-temperature controlled circuits. The advanced options form offers the same selection beside the installed heating circuits.
3. Save and let the integration reload. Check the storage/reference measurements against your controller. The difference is reference minus storage, in K.

The selection is empty by default and works in both feature profiles. With a configured web PIN on a Navigator 10, differential circuits are detected automatically: every web poll evaluates the controller's system/overview frame, which lists each heating circuit with its regulation type on the plain end-user level. The manual selection stays authoritative — it covers installations without the web supplement and overrides the detection. The selection changes the Home Assistant representation, not the controller's heating system, and is separate from the Navigator's internal differential-control module.

Normal heating controls and climate entities are removed for selected circuits; review dashboards and automations using those controls before saving. The two temperature sensors keep their existing entity IDs. Switching back restores normal controls, but customizations of removed controls are not preserved. Hysteresis, thresholds and maximum-temperature settings are not exposed because their registers are unverified. A follow-up review for 0.21.1 found no confirmed parameter mapping in the API catalog or the available Modbus table. In particular, hc_d_setpoint_flow_constant is documented as the constant-flow setpoint; an equal observed value does not prove it is the differential threshold. The mapping follows the Navigator 10 report in issue #429 and still needs confirmation on differential-control hardware. See entities, status meanings and migration details.

Feature profile

The Feature profile controls optional IDM-specific entities:

The Smart profile is enabled by default to preserve the complete existing integration behavior. Vanilla is useful when only the original controller values and controls should be exposed. Switching profiles reloads the entry; optional entities may be removed or recreated, while core entity IDs remain unchanged.

The profile does not automatically write energy values or modify the heating curve. External PV, battery, room-temperature, humidity and storage forwarding remain separate opt-in functions and are documented in their own sections.

Smart also exposes persistent energy, COP, cost, CO₂ and optional PV self-consumption statistics when the required power registers are available. The electricity price and CO₂ factor are configured locally in the options; they are not fetched from an external service.

When Device hierarchy is enabled, optional entities are kept in their own logical groups: iDM Analytics, iDM Health Monitor, and iDM Comfort. Existing controller, heating-circuit, warm-water and web entities remain in their existing groups and retain their entity IDs.

External power source mapping and forwarding

When using ModBridge or another Modbus proxy, the Modbus host/port must name its listener, while the web host must name the actual Navigator. For example, a proxy listener on 192.0.2.10:5020 can forward to a Navigator on 192.0.2.20:502, with the web supplement using 192.0.2.20. A port such as 5020 is not inherently incorrect; use the configured proxy route. Connection failures require checking that route and its availability, not register access permissions. The write warning clears after a successful write to its own register. Success on a different register does not dismiss it.

The external-power selectors support clearing an existing source. Remove a selection and save to stop that register's automatic forwarding; remaining selected sources stay configured. Removing battery SOC also removes the optional HA energy-manager SOC condition. No fallback register value is written. Fractional SOC percentages are accepted and rounded for the integer GLT input.

The External power forwarding category maps existing Home Assistant sensors to PV surplus, PV production, house consumption, battery charge/discharge, battery SOC and electric-heater power. The forwarding switch is off by default. When enabled, valid values are written to the corresponding IDM GLT registers on source changes and with a nominal three-second cyclic refresh, including unchanged values. This refresh takes precedence over the configurable 30–3600-second interval (default: 60 seconds); actual completion times depend on connection load and write cooldowns.

Power sensors must report W, kW or MW; forwarding converts to kW. Battery SOC must be a finite percentage from 0 to 100; fractional values are rounded for GLT. The battery sign can be kept or inverted to match the source convention. Invalid or out-of-range values are skipped; an unavailable source does not write a fallback zero. Blank fields leave their registers untouched. Do not have another energy manager write the same register at the same time.

When a battery is used, also map battery charge/discharge so register 84 is written together with battery SoC (register 86). IDM support confirmed this requirement; writing SoC alone is not sufficient (#493).

The saved mapping also supplies the optional PV estimate and automatic DHW manager. They can read an existing mapping while forwarding is off. The current guided wizard shows the mapping page only when forwarding is enabled; it does not yet provide a separate source-selection page for read-only use. See external power setup for controller preparation and field mappings. For a battery-connected SolarEdge inverter with additional inverters, see the GLT recipe and template generator.

Optional workaround for PV message 20300 at zero production

Some Navigator controllers report 20300: PV not connected at night or in low light even while valid zero-production values are repeatedly written successfully over GLT. A controlled series on 2026-11-10 on a Navigator 10 with firmware T_NAV10_20.24-1580-g02a20b66f established the mechanism: the controller flags a frozen pv_production value — after roughly ten minutes without a register change, message 20300 latches regardless of the level (10 W, 20 W and 50 W static all latched), while any value change — up or down, 10 W or 50 W — clears it within seconds. There is no wattage threshold; a constant substitute of any size therefore cannot keep the message away.

For an affected plant, open Settings → Devices & services → IDM Heatpump → Configure, or Reconfigure → Features. In the guided feature settings, enable external power forwarding and open its sensor mapping page. Enable PV zero-power workaround and save the remaining wizard steps. The same checkbox is available during initial setup. It is off by default.

With the workaround on, a valid PV-production source that rounds to the register's 10 W resolution — anything below 5 W, positive like a dusk value of 3 W or negative like a small inverter standby reading — is transmitted as an alternating 10 W / 20 W heartbeat: the substitute changes every minute, so the register never freezes long enough to latch the message (the longest verified frozen stretch without a latch is 127 seconds). As soon as the source reports 5 W or more, forwarding uses its live value again with the usual GLT rounding. Unavailable, invalid or unmapped sources are not replaced. PV surplus, battery values, household balance calculations and the original HA source sensor are unchanged; the heartbeat does not create a fake surplus signal. The controller and its PV-derived displays/statistics see an artificial nightly production averaging 15 W. Do not use this to hide a real communication failure. Disable the checkbox to restore ordinary zero forwarding; no controller firmware modification is made.

Optional PV energy manager

The automatic PV surplus DHW charging option is off by default. It only starts the existing safe DHW boost when the selected PV surplus is available. It requires the external power source mapping and the explicit confirmation that Home Assistant is the only DHW controller. This is an ownership declaration, not automatic detection of Smartfox, openWB or another controller. Disable competing DHW control before confirming it.

Missing, unavailable or invalid source values fail closed. The manager does not write GLT energy registers and does not alter normal heating, the heating curve or the electric heater. Tariff, weather and heating preheat controls are not enabled by this option. A selected tariff sensor changes cost accounting only; automatic price-based heating control is not implemented. See Smart Energy & Comfort for source precedence, defaults and the behavior of an already running boost.

Optional comfort schedule and advisers

The comfort schedule is disabled by default and requires the explicit single-controller confirmation. It writes only the selected circuit's room temperature target inside the configured daily window and restores the prior target afterwards if the current value still matches the scheduled target. A manual change made while the schedule is active is left untouched. Advanced mode offers up to 16 daily windows across configured circuits, including overnight windows, in Home Assistant's configured timezone. See schedule examples.

The heating-curve assistant and weather-preheat adviser are read-only. They publish recommendations without changing any IDM register. The weather adviser requires a selected Home Assistant weather entity. All comfort entities are shown under iDM Comfort when device hierarchy is enabled.

Optional iDM Health Monitor

The iDM Health Monitor is disabled by default and adds read-only diagnostic entities. It checks communication failures, compressor start frequency, low current COP, DHW temperature deviation and implausible temperature values. The iDM health report sensor exposes ok or problem and lists active checks in its attributes. It does not change any heat-pump setting.

Predictive Advisor

The Predictive Advisor is a strictly read-only analysis and recommendation layer, on by default with the Smart profile. It explains why the heat pump is running, detects anomalies against the plant's own baselines, scores health and efficiency, learns a COP map and building model, and recommends heating-curve steps, hot-water windows and a 24-hour plan. Details: Predictive Advisor.

The advisor works fully local and deterministic — no AI, cloud or LLM. The price sensor and the weather entity are additionally used by the energy statistics and the weather advice.

Scan Interval

The scan interval determines how often registers are polled.

Web Supplement Data

The integration can optionally read additional local Navigator web data through idm-heatpump-api. This is read-only and additive. It is used for values such as Navigator generation, software version, selected Web UI diagnostics, and Navigator 10 infosystem notifications. (The heat pump model is an attribute of the Navigator version (Web) sensor where the firmware reports it — see Entities.)

Important behavior:

• If no PIN is configured, no web client is created and the integration stays in Modbus-only mode.
• During setup, reconfiguration and repair, the Modbus model is used only to choose which local web protocol to try first. If that attempt fails, the other supported protocol is also tested. The protocol that actually succeeds is stored with the config entry.
• During normal polling, the successful authenticated client is reused. If its session expires or the connection fails, the client is closed and the same known protocol is rebuilt immediately. The other Navigator generation is not probed during routine runtime recovery.
• After replacing the Navigator, changing the web endpoint or making a firmware change that alters the local interface, run Reconfigure → Change connection settings so protocol detection can run again.
• If the PIN is wrong during setup or reconfiguration, the form shows the PIN error immediately. After a Modbus failure, the PIN can be corrected directly in the recovery form without restarting setup.
• If the web interface is unreachable later, Modbus polling continues.
• Web polling runs separately and starts slightly after Modbus polling so both protocols do not hit the controller at the exact same moment.
• Modbus register values always have priority. Web sensors are only created for extra values or values without an existing Modbus entity. Web model/firmware metadata may complete an unknown Modbus result, but a definite family conflict is ignored.
• If a Modbus proxy is used, enter the proxy IP as Host and the original heat pump IP as Web host so the local Navigator web interface can still be reached.

Navigator 2.0 uses a local HTTP/CSRF login; Navigator 10 and Navigator Pro use the Navigator-10 WebSocket login family. See Local Navigator Web Interface for the complete detection and recovery state machine.

Room Temperature Forwarding

Room temperature forwarding is optional and disabled by default. When enabled, the integration can forward selected Home Assistant temperature sensors to the IDM external room temperature registers of the active heating circuits, for example hc_a_ext_room_temp.

Important behavior:

• Values are written on sensor state changes and also refreshed periodically.
• Invalid, unavailable, non-numeric or out-of-range values are skipped.
• Leaving a circuit without a selected sensor keeps that circuit untouched.
• This feature writes Modbus values. Use sensors that represent the actual room temperature you want the heat pump to see.

External Humidity Forwarding

External humidity forwarding is optional and disabled by default. When enabled, the integration forwards one selected Home Assistant humidity sensor to the global IDM GLT humidity register (ext_humidity). Unlike room temperature, humidity has no per-heating-circuit register, so only a single sensor can be selected.

The same behavior notes as room temperature forwarding apply: values are written on state changes and refreshed periodically, invalid or out-of-range values are skipped, and leaving the sensor field empty disables forwarding.

External Storage Temperature Forwarding

External storage temperature forwarding is optional and disabled by default. When enabled, the integration forwards up to four selected Home Assistant temperature sensors to the fixed IDM GLT storage registers: heat storage (glt_heat_storage_temp), cold storage (glt_cold_storage_temp), and DHW storage bottom/top (glt_dhw_temp_bottom / glt_dhw_temp_top).

The same behavior notes as room temperature forwarding apply: values are written on state changes and refreshed periodically, invalid or out-of-range values are skipped, and leaving a register's field empty keeps it untouched.

External Power Forwarding

External power forwarding is optional and disabled by default. When enabled, the integration forwards selected Home Assistant power and battery sensors — or a bidirectional grid meter together with PV production — to the IDM GLT power registers (pv_surplus, pv_production, house_consumption, battery_discharge, battery_fill_level).

Important behavior:

• When a bidirectional Grid meter sensor and PV production sensor are configured, the integration automatically derives pv_surplus and house_consumption when their direct sensor fields are left empty (#519).
• When a battery is used, map battery charge/discharge as well as battery SoC so register 84 is written together with register 86. IDM support requires that write; see external power setup and #493.
• Forwarded values are written to the controller's GLT input registers (for example register 74 pv_surplus and register 82 house_consumption). In Home Assistant, the writable GLT input registers appear as number entities with the (setpoint) / (Vorgabe) suffix (disabled by default in the entity registry), whereas the read-only sensor entities without that suffix display what the controller reports back. Enable the corresponding number entity in Home Assistant if you want to inspect the exact GLT value written by forwarding.

External-power GLT sensors are created even when their first supported readback is an unset sentinel. They report unavailable until a valid readback arrives, then recover without a reload. The writable Number remains available with an unknown value while unset. This does not depend on automatic forwarding being enabled. Absent or unsupported registers remain filtered. Disabling forwarding stops writes; it does not reset the controller input or guarantee its retention.

KNX Bridge

The KNX bridge is optional and disabled by default. When enabled, the integration publishes the IDM KNX communication objects on a KNX bus and accepts commands from it — replacing the Weinzierl KNX IP BAOS gateway module IDM sells for the Navigator. It drives the Home Assistant KNX integration, which must be set up: gateway, tunnelling and KNX Secure come from there.

Group addresses are derived as base address + IDM object number, so with the default base object 1 (outdoor temperature) lands on 8/0/1 and object 222 (heating circuit A mode) on 8/0/222. The whole catalogue fits inside one main group. Use idm_heatpump.export_knx_group_addresses to get the full table for your controller.

Full details, including the object groups and datapoint types, are in KNX Bridge.

Heating Circuits

Select the active heating circuits (A through G). Only enabled circuits create entities in Home Assistant.

Zones

Specify the number of zone modules (0–10) and the active rooms per module. The integration supports up to 8 rooms per zone; 6 is the API default for current Navigator 10 hardware. Configure only physically present rooms to avoid unnecessary individual room-mode validation traffic.

Room Names

For each room in each zone, you can assign a custom name. These names are used as entity names in Home Assistant.

Reconfiguration

Where these buttons live: current Home Assistant versions show no labeled Configure button anymore — the options dialog opens with the gear icon (⚙) at the right end of your entry's row under Settings → Devices & Services → IDM Heatpump. The labeled Reconfigure item sits in the three-dot menu (⋮) of that row and opens the connection wizard, whose Configure features action leads to the same options. While the entry shows an error state the gear icon is hidden — use the Reconfigure menu in that case.

1. Go to Settings → Devices & Services
2. Click IDM Heatpump
3. Open the three-dot menu (⋮) of your entry's row and click Reconfigure
4. Choose the action you need:
   • Features opens Standard, Advanced or Expert setup to change selected feature settings without changing unselected categories.
   • Change connection settings updates host, port, slave ID, local web PIN, and proxy settings after validating them.
   • Test current connection runs a read-only check against the saved settings. It does not save anything and never writes Modbus registers.

flowchart TD
    reconf["IDM Heatpump → Reconfigure<br/>(Connection and diagnostics)"] --> choice{"Choose an action"}
    choice -- "Change connection settings" --> conn["Host, port, slave ID, web PIN,<br/>proxy — validated on submit"]
    conn --> ctest{"Validation"}
    ctest -- "Modbus fails,<br/>web PIN valid" --> wofallback{"Web-only fallback offered"}
    wofallback -- "accept" --> webonly["Web-only mode; existing circuits, zones<br/>and advanced options stay preserved"]
    wofallback -- "retry Modbus" --> conn
    ctest -- "ok" --> applied["Entry reloaded with the new settings"]
    webonly --> applied
    choice -- "Configure features" --> guided["Guided feature editor — the same steps<br/>as setup, without touching the connection"]
    guided --> applied
    choice -- "Test current connection" --> diag["Read-only diagnostics: DNS/TCP,<br/>a known IDM register, optional web endpoint.<br/>Nothing is saved or written"]
    diag --> result{"Result"}
    result -- "ok" --> okmsg["Success confirmed"]
    result -- "error" --> errmsg["Named cause + recommended checks;<br/>resubmit the form to repeat the test"]
    result -.-> diag

The test reads a known IDM Modbus register. If that fails, a short DNS/TCP check identifies the network failure more precisely. If a local web PIN is configured, it also verifies the Navigator web endpoint and authentication. The result distinguishes hostname, refused connection, timeout, unreachable endpoint, missing Modbus response, invalid PIN, and web interface errors. Submit the result form again to repeat the test.

A wrong web PIN is rejected directly when changing the connection. Leaving it empty keeps the entry in Modbus-only mode.

If Modbus fails while a valid web PIN is present, the flow offers web-only mode and clearly lists its limitations. Choosing Retry Modbus connection returns to the correct reconfiguration form; switching back from web-only mode clears the fallback flag after a successful Modbus check. Existing heating-circuit, zone and advanced Modbus options are preserved while web-only mode is active, so they are available again after Modbus is restored.

Use Configure (the gear icon on the entry row) or Reconfigure → Configure features to edit the complete options form, including scan interval, circuits, zones, Smart Energy & Comfort, health monitoring, forwarding, and automatic controls. Saving reloads the integration so optional entities follow the selected settings. Newly enabled beta features require an explicit acknowledgement before saving.

Advanced Modbus options

The collapsed Advanced Modbus settings section also provides power-user controls in addition to timeout and retry settings:

• Pause between requests (0–0.5 seconds) is the minimum gap the connection keeps between two Modbus requests, measured from the end of one request to the start of the next. 0 s (the default) sends requests back-to-back, as every release before this option did. Raise it when the controller or a Modbus gateway answers "device busy", drops requests, or times out under a dense request stream. The pause applies to every request, so a full polling cycle takes correspondingly longer: with roughly 40 batches, 0.1 s adds about 4 seconds per cycle. Start at 0.05 s.
• Pause after connect (0–5 seconds) is awaited once after the link is established, before the first request is sent — on the first connect and on every reconnect, not per request. 0 s (the default) sends immediately. Raise it for gateways that accept a connection before they are ready to answer.
• Polling jitter (0–20%) adds a random delay of up to the selected percentage of the scan interval to every poll. This spreads network and controller load when several heat pumps start polling at the same time. 0% disables jitter.
• Extended communication diagnostics creates diagnostic entities for the last successful poll, poll duration, consecutive failures, and the active register count. Total polls and failures are included as attributes and in downloaded diagnostics.
• Write cooldown (0–600 seconds) applies per register. A second write to the same register during the configured interval is rejected without sending anything to the heat pump, and Home Assistant reports the remaining wait. 0 completely disables this protection; changing it is at the user's own risk. Different register addresses do not block one another.

The general write cooldown is independent of the API's EEPROM protection. EEPROM-sensitive registers can therefore still be subject to the separately configured EEPROM interval and its safety rules.

Connection mode

The first field of the advanced section selects which data paths the entry may use:

• Automatic (recommended) keeps the historical behaviour: Modbus for registers and all writes, the local web supplement for additional values when a web PIN is configured, and the web-only setup fallback when Modbus is unreachable while a valid PIN exists.
• Modbus + web supplement pins both paths on and disables the web-only setup fallback: a failing Modbus connection retries instead of degrading to web-only.
• Web only runs the entry entirely through the local web interface — setup does not attempt a Modbus connection. On a Navigator 10 the operating mode and error acknowledgement are controlled through the web interface (same numbering as Modbus, validated before sending); setpoints and further controls still require Modbus. It needs a configured web PIN and is available on Navigator 10/Pro (WebSocket) and Navigator 2.0 (HTTP) web interfaces — the web controls need the WebSocket variant.
• Modbus only never contacts the web interface, even with a PIN configured; the web entities are not created for this entry.

The selection survives reload. An explicit mode overrides the legacy web-only flag that the setup fallback once wrote, so choosing Modbus + web supplement restores full Modbus operation on such an entry. The diagnostics export reports the active mode in its connection block together with the detected controller family, the firmware version and whether a web PIN is configured (presence only).

Runtime and API versions

IDM Heatpump is a Home Assistant custom integration rather than an add-on. The integration creates a diagnostic sensor named IDM Heatpump API version (German: IDM-Heatpump-API-Version). Its state is the actually installed idm-heatpump-api distribution version. The sensor attributes also show:

• integration_version: installed custom integration version
• modbus_connection_version: installed connection-library version
• tmodbus_version: installed direct socket-backend version
• home_assistant_version: installed Home Assistant Core version
• python_version: Python runtime version

The same version set is included in downloaded diagnostics. The integration and its direct dependency versions are also logged when the entry starts. This is the authoritative way to check the runtime; the version pinned in custom_components/idm_heatpump/manifest.json describes what should be installed, while the sensor shows what is actually loaded.

Integration and API release pairing

This project has two independently versioned packages:

The manifest lists the tested runtime in this order: modbus-connection>=4.12.7, tmodbus[async-serial]>=0.6.2, and idm-heatpump-api[web]==2.16.2. The first two packages own the direct socket. idm-heatpump-api remains responsible for IDM-specific device logic and owns its exception hierarchy; the integration no longer installs pymodbus. 4.12.7 is the version of modbus-connection, not an IDM integration version. The transport was first shipped by IDM integration beta 0.11.0-beta.1.

The adapter is implemented, covered by automated tests and live-verified on a Navigator 10. Its redacted diagnostics report the active transport source. On Home Assistant 2026.10 and newer every config entry claims Home Assistant's central shared Modbus connection: diagnostics then report source: homeassistant.modbus, owns_socket: false and supports_shared_connection: true, several entries on one controller share a single socket, and the configured Modbus timeout is negotiated onto the shared link. On older releases — and whenever the shared claim cannot be established — diagnostics report source: modbus_connection.tmodbus, owns_socket: true and supports_shared_connection: false, meaning one private socket per config entry. Navigator 2.0/Pro coverage and an intentional connection-loss/reconnect test remain open; real-hardware writes stay out of scope unless explicitly authorized. IDM Heatpump is a custom integration, not a Home Assistant add-on.

Assist (text and voice)

The integration ships a local Assist agent (entity Assistant under the heat pump device). Select it under Settings → Devices & Services → Assist as the preferred agent — or address it explicitly — and ask in German or English:

• "Why is the heat pump running?" — answered by the operation-reason composer: operating mode, power draw, temperatures and the controller's own demand reason when the web supplement supplies it.
• "Any recommendation?" — the top read-only predictive-advisor recommendations.
• "How is the hot water?", "What are the temperatures?", "What is the consumption?", "What is the status?".

Every answer is composed locally from the current coordinator snapshot by deterministic keyword routing. No utterance leaves the instance and no language model is involved.

Shared evidence in Assist

The local agent also answers questions such as "What changed?", "Did consumption increase?", "How did cycling develop?", "Which evidence is missing?" and "Did the change help?" using the bounded history shared by reports and Predictive Advisor. It identifies missing or incomparable data. Observed associations do not prove causality or savings. See shared evidence and optimization review.

Debug Logging

Enable extended logging for troubleshooting:

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

EEPROM Notice

Certain registers are EEPROM-sensitive (88 total). These registers are stored in EEPROM when written and have a limited number of write cycles. The integration warns about excessive writing of these registers.

BMS Cyclic Writing

Registers 1696 and 1698 (BMS temperature requests) must be written cyclically every 10 minutes to remain active. The switch entities for BMS requests handle this automatically.

Experimental AI adviser

The optional, read-only adviser creates daily and weekly reports, plant checks and efficiency reviews. Local measured-data reports without model calls are the default. Free-form explanations through Ollama, an HA AI Task entity or a separately consented cloud provider can be enabled additionally. Reports never control the plant. See setup, actions, data coverage and limits.