Upgrading¶

Restart Home Assistant after any HACS update. Notes are newest first; you only need to read the entries between your current version and the one you are moving to.

To 4.3.0¶

Hot-water cylinders are now handled as cylinders rather than as room heaters, the temperature guard covers more than the 255 sentinel, and the cumulative energy sensors can show the figure the cloud is actually sending.

Hot-water cylinders lose the room-heater entities¶

A cylinder reports its water target — 45 °C, say — in the same field a room heater uses for its room target. It was therefore being set up as a room heater: a thermostat with a 7–30 °C range that rejected the cylinder's real target, plus room temperature, open window, EcoStart, setback, comfort, away, frost protection, advance and boost-duration entities that a cylinder has no use for. Room-heater features are now stripped from a hot-water appliance unless it also reports a room temperature, and the switches and binary sensors are capability-gated like the sensors already were.

On an existing cylinder those entities become "no longer provided". That is expected, and safe to remove from the entity registry. In their place:

• A read-only Water heater entity — the app's mode (standby / timer / holiday / boost / hygiene) and the water target.
• Hot water available, now in litres and enabled by default, matching the app's "336 L Hot water". The previously disabled entity keeps its disabled state.
• Hot water capacity, Hot water mode, Hygiene recurrence and Holiday days, with Heating water, Green energy and Holiday binary sensors.
• A Holiday switch and a Holiday ends datetime, verified against a live cylinder.
• A read-only Hot water schedule sensor, read from the heat-pump endpoint.

Writing that schedule is not offered: UpdateHeatPumpHwcSchedulePeriods answered HTTP 403 to every request shape tried, so it stays a read. Room heaters are unchanged by any of this. See Entities for the full list.

Nonsensical temperatures become unknown everywhere¶

The climate card only filtered the cloud's 0xFF "no value" sentinel, so any other impossible reading — a glitch reporting 200 °C — reached the thermostat and the temperature sensors as-is. A reading outside −40…80 °C, as well as the sentinel, now reads as unknown; setpoint reads are checked against the tighter 7–30 °C band. Genuine ambient readings outside 7–30 °C are unaffected.

The cumulative energy sensors show the unheld total¶

Energy lifetime and Energy T2 lifetime report the highest total seen, so a truncated cloud read cannot look like a meter reset. The cost is that a permanently reduced history is held at the old peak rather than reported, so the sensors now also carry raw_total (what the cloud is sending now) and peak_total, and a suppressed drop of more than 10% logs a warning. If raw_total sits below the state across consecutive polls, the cloud has lost history for that appliance — see Troubleshooting.

To 4.1.1¶

A fix for energy statistics, and nothing else. If you are on 4.1.0, upgrade — that release took the Energy lifetime sensors off the Energy Dashboard and raises a repair for each one.

• The lifetime sensors are meters again. 4.1.0 removed their state class on the belief that they were rolling 30-day windows. They are not: the cloud returns the appliance's full available history, so the figure rises like a meter and total_increasing was right. The state class is restored, they are selectable on the Energy Dashboard again, and the repairs clear themselves once Home Assistant resumes recording.
• The value can no longer fall. A truncated cloud response used to make the sum dip, and Home Assistant reads a fall of more than 10% on a rising meter as a meter reset — adding the whole total to statistics again. The highest value seen is now what gets reported, and it survives a restart.
• The names go back: Energy lifetime / Energy T2 lifetime. The misleading window_days attribute is gone — it claimed a fixed 30 days the data never matched — but window_start and window_end still show the real span.

If your recorded history was inflated under the older bug it stays inflated; see the 4.1.0 notes below for how to delete it.

To 4.1.0¶

Behaviour fixes plus new control surface. Everything in the first list is a correction — if you were working around any of it, stop. The new entities and actions at the end change no existing configuration.

• Setting a target no longer rewrites your schedule. Writes go through the cloud's dedicated setpoint endpoint, with the old schedule rewrite kept only as a fallback for appliances that reject it. See setting a target.
• HVAC off engages frost protection at 7 °C, which is how the official app turns a heater off. The entity will report a 7 °C target when off — this is correct. See why "off" reports 7 °C.
• Boost and away actually engage the right modes. Earlier releases assumed boost was mode bit 16 and away bit 32; those are in fact Advance and FrostProtect. Asking for boost engaged advance instead. The corrected values are listed in Modes & presets.
• Presets are mutually exclusive. Selecting one now clears the others, so switching straight from away to eco works. Previously each preset only added its own state, and because the entity resolves boost before away before EcoStart, the change appeared to do nothing.
• Away is capped at 18 °C, the range the cloud actually accepts. Values above 18 are clamped with a log warning instead of being silently reduced.
• Away accepts a duration — days or until.
• Advance is controllable via dimplex.set_advance / dimplex.clear_advance.
• Four new diagnostic sensors expose the engaged modes individually: boost, away, frost protection, advance.
• A dropped connection can no longer wipe your schedule. The schedule-rewrite fallback now runs only when the appliance genuinely refuses the setpoint endpoint (HTTP 403, 405, 501). A timeout or a server error is reported as an error and writes nothing, and when the fallback does run it says so in the log. See setting a target.
• Room temperature no longer shows 255 °C. The cloud's 0xFF "no value" sentinel was being passed through by the climate entity, while the room-temperature sensor beside it correctly showed nothing.
• Failed switches and actions explain themselves. A refused EcoStart toggle or dimplex.set_boost used to surface a raw traceback; every control now produces the same readable message the thermostat has given since 4.0.2, and distinguishes "this appliance will not do this" from "the cloud was unreachable".

New entities and actions¶

New control surface; no configuration changes, and nothing existing is removed.

• Controls are gated on the cloud's own capability matrix. The integration now fetches the account's product catalogue, so an appliance the library says cannot take a control no longer offers it — and the hot-water / heat-pump flags are derivable for the first time. An appliance affected by this gains or loses an entity it could not have used anyway; diagnostics list the resolved flags per appliance, which is the place to look if a control is missing.
• Setback is writable. A new Setback target number entity per capable appliance writes the reduced temperature instead of only reporting it. See Entities.
• The weekly schedule can be edited from Home Assistant, through two actions: dimplex.copy_schedule applies one appliance's programme to others, and dimplex.set_period_setpoint changes one period's target. See Actions.
• Hot water cylinders have a control surface for the first time. Two actions, dimplex.set_hot_water_temperature and dimplex.set_hot_water_hygiene, plus a disabled-by-default diagnostic sensor. All of it is untested against real hardware — see appliance support.
• The Boost preset's length now follows the appliance when the Boost duration option has never been set, instead of always using a fixed 60 minutes. If you set that option, nothing changes.

After upgrading¶

• Confirm the config entry loaded without requirement errors in the log.
• If you had automations working around boost engaging the wrong mode, remove the workaround.
• If any appliance is stuck reporting off, toggle it on once — this restores user-timer mode on appliances an earlier release parked in the frost/off timer mode.
• Enable the new mode binary sensors if you want them on a dashboard; they are diagnostic and off by default.
• And if you have a hot water cylinder: enable its Hot water available diagnostic sensor and compare the number it shows against the official app. It is deliberately unitless because nothing documents what that field measures, so what it reports is genuinely useful — please say so on the issue rather than assuming.
• If an Energy lifetime sensor was a consumption source, remove it, add Energy today instead, and delete the old statistic if the history looks inflated.

To 3.0.0¶

A major release relative to 2.0.0.

Breaking and behavioural changes¶

• Climate entities are created per appliance. Prefer them for setpoints and for the boost / away / eco presets.
• Energy became two sensors: Energy lifetime and Energy today (local calendar day from midnight). Prefer Energy today for the Energy Dashboard.

The three-year detour: 4.1.0 briefly renamed the lifetime sensor to Energy last 30 days and removed its state class, on the belief that it was a rolling window. It never was — the cloud returns the appliance's full history — and 4.1.1 put the name and the state class back. If you are coming from 3.x, both are as they should be.

• Entity unique IDs and names may change. EcoStart gained a stable _ecostart suffix, and open-window detection became a switch as well as a binary sensor. Expect some renamed entities and a one-off orphan cleanup.
• Polling is split into a short status interval and a longer energy interval, both configurable in options.
• Diagnostic entities — error and warning codes, last telemetry, rated power, charge capacity, Energy T2 — exist but are disabled by default. Enable them in the entity registry if you need them.

After upgrading¶

• Confirm the config entry is loaded, with no import or requirement errors in the log.
• Review the new climate.* entities and the energy sensors.
• Re-point automations that used old entity IDs.
• For the Energy Dashboard use Energy today. (In 4.1.0 the window sensors can no longer be selected as a consumption source at all.)

Requirements¶

Any recent version needs:

• Home Assistant 2026.9 or later.
• dimplex-controller>=0.15.1, installed automatically from the integration requirements.

If an upgrade goes wrong¶

• Entities missing → check the platform is enabled in options, then restart.
• Entities unavailable → usually the cloud returning an empty overview, not the upgrade. See entities are unavailable.
• HACS offering an older version → see HACS shows an update after installing a pre-release.

Full detail for every release is in the changelog.