# Design decisions

> The structural decisions and the chosen constants, with the anchor and revisit trigger for each value.

Source: https://better-thermostat.org/internals/design-decisions/

Two kinds of decisions live in this codebase, and the two need
different scrutiny. **Anchored thresholds** derive from a physical or
device-given limit; challenging them means challenging the anchor.
**Chosen constants** are engineering trade-offs between two named
pressures. They are legitimate to revisit, and this page names the
pressures so a revisit argues against the right thing.

## Structural decisions

**The snapshot is pulled, not maintained.** A per-cycle observation
guarantees every decision sees one coherent world and makes replay
deterministic. An event-maintained snapshot would buy nothing (the
write path is serialized anyway) and cost torn reads.

**Regions are not persisted.** Window, maintenance, lifecycle, mode,
ladder, reachability all re-derive from live observations, at the
latest within one debounce window. A persisted region could only pin
stale conclusions whose inputs are gone after a restart. Only state
with learning value (controller models, thermal stats, filters)
persists.

**Standby is tracking, never learning.** Entity-level estimates keep
converging while heating is suppressed; controllers neither integrate
error (windup) nor learn parameters from disturbance-flagged samples
(model poisoning: a window-open interval would teach the model that
heating does not work). Re-entry from held controller state plus fresh
estimates is what makes the transfer bumpless.

**Self-healing only for unambiguous pathologies; oscillation is
annunciation-only.** Non-finite state, runaway gains, and wound-up
integrators have crisp definitions and safe resets. An oscillation
detector with an automatic gain backoff would thrash the controller on
a false positive, which is worse than the oscillation it reacts to.
Backoff stays manual until the detector is validated against the
benchmark.

**No external readiness gate in front of actuation.** Closed-loop
learners bootstrap *through* actuation; an external "only actuate when
ready" gate would prevent them from ever warming up. The controllers
gate themselves (standby skips, gap resets), and capability/health is
annunciation.

**Reachability filters addresses and paces re-checks; it does not
retry writes.** An unreachable TRV is dropped from the addressed set
(boost excepted), because in Home Assistant writing to an unavailable
entity does nothing. Availability is push-based: a returning device
normally queues a control cycle through its own state event. The
region adds a re-check for the return that queues none: each cycle that
skips an offline TRV queues one cycle for the region's `retry_at`, 30 s
after the TRV went offline and doubling up to 600 s. That cycle only
re-observes; it sends nothing to the offline TRV. The doubling keeps a
long outage from queuing a cycle every 30 s, and the cap bounds how
long a silent return can go unnoticed to ten minutes. Flapping write
churn stays bounded by the write budget, and `offline_since` /
`retry_count` in the flight recorder serve outage analysis.

**HOLD keeps the last commanded state instead of handing over to the
TRV.** With no usable temperature anywhere, both options are blind;
keeping the last commanded state is the predictable one, and the frost
floor stays enforced. For a *single* dead TRV the hand-over happens
naturally: it receives no intent and its native thermostat continues.

**`unknown`/`unavailable` window readings count as closed.** Windows are
usually closed, and a lost sensor (e.g. a dead battery) must not stop
heating and leave the room cold; the frost floor still applies, and the
unavailability is surfaced separately. The reverse, treating an absent
reading as open, heats the street only when a window is actually open
but freezes the occupant on every dead battery.

**MPC v2 takes no flow temperature.** It models the heat source as a
boiler at 65 °C and accepts neither a configured value nor a sensor.
The valve opening that holds a room depends on the radiator's size
relative to the flow temperature: a 65 °C model with a boiler-sized
radiator and a 35 °C model with a radiator about three times as large
need the same opening at every outdoor temperature. In the benchmark, a
configured value without the matching radiator size hurt rooms on a
heat pump (S39 and S40: mean deviation 0.108 vs 0.044 K, valve travel
2928 vs 787 %/day). With the radiator size derived from it, it scored
the same as the default and lost the gain it had on undersized
radiators (S29, S33). A live sensor lowered the mean deviation by
0.016 K and the valve travel by about 45 %, and only with the matching
radiator size. The hot water pauses in S40 cost every controller the
same, the oracle included. To revisit, run
`uv run python -m tests.benchmark.runner --controller mpc_v2 --controller mpc_v2+flow_temperature --scenario S29_heatpump_steady_state --scenario S33_ufh_asymmetric --scenario S39_heat_pump_heating_curve --scenario S40_heat_pump_hot_water`.
The benchmark does not run the re-identification yet, so how much of
the radiator size *Auto* learns in operation is not measured.

## Chosen constants

| Value | What | The two pressures | Anchor / revisit trigger |
|---|---|---|---|
| **30 s** | write budget per TRV and channel | battery & radio load ↔ worst-case latency of a fine-tuning write | TRVs are battery devices on contended radio; write bursts are a real failure cause. 30 s caps a channel at ~120 writes/h while keeping deferred writes promptly delivered (safety writes bypass entirely). Faster budgets mainly buy more radio traffic rather than better control; room dynamics are far slower. |
| **10 min** | write budget per channel with the HomematicIP option enabled | radio duty cycle ↔ latency of following the user | Anchored: a HomematicIP head shares its access point's 1 % duty cycle (36 s of airtime an hour) with every other HomematicIP device, and it reads its own temperature every ten minutes. The first setpoint write after a user change of target or mode goes out at the 30 s pace. |
| **5 min** | periodic tick (Default, controller and balance modes) | control freshness without events ↔ pointless wake-ups | Room thermal time constants are tens of minutes; 5 min samples the plant several times per time constant. A faster tick could not act faster anyway, since actuation is bounded by the 30 s budget. |
| **5 min** | reconciler tick | healing latency for lost writes ↔ cost of observe+decide per tick | Lost writes are rare and not safety-relevant (those bypass and confirm); healing within minutes suffices. |
| **2 min / 5 min** | ladder down-debounce / up-stability | reacting to real outages ↔ flapping on sensor blips | Asymmetric on purpose: degrade quickly enough to matter, re-promote only after sustained recovery, which is classic reversionary-mode hysteresis. |
| **15 min** | watchdog stall threshold | catching a silent hang ↔ false alarms | Anchored: the 5-minute ticks guarantee a cycle at least every 5 minutes, so 15 minutes = three missed ticks = a real hang, not jitter. |
| **1 h** | maintenance max runtime | letting a slow valve exercise finish ↔ a dead run blocking control forever | A valve exercise takes minutes per TRV; an hour means the run died. The bound exists so maintenance can never block control permanently. |
| **3 s** | post-write propagation wait | reading the device echo as confirmation ↔ misreading it as an external change | Typical Zigbee/MQTT echo latency; without the wait, BT would treat its own write's echo as a user action. |
| **max(0.05 K, half device step)** | reconcile setpoint tolerance | detecting lost writes ↔ fighting device quantization | Anchored: a device snapping a value onto its own grid moves it at most half a step; below that is float noise. Fighting quantization would re-send every 5 minutes and drain batteries. |
| **5 % of the entity's range, at least one step below** | reconcile valve tolerance | detecting lost valve writes ↔ fighting device-side modulation and quantization | Real lost writes look like 0 vs 80, not 77 vs 80. Measured in the valve entity's own units, so a 0–255 entity gets the same 5 points of opening as a 0–100 one. The step below covers ZHA truncating a number onto its grid; nothing rounds a value already on the grid upwards. |
| **4 reversals / ≥20-point swings / 10 samples** | oscillation detector | catching thrash ↔ false positives | Biased toward quiet (annunciation-only makes a miss cheap and a false alarm noisy). To be tightened against benchmark data. |
| **Per-gain plausibility bands** | runaway-gain reset (PID auto-tune) | never clipping a legitimate tune ↔ catching divergence | Each gain has a fixed min–max band (`PIDParams` in `utils/calibration/pid.py`), the same limits the auto-tuner clamps its own steps to, so a legitimate tune cannot leave them; a stored gain outside its band resets the gains to defaults. The bands are generous; tighten them once benchmark/telemetry data justifies it. |
| **5 min** | startup degraded-mode grace | alarming on real outages ↔ alarming on slow cloud integrations at boot | Weather/cloud entities routinely need minutes to come online after a restart. |
| **50 entries** | flight-recorder ring | covering the window around an incident ↔ diagnostics download size | With background ticks every 5 minutes, 50 tuples span hours around the moment a user hits "download diagnostics". |

When one of these constants changes, the table entry is the review
checklist: name which pressure moved and what evidence moved it.
