v9.4.3

Changed

• Raw reservation writes are now validated (#148).
  update_reservations() and update_reservations_confirmed() sent
  their entry dicts unchecked, so an unknown mode such as 7, an hour of 99
  or a setpoint of 200 (100 degC) went to the device as-is. A Python
  True for enable was worse: the confirmed helper read it as 1,
  which means disabled. Every entry is now checked before anything is
  sent, with the same rules as build_reservation_entry(): the six
  protocol fields present and plain integers, enable 1 or 2, week
  a day bitfield, hour 0-23, min 0-59 and mode a
  DhwOperationSetting id. param is held to the setpoint range the
  heater reports in its feature data (dhw_temperature_min_raw to
  dhw_temperature_max_raw), which is requested if it is not cached;
  clearing the schedule with an empty list needs none. A bad entry raises
  ParameterValidationError or RangeValidationError, and missing
  feature data raises DeviceCapabilityError. Callers that wrote
  entries outside these ranges and relied on the heater to clamp them now
  get an error instead. The checks are also available on their own as
  nwp500.mqtt.control.validate_reservation_entries().

Documentation

• New: what starts a recovery
  (docs/explanation/what-starts-a-recovery.rst). The lower-tank
  turn-on setting is one trigger among several. Measured on one unit:
  outside a TOU window the lower setting reads 104.9 degF at every
  setpoint and never follows it; at a window's opening the upper tank
  starts a cycle when it is well below the setpoint, and the lower trigger
  waits for the close. A control write re-evaluates: outside a window,
  in HEAT_PUMP with the compressor off, a setpoint write leaving the
  upper tank below the new setpoint started the compressor within
  2 minutes in 112 of 117 writes (a median 30 s later), lowerings
  included. 46 of 81 mode writes made with the compressor off did the
  same. A setpoint dropped well below the upper tank stopped a running
  compressor within 5 s (one run). A lowered setpoint did not hold off a
  draw-driven start (one run, in ENERGY_SAVER). The page also covers
  traps for anyone re-deriving this from history.

• TOU window: the two open cases measured, and three more results. In
  docs/how-to/schedule-operation.rst (one or two runs each): an entry
  scheduled after a window fires on its minute; a mode held in a window
  takes effect when the window ends naturally; writing HEAT_PUMP over
  a held mode withdraws it; turning TOU back on inside a window drops a
  running element mode; and the operation setting reports the configured
  mode, not activity. The section's first measurement date is corrected to
  local time (2026-09-19).

• New: what the heating elements actually do
  (docs/explanation/heating-elements.rst). The four
  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
  mode-dependent, one bracket per mode: ELECTRIC at most
  0.3 degC below the setpoint, HIGH_DEMAND within
  (0.2, 0.7] degC, ENERGY_SAVER within (0.8, 1.0] degC.
  Whether the first two share one threshold is an open question, not a
  finding. At 0.7 degC short, High Demand runs the element and Energy
  Saver does not. These
  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.

  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, 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.
  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
  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
  window is in force. device_status.rst's Heating Elements notes now
  point at it.

• currentInstPower includes the heating elements. The field
  table and Power and Energy Fields in the protocol reference, and the
  current_inst_power field description, said it excludes element
  power; track-energy.rst said it includes it. On a 240 V NWP500-65
  it includes it: element-only minutes read about 5.1 kW, compressor
  and element together about 5.5 kW, and the tank's heat gain agrees.
  All four now say so, with the measurement and its limits (one model,
  240 V only). (#139)

• TOU does not suspend reservations. schedule-operation.rst
  said twice that it does, and its own priority table said otherwise. On
  one NWP500, inside an active peak window, a reservation entry moved the
  setpoint at its scheduled minute, twice. What the window holds back is
  the entry's mode, as it does a direct set_operation_mode().
  The mode is held, not discarded: a mode written in the window took
  effect when TOU was switched off, and the upper element came on. The
  priority table and Important Notes are corrected, and a new section
  gives the measurements and their limits. heating-elements.rst now
  links to it instead of to the issue. (#141)

• tank-energy: what selects the second branch, and where usable_energy
  under-reads. tank-energy.rst left open what selects
  full_recovery_energy's second branch. On one NWP500-65 over 50,819
  HEAT_PUMP minutes, hpUpperOnTempSetting separates the branches
  with no exceptions: 104.9 degF on the primary, raised to about the
  setpoint during the afternoon TOU window on the secondary.
  energy_to_setpoint shifts by the same 2 degC. Because of that,
  usable_energy is not always robust to the branch. In the window it
  caps at full_recovery_energy once energy_to_setpoint hits 0,
  up to about 3.6 degF short of the setpoint, and under-reads by up to
  561 Wh. The page and the usable_energy docstring now say so and
  recommend the thermistors in that case. The full_recovery_energy
  and energy_to_setpoint descriptions in the model, the protocol
  reference, the API reference and track-energy.rst now note the
  window too. (#140)