docs: the on-setting is wrong on entry and right after it by eman · Pull Request #143 · eman/nwp500-python

eman · 2026-09-20T19:50:15Z

#142 established that switching into an element mode engages the element on a
differential the device does not publish, and concluded that
heUpperOnTempSetting "is not being driven by that field". The first half is
right; the generalisation is not — and it left this reference contradicting
itself, since data_conversions.rst describes these fields as thermostats while
#142's warning said flatly that they do not predict when an element runs.

Both were true only of the moment a mode is switched.

Later in the same stint, the published description is exactly right

From one unit's recorded history:

Mode	mid-stint starts	probe in 39.4–41.1 degC	median vs `heUpperOnTempSetting`
`ENERGY_SAVER`	23	17	0.2 degC below
`HIGH_DEMAND`	12	0	2.1 degC below

In ENERGY_SAVER the on-setting rests at 40.5 degC and the element comes on as
the probe reaches it — the field working as documented.

HIGH_DEMAND is the contrast that makes the point: its on-setting tracks the
setpoint, and its mid-stint starts come 2.1 degC below that, nowhere near the
device-minimum band. That differential is real and published nowhere.

So entry is the exception and the reference description is the rule.

What changed

heating-elements.rst — the summary row narrowed to "on entry", a new row
for later in a stint, and the "what the on-setting does and does not tell you"
section rewritten with a per-mode entry/mid-stint table.
data_conversions.rst — the warning docs: what the heating elements actually do #142 added said flatly that these
fields do not predict when an element runs. It now says which rule applies
when.
device_status.rst — same narrowing.
CHANGELOG.rst — the entry is still Unreleased and is docs: what the heating elements actually do #142's own, so it
is amended rather than contradicted; nothing has shipped with the broad claim.
Limits — "what engages the element later in an Energy Saver stint" was
listed as not established. It now is, from history. What remains unestablished
is Electric's mid-stint behaviour, which has only two starts on record.

A sampling note that travels with the figures

An earlier revision of this PR claimed the element binary sensors assert
one-minute elements the meter never sees. That was wrong — an adversarial
review of the analysis caught it, and the commit history here shows the
correction.

The short elements are real. On 2026-04-12 the flag ran 22:21:58 → 22:22:18
and currentPower inside reads 5558 W and 5547 W, compressor steady at
~470 W either side. The "538 W" that made it look phantom was the last sample
at or before the minute boundary — a one-minute resample using a backward
as-of join instead of a maximum. currentPower samples at a median 30 s with
24 % of gaps over a minute, so a sub-minute burst falls between the samples
such a resample keeps.

What is true, and more useful: element runs come in two lengths. Of 128 raw
upper-element runs, 31 (24 %) are under a minute — median 9 s — and together
carry 0.8 kWh across nine months against 97.9 kWh for the other 97. A
20-second burst moves the probe ~0.1 degC, at its own resolution. So resample
power with a maximum or work from raw edges, and filter on duration or
energy when predicting recovery.

No mid-stint figure in this PR changes. The review confirmed the Energy
Saver and High Demand results are identical with or without the power filter.

Scope

These are history-derived, not commanded runs, and the page labels them that
way — #142's bounded device runs remain the source for the entry thresholds.
he_upper_on is recorded for only 8 of the 23 Energy Saver starts and 6 of the
12 High Demand ones; the rest rest on the probe clustering in the same band.

Docs build clean (no new Sphinx warnings against baseline).

Refs #142

Update: confirmed on the device, and two retractions

The Energy Saver on-point is now confirmed by a commanded run (one unit, 2026-09-21), not just history. History could not separate "at heUpperOnTempSetting" from "a fixed gap below the setpoint", because the setpoint barely moved. With it lowered to 42.0 degC, a fixed gap predicted engagement near 22 degC; the element engaged three times at an upper-probe reading of 39.8 degC. Cautions: all three came with water moving through the tank, and the working threshold may be a little under the published 40.5.

Also added, each with its n: the element runs to ~0.9 degC under the setpoint-tracking heUpperOffTempSetting rather than to a fixed point; raising the setpoint in ENERGY_SAVER starts the element through the entry rule (n = 1); and demand versus temperature alone cannot be separated from these runs.

Retracted:

The short-element warning said a 20 s burst "heats nothing" (~0.1 degC). That used the whole tank's heat capacity; it is ~0.3 degC, and 41–58 s bursts measured 0.7–1.5 degC. Counts restated on a clean basis: 115 upper-element runs, 20 under a minute, median 16 s.
The page said heUpperOnTempSetting rests at 40.5 degC in HEAT_PUMP as well as ENERGY_SAVER. It does in Energy Saver (96 % of minutes); in Heat Pump only 48.5 %, and the other values match the current setpoint only 6 % of the time. Now marked unreliable in Heat Pump mode.

Docs build clean against baseline.

#142 established that switching into an element mode engages the element on a differential the device does not publish, and concluded that heUpperOnTempSetting "is not being driven by that field". The first half is right. The generalisation is not, and it made this reference contradict itself: data_conversions.rst describes these fields as thermostats, #142 added a warning saying they do not predict when an element runs, and both were then true only of the moment a mode is switched. Later in the same stint the published description is exactly right. In 23 mid-stint upper-element starts in ENERGY_SAVER, drawn from one unit's recorded history, 17 have the probe in the 39.4-41.1 degC band where heUpperOnTempSetting rests, and where the field itself is recorded the median start is 0.2 degC below it. The element comes on as the probe reaches the on-setting. HIGH_DEMAND is the contrast that makes the point: its on-setting tracks the setpoint, and 12 mid-stint starts came a median 2.1 degC *below* it, none anywhere near that band. That differential is real and published nowhere. So entry is the exception and the reference description is the rule. Narrowed in four places: the explanation page's summary row and its "what the on-setting does and does not tell you" section, which now carries a per-mode entry/mid-stint table; data_conversions.rst's warning, which said flatly that these fields do not predict when an element runs and now says which rule applies when; device_status.rst's note; and the unreleased changelog entry, amended rather than contradicted since nothing has shipped with the broad claim. One measurement note travels with the new figures, because anyone repeating this will hit it. This unit's element binary sensors assert one-minute elements the power meter never sees: 9 of 112 apparent upper-element starts drew 750 W or less, against 5.1-5.6 kW for a real one, while every run of two minutes or more was genuine. Element starts counted from those sensors alone are overstated. Every figure here is corroborated against the whole-unit power reading. These are history-derived, not commanded runs, and the page says so. Refs #142

Copilot

Copilot review overview

🟡 Changes recommended

Resolve the remaining mode-scope, evidence-coverage, and measurement-cutoff inconsistencies.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 4

Open (4)

Scope later-stint conclusion to mode-dependent behavior · New
Resolve contradiction about later-stint behavior · New
Limit later-stint claim to Energy Saver or qualify it · New
Make later-stint behavior statement mode-specific · New

What changed in this PR

This pull request refines heating-element documentation by distinguishing mode-entry behavior from later in-stint behavior.

Changes:

Documents Energy Saver and High Demand behavior and measurement limitations.
Updates protocol warnings and device-status notes.
Amends the unreleased changelog entry.

File	Summary
`docs/reference/protocol/device_status.rst`	Updates heating-element behavior notes.
`docs/reference/protocol/data_conversions.rst`	Clarifies thermostat-field applicability.
`docs/explanation/heating-elements.rst`	Documents entry, mid-stint behavior, and evidence caveats.
`CHANGELOG.rst`	Records the revised findings and measurement details.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

eman · 2026-09-21T16:48:02Z

+  it. So entry is the exception and the reference description is the
+  rule; ``data_conversions.rst``'s warning now says which applies when.


Fixed in 6f9f0c0. Right — the later-stint rule is mode-specific. The changelog now reads "Later in a stint it depends on the mode": in ENERGY_SAVER entry is the exception and the reference description is the rule; in HIGH_DEMAND it is not (re-engages ~2.1 degC below the ON setting); ELECTRIC is uncharacterised.

eman · 2026-09-21T16:48:03Z

+   * - Energy Saver later in a stint
+     - Different rule. The element re-engages **as the upper probe
+       reaches** ``heUpperOnTempSetting`` - the field working exactly
+       as this reference describes it. Entry is the exception, not the
+       rule.


Fixed in 6f9f0c0. The opening now says how far the fields hold by mode and moment instead of flatly that they don't: not on entry to any element mode; yes later in ENERGY_SAVER (history, and now confirmed by a commanded run); no later in HIGH_DEMAND (history only); ELECTRIC uncharacterised. That also separates the history-derived evidence from the commanded run, as you asked.

eman · 2026-09-21T16:48:04Z

+   - **Later in a stint the descriptions below hold.** In
+     ``ENERGY_SAVER`` the upper element comes on as the probe reaches
+     ``heUpperOnTempSetting``, exactly as described.


Fixed in 6f9f0c0 — scoped to ENERGY_SAVER, with HIGH_DEMAND's ~2.1 degC-below re-engagement moved into the same bullet so the lead-in no longer contradicts it. While there I also scoped "the ON setting is 33 degC below the tank in HEAT_PUMP and ENERGY_SAVER" to Energy Saver: this PR already found the field unreliable in Heat Pump mode (40.5 degC in only ~48.5 % of minutes).

eman · 2026-09-21T16:48:05Z

+* **Later in a stint they do.** ``ENERGY_SAVER`` re-engages the upper
+  element as the probe reaches ``heUpperOnTempSetting``;
+  ``HIGH_DEMAND`` re-engages about 2.1 degC below it. See


Fixed in 6f9f0c0. The lead-in is now "Later in a stint it depends on the mode", then ENERGY_SAVER (as the field describes), HIGH_DEMAND (does not — ~2.1 degC below), ELECTRIC (uncharacterised).

The warning added with the mid-stint figures said this unit's element binary sensors "assert one-minute elements the power meter does not see", with 9 of 112 apparent starts drawing 500-750 W or less. That is wrong, and an adversarial review of the analysis behind it caught it. The elements were real. Pulling raw samples: on 2026-04-12 the flag went on at 22:21:58 and off at 22:22:18, and currentPower inside that window reads 5558 W and 5547 W, with the compressor steady at ~470 W either side. A 20-second element at full power. The "538 W" that made it look phantom was the last sample at or before the minute boundary, taken by a one-minute resample that used a backward as-of join instead of a maximum. currentPower samples at a median 30 s with 24 % of gaps over a minute, so a sub-minute burst falls between the samples such a resample keeps. What is true, and more useful, is that element runs come in two lengths. Of 128 raw upper-element runs, 31 (24 %) are under a minute, median 9 s, and together carry 0.8 kWh across nine months against 97.9 kWh for the other 97. A 20-second burst moves the upper probe about 0.1 degC, at its own resolution — which is why "the tank did not move" looked like corroboration and was not evidence either way. So the note now describes the sampling hazard rather than accusing the sensor: resample power with a maximum or work from raw edges, and filter on duration or energy when predicting recovery, because it is the sustained runs that heat the tank. No mid-stint figure changes: the review confirmed the Energy Saver and High Demand results are identical with or without the power filter. Refs #142

…aims A commanded run on 2026-09-21 answers what the recorded history on this page could not. With the setpoint fixed for almost the whole record, "the element engages at heUpperOnTempSetting" and "it engages a fixed gap below the setpoint" made the same prediction. So the setpoint was lowered to 42.0 degC and the unit left in ENERGY_SAVER. A fixed gap predicted engagement near 22 degC; it engaged three times with the upper probe at 39.8. The on-setting is what drives it — with two cautions stated: every engagement came while water moved through the tank, and readings of 40.4, 40.1 and 40.0 did not trigger, so the working threshold may sit a little under the published 40.5. Three further behaviours from the same run, each with its n: - The element runs to ~0.9 degC under the setpoint-tracking heUpperOffTempSetting, not to a fixed point. Only engagement is fixed. - Raising the setpoint in ENERGY_SAVER starts the element, through the entry rule (n = 1). A controller writing setpoints in that mode can start a 5 kW element. - Whether water movement is required, or temperature suffices, cannot be separated: all three engagements had it, one from a shower and two from a recirculation pump on a cooled loop. Two retractions. The short-element warning said a 20-second burst moves the upper probe ~0.1 degC, "below its own resolution. They heat nothing." That divided by the whole tank's heat capacity; the upper element heats the upper zone, a third of it. A 20 s burst is ~0.3 degC, and measured 41-58 s bursts moved it 0.7-1.5 degC. The counts are also restated on a clean basis — upper element only, commanded test days excluded, at the fitted 5,148 W: 115 runs, 20 under a minute. And the page said heUpperOnTempSetting rests at 40.5 degC in both HEAT_PUMP and ENERGY_SAVER. True of Energy Saver (96 % of minutes on this unit); in Heat Pump only 48.5 %, and the other values match the current setpoint in only 6 % of minutes, so it is not tracking the setpoint either. Marked as unreliable in Heat Pump mode. Refs #142

Copilot

Copilot review overview

🟡 Changes recommended

Unresolved documentation contradictions and stale or retracted claims remain in the reviewed files.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5

Open (5)

Update changelog with corrected sampling analysis · New
Make later-stint behavior statement mode-specific
Limit later-stint claim to Energy Saver or qualify it
Resolve contradiction about later-stint behavior
Scope later-stint conclusion to mode-dependent behavior

Previously missed (3)

In code that hasn't changed since last review

Mark Heat Pump behavior unreliable in all descriptions

docs/explanation/heating-elements.rst:56

The PR update also retracts the mode-wide claim that the setting rests at 40.5 degC in Heat Pump, but the short-version row immediately above this changed entry text still states that as a fact (and the detailed section repeats it). Mark Heat Pump unreliable here and in the detailed description so this page does not retain the retracted generalization.

Add qualified Energy Saver setpoint and off-setting results

docs/explanation/heating-elements.rst:261

The update says the Energy Saver on-point is now supported by a commanded run (setpoint 42.0 degC, n=3 at 39.8 degC, all with water movement, possibly slightly below 40.5), but this paragraph still presents only the 17/23 historical clustering as "exactly" causal. It also omits the update's qualified off-setting and setpoint-raise observations. Add those results with their sample sizes and caveats, or align the PR description with the actual page.

This issue also appears on line 294 of the same file.

Limit 33-degree-below-tank claim to Energy Saver

docs/reference/protocol/data_conversions.rst:179

The update retracts the Heat Pump part of this generalization: the setting is 40.5 degC in only 48.5% of Heat Pump minutes, and the remaining observations do not establish the same entry behavior as Energy Saver. Saying both modes are sitting 33 degC below the tank is therefore inaccurate; qualify this statement to Energy Saver and mark Heat Pump behavior unreliable.

eman · 2026-09-21T16:48:07Z

+  A sampling note with it: the element runs in two very different
+  lengths. Of 128 raw upper-element runs, 31 lasted under a minute
+  (median 9 s) and carry 0.8 kWh across nine months against 97.9 kWh
+  for the other 97 - real elements, but they heat nothing. Because


Already addressed in 9ad7f34, which landed at 16:27Z, just before this review at 16:36Z — the Unreleased note now gives the corrected basis (115 upper-element runs, 20 under a minute, median 16 s) and says the short runs are real thermal input (~0.3 degC for a 20 s burst), not "heat nothing".

Review on #143 found four places that said the published thermostat description holds later in a stint, then gave High Demand — which re-engages ~2.1 degC *below* its ON setting — as a counterexample in the next clause. The evidence supports the ON-setting description for ENERGY_SAVER only. - The page's opening said the four fields do not describe when the elements run, which contradicted the row beneath it saying they are the rule later in a stint. It now says how far they hold by mode and moment: not on entry to any element mode; yes later in ENERGY_SAVER (history, confirmed by a commanded run); no later in HIGH_DEMAND (history only); ELECTRIC uncharacterised. - CHANGELOG, data_conversions.rst and device_status.rst said "the reference description is the rule" / "the descriptions below hold" / "later in a stint they do". Each is now scoped to the mode. - data_conversions.rst also still said the ON setting sits 33 degC below the tank in HEAT_PUMP and ENERGY_SAVER. This PR already found that true of Energy Saver and unreliable in Heat Pump; scoped to match. The fifth comment, on the changelog's short-element counts, was already addressed in 9ad7f34. Refs #142

eman requested a lite review from Copilot September 20, 2026 20:02

Copilot started reviewing on behalf of eman September 20, 2026 20:03 View session

Copilot AI reviewed Sep 20, 2026

View reviewed changes

eman added 2 commits September 20, 2026 13:22

eman requested a lite review from Copilot September 21, 2026 16:32

Copilot started reviewing on behalf of eman September 21, 2026 16:32 View session

Copilot AI reviewed Sep 21, 2026

View reviewed changes

eman merged commit 1196fa3 into main Sep 21, 2026
6 checks passed

eman deleted the docs/mid-stint-reengagement branch September 21, 2026 16:48

Navigation Menu

Repository navigation

docs: the on-setting is wrong on entry and right after it - #143

docs: the on-setting is wrong on entry and right after it#143
eman merged 4 commits into
mainfrom
docs/mid-stint-reengagement

eman commented Sep 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

eman Sep 21, 2026

Uh oh!

eman Sep 21, 2026

Uh oh!

eman Sep 21, 2026

Uh oh!

eman Sep 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

eman Sep 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		it. So entry is the exception and the reference description is the
		rule; ``data_conversions.rst``'s warning now says which applies when.

Conversation

eman commented Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Later in the same stint, the published description is exactly right

What changed

A sampling note that travels with the figures

Scope

Update: confirmed on the device, and two retractions

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

eman Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

eman Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

eman Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

eman Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

eman Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eman commented Sep 20, 2026 •

edited

Loading