Skip to content

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.

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.

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.