Entities
Smart feature entities
The optional Smart Energy & Comfort profile adds electrical and thermal energy totals for lifetime, day and month, COP for the same periods, estimated costs, CO₂ and optional PV use, plus compressor-cycle and operating analysis. These are derived values, not additional physical meters. The required power registers must be available.
Health Monitor adds eight problem checks and a report sensor. Heating-curve and weather advisers add read-only recommendations. The Predictive Advisor adds a strictly read-only recommendation framework (status, recommendations, data quality). The optional comfort schedule changes the existing circuit room target; it does not create a second climate controller entity. Automatic DHW charging uses the existing boost controls and state machine.
Every entity these packages can create is listed with its exact name under Optional feature entities, and the sub-device grouping is described under Device groups (device hierarchy).
With device hierarchy enabled, iDM Analytics, iDM Health Monitor, iDM Comfort and Diagnostics separate these features from controller entities. Disabling optional features removes their entity registrations; re-enabling them restores the same IDs. Existing controller IDs are retained.
The integration dynamically generates entities based on your heat pump configuration (heating circuits, zones, optional features).
Entity Platforms
| Platform | Count | Description |
|---|---|---|
| Sensor | model-dependent | Temperatures, pressures, flow rates, energy, PV, solar, cascade, booster, runtime versions, diagnostics |
| Binary Sensor | model-dependent | Fault alarms, compressor status, heating/cooling/DHW demand, web states |
| Number | model-dependent | Writable setpoints, temperature limits, GLT parameters, power limits |
| Select | model-dependent | System mode, heating circuit modes, solar mode, ISC mode |
| Switch | model-dependent | External heating/cooling/DHW demand, one-time DHW charge |
| Climate | per circuit + zone room | Heating/cooling mode + target temperature for heating circuits and zone-module rooms |
| Water Heater | 1 | DHW target temperature with current temperature readback |
| Button | 1 | Acknowledge active errors on the heat pump |
Exact counts depend on the detected model, active heating circuits, zones, rooms and optional features. Adding circuits, zones, cascade or web supplement data can add entities.
Entities are grouped by function in Home Assistant where possible. Configuration entities come first, followed by switches, writable values, live measurements and diagnostics.
Entity names and languages
Entity names come from the integration's translation files and follow the language configured in Home Assistant: an English installation shows English names, a German one shows the German names the integration has always used. Heating circuits and zone rooms share one name per measurement and fill in their circuit letter or zone/room number, for example Heating circuit A flow temperature and Zone 1 room 2 temperature.
Changing the Home Assistant language changes the displayed names only. Entity IDs and unique IDs stay exactly as they are, so dashboards, automations and long-term statistics keep working. An entity created after a language change derives its entity ID from the name in that language, as with every Home Assistant integration.
Sensors
Runtime diagnostics
| Entity | State | Attributes | Category |
|---|---|---|---|
| IDM Heatpump API version | Installed idm-heatpump-api version |
integration_version, modbus_connection_version, tmodbus_version, home_assistant_version, python_version |
Diagnostic |
This sensor remains available even if heat-pump polling fails, making it useful
when collecting information for a bug report. The direct socket runtime is
identified by the modbus_connection_version and tmodbus_version attributes.
System Temperatures & Pressures
| Entity | Register | Unit |
|---|---|---|
| Outdoor temperature | 1000 | °C |
| Average outdoor temperature | 1002 | °C |
| Storage tank temperature | 1008 | °C |
| Cold storage temperature | 1010 | °C |
| DHW temperature bottom | 1012 | °C |
| DHW temperature top | 1014 | °C |
| HP flow temperature | 1050 | °C |
| HP return temperature | 1052 | °C |
| HGL flow temperature | 1054 | °C |
| Heat source inlet/outlet | 1056/1058 | °C |
| Air intake temperatures | 1060/1064 | °C |
| Air heat exchanger temp | 1062 | °C |
Navigator 10 — Heat Sink (Trennwärmetauscher)
| Entity | Register | Unit |
|---|---|---|
| Heat sink return temp (B124) | 1068 | °C |
| Heat sink flow temp (B125) | 1070 | °C |
| Heat sink flow rate (B2) | 1072 | L/min |
| Heat sink charging pump signal (M73) | 1074 | % |
Register 1072 is a word-swapped FLOAT32 — the official IDM doc lists UCHAR,
but field readings proved the float (0.23.0-b8): a plant with a live flow
signal shows real L/min values. Without a plate heat exchanger the whole
block reports not-present (-1.0) and these entities stay unavailable;
when the web supplement serves its own flowmeter row, that value fills the
flow rate in automatically (see Known Limitations).
Compressors & Pumps
| Entity | Register |
|---|---|
| Compressor status 1–4 | 1100–1103 |
| Charging pump status (M73) | 1104 |
| Brine pump status (M16) | 1105 |
| Heat source pump status (M15) | 1106 |
| ISC cold storage pump (M84) | 1108 |
| ISC recooling pump (M17) | 1109 |
| Circulation pump (M64) | 1118 |
Energy & Power
| Entity | Register | Unit |
|---|---|---|
| Energy heating | 1748 | kWh |
| Energy total | 1750 | kWh |
| Energy cooling | 1752 | kWh |
| Energy DHW | 1754 | kWh |
| Energy defrost | 1756 | kWh |
| Energy passive cooling | 1758 | kWh |
| Energy solar | 1760 | kWh |
| Energy electric heater | 1762 | kWh |
| Current power draw | 1790 | kW |
| Current power solar | 1792 | kW |
| Power consumption HP | 4122 | kW |
| Thermal power | 4126 | kW |
PV / Energy Management
| Entity | Register | Datatype | Unit |
|---|---|---|---|
| PV surplus | 74 | FLOAT, word-swapped | kW |
| Electric heater power | 76 | FLOAT, word-swapped | kW |
| PV production | 78 | FLOAT, word-swapped | kW |
| House consumption | 82 | FLOAT, word-swapped | kW |
| Battery discharge | 84 | FLOAT, word-swapped | kW |
| Battery SOC | 86 | signed INT16, one register | % |
Battery SOC accepts 0–100; -1 means that no battery value is available.
Treating address 86 like the surrounding two-register FLOAT values produces an
implausible result. When a battery is used, IDM support also requires that
register 84 (battery_discharge) is written; mapping SoC alone is not
sufficient (#493).
PV surplus operation (derived diagnostic)
The Navigator controllers do not expose an internal "PV surplus charging
active" state register — the whole PV block (74–88) consists of GLT
measurement inputs written by an external energy manager. The integration
therefore provides the derived diagnostic binary sensor PV-Überschussbetrieb
(calculated_pv_surplus_operation, issue #353). It is on when both halves of
the state are true:
- Surplus is currently signalled to the controller:
pv_surplus(register- ≥ 0.05 kW or the SG-Ready signal
smart_grid_status(register 90) reports Supergreen.
- ≥ 0.05 kW or the SG-Ready signal
- The heat pump is actually drawing electrical power:
power_consumption_hp(register 4122) ≥ 0.05 kW, falling back tohp_operating_mode(register 1090) ≠ Off on installations without the Nav 10 power measurement.
The entity is only created when at least one source per half exists on the
detected installation; thresholds and the currently active sources are exposed
as attributes. Note for installations where the surplus is measured behind the
heat pump feeder: pv_surplus collapses toward zero while the heat pump absorbs
the surplus it is charged with — there the SG-Ready signal (or pv_production)
remains the reliable indicator, and the SG-Ready source keeps the diagnostic
meaningful.
Solar Thermal
| Entity | Register | Unit |
|---|---|---|
| Solar collector temperature | 1850 | °C |
| Solar return temperature | 1852 | °C |
| Solar charging temperature | 1854 | °C |
| Solar WQ reference / pool temp | 1857 | °C |
These entities only exist while the solar thermal system option is enabled (default). Plants without collectors can switch the option off in the integration settings: the solar registers leave the poll and the empty Solaranlage device group disappears after a reload. Re-enabling it restores the entities with their previous IDs.
The integration also notices on its own: when every solar register reports "not configured" for a full day, a repair suggestion offers to switch the module off (or keep it, which dismisses that round of the suggestion).
ISC (Intelligent Surface Cooling)
| Entity | Register | Unit |
|---|---|---|
| ISC charging temp cooling | 1870 | °C |
| ISC recooling temperature | 1872 | °C |
Booster A/B (2nd heat generator)
| Entity | Register |
|---|---|
| Booster fault | 4001 |
| Booster interlock | 4002 |
| Booster A: source inlet/outlet, storage, flow, return temps | 4010–4018 |
| Booster A: source pump, charging pump, compressor | 4020–4022 |
| Booster B: equivalent registers | 4040–4052 |
Cascade (multi-heat pump)
| Entity | Register |
|---|---|
| Cascade available heating/cooling/DHW | 1147–1149 |
| Cascade running heating/cooling/DHW | 1150–1152 |
| Cascade requested temps (heat/cool/DHW) | 1200–1204 |
| Cascade average flow temps | 1206–1210 |
| Cascade min/max power | 1220–1225 |
| Cascade bivalence settings | 1226–1231 |
Heating Circuit Sensors (per circuit A–G)
| Entity | Description |
|---|---|
hc_{x}_flow_temp |
Flow temperature |
hc_{x}_room_temp |
Room temperature; unavailable when no room sensor is wired (see Findings) |
hc_{x}_setpoint_flow_temp |
Current setpoint flow temp |
hc_{x}_active_mode |
Active operating mode |
Calculated Sensors
These sensors are derived from register values of the same snapshot. Nothing is estimated: every operand is a decoded register value, and the sensor reports no value rather than a guess when its sources are not meaningful.
| Entity | Description |
|---|---|
calculated_hp_temperature_delta |
Heat pump spread (flow minus return) |
calculated_heat_source_temperature_delta |
Heat source spread (inlet minus outlet) |
calculated_dhw_setpoint_deviation |
DHW actual minus setpoint |
calculated_cop |
Momentary COP (thermal power / electrical power) |
calculated_hc_{x}_flow_deviation |
Flow deviation per heating circuit |
calculated_hp_flow_deviation |
Heat pump flow deviation (heating mode only) |
Flow deviation per heating circuit compares the measured flow temperature of
a circuit (hc_{x}_flow_temp) with the flow setpoint the controller currently
requests for that circuit (hc_{x}_setpoint_flow_temp):
- Positive — the circuit runs above the requested setpoint (overshoot, typically a heating curve set too high or a mixer that opens too far).
- Around zero — the circuit follows its heating curve.
- Negative — the circuit does not reach its setpoint (undersized heat source, high load, defrost, or a limiting setting).
The sensor becomes unavailable while the circuit is idle (the controller
reports 0.0) and on circuits that are not configured (-1.0). That is
intentional: a deviation calculated from a placeholder value would be
meaningless. The entity itself is created as soon as both registers exist, so a
Home Assistant restart during standby does not make it disappear.
Heat pump flow deviation (calculated_hp_flow_deviation) compares the
heat pump's own flow temperature (hp_flow_temp, register 1050) with the
highest circuit setpoint currently requesting flow. No register exists
for a heat-pump-level flow setpoint (verified against the full Navigator 10
map), so the requested level is derived from the active circuit setpoints —
idle circuits reporting 0.0 and unconfigured circuits reporting -1.0 are
excluded. The sensor publishes only while the heat pump reports pure
heating mode (register 1090): during a DHW charge the heat-pump flow rises
to charging temperature while the circuit setpoints stay at their curve
values, and reporting that difference as a "deviation" would be misleading —
the same applies to cooling, defrost, standby and combined states, which
report no value instead. Field evidence: 2026-10-20 probe on the reference
plant, see docs/dev/open-work-audit.md.
Optional Web Supplement Sensors
When Web supplement data is enabled and a local Navigator web PIN is configured, the integration adds read-only diagnostic sensors from the local web API. These sensors are additive; Modbus entities remain the primary data source.
Typical web-only sensors include:
| Entity | Description |
|---|---|
| Navigator version (Web) | Detected Navigator generation, for example Navigator 2.0 or Navigator 10; carries the heat pump model as an attribute where the firmware reports it |
| Software version (Web) | Controller software version reported by the local web interface |
| myIDM ID (Web) | Compact myIDM ID derived from the local web account value before @ |
| Info system notification count (Web) | Number of active Navigator 10 infosystem notifications |
| Anforderungsgrund (Web) | Navigator 10 only: the controller's own demand reason (issue #353) |
| Flow meter (Web) | Heat-sink flow rate in L/min from the controller's own flowmeter row; when the Modbus register 1072 reports not-present (no plate heat exchanger), this value fills the Heat sink flow rate (B2) entity automatically |
| Intermediate circuit flow temperature (Web) | Flow temperature of the intermediate circuit on plants with a separation heat exchanger; the web interface reports the sensor under the dual label B33/B113. Exists alongside the Modbus flow/return entities, because it is a distinct physical sensor (issue #598) |
| Intermediate circuit return temperature (Web) | Return temperature of the intermediate circuit (dual label B34/B114); see above |
| Hot water station flow (Web) | Potable-water (tapping) flow through the hot water station in L/min from the web interface; reads 0.0 when nothing is drawn. Recorder history from a Navigator 10 plant (2026-11) shows the value follows the tap — typical shower draws cluster at 5.5–6.1 L/min, a wide-open bath tap peaked at 19.4 L/min. Station model names such as "35 l" denote the tapping-capacity rating (35 L/min), not a value this sensor reports. See Findings |
The heat pump model is deliberately no entity of its own: Navigator 10
firmware 20.24-1580 (installed from 2026-09-29) removed the model row from
the sensor page, and no other accessible web frame reports it — live-verified
against the controller, an entity would sit unavailable forever on current
firmware. Where a firmware still delivers the row (Navigator 2.0 web, older
Navigator 10 firmware) the value appears as the heatpump_model attribute of
the Navigator version (Web) sensor.
Demand reason from the web interface (Navigator 10 only)
The Navigator controllers expose no internal PV-mode state register over
Modbus, but the Navigator 10 web interface renders the display's
"Anforderungsgrund" — including PV — from a bitmask in the WebSocket
home/detail frame. With the web supplement active on a Navigator 10, the
integration evaluates that frame every web poll and exposes:
- Anforderungsgrund (Web) (
web_demand_reason): the human-readable demand reason, worded like the controller's own display — for example PV, Heizkreis A, Zeitprogramm, Mehrere Anforderungen, Keine Anforderung or Aus — with the rawoperationMode/infovalues of every contributing widget as attributes. - PV-Anforderungsgrund (Web) (
web_demand_reason_pv): binary sensor that isonwhile the controller itself reports PV as its demand reason (bit 32), in the heating as well as the domestic-hot-water reason table.
This is the device-reported counterpart of the derived
calculated_pv_surplus_operation
diagnostic: the web entity reflects what the controller decided, the Modbus
entity works without a web PIN. On Navigator 2.0 (different, PHP-based web
interface) only the derived Modbus entity is available.
With the device hierarchy enabled, all PV entities — the PV registers
(pv_surplus, pv_production, pv_target_value), smart_grid_status, the
derived diagnostic and the two web entities — share the dedicated
Photovoltaik subdevice instead of the main device.
| Info system notifications (Web) | Summary of active Navigator 10 infosystem notifications |
| Hot gas temperature (Web) | Web-only diagnostic temperature when available |
| Evaporator pressure (Web) | Web-only refrigerant pressure when available |
| Board temperature (Web) | Controller board temperature when available |
| Current/projected heating / cooling / hot water power (Web) | The controller's current or projected thermal power for that mode |
"Momentane/prognostizierte Leistung" is not a live measurement
The Navigator labels these three values mom./prog. Leistung Heizen,
mom./prog. Leistung Kühlen and mom./prog. Leistung Vorrang — momentane bzw.
prognostizierte power. They report what the controller currently expects to
deliver for that mode, so a non-zero value while heating or cooling is switched
off is normal and not a fault. A value that changes while the compressor is
idle is the controller re-planning, not the heat pump running.
For actual electrical draw, use Wärmepumpe Aufnahmeleistung /
current_electrical_power instead.
Device-side heat quantities, DHW detail and controller clock (Navigator 10 only)
Three further read-only WebSocket controllers are evaluated on every web poll (live-verified on firmware jsonVersion 11, September 2026):
- Heat quantity heating/hot water, total and today (Web)
(
web_heat_quantity_heating_total,web_heat_quantity_hotwater_total,web_heat_quantity_heating_today,web_heat_quantity_hotwater_today): the controller's ownstatistic/detailheat-quantity block — the lifetime totals and today's values in kWh. They are an independent cross-check for the integration's own energy statistics and work without any Modbus access. - Hot water circulation (Web) (
web_dhw_circulation_active): binary sensor for the domestic-hot-water circulation pump from thesystem.freshwater/overviewframe — a state the Modbus map does not expose. - Hot water status info (Web) (
web_dhw_status_info): the numeric status of the freshwater block, diagnostic category. - Controller clock (Web) (
web_controller_clock): the controller's own clock as a timestamp sensor, withjsonVersion, active user level, language, notification count, frost-protection flag and network flag as attributes. The controller clock can drift — this sensor makes the drift visible.
Connection state
Diagnostic entities make the effective connection visible on the dashboard — they exist in every connection mode, so a fallback is visible at a glance:
- Connection mode (
connection_mode): which transports are actually live right now — Modbus + Web, Modbus only or Web only. The web half reflects the last web refresh (a supplement that stopped answering flips the state to Modbus only and back on recovery). The attributes carry the configured mode (theconnection_modeoption from Configure → Modbus section, default auto) and the detected web variant (nav10ornav20). Every transport transition is written to the log at INFO level (IDM connection state changed: …), so support cases can answer "since when does the web path not answer" without log spam. - Reload connection (
connection_reload, diagnostic button): reloads this integration entry, restarting setup and connection validation without waiting for Home Assistant's setup-retry backoff. This does not reboot the heat pump. The connection must succeed before an outage is resolved. - Last web update (Web) (
web_last_success): when the local web interface last answered successfully — the web counterpart of the Modbus last success diagnostic, always available when a web PIN is configured.
System controllers (Navigator 10)
Four read-only WebSocket controllers that the shipped frontend uses for its
performance page, weather tile, iON status and energy-flow widget are part of
the web supplement (idm-heatpump-api 2.12.0 or newer). They are additive —
the frames are read with the regular web poll, and every entity reports
unavailable until its frame has landed:
- Heat pump power consumption (Web) (
web_hp_power_consumption): the live electrical consumption power in kW, with the performance mode, the system mode, the measurement source, the battery flag and the production flow temperature as attributes. - Heat pump environment power (Web) (
web_hp_power_environment): the source-side power in kW, with the environment source and the source inlet temperature as attributes. - Heating rod (Web) (
web_hp_heating_rod): binary sensor for the heating-rod state of the performance page. - Grid power (Web) (
web_energyflow_grid) and PV power (Web) (web_energyflow_pv): the energy-flow widget's grid and PV power in kW — placed on the PV subdevice when the device hierarchy is enabled. FirmwareT_NAV10_20.24-1580removed thehousechannel from the frame; when an older firmware still delivers it, it is exposed as an attribute. - Weather forecast (Web) (
web_weather_forecast): the controller's own forecast, which it pulls through the myiDM service — today's temperature as the state, and today plus up to six forecast days (min/max/actual temperature, cloud cover, rain probability, sunshine seconds, weather symbol, wind speed) as attributes. - iON optimization active (Web) (
web_ion_active): diagnostic binary sensor for IDM's cloud energy optimization, with the enable setting and the subscription status as attributes.
Web-only controls (Navigator 10, Phase 4)
A web-only entry is no longer purely read-only: with the WebSocket variant connected it gains two controls that write through the local web interface — every other connection mode keeps writing through Modbus exactly as before:
- Betriebsart (Web) (
web_system_mode): select for the operating mode. It reads the current mode and the controller's own selectable values from thehome/overviewtile and writes throughhome/save— the same numbering as the Modbussystem_moderegister, validated before sending. A rejected write raises instead of silently failing. - Fehler quittieren (Web) (
web_acknowledge_errors): the acknowledge button, writingnotification/save. - Warmwasser-Solltemperatur (Web) (
web_dhw_setpoint): the hot-water setpoint as a number entity. Bounds, step and the current value come from the device's own declared parameter definition, and every write is validated against that range before sending — the same write safety as the register path. - Heizkreis X (Web) climate card per circuit (room temperature, target
temperature, mode;
HVACActionfrom the pump state) and the Warmwasser (Web) water-heater card (tank top temperature + setpoint) — the same validated web writes, presented as the standard Home Assistant cards. - Heizkreis X Raumsolltemperatur (Web) / Heizkreis X Betriebsart
(Web) (per configured circuit): the normal room setpoint (parameter
HK<x>04) as a number and the circuit mode (parameterHK<x>01) as a select, with the device's own declared bounds/options. Onesystem.heatingcircuit/detailframe per circuit also carries the room temperature and pump state. The DHW one-shot boost deliberately stays off the web path: this firmware exposes it only as a weekly timetable, and writing whole timetable strings is out of scope.
The set_system_mode and acknowledge_errors services use the same web
path automatically for web-only entries. Writes reuse the authorized web
session of the poll loop and read the state back after every write, like the
official web UI. KNX bus commands route through the same web writes for the everyday
controls (system mode, hot-water setpoint, circuit mode/setpoint,
acknowledge); other registers still require Modbus.
On Navigator 2.0, the statistics pages deliver the same shape from the older web interface: runtime / heat quantity / electrical energy, total per category (Web 2.0) sensors — hours for runtime, kWh for the energy types, normalized with the page's own unit scale.
If a firmware does not answer one of these controllers, the affected entities simply stay unavailable; the rest of the web snapshot is unaffected.
If a web value duplicates an existing Modbus entity, the web entity is skipped. This prevents duplicate dashboard values and keeps Modbus as the authoritative source for register-backed data.
Only values returned by the current local web snapshot are available. Optional Navigator 10 infosystem notifications are read independently; if that optional request fails, the other valid web values remain available. See Local Navigator Web Interface for protocol and web-only-mode details.
Internal Message Sensor
The internal_message diagnostic sensor exposes the active IDM internal
message as readable text, for example a code plus message description. It also
provides the structured attributes message_code and message_text so
automations can react either to the numeric code or to the human-readable
description.
Binary Sensors
| Entity | Register | Description |
|---|---|---|
hp_sum_alarm |
1099 | Sum alarm (total fault) |
compressor_status_1 |
1100 | Compressor 1 running |
compressor_status_2 |
1101 | Compressor 2 running |
compressor_status_3 |
1102 | Compressor 3 running |
compressor_status_4 |
1103 | Compressor 4 running |
heating_demand |
1091 | Heating demand active |
cooling_demand |
1092 | Cooling demand active |
dhw_demand |
1093 | DHW demand active |
calculated_pv_surplus_operation |
derived | Heat pump running on signalled PV surplus (see PV / Energy Management) |
Navigator 1.0/1.7 — momentary coils (c3000/c3003)
The 1.x coil block (ma_de_812049 Rev.1) consists of momentary command bits, not status signals: the controller executes a request the moment the bit is set and the bit immediately falls back to 0 (verified on real 1.7 hardware, issue #319). The coils therefore carry no state entities:
- c3003 — Anforderung Vorrangladung backs the Request DHW priority charge button (see Button): a single-coil write of ON (function code 05), the 1.x hot-water boost. No switch exists by design — a switch would also write OFF, which a momentary command bit must never receive.
- c3000 — Störung quittieren backs the Acknowledge errors button (see Services), single-coil write (FC05) on the 1.x family and holding-register write on the shared Navigator 2.0/10 family.
- c3001/c3002 — Anforderung Heizen/Kühlen are not exposed: requesting heating or cooling is what the operating-mode selects are for.
Numbers (Writable)
DHW
| Entity | Register | Range |
|---|---|---|
dhw_setpoint |
1032 | 35–95 °C |
dhw_charge_on_temp |
1033 | 30–50 °C |
dhw_charge_off_temp |
1034 | 46–67 °C |
Heating Circuit (per circuit)
| Entity | Register | Range |
|---|---|---|
hc_{x}_room_setpoint_heat_normal |
1401+ | 15–30 °C |
hc_{x}_room_setpoint_heat_eco |
1415+ | 10–25 °C |
hc_{x}_room_setpoint_cool_normal |
1457+ | 15–30 °C |
hc_{x}_room_setpoint_cool_eco |
1471+ | 15–30 °C |
hc_{x}_heating_curve |
1429+ | 0.1–3.5 (step 0.1, expert) |
hc_{x}_heating_limit |
1442+ | 0–50 °C |
hc_{x}_cooling_limit |
1484+ | 0–36 °C |
hc_{x}_parallel_shift |
1505+ | 0–30 (expert) |
hc_{x}_ext_room_temp |
1650+ | 15–30 °C |
Entries marked expert shape the heating curve of the whole installation and
write to EEPROM registers. They are created disabled on new installations —
enable them under Settings -> Devices & Services -> IDM Heatpump -> Entities.
Existing installations keep whatever state the entity already had.
hc_{x}_setpoint_flow_constant and hc_{x}_setpoint_flow_cooling are expert
entities for the same reason.
hc_{x}_ext_room_temp can be controlled manually like any other number entity
or filled automatically by optional room temperature forwarding. When
forwarding is enabled, selected Home Assistant temperature sensors are written
to these external room temperature registers on state changes and periodically
with a 300 second default interval.
GLT / External Control
| Entity | Register |
|---|---|
ext_outdoor_temp |
1690 |
ext_humidity |
1692 |
ext_demand_temp_heating |
1694 |
ext_demand_temp_cooling |
1695 |
glt_temp_demand_heating |
1696 |
glt_temp_demand_cooling |
1698 |
glt_heat_storage_temp |
1716 |
glt_cold_storage_temp |
1718 |
glt_dhw_temp_bottom |
1720 |
glt_dhw_temp_top |
1722 |
Power Limits
These registers are model-dependent and disabled by default. Do not use them for legal or contractual load control until the behavior is verified for your exact hardware and firmware.
| Entity | Register |
|---|---|
power_limit_hp |
4108 |
power_limit_cascade |
4112 |
Selects
| Entity | Register | Options |
|---|---|---|
system_mode |
1005 | Standby, Automatic, Absent, Hot Water Only, Heating/Cooling Only |
hc_{x}_mode |
1393+ | Off, Time Program, Normal, Eco, Manual Heat, Manual Cool |
solar_mode |
1856 | Off, Automatic, Manual |
isc_mode |
1874 | Off, Automatic, Manual |
Switches
| Entity | Register | Description |
|---|---|---|
demand_heating |
1710 | External heating demand |
demand_cooling |
1711 | External cooling demand |
demand_dhw_charging |
1712 | External DHW charge demand |
demand_onetime_dhw |
1713 | One-time DHW charge |
Climate
Climate entities combine a mode selector and a temperature target into the standard Home Assistant thermostat card. Two types are created:
Heating Circuit Climate (climate.hc_x)
One per configured heating circuit (A–G). Controls the circuit operating mode and its normal (day) room setpoint temperature.
| Control | Register | Notes |
|---|---|---|
| HVAC mode | hc_{x}_mode |
Off, Time Program, Normal, Eco, Manual Heat, Manual Cool |
| Target temperature | hc_{x}_room_setpoint_heat_normal |
Range depends on circuit config |
| Current temperature | hc_{x}_room_temp |
Room temperature sensor |
| HVAC action | hp_operating_mode |
Derives HEATING/COOLING/IDLE from heat pump status |
Zone Room Climate (climate.zm{z}_room{r})
One per configured room in each zone module. Controls the room operating mode and its temperature setpoint.
| Control | Register | Notes |
|---|---|---|
| HVAC mode | zm{z}_room{r}_mode |
Off, Time Program, Normal, Eco, Manual Heat, Manual Cool |
| Target temperature | zm{z}_room{r}_setpoint |
Range depends on zone config |
| Current temperature | zm{z}_room{r}_temp |
Room temperature sensor |
| HVAC action | hp_operating_mode |
Derives HEATING/COOLING/IDLE from heat pump status |
Writes go through the coordinator's centralized write path with optimistic updates and translated error messages.
Water Heater
A single water heater entity (water_heater.idm_heatpump) provides DHW target
temperature control with current temperature readback. Created when the target
register (dhw_setpoint) and a DHW tank temperature register exist — the
shared family reports dhw_temp_top, the Navigator 1.0/1.7 map offers
dhw_temp (tank temperature, address 1012) instead.
| Property | Register | Notes |
|---|---|---|
| Current temperature | dhw_temp_top / dhw_temp |
Shared family: top DHW tank temperature; Navigator 1.x: dhw_temp tank temperature |
| Target temperature | dhw_setpoint |
Writable setpoint (shared family 35–95 °C typical; Navigator 1.x 35–60 °C, float pair 2152–2153) |
| Operation mode | N/A | Always "Heat Pump" |
Uses the same coordinator write path as climate entities.
Button
Buttons are one-shot actions. Which buttons exist depends on the Navigator model, the feature profile and the connection mode:
| Button | Created when | Action |
|---|---|---|
| Acknowledge Errors | The register map has a writable error_acknowledge (all models) |
Writes 1 to acknowledge active errors |
| Request DHW priority charge | Navigator 1.0/1.7 (writable demand_dhw_17 coil c3003) |
One FC05 write of ON to request a Vorrangladung |
| Start DHW boost | Smart profile, writable system mode, DHW setpoint and dhw_temp_top |
Starts the restart-safe DHW boost state machine |
| Cancel DHW boost | same conditions as Start DHW boost | Cancels an active boost and restores the previous state |
| AI daily report (experimental) | AI plant adviser enabled | Generates the daily AI report on demand |
| AI weekly report (experimental) | AI plant adviser enabled | Generates the weekly AI report on demand |
| AI health explanation (experimental) | AI plant adviser enabled | Explains the health findings in free text |
| AI efficiency explanation (experimental) | AI plant adviser enabled | Explains the efficiency findings in free text |
| Reload connection | always (diagnostic) | Reloads the config entry immediately instead of waiting out the setup-retry backoff |
In a web-only entry on a Navigator 10 the web supplement adds its own acknowledge button with the same name, backed by the web interface instead of Modbus. The Modbus buttons are not created in web-only mode.
The primary button (button.idm_heatpump_acknowledge_errors) acknowledges active
errors on the heat pump by writing 1 to the error_acknowledge write-only
register. Always available so automations can trigger on alarm state changes.
On a detected Navigator 1.0/1.7 a second button
(button.idm_heatpump_request_dhw_priority_charge, Vorrangladung anfordern)
requests a DHW priority charge: a single FC05 write of ON to coil c3003.
Manual use only — the official table puts the coil block under the EEPROM
note, so it must not be driven by a schedule or a timed automation.
On at least one 1.x firmware the coil-triggered priority charge does not
terminate by itself: the controller stays in DHW mode until error 020
(Wärmepumpenvorlauf Maximaltemperatur) trips (issue #319).
If your unit behaves this way, use the system mode Warmwasser einmalig
(the system_mode select, or the DHW boost) instead — that path ends the
charge normally on the affected hardware. On verified firmware the coil
falls back to 0 immediately after the write, which is why the button never
writes OFF; please report your firmware behavior in the issue.
Optional feature entities
The optional feature packages add the entities below. The tables list every entity each package can create, with the exact name Home Assistant shows in an English installation (German installations show the German names from the translation files). Entities of a disabled feature are removed from the registry; re-enabling the feature restores the same entity IDs.
Operating analysis (Smart profile)
Derived from observed compressor, defrost and operating-mode transitions. Restart-safe: the counters persist across Home Assistant restarts, and communication gaps are never counted as operating events.
| Entity | Description |
|---|---|
Heat pump cycles recorded (analysis_heat_pump_cycles_recorded) |
Total observed compressor cycles since installation of the profile |
Heat pump cycles today (analysis_heat_pump_cycles_today) |
Compressor cycles since midnight |
Heat pump cycles last 2 hours (analysis_heat_pump_cycles_2h) |
Rolling 2-hour cycle count |
Heat pump cycles last 4 hours (analysis_heat_pump_cycles_4h) |
Rolling 4-hour cycle count |
Current cycle runtime (analysis_current_cycle_duration) |
Runtime of the currently running compressor cycle |
Average cycle runtime (analysis_average_cycle_duration) |
Mean runtime over the retained cycle history |
Last compressor start (analysis_last_compressor_start) |
Timestamp of the last observed start |
Last cycle runtime (analysis_last_cycle_duration) |
Runtime of the last finished cycle |
Last compressor cycle too short (analysis_last_cycle_short) |
Binary: the last cycle stayed below the configured short-cycle threshold |
Defrost cycles recorded (analysis_defrost_starts_recorded) |
Total observed defrost starts |
Defrost cycles today (analysis_defrost_starts_today) |
Defrost starts since midnight |
Last defrost start (analysis_last_defrost_start) |
Timestamp of the last defrost start |
Time since last defrost start (analysis_time_since_last_defrost) |
Time since the last defrost start |
Operating share heating (analysis_operating_share_heating) |
Share of the observation window spent heating |
Operating share hot water (analysis_operating_share_dhw) |
Share spent in domestic hot water mode |
Operating share cooling (analysis_operating_share_cooling) |
Share spent cooling |
Operating share defrost (analysis_operating_share_defrost) |
Share spent defrosting |
Energy statistics (Smart profile)
Persistent totals computed from the power registers and stored per config entry — day, month and lifetime. They survive restarts; the device's own register meters (energy heating, energy DHW, …) are separate entities listed under Energy & Power. Costs and CO₂ use the optional price and emission factors configured in the Smart profile.
| Entity | Description |
|---|---|
Heat pump electrical energy today / this month / total (energy_electrical_today …) |
Electrical energy the heat pump consumed in the period |
Heat pump thermal energy today / this month / total (energy_thermal_today …) |
Thermal energy delivered in the period |
Heat pump COP today / this month / total (energy_cop_today …) |
Seasonal performance factor over the period |
Heat pump COP heating today / this month / total (energy_cop_heating_today …) |
COP over the periods' pure space-heating intervals; the period's heating electrical/thermal energies are attributes. Intervals with mixed, defrost, cooling or unknown operating modes stay in the all-mode totals and never bias the per-mode values. Per-mode counting starts when the feature is installed — the values are not reconstructed from earlier totals |
Heat pump COP hot water today / this month / total (energy_cop_dhw_today …) |
Same as the heating row, for pure hot-water charging intervals |
Heat pump electricity cost today / this month / total (energy_cost_today …) |
Electricity cost of the period |
Heat pump CO₂ emissions this month / total (energy_co2_month, energy_co2_total) |
CO₂ emissions of the period |
Heat pump PV self-consumption today / this month / total (energy_pv_self_consumed_today …) |
Electrical energy attributed to PV surplus in the period |
Health monitor (Smart profile option)
Read-only problem checks plus one combined report. Every check is a binary
sensor that turns on when its criterion is met; the report bundles the
findings as attributes.
| Entity | Description |
|---|---|
iDM health report (health_report) |
Combined report of all findings, with details as attributes |
Communication problem (health_communication) |
Repeated Modbus communication failures |
Recurring heat-pump alarms (health_recurrent_alarms) |
Alarm signal returns repeatedly |
DHW does not reach target (health_dhw_not_reaching_target) |
Hot water stays below its setpoint under load |
COP unusually low (health_low_cop) |
Observed COP is below the expected range |
Too many compressor starts (health_many_compressor_starts) |
Compressor start count exceeds the configured limit |
Compressor cycles getting shorter (health_shortening_cycles) |
Cycle runtimes shrink over time — a classic wear indicator |
Defrost cycle unusually long (health_long_defrost) |
A defrost cycle runs far longer than usual |
Implausible sensor value (health_implausible_sensor) |
A sensor reports a physically implausible value |
Comfort advisory (Smart profile options)
Read-only recommendations, one entity each:
| Entity | Description |
|---|---|
Heating curve advice (heating_curve_advice) |
Compares flow temperature with the requested setpoint: increase, decrease or stable |
Weather preheat advice (weather_preheat_advice) |
Watches the configured HA weather entity and recommends preheating before a forecast cold front |
The heating-curve entity is created for the circuit selected in the comfort schedule option; the weather entity requires a configured weather integration.
Predictive advisor (Smart profile option)
Strictly read-only recommendation framework — the advisor never writes to the
heat pump. See Predictive Advisor for thresholds,
observation levels and the idm_advisor_recommendation event.
| Entity | Description |
|---|---|
Advisor status (advisor_status) |
Lifecycle: warm-up, learning, active, insufficient data |
Advisor recommendations (advisor_recommendations) |
Current recommendations as text |
Advisor confidence (advisor_confidence) |
Confidence level of the current recommendations |
Advisor operation reason (advisor_operation_reason) |
Why the heat pump is running right now |
Advisor health score (advisor_health_score) |
Plant condition score |
Advisor efficiency score (advisor_efficiency_score) |
Efficiency score |
Advisor expected COP (advisor_expected_cop) |
COP expected from the learned building model |
Advisor building heat loss (advisor_building_heat_loss) |
Learned heat loss in kW |
Advisor building thermal inertia (advisor_building_thermal_inertia) |
Learned thermal inertia |
Advisor optimal flow temperature (advisor_optimal_flow_temp) |
Model-optimal flow temperature |
Advisor heating curve {circuit} recommendation (advisor_curve_recommendation) |
Heating-curve recommendation per circuit |
Advisor hot water recommendation (advisor_dhw_recommendation) |
PV/price-optimized hot-water window recommendation |
Advisor predicted heat demand 24h (advisor_predicted_heat_demand) |
Predicted heat demand for the next 24 hours |
Advisor 24 hour plan (advisor_next_24h) |
The advisor's 24-hour plan |
Advisor optimization available (advisor_optimization_available) |
Binary: a recommendation is ready to apply |
Advisor anomaly detected (advisor_anomaly_detected) |
Binary: current behavior deviates from the learned baseline |
AI plant adviser (experimental, off by default)
Deterministic measured-data reports with optional free-form explanations via local Ollama, an HA AI Task entity or explicitly consented cloud requests. See Experimental AI Adviser and Local Ollama for the privacy boundary.
| Entity | Description |
|---|---|
AI report (experimental) (ai_report) |
The latest generated report; coverage details as attributes |
AI learning status (ai_learning_status) |
State of the bounded local learning |
AI storage used (ai_storage_used) |
Storage the learned baselines occupy |
AI observed coverage (ai_coverage) |
Share of the report's data the adviser could actually observe |
AI observed COP (ai_observed_cop) |
COP from the observed data window |
AI daily report (experimental) (ai_report_daily) |
Button: generate the daily report on demand |
AI weekly report (experimental) (ai_report_weekly) |
Button: generate the weekly report on demand |
AI health explanation (experimental) (ai_report_health) |
Button: explain the health findings |
AI efficiency explanation (experimental) (ai_report_efficiency) |
Button: explain the efficiency findings |
The four buttons are also listed under Button. With the device hierarchy disabled the AI entities still move to their own iDM KI-Anlagenberater device — the AI group is the one sub-device that exists regardless of the hierarchy option.
Assist agent (always on)
A local, deterministic conversation entity. It answers natural-language questions about the running plant — why the heat pump is running, advisor recommendations, temperatures, hot water, consumption/COP and status — in German or English. Everything is computed from the local coordinator snapshot by keyword routing; no utterance leaves the instance and no language model is involved. See Configuration → Assist.
| Entity | Description |
|---|---|
Assistant (assist_agent) |
Conversation agent: ask it about the plant in Assist (text or voice) |
Device groups (device hierarchy)
With Device hierarchy enabled (Configure → Features), the integration
distributes its entities over sub-devices so the main heat-pump device stays
focused on the controller. These groups are child devices of the heat pump;
an upgrade from an older integration release converts the previously
via_device-linked devices in place, keeping their device IDs. Zone modules
stay ordinary linked devices — separate hardware, not a logical part — and
their rooms are children of the module.
| Group | Created when | Contains |
|---|---|---|
| Heizkreis A–G | Circuit enabled in the plant configuration | All hc_{x}_* registers plus the web flow, room, mixer and pump values of that circuit |
| Zone module (e.g. Zonenmodul 1) | Zone module with rooms configured | Module-level zm{z}_* registers; linked device (via_device), not a child |
| Zone room | Room configured in its zone module | zm{z}_room{r}_* entities as children of the zone module |
| Solaranlage | Solar registers present | solar_* entities |
| IDM ISC | ISC registers present | isc_* entities |
| IDM Kaskade | Cascade enabled | cascade_* entities |
| Zusatzwärmeerzeuger | Booster/bivalence/second-generator/e-heating registers present | booster_*, bivalence_*, second_heat_generator_*, eheating_*, electric_heater_* |
| Warmwasser | DHW registers present | dhw_*, hotwater_*, water_temp_* and related keys |
| Photovoltaik | PV registers or SG-Ready present | pv_*, smart_grid_status, PV surplus operation, web demand reason and web energy flow |
| Diagnose | Always | Versions, internal message, Modbus poll health, controller online time |
| iDM Analytics | Smart profile | Calculated sensors, operating analysis, energy statistics |
| iDM Health Monitor | Health monitor enabled | All health_* entities |
| iDM Comfort | Comfort advisory enabled | Heating curve advice, weather preheat advice |
| iDM KI-Anlagenberater | AI adviser enabled | All ai_* entities — also without the hierarchy option |
The predictive advisor entities (advisor_*) deliberately stay on the main
heat-pump device: they describe the plant as a whole, not one removable
module. Disabling the hierarchy moves every group back onto the main device
(except the AI group); entity IDs never change either way.
Zone Modules
For each enabled zone module (up to 10), room-level entities are created:
| Entity per room | Description |
|---|---|
zm{z}_room{r}_temp |
Room temperature |
zm{z}_room{r}_setpoint |
Room setpoint (writable) |
zm{z}_room{r}_humidity |
Room humidity |
zm{z}_room{r}_mode |
Room operating mode |
zm{z}_room{r}_relay |
Relay status (binary_sensor: on/off) |
Plus per-zone: zm{z}_mode_heat_cool, zm{z}_dehumidification
Differential-temperature controlled heating circuits
For a Navigator 10 circuit configured as Differential temperature control (German controller label: Differenztemperaturgeregelt), select the circuit in Configure → Plant → Differential-temperature controlled circuits, as well as in the installed heating-circuit list. In the advanced form the same selection appears next to Heating circuits. The default is an empty list; normal heating circuits keep their existing behavior. The manual selection is authoritative and separate from the controller's internal differential-control module; with a configured web PIN, Navigator 10 circuits of this type are additionally detected automatically through the local web interface.
For HC D, the measurements reported in issue #429 are mapped as follows; other selected circuits use their corresponding library registers rather than fixed HC D addresses:
| Entity | HC D source | Meaning |
|---|---|---|
| Storage temperature | hc_d_flow_temp (1356) |
Storage measurement |
| Reference temperature | hc_d_room_temp (1370) |
Reference measurement |
| Temperature difference | Reference minus storage | Signed difference in K; 22.63 − 41.83 = −19.20 K |
| Differential control status | hc_d_active_mode (1501) |
255 is standby in this circuit context; 0/1/2 retain the documented off/heating/cooling meanings |
| Heating-circuit pump | pump_heating_circuitD |
Actual pump state, when the local web supplement provides it |
The difference is available in every feature profile. Missing, unsupported or invalid measurements produce no usable difference. Status does not substitute for a pump measurement or infer charging from the temperature difference.
Migration: the storage and reference sensors keep their original unique
IDs and existing entity IDs (hc_d_flow_temp / hc_d_room_temp); their default
names change, while user-customized names remain under user control. Existing
automations referencing these IDs continue to work. Normal circuit setpoints,
heating curves, heating/cooling limits, external room-temperature inputs,
climate entities, flow deviation and web mixer/flow sensors are removed from
the registry for selected differential circuits. Update dashboards and
automations that referenced those controls. Turning the option off recreates
normal circuit entities and removes the difference sensor; customizations of
removed controls are not preserved.
Entity IDs: the circuit device is named Heizkreis D and carries the type
as its model (Differential temperature control), because Home Assistant
prefixes every new entity ID of a device with the device-name slug — a type
suffix in the name would double the length of every ID. Entity IDs registered
while the device name still ended in (Differenztemperaturgeregelt)
(0.20.1-b1…b4) are shortened automatically on the next start:
sensor.heizkreis_d_differenztemperaturgeregelt_temperaturdifferenz_hk_d
becomes sensor.heizkreis_d_temperaturdifferenz_hk_d. Update dashboards
written against those long prerelease IDs; entity IDs you renamed yourself and
short IDs already owned by another entity are left untouched.
Unverified parameters: the API does not provide a circuit-type detection
register or confirmed differential hysteresis/threshold/maximum-temperature
registers. In particular, the reported 60 °C at hc_d_setpoint_flow_constant
(1452) is not enough to identify it as the differential threshold. These
parameters are deliberately not exposed under guessed names and no new
writes are added. This mapping is based on the Navigator 10 report in #429;
it still needs confirmation on the reporter's hardware.
Independent firmware observations
Under Reconfigure → Firmware query, a separate explicit switch enables Latest reported firmware. It is off by default and never inherits consent from telemetry. Firmware-only operation works without a myIDM ID or telemetry. Disabling telemetry does not disable separately authorized firmware queries. Disabling firmware queries cancels the request and removes the sensor and its registry entry immediately. Without firmware consent there is no catalog contact.
The query sends only Navigator family, controller/plant model and installed firmware, after a random startup delay of up to 30 minutes, then every six hours plus up to 30 minutes of random delay. It sends no myIDM ID, operating counters, temperatures, credentials or other HA data. There is no persistent firmware queue; the integration keeps only the current result. HA may retain sensor states according to the local Recorder/backup configuration. The server uses metadata transiently and does not save a plant report. The connection IP is technically visible; short-lived rate identifiers expire within two hours at the next hourly cleanup. Both features have a prominent link to the full privacy notice before their consent switch.
The catalog uses community telemetry observations only, never old diagnostic ZIPs. Matching requires the same Navigator/controller and known plant model, firmware prefix/channel and major line. Missing plant types match only other missing-type reports in that same known controller/software series. Test and stable channels remain separate. Ordering includes numeric build numbers. Unknown metadata or absent observations produce no version recommendation.
This is not official IDM availability, installation permission or compatibility
approval. Only IDM/your installer can assess and install firmware. Sharing
telemetry helps build the catalog, but is not required to use firmware queries.
Telemetry notice v3 remains unchanged; independent firmware consent uses
idm-firmware-v1. The locally recorded consent time/revision is not sent in
firmware queries. Only telemetry uploads carry their own identity and consent.
With device hierarchy enabled, Latest reported firmware and the unconfirmed newer-version indicator belong to the logical Diagnostics device alongside the installed software version. Without hierarchy they remain diagnostic entities on the plant device. Existing unique IDs and entity history are preserved. A newer matching observation can create a Repairs notice; acknowledgement is persisted per device/version. See activation and interpretation.