Architecture overview
Better Thermostat separates a pure decision core from an imperative shell. The core computes what every TRV should do; the shell observes Home Assistant and performs the device writes. The boundary is one function:
decide(snapshot, state) -> (desired, state')- A
WorldSnapshotis the immutable observation of one control cycle: temperatures, modes, environment, and the reported state of every TRV. - The
KernelStateaggregates the discrete state machines (the regions) that persist between cycles. - A
DesiredStateexpresses intent per TRV: mode, setpoint, valve percent, offset, and why heating is suppressed. The shell translates that intent into device writes.
decide() imports no Home Assistant code, performs no IO, reads no
clocks (time arrives inside the snapshot), and never mutates its input
state. The same inputs always produce the same decision, which is what
makes the flight recorder
replayable.
One control cycle
Section titled “One control cycle”flowchart LR
subgraph Triggers
EV[Sensor events]
UA[User actions]
TK[5-minute ticks]
end
EV --> RQ["request_control_cycle()"]
UA --> RQ
TK --> RQ
RQ --> Q["Queue (max. 1 pending)"]
Q --> SN["build_snapshot()"]
SN --> DE["decide(snapshot, state)"]
DE --> FR[Flight recorder]
DE --> HU[Safety hull]
HU --> WB[Write budget]
WB --> AD[Adapter / quirks]
AD --> TRV[(TRV)]
The snapshot is pulled, not maintained: it is built fresh at the start of each cycle and discarded afterwards, so a decision always sees one coherent world. Reactivity comes from the push side: every trigger requests a cycle, and the queue holds at most one pending request. A pending cycle automatically covers any state change that arrives before it runs, so bursts of events coalesce into one decision instead of many.
A cycle runs on:
- sensor events — a relevant room-temperature change, a TRV state change, a window transition (after the configured debounce; window kicks replace a pending request),
- user actions on the entity — target temperature, preset, HVAC mode (the service path requests the cycle directly),
- the five-minute ticks — the periodic tick and the
reconciler. The periodic tick
requests a cycle when a TRV runs a balance mode or the
default(external sensor offset only), MPC, MPC v2, TPI or PID calibration mode; in every other configuration it is an availability tick that advances the fail-soft ladder without requesting a cycle. A new configuration starts in the time-based mode, so it gets the availability tick unless a balance mode is set, - the follow-ups the shell schedules for itself: a budget-deferred write queues a cycle for the moment the budget reopens, and a skipped offline TRV queues one on the reachability region’s retry backoff.
Only one cycle runs at a time. The worst-case latency from event to decision is the remainder of the cycle currently running: a few seconds, dominated by device writes and their propagation wait.
The decision cascade
Section titled “The decision cascade”decide() evaluates one precedence cascade; the first tier that fires
wins:
flowchart TD
R{Devices released?} -->|yes| R1[No intents, released]
R -->|no| T{Every TRV released on its own?}
T -->|yes| T1[No intents, cooler still controlled]
T -->|no| A
A{Startup or maintenance running?} -->|yes| A1[No intents]
A -->|no| B{Mode OFF?}
B -->|yes| B1[OFF intent for every TRV]
B -->|no| C{Window or door open?}
C -->|yes| C1[OFF intent, suppression = window or door]
C -->|no| D{Call for heat?}
D -->|no| D1[OFF intent, suppression = no_call_for_heat]
D -->|yes| E[Heating intent: mode + setpoint = room target]
The cascade does not branch on the fail-soft ladder: every rung gets the same heating intent, with the user’s target as the setpoint. The shell reads the rung when it applies that intent. On OPTIMAL and SENSOR_FALLBACK it runs calibration on top of the setpoint; on HOLD it sends the setpoint uncalibrated and writes no offset and no calibrated valve percentage. The one valve write left on HOLD is the close on an OFF intent: a direct-valve TRV whose valve BT drives (by a calibration mode that writes the valve, or by boost) still gets it closed to 0 %.
The release tier is the user’s Release devices switch. Its intent addresses no TRV and is marked as released, and the shell reads the mark: it leaves the cooler alone as well and writes nothing else to the devices until the switch is turned off again. The learners are held as during a learning pause, the take-back cycle included. The regions keep tracking meanwhile, so the first cycle after the release decides on the window, mode and targets that hold by then.
A TRV released on its own reaches the kernel as TrvReported.released.
The address filter drops it from every tier, boost included, which keeps
commanding an unreachable TRV but never a released one. A snapshot whose
TRVs are all released gets the release tier’s block with no intents, but
the intent is not marked as released: the cooler is no TRV and stays
under the cooling channel. The snapshot keeps a released TRV that is still
waiting for its initialisation, so a room that starts with its TRVs
released reads as such.
Every tier above the heating intent also puts its own heating_blocked_by
block into the desired state: devices_released, startup,
valve_maintenance, hvac_off, window, door or no_call_for_heat.
The heating intent names none. The shell publishes the block of each
decision it commits as the thermostat attribute of the same name, and
asks the kernel once more where a cascade input changes without a control
cycle: when the devices are released or taken back, and when valve
maintenance starts and ends. These words are the public values of that
attribute; window, door and no_call_for_heat are also the suppression
reasons below.
OFF intents carry their suppression reason so the shell can choose between a literal OFF (window, no heat demand) and the device-specific remap of the user’s OFF mode, without reading the kernel’s internals. Reachability is an address filter rather than a cascade tier: an unreachable TRV is dropped from the commanded set and receives no intent, and its native thermostat keeps controlling at the last commanded state. Boost is the exception: while boost heating is active, unreachable TRVs stay addressed so they catch up the moment they return. Intents are strictly per TRV, so one dead TRV never drags the others down.
Where things live
Section titled “Where things live”| Concern | Home |
|---|---|
| Decisions (gates, precedence, modes) | core/decide.py + the regions |
| Observation | utils/snapshot.py → core/snapshot.py |
| Device writes | utils/controlling.py behind hull + budget |
| Cycle scheduling | utils/scheduler.py (requests coalesce) |
| Calibration math | calibration.py + utils/calibration/ |
| Persistence | utils/state_manager.py |
| Diagnostics | core/recorder.py + diagnostics.py |
The placement rule for new code: a new rule about what should happen
belongs in the core, with pure unit tests. New device interaction
belongs in the shell behind the existing boundaries. Writes go through
the safety hull and the write budget, cycles are requested through the
scheduler, and the shell applies intent without second-guessing the
kernel after decide() ran.