Skip to content

fix(text): 🩹 rename the DHW schedule entities to blocking times - #786

Merged
rhammen merged 1 commit into
mainfrom
chore/rename-dhw-blocking-times
Sep 4, 2026
Merged

fix(text): 🩹 rename the DHW schedule entities to blocking times#786
rhammen merged 1 commit into
mainfrom
chore/rename-dhw-blocking-times

Conversation

@rhammen

@rhammen rhammen commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

🔍 What this fixes

In #785 a reporter set text.luxtronik2_timer_dhw_schedule_week to 00:00-23:59 believing it meant "always allowed", and thereby blocked automatic hot water heating 23 h 59 m per day. His diagnostics dump confirms it: P0405 ID_Einst_SUBW_akt2 = week, P0406/P0407 = 00:00/23:59. He then spent several days debugging a heat pump that was doing exactly what it was told.

DHW schedule windows are blocking windows — the controller calls them Sperrzeiten — which is the opposite polarity from the heating circuit's raise/setback windows. TIMER_SCHEDULES.md already documented this correctly, and the reporter quoted it himself after the fact. So the documentation was not the gap: the mistake happens in the Home Assistant UI, before anyone opens the docs. The entity name is where the meaning has to be visible.

✨ Changes

Entity display names (custom_components/luxtronik2/translations/{en,de,nl,cs,pl}.json) — all 10 timer_dhw_schedule_* keys in each of the five languages:

before after
en DHW Timer Schedule (Week) DHW Blocking Times (Week)
de Warmwasser-Zeitschaltplan (Woche) Warmwasser-Sperrzeiten (Woche)
nl Warmwater tijdschema (week) Warmwater blokkeertijden (week)
cs Časový plán teplé vody (týden) Blokovací časy teplé vody (týden)
pl Harmonogram czasowy ciepłej wody (tydzień) Czasy blokady ciepłej wody (tydzień)

German uses the controller's own term, so the entity name matches what the user sees on the physical panel.

Documentation:

  • TIMER_SCHEDULES.md — DHW entity table renamed to match, plus a ⚠️ callout stating that an empty field means "no restriction" and that a whole-day window blocks DHW around the clock.
  • README.md §2.4.1 — names the entities and repeats the warning in one sentence.

Deliberately untouched: the heating and ventilation schedule entities. Their windows really are raise/setback schedules, and the contrast with DHW is precisely the point being made.

No Python changed. Entity IDs are unaffected: _timer_schedule_unique_id() (text.py:37-48) builds the id from description.key and the config entry prefix, and text.py:369-370 reuses that string as the unique_id; _attr_name is never set anywhere. Fresh installs derive the id from the key, existing installs recover it from the registry via the unchanged unique_id. No automations, dashboards or templates break.

🧪 Tests

No new tests — this changes display strings and documentation only, and the existing translation guards (test_translation_files_are_valid_json, test_translation_files_use_literal_utf8, the key-completeness checks) already cover the files that changed.

Full run on the branch: 1219 passed, 1 skipped, coverage 100% (unchanged). codespell clean, git diff --check clean. All five locale files verified: no BOM, LF endings, literal UTF-8, 10/10 keys changed each.

Reviewed by a code-review subagent, which independently verified the entity_id stability claim in text.py rather than taking it from the description, and confirmed no stale references to the old names remain in shipped content. Two markdown consistency fixes from that review are folded in.

⚠️ Upgrade notes

The DHW timer schedule entities are now called DHW Blocking Times instead of DHW Timer Schedule (German: Warmwasser-Sperrzeiten). This is a display-name change only — the entity IDs such as text.luxtronik2_timer_dhw_schedule_week are unchanged, so automations, dashboards and templates keep working and nothing needs to be adjusted by hand.

The new name reflects what these entities have always done: each window is a period in which automatic hot water heating is switched off. Leave the field empty for no restriction. A window covering the whole day, such as 00:00-23:59, blocks hot water heating around the clock.

If you previously renamed one of these entities yourself, Home Assistant keeps your custom name and you will not see the new one.

🤖 Generated with Claude Code

- rename the 10 `timer_dhw_schedule_*` entity display names in all five
  languages: "DHW Timer Schedule (Week)" becomes "DHW Blocking Times (Week)",
  German uses the controller's own term *Sperrzeiten*
- update the DHW entity table in TIMER_SCHEDULES.md and section 2.4.1 of the
  README to match, and add a callout that an empty field means "no
  restriction" while a whole-day window blocks DHW around the clock
- leave the heating and ventilation schedule entities alone: their windows
  really are raise/setback schedules, and the contrast with DHW is the point

A reporter configured the DHW week schedule to `00:00-23:59` believing it
meant "always allowed" and blocked automatic hot water heating 24/7. The
documentation already described the blocking semantics correctly, but the
mistake happens in the Home Assistant UI before anyone opens the docs, so
the entity name is where the meaning has to be visible.

Display names only - no Python changed. Entity IDs are unaffected because
`_timer_schedule_unique_id()` (text.py:37-48) builds them from
`description.key` and the config entry prefix, and `text.py:369-370` reuses
that string as the unique_id; `_attr_name` is never set. Fresh installs
derive the id from the key, existing installs recover it from the registry
via the unchanged unique_id, so no automations or dashboards break.

Note that a user who renamed one of these entities in the UI keeps their
custom name: Home Assistant refreshes `original_name` on restart but never
overwrites a user-set `name`.

Refs #785

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Code Coverage

Package Line Rate Health
custom_components.luxtronik2 100%
Summary 100% (3718 / 3718)

@rhammen
rhammen merged commit 58b6638 into main Sep 4, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant