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
• If this menu is missing or locked, sign in at installer/technician level or ask your heating installer/iDM service to enable it
• 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.

Each IDM config entry currently owns its direct tmodbus socket. Home Assistant central cross-entry connection sharing is not available, and diagnostics therefore report supports_shared_connection: false. Avoid running another Modbus client against the same endpoint while diagnosing connection loss.

"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. If the web interface can be authenticated, the recovery step offers web data only. This mode exposes read-only web sensors but no Modbus heating-circuit/zone registers, writable entities, mode control, or error acknowledgement. Full functionality still requires Modbus TCP to be enabled by the installer or iDM service if the local controller does not expose the setting.

"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.

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.

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.

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.

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