From 62506d5574749648b1e1f6199304411d3c5097f5 Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Sun, 20 Sep 2026 12:49:57 -0700 Subject: [PATCH 1/4] docs: the on-setting is wrong on entry and right after it #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 --- CHANGELOG.rst | 23 ++++-- docs/explanation/heating-elements.rst | 75 ++++++++++++++++---- docs/reference/protocol/data_conversions.rst | 32 +++++---- docs/reference/protocol/device_status.rst | 17 +++-- 4 files changed, 110 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 0447a29..e8e45ab 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -9,7 +9,8 @@ Documentation ------------- - **New: what the heating elements actually do** (``docs/explanation/heating-elements.rst``). The four - ``he*TempSetting`` fields do not describe when an element runs: in + ``he*TempSetting`` fields describe the thermostat, and **on entry to + a mode the thermostat is not what runs the element**: in Electric and High Demand the on and off settings are the same value, and every ``he*DiffTempSetting`` reads 0. Measured on one unit by commanding the modes and watching, the start differential is @@ -22,9 +23,23 @@ Documentation are **entry** thresholds, not thermostats: in High Demand's steady state this unit's history has the element on in 1 of 47 minutes 0.2-0.3 degC short and 168 of 169 more than 2.2 degC short. - Neither differential is published anywhere in the status message. Also documents Energy - Saver's entry behaviour (the element engages although - ``heUpperOnTempSetting`` rests 33 degC below the tank), Electric's + Neither differential is published anywhere in the status message. + + **Later in a stint the published thermostat is right.** From one + unit's recorded history, 17 of 23 mid-stint upper-element starts in + ``ENERGY_SAVER`` have the probe in the 39.4-41.1 degC band where + ``heUpperOnTempSetting`` rests, a median 0.2 degC below the field - + the element comes on as the probe reaches it. ``HIGH_DEMAND``, whose + ON setting tracks the setpoint, re-engages a median 2.1 degC *below* + it. So entry is the exception and the reference description is the + rule; ``data_conversions.rst``'s warning now says which applies when. + A measurement note with it: this unit's element binary sensors assert + one-minute elements the meter never sees (9 of 112 apparent starts + drew under 750 W), so element starts must be corroborated against the + power reading. + + Also documents Energy Saver's entry behaviour (the element engages + although ``heUpperOnTempSetting`` rests 33 degC below the tank), Electric's upper-to-lower handover and the upper probe **falling** 1.9 degC while the lower element runs, measured element power of 5,219 W against the 5,000 W rating, and that a mode write may not take effect while a TOU diff --git a/docs/explanation/heating-elements.rst b/docs/explanation/heating-elements.rst index efb5609..b94cc96 100644 --- a/docs/explanation/heating-elements.rst +++ b/docs/explanation/heating-elements.rst @@ -53,10 +53,15 @@ The short version * - Energy Saver on entry - Switching into ``ENERGY_SAVER`` engages the upper element even though ``heUpperOnTempSetting`` rests 33 degC below the tank, so - whatever drives it, that field is not it. Its bracket also sits - higher than the other two modes'. Why the two differ is **not** - established: the Energy Saver runs had the compressor running - and the others did not. + **on entry** that field is not what drives it. Its bracket also + sits higher than the other two modes'. Why the two differ is + **not** established: the Energy Saver runs had the compressor + running and the others did not. + * - 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. * - Electric ordering - Upper element to the setpoint, then the lower element, never both, as the protocol reference already states. The handover @@ -238,18 +243,59 @@ What the on-setting does and does not tell you * In ``HEAT_PUMP`` and ``ENERGY_SAVER`` it rests at 40.5 degC, the device minimum, which is 33 degC below a normally charged tank. -The second case is the one that misleads. In ``ENERGY_SAVER`` the upper -element **does** run, and it runs with the on-setting far below the tank -- so the element is not being driven by that field. Switching into the -mode with the tank 1.0 degC or more short brought the element on within -one poll in both runs tested, and ``heUpperOnTempSetting`` dropped from -the setpoint to 40.5 degC in the *same* status message. Watching that -field for an explanation of the element will not find one. +The second case misleads **on entry only**. Switching into +``ENERGY_SAVER`` with the tank 1.0 degC or more short brought the upper +element on within one poll in both runs tested, while +``heUpperOnTempSetting`` dropped from the setpoint to 40.5 degC in the +*same* status message - 33 degC below the probe. For that moment the +field explains nothing. -That is as far as the observation goes. It does not explain *why* +That is as far as the entry observation goes. It does not explain *why* Energy Saver's bracket sits higher than Electric's; the runs differ in compressor state as well as mode, and nothing here separates the two. +**Later in the same stint the field is exactly what drives the +element.** In 23 mid-stint upper-element starts in ``ENERGY_SAVER`` +drawn from one unit's recorded history, **17 have the upper probe +between 39.4 and 41.1 degC** - the band ``heUpperOnTempSetting`` rests +in for this mode - 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, which is what this reference has said all +along. + +``HIGH_DEMAND`` behaves differently, and this is the clearest statement +of the difference on this page. There ``heUpperOnTempSetting`` tracks +the setpoint, and 12 mid-stint starts came a median **2.1 degC below +it**, none in the 39.4-41.1 degC band. That differential is real and is +published nowhere. + +So a consumer needs both halves: + +.. list-table:: + :header-rows: 1 + :widths: 26 37 37 + + * - Mode + - On entry + - Later in the stint + * - ``ENERGY_SAVER`` + - element on, on-setting irrelevant (1.0 degC below setpoint) + - element on **at** ``heUpperOnTempSetting`` + * - ``HIGH_DEMAND`` + - element on, (0.2, 0.7] degC below setpoint + - element on ~2.1 degC **below** ``heUpperOnTempSetting`` + +.. warning:: + + These mid-stint figures come from **recorded history, not commanded + runs**, and they carry a measurement hazard worth repeating. This + unit's element binary sensors assert one-minute elements the power + meter does not see: 9 of 112 apparent upper-element starts drew + 500-750 W or less, against 5.1-5.6 kW for a real one, while every + run of two minutes or more was genuine. Counting element starts from + those sensors alone overstates them. Every figure above is + corroborated against the whole-unit power reading. + Electric: the handover, and what happens to the upper zone =========================================================== @@ -326,8 +372,9 @@ established: has a run on each side, so it is bracketed - but that bracket is more than twice Electric's width, and one run at 0.4 degC would halve it. Until then, whether the two modes share a threshold is unresolved. -* what engages the element **later** in an Energy Saver stint, as - opposed to on entry. +* **Electric's** behaviour later in a stint. Energy Saver's and High + Demand's are described above from history; Electric has only two + mid-stint starts on record, which characterises nothing. * anything about runs longer than six minutes. * whether either differential is firmware-dependent. The unit reported ``heUpperOnDiffTempSetting`` as 0 throughout; if another unit reports diff --git a/docs/reference/protocol/data_conversions.rst b/docs/reference/protocol/data_conversions.rst index d2bebd4..8207ae5 100644 --- a/docs/reference/protocol/data_conversions.rst +++ b/docs/reference/protocol/data_conversions.rst @@ -166,18 +166,26 @@ Electric heating elements are controlled via thermostat ranges. Two sensors (upp .. warning:: - **These fields do not predict when an element runs.** The - descriptions below are the protocol's own semantics for each field. - Measured against the device, they do not hold: in ``ELECTRIC`` and - ``HIGH_DEMAND`` the ON and OFF settings are **the same value** (no - hysteresis at all, which cannot be how the device behaves), in - ``HEAT_PUMP`` and ``ENERGY_SAVER`` the ON setting rests at the - 40.5 degC device minimum while the element still runs, and **every** - ``he*DiffTempSetting`` reads 0 rather than the 2-5 degF below. - - The differential the device actually uses is mode-dependent and is - published nowhere in the status message. See - :doc:`/explanation/heating-elements` for the measured values. + **These fields describe the thermostat, and the thermostat is not + the whole story.** Measured against the device: + + - **Later in a stint the descriptions below hold.** In + ``ENERGY_SAVER`` the upper element comes on as the probe reaches + ``heUpperOnTempSetting``, exactly as described. + - **On entry to a mode they do not.** Switching into an element mode + engages the element on a mode-dependent differential of its own, + while in ``HEAT_PUMP`` and ``ENERGY_SAVER`` the ON setting is + sitting 33 degC below the tank. That differential is published + nowhere. + - In ``ELECTRIC`` and ``HIGH_DEMAND`` the ON and OFF settings are + **the same value** - no hysteresis at all, which cannot be how the + device behaves - and ``HIGH_DEMAND`` re-engages about 2.1 degC + *below* its ON setting. + - **Every** ``he*DiffTempSetting`` reads 0 on a 9.x-firmware unit + rather than the 2-5 degF described below. + + See :doc:`/explanation/heating-elements` for the measured values and + which rule applies when. .. list-table:: :header-rows: 1 diff --git a/docs/reference/protocol/device_status.rst b/docs/reference/protocol/device_status.rst index 17885d0..f03a26d 100644 --- a/docs/reference/protocol/device_status.rst +++ b/docs/reference/protocol/device_status.rst @@ -739,13 +739,16 @@ Technical Notes * Elements do not operate simultaneously in Electric mode - upper first, then lower, with the handover in a single status message * Heating elements activate for freeze protection when tank < 43°F (6°C) -* The ``he*TempSetting`` fields do **not** describe when an element - runs: in Electric and High Demand the on and off settings are equal - and every ``he*DiffTempSetting`` reads 0. The measured start - differential is **mode-dependent** - at most 0.3 degC in - ``ELECTRIC``, within (0.2, 0.7] degC in ``HIGH_DEMAND``, and within - (0.8, 1.0] degC in ``ENERGY_SAVER``, all measured on entry to the - mode. See :doc:`/explanation/heating-elements`. +* The ``he*TempSetting`` fields do **not** describe what happens on + **entry** to a mode: in Electric and High Demand the on and off + settings are equal and every ``he*DiffTempSetting`` reads 0. The + measured entry differential is **mode-dependent** - at most 0.3 degC + in ``ELECTRIC``, within (0.2, 0.7] degC in ``HIGH_DEMAND``, and + within (0.8, 1.0] degC in ``ENERGY_SAVER``. +* **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 + :doc:`/explanation/heating-elements`. **Heat Pump Specifications:** From b92c77b660bd7ebb4340b7c8f7ad5b9b94f68e6e Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Sun, 20 Sep 2026 13:22:31 -0700 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20the=20short=20elements=20are=20real?= =?UTF-8?q?=20=E2=80=94=20correct=20the=20hazard=20note?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.rst | 12 +++++++---- docs/explanation/heating-elements.rst | 29 ++++++++++++++++++++------- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e8e45ab..f11bc07 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -33,10 +33,14 @@ Documentation ON setting tracks the setpoint, re-engages a median 2.1 degC *below* it. So entry is the exception and the reference description is the rule; ``data_conversions.rst``'s warning now says which applies when. - A measurement note with it: this unit's element binary sensors assert - one-minute elements the meter never sees (9 of 112 apparent starts - drew under 750 W), so element starts must be corroborated against the - power reading. + 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 + ``currentPower`` samples at a median 30 s, a one-minute-resampled + power series can miss one entirely, making a 5.5 kW element look like + 0.5 kW. Resample power with a maximum, and filter on duration or + energy when predicting recovery. Also documents Energy Saver's entry behaviour (the element engages although ``heUpperOnTempSetting`` rests 33 degC below the tank), Electric's diff --git a/docs/explanation/heating-elements.rst b/docs/explanation/heating-elements.rst index b94cc96..a32f26c 100644 --- a/docs/explanation/heating-elements.rst +++ b/docs/explanation/heating-elements.rst @@ -288,13 +288,28 @@ So a consumer needs both halves: .. warning:: These mid-stint figures come from **recorded history, not commanded - runs**, and they carry a measurement hazard worth repeating. This - unit's element binary sensors assert one-minute elements the power - meter does not see: 9 of 112 apparent upper-element starts drew - 500-750 W or less, against 5.1-5.6 kW for a real one, while every - run of two minutes or more was genuine. Counting element starts from - those sensors alone overstates them. Every figure above is - corroborated against the whole-unit power reading. + runs**, and they carry a sampling hazard worth repeating - one that + bit us. + + **The element runs in two very different lengths.** Of 128 raw + upper-element runs on this unit, 31 (24 %) lasted **under a minute** + - median 9 s, some as short as 2 s - and 97 ran a median 8 minutes. + The short ones are real elements at full power, but they carry + **0.8 kWh across nine months** against 97.9 kWh for the rest, and a + 20-second burst moves the upper probe about 0.1 degC, below its own + 0.1 degC resolution. They heat nothing. + + They are also easy to lose or to misread. ``currentPower`` samples + at a median 30 s, with 24 % of gaps over a minute, so **a + one-minute-resampled power series can miss a sub-minute burst + entirely** - taking the last sample at or before each minute makes a + real 5.5 kW element look like 0.5 kW. Resample power with a + **maximum** over the interval, or work from the raw edges, and + corroborate a run's duration rather than a single aligned sample. + + For predicting recovery, filter on **duration or energy**, not on + the flag and not on one power reading: it is the sustained runs that + heat the tank. Electric: the handover, and what happens to the upper zone From 9ad7f34d912e2268cf432d2160d9ad9743f339d7 Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Mon, 21 Sep 2026 09:27:29 -0700 Subject: [PATCH 3/4] docs: confirm the Energy Saver on-point on the device; retract two claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.rst | 23 ++++++--- docs/explanation/heating-elements.rst | 67 ++++++++++++++++++++++----- 2 files changed, 71 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f11bc07..5074e9b 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -34,13 +34,22 @@ Documentation it. So entry is the exception and the reference description is the rule; ``data_conversions.rst``'s warning now says which applies when. 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 - ``currentPower`` samples at a median 30 s, a one-minute-resampled - power series can miss one entirely, making a 5.5 kW element look like - 0.5 kW. Resample power with a maximum, and filter on duration or - energy when predicting recovery. + lengths. Of 115 upper-element runs over eight months, 20 lasted under + a minute (median 16 s), carrying 0.6 kWh against 93 kWh for the rest. + They are real elements, and not negligible to the probe - a 20 s burst + is ~0.3 degC. Because ``currentPower`` samples at a median 30 s, a + one-minute-resampled power series can miss one entirely, making a + 5.5 kW element look like 0.5 kW. Resample power with a maximum. + + Confirmed on the device, one unit, 2026-09-21: in ``ENERGY_SAVER`` + the upper element engages near ``heUpperOnTempSetting`` rather than a + fixed gap below the setpoint (setpoint lowered to 42.0 degC; a gap + predicted 22 degC; it engaged at 39.8, three times). It then runs to + ~0.9 degC under the setpoint-tracking ``heUpperOffTempSetting``, not + to a fixed point. Raising the setpoint in that mode starts the element + through the entry rule. And ``heUpperOnTempSetting`` rests at 40.5 + degC reliably only in ``ENERGY_SAVER`` - in ``HEAT_PUMP`` about half + the time. Also documents Energy Saver's entry behaviour (the element engages although ``heUpperOnTempSetting`` rests 33 degC below the tank), Electric's diff --git a/docs/explanation/heating-elements.rst b/docs/explanation/heating-elements.rst index a32f26c..d4da0d4 100644 --- a/docs/explanation/heating-elements.rst +++ b/docs/explanation/heating-elements.rst @@ -48,8 +48,11 @@ The short version read 0 on this unit while the behaviour above holds. * - ``heUpperOnTempSetting`` by mode - ``ELECTRIC`` and ``HIGH_DEMAND``: the setpoint, same as - ``heUpperOffTempSetting``. ``HEAT_PUMP`` and ``ENERGY_SAVER``: - 40.5 degC (104.9 degF), the device minimum. + ``heUpperOffTempSetting``. ``ENERGY_SAVER``: 40.5 degC + (104.9 degF), the device minimum, in 96 % of recorded minutes on + this unit. ``HEAT_PUMP``: 40.5 degC only about **half** the time; + the rest are other values that match the current setpoint only + 6 % of the time. Why is not known. * - Energy Saver on entry - Switching into ``ENERGY_SAVER`` engages the upper element even though ``heUpperOnTempSetting`` rests 33 degC below the tank, so @@ -240,8 +243,14 @@ What the on-setting does and does not tell you with no hysteresis at all, which cannot be how the device behaves; on entry the measured differential is at most 0.3 degC in Electric and within (0.2, 0.7] degC in High Demand. -* In ``HEAT_PUMP`` and ``ENERGY_SAVER`` it rests at 40.5 degC, the - device minimum, which is 33 degC below a normally charged tank. +* In ``ENERGY_SAVER`` it rests at 40.5 degC, the device minimum, which + is 33 degC below a normally charged tank. An earlier version of this + page said the same of ``HEAT_PUMP``; on this unit that holds in only + 48.5 % of Heat Pump minutes. The rest are other values - 63.0 degC + most often - which equal the *current* setpoint in only 6 % of Heat + Pump minutes, so this is not the field tracking the setpoint; it may + be holding a value over from an earlier mode. Do not rely on it in + Heat Pump mode. The second case misleads **on entry only**. Switching into ``ENERGY_SAVER`` with the tank 1.0 degC or more short brought the upper @@ -263,6 +272,17 @@ start is **0.2 degC below it**. The element comes on as the probe reaches the on-setting, which is what this reference has said all along. +**Confirmed on the device.** The history above cannot prove it on its +own: with the setpoint fixed for almost the whole record, "at the +on-setting" and "a fixed gap below the setpoint" are the same +prediction. So the setpoint was lowered to 42.0 degC and the unit left +in ``ENERGY_SAVER``. With the on-setting still at 40.5 degC, a fixed gap +would have put the element near 22 degC; it came on three times with +the upper probe reading **39.8 degC**. Two cautions: all three came +while water was moving through the tank, and readings of 40.4, 40.1 and +40.0 degC did not trigger, so on this probe the working threshold may +sit a little under the published 40.5. + ``HIGH_DEMAND`` behaves differently, and this is the clearest statement of the difference on this page. There ``heUpperOnTempSetting`` tracks the setpoint, and 12 mid-stint starts came a median **2.1 degC below @@ -280,24 +300,47 @@ So a consumer needs both halves: - Later in the stint * - ``ENERGY_SAVER`` - element on, on-setting irrelevant (1.0 degC below setpoint) - - element on **at** ``heUpperOnTempSetting`` + - element on **near** ``heUpperOnTempSetting`` * - ``HIGH_DEMAND`` - element on, (0.2, 0.7] degC below setpoint - element on ~2.1 degC **below** ``heUpperOnTempSetting`` +Three more behaviours, from the same commanded run. Each is one unit +and one morning; the counts are given so they can be weighed. + +* **The element runs to the setpoint, not to a fixed point.** It + stopped about 0.9 degC under ``heUpperOffTempSetting``, which follows + the setpoint. At a 42.0 degC setpoint that was 41.1 degC; historical + runs at a 60.5 degC setpoint stop around 59. Only the *engagement* + point is fixed. +* **Raising the setpoint in** ``ENERGY_SAVER`` **starts the element.** + With the tank at 41.7 degC, a setpoint raise to 61.0 degC switched the + heat source to heat pump plus element in the same second (n = 1). It + is the entry rule again, triggered by the setpoint rather than a mode + change. A controller writing setpoints in this mode can start a 5 kW + element. +* **Every engagement came with water moving through the tank** — one + shower and two runs of a recirculation pump on a cooled loop, which + the tank experiences as draws. Whether movement is *required*, or the + temperature alone suffices, is not separable from these. + .. warning:: These mid-stint figures come from **recorded history, not commanded runs**, and they carry a sampling hazard worth repeating - one that bit us. - **The element runs in two very different lengths.** Of 128 raw - upper-element runs on this unit, 31 (24 %) lasted **under a minute** - - median 9 s, some as short as 2 s - and 97 ran a median 8 minutes. - The short ones are real elements at full power, but they carry - **0.8 kWh across nine months** against 97.9 kWh for the rest, and a - 20-second burst moves the upper probe about 0.1 degC, below its own - 0.1 degC resolution. They heat nothing. + **The element runs in two very different lengths.** Of 115 raw + upper-element runs on this unit over eight months, 20 (17 %) lasted + **under a minute** - median 16 s - and 95 ran a median 8 minutes. + The short ones are real elements at full power. They carry little + energy - 0.6 kWh across the record against 93 kWh for the rest - + but they are not negligible to the probe: a 20-second burst raises + the upper zone about 0.3 degC, three quanta of its 0.1 degC + resolution, and measured bursts of 41-58 s moved it 0.7-1.5 degC. + *(An earlier version said they "heat nothing", from dividing by the + whole tank's heat capacity rather than the upper zone's - three + times too large.)* They are also easy to lose or to misread. ``currentPower`` samples at a median 30 s, with 24 % of gaps over a minute, so **a From 6f9f0c0f796df4fd06d208d711c577d42b4595cb Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Mon, 21 Sep 2026 09:47:59 -0700 Subject: [PATCH 4/4] docs: later-stint behaviour is mode-dependent, not "the rule" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.rst | 8 +++++--- docs/explanation/heating-elements.rst | 21 +++++++++++++++----- docs/reference/protocol/data_conversions.rst | 15 +++++++------- docs/reference/protocol/device_status.rst | 9 +++++---- 4 files changed, 34 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 5074e9b..b44deb3 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -25,14 +25,16 @@ Documentation 0.2-0.3 degC short and 168 of 169 more than 2.2 degC short. Neither differential is published anywhere in the status message. - **Later in a stint the published thermostat is right.** From one + **Later in a stint it depends on the mode.** From one unit's recorded history, 17 of 23 mid-stint upper-element starts in ``ENERGY_SAVER`` have the probe in the 39.4-41.1 degC band where ``heUpperOnTempSetting`` rests, a median 0.2 degC below the field - the element comes on as the probe reaches it. ``HIGH_DEMAND``, whose ON setting tracks the setpoint, re-engages a median 2.1 degC *below* - it. So entry is the exception and the reference description is the - rule; ``data_conversions.rst``'s warning now says which applies when. + it, which the field does not describe. So in ``ENERGY_SAVER`` entry is + the exception and the reference description is the rule; in + ``HIGH_DEMAND`` it is not; ``ELECTRIC`` is uncharacterised. + ``data_conversions.rst``'s warning now says which applies when. A sampling note with it: the element runs in two very different lengths. Of 115 upper-element runs over eight months, 20 lasted under a minute (median 16 s), carrying 0.6 kWh against 93 kWh for the rest. diff --git a/docs/explanation/heating-elements.rst b/docs/explanation/heating-elements.rst index d4da0d4..5a242d5 100644 --- a/docs/explanation/heating-elements.rst +++ b/docs/explanation/heating-elements.rst @@ -4,11 +4,22 @@ The Heating Elements The NWP500 publishes four element thermostat settings - ``heUpperOnTempSetting``, ``heUpperOffTempSetting`` and their lower-zone -pair - plus a differential for each. Read literally they do not describe -when the elements actually run: in Electric and High Demand the on and -off settings are **the same value**, and every ``he*DiffTempSetting`` -reads 0. The device nevertheless has a differential, and this page -gives the measured one. +pair - plus a differential for each. Read literally they describe a +thermostat, and how far that holds depends on the mode and the moment: + +* **On entry to any element mode they do not** describe when the element + runs. It engages on a mode-dependent differential of its own, published + nowhere - the start thresholds below. +* **Later in a stint, in** ``ENERGY_SAVER`` **they do**: the element + engages as the probe reaches ``heUpperOnTempSetting``. That is from this + unit's history and confirmed by a commanded run. +* **Later in a stint, in** ``HIGH_DEMAND`` **they do not**: it re-engages + about 2.1 degC below its ON setting. That is from history only. + ``ELECTRIC`` is uncharacterised. + +The fields also look wrong as a thermostat taken literally: in Electric +and High Demand the on and off settings are **the same value**, and every +``he*DiffTempSetting`` reads 0. **The start thresholds** here were measured on one unit by commanding the modes and watching - not inferred from historical logs. That diff --git a/docs/reference/protocol/data_conversions.rst b/docs/reference/protocol/data_conversions.rst index 8207ae5..7776f61 100644 --- a/docs/reference/protocol/data_conversions.rst +++ b/docs/reference/protocol/data_conversions.rst @@ -169,18 +169,19 @@ Electric heating elements are controlled via thermostat ranges. Two sensors (upp **These fields describe the thermostat, and the thermostat is not the whole story.** Measured against the device: - - **Later in a stint the descriptions below hold.** In - ``ENERGY_SAVER`` the upper element comes on as the probe reaches - ``heUpperOnTempSetting``, exactly as described. + - **Later in a stint it depends on the mode.** In ``ENERGY_SAVER`` + the upper element comes on as the probe reaches + ``heUpperOnTempSetting``, as described below. In ``HIGH_DEMAND`` it + does not: it re-engages about 2.1 degC *below* its ON setting. + ``ELECTRIC`` is uncharacterised. - **On entry to a mode they do not.** Switching into an element mode engages the element on a mode-dependent differential of its own, - while in ``HEAT_PUMP`` and ``ENERGY_SAVER`` the ON setting is - sitting 33 degC below the tank. That differential is published + while in ``ENERGY_SAVER`` the ON setting is sitting 33 degC below + the tank. That differential is published nowhere. - In ``ELECTRIC`` and ``HIGH_DEMAND`` the ON and OFF settings are **the same value** - no hysteresis at all, which cannot be how the - device behaves - and ``HIGH_DEMAND`` re-engages about 2.1 degC - *below* its ON setting. + device behaves. - **Every** ``he*DiffTempSetting`` reads 0 on a 9.x-firmware unit rather than the 2-5 degF described below. diff --git a/docs/reference/protocol/device_status.rst b/docs/reference/protocol/device_status.rst index f03a26d..ca3a43e 100644 --- a/docs/reference/protocol/device_status.rst +++ b/docs/reference/protocol/device_status.rst @@ -745,10 +745,11 @@ Technical Notes measured entry differential is **mode-dependent** - at most 0.3 degC in ``ELECTRIC``, within (0.2, 0.7] degC in ``HIGH_DEMAND``, and within (0.8, 1.0] degC in ``ENERGY_SAVER``. -* **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 - :doc:`/explanation/heating-elements`. +* **Later in a stint it depends on the mode.** ``ENERGY_SAVER`` + re-engages the upper element as the probe reaches + ``heUpperOnTempSetting``, as the field describes. ``HIGH_DEMAND`` does + not: it re-engages about 2.1 degC below it. ``ELECTRIC`` is + uncharacterised. See :doc:`/explanation/heating-elements`. **Heat Pump Specifications:**