IDM Heatpump - Home Assistant Integration

AI generated

The complete documentation for the IDM Heatpump integration. From installation to troubleshooting — with all features, entities, and services.

For Modbus operation: Modbus TCP must be enabled on the IDM Navigator/controller under Building management system (Gebäudeleittechnik) → Modbus TCP → On (Ein). See Installation & Setup.

What is the IDM Heatpump Integration?

The IDM Heatpump Home Assistant Integration connects Home Assistant with IDM Navigator controllers by IDM EnergieSysteme GmbH. It enables local monitoring and supported controls via Modbus TCP — no cloud, no subscription. Navigator 10 has direct hardware confirmation; Navigator 2.0 and Navigator Pro remain under broader compatibility validation.

Core Features

Which dependency version belongs to an installed release?

This documentation follows the current source tree, which can include unreleased dependency updates. Its library versions do not describe every older installed release. The authoritative requirements for an installed version are in that release tag's manifest, not main. For example, the 0.19.0 manifest pins API version 2.4.3. A runtime reporting that version on 0.19.0 is correct. Compare the integration/API version sensor and diagnostics with your tag before treating a newer version in the current website as an installation error.

CI, release validation and Pages deployment check current version claims against the checked-out manifest. Dependency automation synchronizes those claims; published changelogs and release evidence remain unchanged history.

Current features in the 0.26 series

The current feature overview includes:

This integration line requires Home Assistant 2026.11.0 or newer. See the Changelog for changes between individual releases.

Differential temperature circuits

For circuits configured accordingly in the Navigator, Home Assistant shows storage and reference temperatures, their signed difference and operating status. Keep the circuit selected in both the ordinary heating-circuit list and the differential-circuit list. Ordinary heating controls are hidden for these circuits; the controller configuration is unchanged. See configuration and entity mapping and limits. Confirmation on differential-control hardware is still pending; hysteresis and threshold controls are not included.

Smart Energy, comfort and AI reports

Optional energy analysis, comfort functions and the experimental AI adviser extend the local controller integration. Automatic controls remain off until explicitly enabled.

Start with iDM Smart Energy & Comfort for activation, examples, defaults and limitations, and with the Experimental AI adviser for setup, report modes, privacy and the dashboard.

Controller integration

• System Monitoring: Flow, return, hot water, outdoor temperature, pressure, flow rate
• Heating Circuits A–G: Up to 7 heating circuits with individual setpoint and mode control
• Zone Modules: Up to 10 zones with up to 8 configurable rooms each; current Navigator 10 hardware defaults to 6 rooms per module.
• Solar & PV: Solar hot water heating, PV surplus utilization, battery monitoring
• Energy Monitoring: Heat quantity, runtimes, energy meters
• Cascade & Bivalence: Multi-heat pump control, heating element integration
• BMS Remote Maintenance: BMS temperature requests (cyclic writing)
• Error Management: Error detection, error acknowledgment, diagnostics export
• Optional Web Supplement: Navigator generation, software version, heat pump model, compact myIDM ID, web-only diagnostics, and Navigator 10 infosystem notifications without replacing Modbus values; default interval 30 seconds
• KNX Bridge (optional): Serves the IDM KNX communication objects — same object numbers, datapoint types and directions as IDM's ETS example project — through the Home Assistant KNX integration, so the Weinzierl KNX IP BAOS gateway module is no longer needed. See KNX Bridge.
• Room Temperature Forwarding: Optional forwarding of Home Assistant temperature sensors to IDM external room temperature registers per heating circuit
• Readable Diagnostics: Internal IDM messages are shown with text plus structured code/text attributes
• Direct local Modbus runtime: modbus-connection and tmodbus provide the shared connection or private fallback socket; idm-heatpump-api keeps the IDM register and safety logic

Platforms & Entities

Quick Navigation

I'm new here

1. Installation & Setup
2. Configuration
3. Entities

I want to automate

1. iDM Smart Energy & Comfort
2. Configuration and source mappings
3. Services Reference

Findings and evidence

• Field findings and documentation maintenance
• Predictive Advisor
• Telemetry and firmware orientation

I have a problem

1. Troubleshooting
2. Local Navigator Web Interface
3. Modbus Registers
4. Stability & Release Readiness

I want to contribute

• Contributing Guide

Technical Details

• Batch reading: Only exactly adjacent, non-overlapping ranges are grouped, up to 40 Modbus words per request
• Value validation: Unavailable sentinels are omitted as unused; suspicious grouped values are checked individually and quarantined for the client session
• Library-powered: All registers from idm-heatpump
• Actionable setup diagnostics: Separate messages for hostname/DNS errors, refused or disabled Modbus TCP, timeouts, unreachable endpoints, wrong slave IDs, invalid web PINs, and unavailable web interfaces
• Runtime version visibility: Integration, idm-heatpump-api, modbus-connection and tmodbus versions are available in a diagnostic sensor, diagnostics exports, and startup logs
• Data types: FLOAT, UCHAR, INT8, INT16, UINT16, BOOL, BITFLAG
• EEPROM protection: Sensitive registers tracked and protected
• Transport boundary: Raw FC03/FC04 reads and FC16 writes use the exact modbus-connection>=4.12.7 / tmodbus[async-serial]>=0.6.2 pair; 4.12.7 is the connection-library version, not the IDM integration version
• API boundary: idm-heatpump-api[web]==2.16.2 provides batching, decoding and write safety. The API owns its own exception hierarchy; the integration uses the tmodbus-backed socket without a pymodbus dependency
• Auto-recovery: API retry/backoff plus reconnect-on-demand in the tmodbus-backed connection
• Connection ownership: Each entry uses Home Assistant's shared Modbus connection when available (owns_socket: false, supports_shared_connection: true), with a private socket fallback when the shared claim cannot be acquired
• Validation status: Automated checks and read-only Navigator 10 observations are available; they do not replace candidate-specific clean-install, long-duration and broader model validation. See Stability & Release Readiness.
• Navigator 10: Heat sink sensors, flow rate (Sieb monitoring), groundwater temps, booster A/B
• Web supplement: Setup tests both supported local protocols when needed, stores the successful Navigator family, reuses its session and retries only that same protocol during normal runtime recovery
• Room forwarding: Optional write path with state-change updates, periodic refresh, tolerance and range checks

Links & Resources

This wiki documents the IDM Heatpump integration. Developed by Xerolux