Troubleshooting

Smart features and beta upgrades

For a support request, use Download diagnostics on the IDM integration. It includes an installer report, runtime versions, polling failures and active health checks with connection secrets redacted. See Smart Energy & Comfort for configuration examples.

Connection Problems

Run the built-in connection test

Open Settings → Devices & Services → IDM Heatpump → Reconfigure → Test current connection. This performs a read-only test using the saved settings:

1. Read a known IDM Modbus register with the configured slave ID.
2. If that fails, run a short DNS/TCP check to identify the network cause.
3. If a local web PIN exists, verify the Navigator web endpoint and PIN.

The test neither changes the config entry nor writes to the heat pump. Its translated result identifies the failed stage, and submitting the result form runs the test again. The same categorized reason is written to the log without exposing the PIN.

"Hostname could not be resolved"

• Check the spelling of the configured hostname
• Verify that Home Assistant can use the same local DNS/mDNS server as your browser
• Reconfigure with the fixed IP address of the heat pump to rule out DNS problems

"Modbus TCP connection refused"

The target device actively rejected TCP. This is the strongest available indication that Modbus TCP is not enabled or that the wrong port was used.

• On the Navigator/controller, open Building management system (Gebäudeleittechnik) → Modbus TCP and set it to On / Ein
• This menu sits at the controller's installer level: ask your heating installer or iDM service to enable Modbus TCP — the integration never unlocks it and provides no access code. Once your installer confirms the setting is on, continue below
• Use TCP port 502 unless the controller or proxy was configured differently
• Restart the Navigator/controller after enabling Modbus if the setting does not become active immediately
• If a proxy is used, confirm that it listens on the entered host and port

This setting must be enabled on the heat pump/Navigator, not on a PV inverter. See Enable Modbus TCP on the IDM heat pump for the complete checklist and official iDM references.

"Modbus TCP connection timed out" or "endpoint is not reachable"

• Check the IP address of the IDM Navigator
• Verify that the controller is powered on
• Check whether a firewall, VLAN, subnet, or routing rule blocks port 502
• Ping the IP address: ping <ip-of-navigator>

Timeout means no answer arrived within five seconds. Unreachable means the operating system reported a network/routing failure.

Connection drops

• Check the network connection (LAN cable recommended)
• Increase the scan interval (e.g., to 30 seconds)
• Enable debug logging (see Configuration)
• The tmodbus-backed connection marks a dropped link as disconnected and reconnects on the next operation; the API retry/backoff policy remains in effect. If drops continue, check the stability of the local network or WiFi.

The integration uses Home Assistant's shared Modbus connection when its unit API is available: source: homeassistant.modbus, owns_socket: false, supports_shared_connection: true. If claiming it fails, diagnostics show source: modbus_connection.tmodbus, owns_socket: true and supports_shared_connection: false for the private fallback. Identify the active path before investigating parallel clients. Other independent Modbus clients can still add load to the controller.

"No valid IDM register response"

• Check the Slave ID (default: 1)
• Confirm that Modbus access is enabled or released for external clients
• Check if other Modbus clients are accessing the same port simultaneously
• Restart the IDM Navigator after enabling Modbus

This message means the TCP endpoint was reached, but the setup probe did not receive usable IDM register data. It is therefore different from a network or firewall failure.

Modbus is not available on the heat pump

Enter the local Navigator web PIN during setup. When authentication succeeds, select web_only (or allow auto to fall back). Navigator 10/Pro exposes web sensors and supported operating-mode, hot-water and heating-circuit controls, including error acknowledgement and climate/water-heater cards. Navigator 2.0 HTTP remains read-only. Raw register writes and one-shot DHW boost require Modbus; availability also depends on the controller's exposed web data. See Local Web Interface for the model-specific limits.

"Navigator web PIN rejected"

• Open Settings → Devices & Services → IDM Heatpump → Reconfigure → Change connection settings
• At the Navigator display, verify Settings → General settings → Network settings → Local network code (German: Einstellungen → Allgemeine Einstellungen → Netzwerkeinstellungen → Code lokales Netzwerk)
• Enter that local network code in Home Assistant
• Do not use a cloud/app password or a two-factor authentication code
• An empty local network code or 0 disables the Navigator's local web access
• Clear the PIN if you intentionally want Modbus-only operation

The runtime repair notification and log identify authentication failures separately from network failures. The repair action can verify a replacement PIN or disable optional web data. The PIN itself is never logged.

After a protocol has worked once, normal runtime recovery intentionally retries only that Navigator 2.0 or Navigator 10/Pro protocol. It closes a failed session and rebuilds the same client instead of silently switching controller generations. If the controller, firmware behavior or web endpoint has changed, run Reconfigure → Change connection settings to perform fresh detection.

"Navigator web interface could not be read"

• With direct Modbus access, the web host is normally the same heat pump IP
• With a Modbus proxy, enable the proxy option and enter the original heat pump address as web host
• Confirm that Home Assistant can reach the local Navigator web interface
• Clear the web PIN to continue with Modbus only

Web authentication and general web connection failures create separate repair issues. Neither failure stops working Modbus polling.

Only one Modbus client at a time

The Navigator's Modbus TCP server serves a single active connection. While Home Assistant (or any other client) is connected, a second connection — a probe script, a Modbus debugging tool, another integration — is not rejected outright: it can read the base block, but optional blocks such as the heat-sink sensors answer the not-present sentinel (-1.0) for it, and the values it measures look "broken" while the primary client keeps receiving live data. To test the API or probe registers directly on your own plant, stop the integration first (disable the config entry or stop Home Assistant), and reconnect it afterwards. Never run a second permanent client next to this integration.

Web-only mode exposes fewer entities than expected

This is intentional. Web-only mode loads only read-only sensors returned by the local web interface. It has no Modbus polling, binary sensors, numbers, selects, switches, register writes, system-mode action or error acknowledgement. Values missing from the latest successful web snapshot remain unavailable.

Entity Problems

Missing entities

• Make sure the corresponding heating circuits and zones are enabled in the configuration
• Reconfigure the integration
• Restart Home Assistant

Incorrect or absurd values (e.g., -3276.8°C)

• Record the entity/register name, displayed value, Navigator model and the time of the observation.
• Download diagnostics and include the installed integration/API versions and detected capabilities.
• If possible, state the value shown on the Navigator at the same time. A plausible but different value is as important as an obviously absurd number.
• Do not assume every 254, 255 or -1 is corrupt: these are valid unavailable sentinels only where the register metadata declares them.
• Report the case as a bug. Maintainers should compare the exact FC03/FC04 address/count and raw words in batch and individual reads before changing datatype or address metadata.

Compare values with the Navigator GLT Monitor

For difficult register or write problems, open the GLT Monitor on the Navigator under the building-management/GLT area. Menu wording and access level vary by controller and firmware; technician access may be required. The monitor shows the values and communication seen by the controller and is therefore the best on-device comparison point for Home Assistant diagnostics.

When reporting a discrepancy, capture at the same time:

• Navigator generation, firmware and heat-pump model
• Entity and library register name, address and datatype
• Home Assistant value and timestamp
• Navigator display value and GLT Monitor value
• Whether the value was read in a batch or individually
• Every system that can write the register, such as Home Assistant, an inverter, E3DC, Smartfox or another building-management controller

If a writable value alternates between two values, first disable every other writer. A repeating change often means two automations or energy managers own the same GLT register; it is not evidence that the datatype is wrong.

PV not connected: message 20300 at zero production

A valid 0 W reading and an unavailable source are different cases:

For a bounded observation, use Enable debug logging on the integration, wait across several forwarding cycles, then disable it again. Compare source, write-result timestamps and controller messages at the same time. The nominal refresh is three seconds, with a two-second per-register cooldown; bus load, retries and source events can change observed spacing. These intervals do not establish a universal controller watchdog/TTL.

On 2026-11-07, a Navigator 10 with firmware T_NAV10_20.24-1580-g02a20b66f retained message 20300 despite repeated successful zero writes. Sending 0.01 kW = 10 W for one minute cleared the message after about 20 seconds without acknowledgement. A single manual write was overwritten by automatic zero forwarding within about three seconds, so it was not a sustained test. The controlled test restored the true source afterward. The normal forwarder rounds kW to two decimals; smaller watt values are not a reliable nonzero workaround on this path.

A controlled series on 2026-11-10 (same plant and firmware) established the actual mechanism — it is a frozen-input detector, not a wattage threshold:

• A static register latches the message after about ten minutes, whatever its level. Static 0.01 kW latched at 15:18 after 10:28; static 0.02 kW latched at 20:15:03 after 10:27; static 0.05 kW latched at 20:02:51 after 9:39; the pre-workaround static 0.00 kW latched every night all night. Ten W or 50 W makes no difference — only change does.
• Any register change clears the message within seconds. A rise 0.01 → 0.05 kW cleared it 37 s later (19:52:35 → 19:53:12); a drop 0.05 → 0.01 kW cleared it 38 s later (20:03:14 → 20:03:52); a drop 0.02 → 0.01 kW cleared it 19 s later (20:15:15 → 20:15:34). Up or down, 10 W or 50 W — the direction and the level are irrelevant. The observed lag is dominated by the 30-second web poll interval.
• This explains the 2026-11-07 observation: that "10 W cleared it after 20 seconds" was the change from 0 to 0.01 kW clearing it, and the message returning later was the frozen constant re-latching. A constant substitute of any size cannot keep the message away.
• The register cannot represent values below 5 W. It quantizes to the 10 W resolution, so a 1 W source is written as 0.00 kW exactly like 0 W or 2 W — verified live: 1 W and 2 W sources each left the forwarded register at exactly 0.00 kW, and a 1↔2 W alternation produces no register change the controller could see. During dusk the mapped source passed through 0.7–7.2 W; the values below 5 W were written as a real 0 W although the workaround was active (it then only matched an exactly zero source). Since 0.27.0 every valid production that rounds to zero is substituted.
• Static zero behaves differently from a frozen positive value. In the controlled series a static 0.00 kW register stayed clear for twelve minutes, while every static positive value latched within about ten minutes — but nights without any workaround show that a permanent 0.00 kW does latch 20300 eventually. The heartbeat avoids both regimes.
• An alternating value keeps the message away. Alternating 10 ↔ 20 W with a change at least every ~80–127 seconds kept the message clear for the whole verified 11½-minute window, well past the ~ten-minute latch timer. The longest verified frozen stretch without a latch is 127 seconds, so the workaround's one-minute alternation has a comfortable margin.
• Separately, 20303: N2_SMARTMETER_NOTCONNECTED appeared around sunrise on both days and cleared with real production; it is a controller-side meter detection, not addressed by the GLT register.

The workaround therefore transmits an alternating 10 W / 20 W heartbeat for valid zero-resolution production instead of a constant. This finding does not resolve the separate #493 battery/display-retention report, establish the exact firmware algorithm, or prove behavior on other firmware or controller generations. Field evidence.

The optional workaround changes only valid PV production that rounds to the register's zero resolution (below 5 W, positive or negative) on transmission. It does not replace missing readings, alter the source sensor, create PV surplus, or change derived household consumption. Controller-side PV statistics can still include the artificial heartbeat. Positive readings from 5 W up resume normal live forwarding.

Controls or actuators appear to be missing

Writable functions are not all shown as traditional "actuators". Open the IDM device and look for number, select and switch entities. In an automation, choose Add action and select the entity action (number.set_value, select.select_option, switch.turn_on/switch.turn_off) or an IDM-specific action. Advanced raw register writing is intentionally available only through the risk-acknowledged IDM action documented under Services.

Values not updating

• Check the scan interval in the options
• Check the Home Assistant logs for error messages
• Reconfigure the integration

"IDM polling barely fits into the scan interval"

This repair issue appears when reading all registers has taken at least 80% of the configured scan interval for several polls in a row. The controller then gets almost no idle time between requests, which usually surfaces as timeouts — especially when a second Modbus client shares the heat pump.

Since 0.27.0-b1 the issue carries a Fix it button: the integration derives a concrete suggested interval from the recorded poll durations (the 95th percentile divided by the warning ratio, rounded up to the next 5 s step), the repair dialog pre-fills that value, and confirming it writes the option and reloads the entry once. You can also pick your own value between 5 and 300 s in the same dialog; nothing changes without your confirmation.

What helps, in order of effect:

1. Increase the scan interval in the integration options. Most values change far more slowly than a 10-second poll suggests.
2. Disable entities you do not use. Polling is entity-aware: a disabled entity's register is dropped from the poll plan, which directly shortens the cycle.
3. Check for a second Modbus client (energy manager, another Home Assistant instance, a KNX gateway) querying the heat pump at the same time.

The issue clears itself once polls have stayed comfortably inside the interval again. To see the underlying numbers, enable Communication diagnostics in the options — it exposes the poll duration and the number of actively polled registers as sensors.

Per-request metrics

Since 0.27.0-b1 the same option also provides Modbus request duration (window): the median duration of the last 100 physical Modbus requests (FC03/FC04 reads, FC16 writes, FC01/FC05 coils) across all function codes. Its attributes carry the full measurement window — request count, outcome classes (timeout, illegal address, device, connection, transport), and per-function-code duration statistics (min/median/average/p95/max). The values land in the diagnostics download too, under client_diagnostics → transport → request_metrics.

Use it to answer questions a whole-poll duration cannot: which request class dominates the cycle, how many extra requests the resilient bisect path adds on a plant with unsupported registers, and how request durations behave when a second Modbus client shares the connection. The measurement is passive — it never sends an additional request.

A register write is rejected

Symptom: changing a value (for example the target temperature of a heating circuit in the climate card) fails immediately, Home Assistant shows a write error, and the Navigator does not change. Reading the same register keeps working.

The integration distinguishes two very different causes, and the message says which one applies:

1. The write was blocked before it was sent. No Modbus request left Home Assistant. Typical reasons and their messages:

2. The heat pump answered with an error. The request reached the controller and it refused it. The message names the Modbus exception code, and the same detail is written to the log and to the diagnostics download as last_write_error.

A read-only value that is nevertheless documented as writable almost always comes down to the controller's own access rules, not the integration:

• Check the GLT access setting on the Navigator. Under the building management (GLT) area the controller keeps a register list with a per-register access column. A register that is not released for writing there is refused even when the address, datatype and value are all correct. This is the most common cause when some writes work (operating mode, external room temperature) while others on the same device do not.
• Check that the function is enabled for that heating circuit or component. A circuit that is not configured, or a feature the installer has not enabled, rejects writes to its registers.
• Check for a second writer. Another building management system, an energy manager or an inverter writing the same register can make a write look like it was refused or immediately reverted.
• Compare with the GLT Monitor as described above. It shows the value and the access rights the controller itself sees.

When reporting this, include the exact log line — it now contains the register name, the address, the value and the technical reason, for example:

The IDM controller refused the write of 24.0 to hc_c_room_setpoint_heat_normal
(address 1405): IdmDeviceError: ... [Modbus exception code 4 (Server Device Failure)]

EEPROM Warnings

If you receive a warning about EEPROM when writing values:

• These registers have a limited number of write cycles
• Changes to these values should be made sparingly
• The integration automatically warns about EEPROM sensitivity

Debug Logging

Enable extended logging:

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

Look for in the logs:

• idm_heatpump - integration-specific messages
• Modbus read error - Modbus read errors
• Modbus write error - Modbus write errors
• Decode failed - Register decoding errors

Export Diagnostics Data

1. Go to Settings → Devices & Services
2. Click IDM Heatpump
3. Click Download diagnostics
4. Attach the file to your bug report

The export includes the installed integration, Home Assistant Core, Python, idm-heatpump-api, modbus-connection and tmodbus versions. They are also visible on the IDM Heatpump API version diagnostic sensor. The client diagnostic block additionally reports a redacted endpoint, transport source, socket ownership, current connection state, and whether central sharing is supported.

Bug Report Checklist

Please include:

• Heat pump model and Navigator/controller model.
• Firmware version from the diagnostics export.
• Home Assistant version plus integration, idm-heatpump-api, modbus-connection and tmodbus versions.
• Active heating circuits, zone modules, PV, Solar, ISC and Cascade flags.
• The redacted diagnostics export.
• Relevant log lines around the first error.
• Whether the problem is read-only, a failed write, an unavailable register or an unexpected value.

Do not include private IP addresses, hostnames, serial numbers, installer/customer data or unredacted network details.

👩‍💻 For Developers (Mock Tests)

Please never run write operations on Modbus (write_register) live against a real heat pump when testing code changes to base logic. Use the repository test suite and fake transports for decoding, encoding, retry, reconnect and write-safety tests. The tmodbus adapter is implemented and automatically tested, but read-only real-hardware validation of its setup, FC03, FC04 and reconnect paths remains pending. Hardware validation must remain read-only unless the owner explicitly authorizes a specific write.

Common Errors and Solutions

Self-Healing After a Modbus Outage

A transient Modbus outage (proxy restart, controller reboot) heals itself — no action needed:

• Short outages stay completely quiet. A connection failure that recovers within five minutes never reaches the repairs page or the error log at all: the coordinator keeps serving the last snapshot (web data keeps flowing on its own schedule), pending writes pause silently and resume on their own retry cycle, and the log gets one gray info line when the connection drops and one when it recovers. Only a connection failure that lasts longer than five minutes escalates to the visible repair notice and error line — errors the controller itself answers with (wrong slave ID, firmware mismatch) always escalate immediately, because a quiet window cannot heal them.
• Once the quiet window has passed, the web interface keeps the calm tone while it keeps delivering (a web PIN is configured and the web path answers), a failed Modbus poll raises the calm repair notice IDM Modbus connection interrupted — web data active instead of a connection error: it states that the data keeps flowing through the local web interface and disappears automatically on the first successful poll. The log stays quiet after the first error line per outage — one line informs, one per scan interval would only cause alarm.
• When an entry is waiting out Home Assistant's setup-retry backoff (up to ~30 minutes after a failed reload), a background watchdog probes the configured Modbus endpoint once a minute and reloads the entry automatically as soon as it answers again. The watchdog only runs while an entry is actually waiting and owns no task on a healthy installation.

The Reload connection diagnostic button on the integration's device page remains the manual shortcut — same effect, immediately.

PV message 20300 despite valid zero production

Some controllers reported "PV not connected" despite repeated successful zero writes. First check the source, GLT activation and forwarding. A completed write does not establish how firmware assesses the PV connection. The optional PV zero-power workaround is off by default and can affect controller displays and statistics. It does not repair a disconnected transport.

GLT availability investigation (#493)

When a battery is used, IDM support requires that register 84 (battery_discharge) is written as well as battery SoC (register 86). Configure both sources under external power forwarding; mapping SoC alone can leave the controller without a required battery-power input and may cause the battery display or GLT readback to flicker or become unknown. See external power setup and #493.

For a supported external-power input, distinguish four cases in diagnostics: unused_sentinel means the controller reports an unset value; not_polled means the poll plan excludes the register; unsupported means the controller rejected its address; no_data means a planned read returned no usable value. These are different causes and must not all be called a forwarding failure.

Enable the relevant read-only Sensor and, for manual control, its Number with the (setpoint) suffix. The Number's _set unique ID explicitly keeps its readback polled even with forwarding off. Record the integration/API versions, forwarding setting, status and entity availability before/after an options reload. A supported sensor starting at an unset sentinel now stays registered and can recover when a later readback is valid. It remains unavailable during unset samples; the Number remains writable with unknown state.

For controller display flicker, compare debug forwarding timestamps with actual readbacks and the display at the same times. Successful writes and optimistic HA states do not prove controller retention. Do not reset inputs to zero or sentinels for diagnosis, and do not change the refresh cadence without evidence.

Read-only field validation queue

Diagnostics already expose last_poll_duration_seconds, total polls/failures, active/known registers and register outcomes. Capture these over a stated observation window before proposing a shorter interval. They are poll metrics, not physical Modbus request counts. For shared-link tests record actual transport ownership and other holders; coordinate any deliberate disconnect with the owner. For DHW/defrost COP record simultaneous electrical and thermal sources, operating mode, coverage gaps and firmware. No cycle or plant setting needs to be forced merely to collect normal-operation evidence.