Local Navigator Web Interface

Purpose and boundaries

The optional local web connection supplies Navigator metadata and diagnostics without the myIDM cloud. Select auto, modbus_web, modbus_only or web_only in the connection settings; auto can fall back to the web connection when Modbus is unavailable and a working web PIN is configured.

Navigator 10/Pro web controls validate writes against the controller's declared ranges. Differential-temperature circuits omit room controls. Raw Modbus register writes and the one-shot DHW boost are unavailable in web_only. The web interface exposes boost as a weekly timetable; rewriting that timetable is outside this integration's supported controls.

Supported local login variants

Navigator generations use different local protocols. The internal variant names describe the protocol client and are not user-selectable settings.

These transports are local controller interfaces. No cloud password, myIDM account login or two-factor code is accepted.

Local network code

The value entered in Home Assistant is the Navigator's local network code. On a German Navigator 2.0 display it is normally located under:

Einstellungen → Allgemeine Einstellungen → Netzwerkeinstellungen → Code lokales Netzwerk

Menu names can differ by generation and firmware. Leading and trailing spaces are removed. An empty value or exactly 0 means that local web access is disabled, so the integration stays in Modbus-only mode.

The code is entered through a masked Home Assistant password selector. It is never logged and is redacted from diagnostics together with the Modbus host, web host, port and slave ID. Web error diagnostics expose only an error category, not a URL, query string or authorization value.

Detection and runtime lifecycle

The integration separates initial protocol discovery from normal runtime recovery:

1. Setup, reconfiguration or repair: The Modbus-detected model is used as a hint so the most likely web protocol is tried first. If it fails, the other supported protocol is also tried before the PIN or connection is rejected.
2. First successful login: The actual nav20 or nav10 result is stored in the config entry. The result comes from the successful client, not merely from the model hint.
3. Normal polling: The successful client and authenticated session are reused across web polling cycles.
4. Expired session or transport failure: The failed session is closed and the same known protocol is rebuilt immediately. Normal runtime recovery does not probe the other Navigator generation.
5. New discovery: Reconfiguration or repair validates the connection again and can test both protocols. This is appropriate after replacing the Navigator, changing the web host or making a controller/firmware change that affects the local interface.

This prevents repeated timeouts on the wrong port and avoids a temporary failure silently changing a previously working Navigator generation.

Model and value precedence

Modbus remains authoritative for register-backed operating values. Web data is additive: it supplies metadata and extra diagnostics that have no equivalent Modbus entity. A duplicate register-backed value is not exposed a second time.

Web model and firmware metadata may complete an unknown Modbus result. If a web-reported Navigator family conflicts with a definite Modbus detection, the conflicting web model and firmware are ignored. Optional Navigator 10 infosystem notifications are read separately; failure of that optional read does not discard the rest of a valid web snapshot.

Polling and recovery behavior

• Web polling has its own interval, 30 seconds by default.
• It starts slightly after Modbus polling to avoid simultaneous requests.
• A web authentication or connection problem creates a separate Home Assistant repair issue and does not stop Modbus updates.
• Missing values from a successful web snapshot remain unavailable; old values are not invented.
• The cached client is closed when the config entry unloads or when its session must be rebuilt.

Troubleshooting checklist

1. Confirm that the code is the local network code, not cloud credentials.
2. Confirm that the code is neither empty nor 0.
3. With direct Modbus access, use the Navigator address as the web host. With a Modbus proxy, configure the original Navigator address separately.
4. Run Settings → Devices & Services → IDM Heatpump → Reconfigure → Test current connection.
5. If the Navigator or its local web protocol changed, use Change connection settings so protocol discovery runs again.
6. Download redacted diagnostics and include the integration, modbus-connection, tmodbus and API versions, plus Navigator model and firmware, when reporting a problem.

See Troubleshooting for categorized errors and Configuration for all web options.

Version pairing

The sticky protocol selection was introduced in integration version 0.8.1-beta.29. The current source tree uses the tested idm-heatpump-api[web]==2.16.2 web clients, which additionally expose Navigator 10 heating-circuit data for circuits B–G.

For the independent Modbus path, the tested manifest order is modbus-connection>=4.12.7, tmodbus[async-serial]>=0.6.2, and idm-heatpump-api[web]==2.16.2. The first two own the direct Modbus socket; since API 2.0.0 pymodbus is no longer installed at all. This does not change the web protocol or make version 4.12.7 an IDM integration release.

Capture-tool updates and failed web login

Use the current IDM Web Capture package when collecting evidence. From tool 1.19.4, a newer signed application release installs and restarts automatically before capture or upload on Windows and Linux/source clients. Linux requires the distribution's openssl command; its system Python is not replaced. Source clients through 1.19.3 require one manual upgrade. A known update or invalid signature blocks collection; when the update service is unreachable, local collection remains available and manifest.json records update_check.

Current captures are preferred, but the server accepts older tool versions too; version age alone does not reject a submission. Existing saved ZIPs remain uploadable after an app update, subject to the same format, size, sanitization and checksum checks. The original capture version stays recorded. Existing donations and issued upload tickets remain valid. A confirmed startup retains the active version and one verified fallback without deleting diagnostic ZIPs.

When supplied web credentials produce no usable HTTP or WebSocket data, the tool pauses. Correct the input, explicitly continue without web data, or cancel. Sanitized web_diagnostics.json and bounded login-response files record failure categories, known login paths, status codes and timings without PIN/form values. Unknown authorization replies remain unknown rather than proof of a wrong PIN. Continuing without web preserves that evidence and proceeds with the selected Modbus path. New login paths and NAVIGATOR Pro authentication remain open until verified; never post a PIN or raw login response publicly.