Skip to content

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 WorldSnapshot is the immutable observation of one control cycle: temperatures, modes, environment, and the reported state of every TRV.
  • The KernelState aggregates the discrete state machines (the regions) that persist between cycles.
  • A DesiredState expresses 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.

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.

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.

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.