Document the TOU recovery cap

[eman]

Under an active Time-of-Use period the NWP500 stops a heat-pump recovery at about 90 % dhw_charge_per instead of running to the setpoint, leaving tank_lower_temperature ~1.9 °C below hp_lower_off_temp_setting. Nothing in the protocol announces it and no error is raised — so code that waits for the setpoint waits forever.

Adds docs/explanation/tou-recovery-cap.rst, following the tank-energy.rst pattern: a measured claim with its evidence, since it is the same shape of finding — device behaviour that contradicts the obvious reading of a field.

Evidence

333 recovery cycles (15–480 min), 2025-12-28 to 2026-09-06, one unit. 196 reached the lower-off setpoint; 137 did not, and their shortfall is bimodal rather than a spread: median 3.42 °F with 59 cycles at exactly that value, then a tail past 8 °F that is ordinary interruption.

3.42 °F is 1.9 °C, 19 steps of the 0.1 °C probe quantum. It holds across eight setpoints from 140.0 to 147.2 °F and all nine months observed — an offset in the control logic, not a proportional or seasonal effect.

Two candidate mechanisms were tested and refuted: the upper zone does not satisfy its own cut-out first (tank_upper_temperature reached hp_upper_off_temp_setting on 2 of 137, against 179 of 196 reached cycles), and the device does not terminate on outlet temperature (2 of 136).

tou_status is not the test

The second commit corrects the first on this point. tou_status reports only that TOU scheduling is enabled — outside an expensive period an enabled schedule does nothing, which is why the flag alone read as "necessary but not sufficient": 98 cycles reached setpoint with it True, because they ran off-peak.

The device marks a period itself, applying non-zero *_diff_temp_setting offsets while inside one and reverting at the end. Among tou_status True cycles:

at cycle end	capped	reached	other
inside a period	42 (62 %)	12	14
outside a period	16 (12 %)	86	34

Test it at the cycle end, where the cap bites — a recovery beginning off-peak and running into a period is still capped (43 of 59 caught, against 17 testing the start).

What the page says it does not know

Being inside a period is a strong predictor, not a deterministic one: 12 cycles reached setpoint from inside one and 16 were capped from outside. The page names the likely cause (the marker is sampled at one instant, so a boundary crossed mid-recovery is missed) and what would settle it (configure_tou_schedule_confirmed reads back the schedule the device holds). The 90 % ceiling is one unit under one schedule; whether it is firmware-fixed, schedule-derived or configurable is unknown.

It also records that tou_status emits sub-second unknown blips on reconnect, and that a low change count means the state was held, not that data was lost — the month with 5 changes was the month TOU was active nearly continuously.

Also

A pointer in the tou_status field description in src/nwp500/models/status.py, since that is where a developer hits this in practice.

Docs build succeeds; 738 tests pass.

Consumer-side handling in eman/dhw-sensor-apps#170.