Calibration Algorithms

Better Thermostat offers several calibration algorithms (the Calibration mode option) that control how your TRV (Thermostatic Radiator Valve) is adjusted to maintain your desired temperature. Each algorithm has different characteristics and is suited for different situations.

Choosing an algorithm

Start here if you are unsure:

Your situation	Algorithm
Setting up for the first time	AI Time Based (default)
Room heats too slowly	Aggressive
Temperature often overshoots	MPC Predictive
You want fine control and know PID tuning	PID Controller
You want something simple	External Sensor Offset Only or TPI Controller
You want to try an experimental predictive controller	MPC v2
You want the TRV to regulate on its own	No Calibration

The algorithms

External Sensor Offset Only

This mode uses your external temperature sensor to correct the TRV’s internal one. Better Thermostat compares the two readings and sends the TRV an offset, or a setpoint that already carries the difference; the TRV keeps running on its own sensor and never sees yours.

It is simple, reliable, works with most TRVs and costs almost nothing to run. In exchange it does not optimise for efficiency and does not adapt to the room.

Use it as a starting point when you want reliable control and no complexity.

Aggressive

Aggressive works like External Sensor Offset Only but pushes the TRV harder: while the thermostat is heating, it shifts the offset or setpoint a further 2.5 °C in the heating direction, unless the correction already reaches that far, so the TRV opens wider than it otherwise would. It also skips the tolerance delay before heating starts.

That gets a slow or poorly insulated room warm quickly. The cost is overshoot, wasted energy when the speed was not needed, and more valve movement.

Use it when the room takes a long time to warm up, or when you need a fast change, such as coming home to a cold house.

AI Time Based

The setup form labels this mode (AI) Time Based (Default). This is the default, and the right choice for most rooms.

It learns your room’s heating characteristics over time. It still reads your external temperature sensor, but derives the calibration from its own model rather than leaving the decision to the TRV’s built-in logic, so it adapts to how fast your room actually heats and cools.

Once settled it balances comfort against energy use, keeps overshoot down and copes with changing conditions. The trade-off is the learning phase: expect two to three days before the results are good, and accept that behaviour in that window is not yet tuned.

MPC Predictive

The setup form labels this mode MPC Predictive (Beta).

MPC (Model Predictive Control) predicts how your room temperature will change over the next 30 minutes, in six steps of five minutes. It reads several inputs, among them:

Room temperature, its trend and your target
Learned thermal properties of your room (how fast it heats and cools)
Outdoor temperature, daylight and solar intensity
Window state, and the valve opening it last asked for

From that prediction it picks the correction that reaches your target smoothly instead of driving hard and correcting afterward, and it keeps updating the model as the room behaves. With direct valve control that correction is a valve opening; without it, the correction reaches the valve through the setpoint the TRV sees.

It aims at arriving at the target rather than at arriving quickly, which is the whole point of predicting ahead. It is the most complex of the modes and it reacts deliberately rather than fast, which can read as sluggish at first. Give it about a day of operation before judging it.

Pick it when you overshoot regularly, when a steady arrival matters more to you than reaction speed, and when your heating system itself is reasonably stable. In the project’s benchmark it works the valve harder than PID or TPI, and with several radiators in one room it can over-react.

MPC v2

The setup form labels this mode (AI) MPC v2 (QP + Kalman, experimental).

MPC v2 is an experimental predictive controller. It estimates the room’s state with a Kalman observer and computes the valve opening by solving a small optimisation problem (a quadratic program) over a receding horizon. With the Direct Valve Based calibration type that opening is written to the TRV as it stands (see Direct valve control). With any other calibration type, MPC v2 turns the opening into a setpoint between the TRV’s current reading and its maximum: the wider the opening, the higher the setpoint. Target Temperature Based sends that setpoint to the TRV as its target temperature; Offset Based leaves the target temperature as it is and moves the calibration offset by the difference instead, rounded to the TRV’s offset step and limited to its offset range.

The MPC v2 room size option sets the room model it starts from. Auto derives it from the heat-loss rate Better Thermostat has learned for the room; the small, medium and large room presets use a fixed model instead.

PID Controller

⚠️ Beta Status: The PID Controller is currently in beta and may require further fine-tuning in the algorithm. While it’s functional and includes auto-tuning capabilities, you may experience some edge cases that need optimization. Feedback and real-world testing are appreciated.

PID (Proportional-Integral-Derivative) is the classic industrial control method. It sets the valve position from three terms:

P (Proportional): how far you are from the target temperature
I (Integral): how long you have been away from it
D (Derivative): how fast the temperature is moving

It tunes those three itself over time.

PID reacts fast and handles disturbances well, which is what makes it a good fit for a room with sun through the windows, draughts or a heat source whose output varies. Early on it can be aggressive and oscillate a little while it tunes, and getting the most out of it means understanding roughly what the three parameters do.

Pick it when your heating power varies, when outside influences keep moving the room temperature, and when you want a responsive controller and are comfortable with the parameters.

Auto-tuning and manual tuning

Auto-tuning is on by default.

How tuning proceeds:

At the start: The controller keeps its gains per TRV and per target temperature, rounded to 0.5 °C. It starts from the gains kept for the current target: values you set on the PID numbers, or values it tuned earlier at that target. A target with neither starts from the defaults (Kp=60, Ki=0.01, Kd=2000), so tuning starts over at a target it has not seen. You may notice slight temperature oscillations as it adjusts.
While tuning: The algorithm adjusts the gains at most every 5 minutes, and only when one of these conditions holds (the “target band” is 0.1 °C either side of the target):
- Overshoot: The room was outside the target band at the previous calculation and is inside it now, coming from either side. It decreases Kp (less aggressive), increases Kd (more damping) and decreases Ki. A room that heats up into the target band from below counts as well
- Sluggish response: The room is more than 0.1 °C below the target, its temperature changes by less than 0.005 °C per minute (0.3 °C per hour) and the valve output is below 95 %. It increases Ki and Kp
- Steady state: The room is inside the target band and the valve output is below 20 %. It decreases Ki
Settled: Each time the room comes back into the target band, Kp falls by 10 % (to no less than 10, so a Kp set below 10 is raised to 10) and Kd rises by 10 % (to no more than 10,000); auto-tuning never lowers Kd, and a Kd of 0 stays 0, so a PI controller stays one. While the room holds the target with a small valve output, Ki keeps shrinking every 5 minutes until it reaches its lower limit of 0.001. How many heating cycles that takes depends on the room; the code sets no fixed period.

What to expect:

Adjustments happen at least 5 minutes apart (300 seconds) to avoid over-tuning
Parameters are constrained to safe ranges:
- Kp: 10-500
- Ki: 0.001-2.0
- Kd: up to 10,000 (auto-tuning only raises it)
Auto-tuning is conservative - it makes small changes and learns gradually

Manual tuning:

Each TRV’s PID Kp (Proportional), PID Ki (Integral) and PID Kd (Derivative) numbers accept Kp from 0 to 1000, Ki from 0 to 100 and Kd from 0 to 10,000, and Better Thermostat keeps a value set there, including 0 (Kd 0 makes a PI controller). With auto-tuning on, a value you set is the starting point it adjusts from; turn off the PID Auto Tune switch to keep fixed values.

If you want to tune PID parameters manually or understand what the auto-tuning is doing:

Kp (Proportional gain): Controls immediate response to temperature error
- Too high: Oscillations and overshoot
- Too low: Slow response, takes long to reach target
- Default: 60
Ki (Integral gain): Eliminates steady-state error over time
- Too high: Oscillations, instability
- Too low: Never quite reaches target (offset)
- Default: 0.01
Kd (Derivative gain): Predicts future error based on rate of change
- Too high: Sensitive to noise, erratic behavior
- Too low: Overshoot, slow damping
- Default: 2000

Monitoring the learned values:

You can monitor the learned PID values in Home Assistant:

Go to Developer Tools → States
Find your Better Thermostat entity
Look for attributes containing PID debug info showing current Kp, Ki, Kd values

Getting the best out of PID:

Give auto-tuning one to two weeks to settle
Keep target temperatures consistent; auto-tuning reads a moving target as a disturbance
Avoid changing the target often during the learning phase
Place the external sensor away from heat sources and draughts
Prefer a device with direct valve control (see Direct valve control)

Turning auto-tuning off:

While not recommended for most users, auto-tuning can be disabled with the PID Auto Tune switch of the device if you prefer fixed PID parameters. This is only useful if you have specific PID values you want to maintain.

TPI Controller

TPI (Time Proportional Integral) turns the distance from your target (plus, when an outdoor temperature is available, the difference between target and outdoor temperature) into a duty cycle between 0 and 100 %. Better Thermostat uses that duty cycle as a steady valve opening: at 60 % demand the valve is held 60 % open.

The model is easy to follow and suits a radiator with real thermal inertia. It does less than MPC or PID, and it adapts less readily when conditions change.

Pick it when your heating system is consistent and you want predictable behaviour without the machinery of the learning modes.

No Calibration

No Calibration passes your target temperature to the TRV unchanged and writes no offset. The TRV regulates on its own sensor and receives no correction from your external sensor.

Pick it when you want the TRV’s built-in control and only use Better Thermostat for scheduling, windows and grouping.

Comparison

Feature	External Sensor Offset Only	Aggressive	AI Time Based	MPC Predictive	PID Controller	TPI Controller
Complexity	Low	Low	Medium	High	Medium	Low
Learning	No	No	Yes	Yes	Yes	No
Response Speed	Medium	Fast	Medium	Measured	Fast	Medium
Writes the valve directly	No	No	Yes	Yes	Yes	Yes
Status	Stable	Stable	Stable	Beta	Beta	Stable
Best For	Simple setups	Fast heating	Most users	Steady arrival	Variable systems	Simple control

Notes:

“Writes the valve directly” applies with the Direct Valve Based calibration type (see Direct valve control below)
MPC v2 (experimental) and No Calibration are left out of the table; see their sections above
PID Controller is in beta and may require further algorithm fine-tuning

How algorithms and calibration types combine

The Calibration Mode (algorithm) works together with the Calibration Type:

Target Temperature Based: The algorithm calculates what target temperature to send to the TRV. For example, if you want 20°C but the room is cold, it might send 22°C to the TRV to make it heat more.
Offset Based: The algorithm calculates what temperature offset to send to the TRV. For example, if the TRV’s internal sensor reads 21°C but your external sensor reads 20°C, it sends an offset of -1°C.
Direct Valve Based: The algorithm’s valve opening is written to the TRV’s valve position entity. Modes that produce no valve opening send a target temperature instead, as with Target Temperature Based.

Not all TRVs support offset-based calibration or direct valve control. Better Thermostat detects your TRV’s capabilities and only offers the calibration types it supports.

Direct valve control

Some TRV devices support direct valve control, where Better Thermostat can directly set the valve opening percentage (0-100%) instead of only adjusting target temperatures or offsets. That sends the selected algorithm’s valve decision straight to the TRV, instead of letting the TRV’s own controller decide what to do with a setpoint.

What direct valve control is

With direct valve control, Better Thermostat can:

Set the exact valve opening (e.g., “open valve to 45%”)
Bypass the TRV’s internal temperature control logic
Achieve more precise and responsive heating control
Better implement advanced algorithms like MPC and PID

Devices that support it

Direct valve control is available for TRVs that expose valve position as a controllable entity, including:

Sonoff TRVZB (via Zigbee2MQTT or ZHA)
TRVs exposed via MQTT with valve position entities
Z-Wave JS TRVs that expose a valve position entity, and the Eurotronic Spirit Z / Aeotec ZWA021
Other Zigbee TRVs that expose valve control through their integration

Better Thermostat detects whether your TRV supports direct valve control and then offers the Direct Valve Based calibration type. It only writes the valve when you select that type.

How the algorithms use it

With the Direct Valve Based calibration type:

MPC Predictive: Calculates a valve opening from its prediction of where the room is heading, and that opening is written as it stands.
PID Controller: Directly outputs valve position based on temperature error and trends.
TPI Controller: Sets valve opening based on heating duty cycle calculations.
MPC v2: Computes the valve opening from its optimisation.
AI Time Based: Derives a valve opening from the heating power it has learned.
External Sensor Offset Only, Aggressive, No Calibration: These produce no valve opening. Better Thermostat sends them to the TRV as a target temperature instead.
Boost preset: While Boost is heating, Better Thermostat opens the valve to the TRV’s Valve Max Opening under every calibration mode. When the TRV is switched off during Boost (Better Thermostat off, a window open, no heat called for), it closes the valve to 0 %, as it does under the modes that write the valve.

Without direct valve control

If your TRV doesn’t support direct valve control, or you pick another calibration type, Better Thermostat uses setpoint manipulation:

Adjusts the target temperature sent to the TRV
Or adjusts the temperature offset (if supported)
The TRV’s internal controller then adjusts the valve based on its own logic

This still works well but gives the TRV’s internal algorithm more influence over the final valve position.

Checking whether you have it

Open the Better Thermostat entry in Settings → Devices & services and choose Configure
Open the Calibration type dropdown in the advanced step
If it offers Direct Valve Based, your TRV supports direct valve control

For MQTT/Zigbee2MQTT users, you can also check if your TRV exposes entities like:

number.your_trv_valve_position
number.your_trv_valve_opening_degree

What it buys you

The algorithm sets the valve opening itself rather than asking the TRV’s own logic for it, so the response arrives without a detour and the room’s reaction is a cleaner signal to learn from. Valve position is not heat output (flow temperature and the valve’s own authority still sit in between), but it is the most direct handle Better Thermostat can get on the device. Every mode runs without it.

If you are buying new TRVs

If you’re purchasing new TRVs and want the best performance from Better Thermostat’s advanced algorithms (especially MPC Predictive or PID Controller), consider devices that support direct valve control through Zigbee2MQTT or similar integrations.

Getting good results

Give it time: Algorithms with learning need time to learn your room:
- MPC Predictive: 1 day for fine-tuned performance
- AI Time Based: 2-3 days for optimal performance
- PID Controller: 1-2 weeks for auto-tuning to settle
Stable placement: Keep your external temperature sensor in a consistent location away from heat sources, drafts, and direct sunlight.
Start with defaults: Try AI Time Based first. Only change if you have specific issues.
Monitor and adjust: Check the temperature graphs in Home Assistant after a few days. If you see problems (overshooting, slow response, etc.), try a different algorithm.
Consider your heating system:
- Fast-responding systems (electric radiators): PID or TPI work well
- Slow-responding systems (water radiators, underfloor): MPC Predictive works well
- Inconsistent heating power: PID Controller handles this best

Troubleshooting

Temperature overshoots:

Try: MPC Predictive, or enable overheating protection (it acts in AI Time Based and Aggressive)

Too slow to reach temperature:

Try: Aggressive mode

Temperature oscillates up and down:

Try: Increase the Tolerance setting in first configuration step

Algorithm isn’t working well:

MPC Predictive: Wait at least 1 day for learning
AI Time Based: Wait 2-3 days for learning
PID Controller: Wait 1-2 weeks for auto-tuning to settle
Check sensor placement and accuracy
Verify TRV is working correctly
Try a different algorithm

Technical details

For developers and advanced users who want to understand the implementation details, see:

Hydraulic balance - How the controller modes drive the valve or the setpoint
Source code in custom_components/better_thermostat/utils/calibration/ directory