# Upgrading from 1.9 to 2.0

> What carries over from Better Thermostat 1.9, what you may need to change, and how 2.0 behaves differently.

Source: https://better-thermostat.org/setup/upgrading-to-2-0/

Your rooms, entities and learned values carry over to 2.0. You don't need
to set anything up again. Most of the changes are in how Better Thermostat
reacts when a sensor, a thermostat or the weather service stops answering.
This page compares 2.0 with 1.9.3, the last 1.9 release. If you are on
1.9.2 or older, also read [Already in 1.9.3](#already-in-193): those
changes reach you with this upgrade as well.

## Before you upgrade

- **Home Assistant 2026.11.0 or newer is required.** 1.9.3 runs on
  2026.9.0, 1.9.2 and older on 2026.7.2; update Home Assistant first.
- **Take a Home Assistant backup.** You can go back to 1.9.3 without one
  (see [Going back to 1.9](#going-back-to-19)), but a backup is the
  safer option.

## What carries over

- **Configuration:** every room keeps its settings. When 2.0 first starts,
  it moves each room's settings from the entry's data into its options; the
  values stay the same. Only 1.9.3 and newer read them there, see
  [Going back to 1.9](#going-back-to-19).
- **Entities:** entity ids and their history stay the same, except for the
  sensors listed under [Removed sensors](#removed-sensors).
- **Learned values:** heating power, heat loss, and the PID, TPI, MPC and
  MPC v2 state continue where 1.9 left off.
- **Services:** the same three services exist with the same fields.
- **Calibration modes:** the list of modes and the default (AI Time Based)
  are the same. Your selected mode stays selected.

## What you may need to change

### Removed sensors

2.0 removes these sensors when it first starts:

- **Sun Intensity Heatup**, the diagnostic solar intensity sensor every
  thermostat had. No controller reads it, and 2.0 has no replacement.
- **PID Kp, PID Ki and PID Kd**, the sensors of a thermostat on the PID
  calibration mode. The number entities *PID Kp (Proportional)*, *PID Ki
  (Integral)* and *PID Kd (Derivative)* show the same gains and stay.

A dashboard card, template or automation that uses one of these sensors
shows it as unavailable. Point the PID ones at the number entities and
remove the solar intensity sensor.

### Templates and automations

- **`saved_temperature` is gone.** The climate entity no longer has this
  attribute. Nothing in 1.9 set it, so it only ever held an old value or
  nothing. The temperature a preset returns to is still in
  `preset_temperature`.
- **`last_change` is gone.** The climate entity no longer has this
  attribute. 1.9 set it once at startup, to two hours before the start, and
  never updated it, so it never said when anything changed. Home Assistant
  records when the entity last changed state in its `last_changed` property,
  for example `states.climate.living_room.last_changed` in a template.
- **Invalid service calls now fail.** Setting an HVAC mode other than heat,
  heat/cool or off, or a temperature that isn't a number, raises an error.
  1.9 logged these calls and ignored them. An automation that sent such
  values now shows the error in its trace.
- **Keys in the learning attributes are renamed.** In `heating_cycle_last`,
  `delta_t` is now `delta_kelvin`, `temp_start` `start_temperature`,
  `temp_peak` `peak_temperature` and `rate_c_min` `rate_kelvin_per_min`. In
  `heat_loss_cycle_last`, `temp_start` is now `start_temperature` and
  `temp_min` `min_temperature`. In `heat_loss_stats`, `dT` is now
  `delta_kelvin`. The values are the same. A template that reads an old key
  gets nothing and has to use the new one.
- **The preset attributes lose their `bt_` prefix.** `bt_preset_cool_temperature`,
  `bt_preset_cool_temperatures` and `bt_preset_heat_temperatures` are now
  `preset_cool_temperature`, `preset_cool_temperatures` and
  `preset_heat_temperatures`. 2.x publishes the old names as well, with the
  same values, so templates keep working; switch them to the new names before
  3.0, which drops the old ones.
- **Two more attributes are renamed the same way.** `external_temp_ema` is now
  `room_temperature_filtered`, and `temp_slope_K_min` is now
  `temperature_slope_kelvin_per_min`. 2.x publishes the old names as well;
  3.0 drops them. The recorder keeps neither name of either attribute: their
  history is on the Temperature EMA and Temperature Slope sensors.
- **The PID and MPC v2 diagnostic attributes spell out their units.**
  `pid_e_K` is now `pid_error_kelvin`, `pid_meas_smooth_C`
  `pid_measurement_filtered`, `pid_d_meas_K_per_min`
  `pid_measurement_slope_kelvin_per_min`, `pid_dt_s` `pid_dt_seconds`,
  `mpc_v2_D_hat_K_per_min` `mpc_v2_disturbance_kelvin_per_min`,
  `mpc_v2_tau_room_min` `mpc_v2_tau_room_minutes` and `mpc_v2_group_valve_pct`
  `mpc_v2_group_valve_percent`. 2.x publishes the old names as well; 3.0
  drops them.
- **More diagnostic attributes are renamed.** `mpc_v2_T_room_hat` is now
  `mpc_v2_room_temperature_estimate`, `mpc_v2_T_rad_hat`
  `mpc_v2_radiator_temperature_estimate`, `mpc_v2_coupling_rad_room`
  `mpc_v2_radiator_room_coupling` and `heating_power_norm`
  `heating_power_normalized`. 2.x publishes the old names as well; 3.0 drops
  them.

### Cooling devices

The option "Minimum seconds between repeated cooler commands" is gone.
Better Thermostat now holds back an unchanged temperature or mode command
if it sent the same value less than 240 seconds earlier, to protect the
compressor. A mode the cooler left on its own since that command, through
its remote or an outage, is sent again at once, but only once in those 240
seconds. A changed value goes out with the next control cycle; if the
previous command failed, it waits at least 30 seconds after that failure. A
failed command is retried with its own growing pause, from 30 seconds up to
30 minutes. You don't need to do anything; a
value you set before is ignored.

## What behaves differently

### A window or door sensor stops reporting

1.9 treated an unavailable window or door sensor as **open**: heating
paused until the sensor came back. 2.0 treats it as **closed**, so the
room keeps heating, and reports the sensor through the
[degraded mode](https://better-thermostat.org/faq/degraded-mode/) repair issue.

If a window sensor with a flat battery used to stop your heating and you
relied on that, keep an eye on your battery levels.

### The room temperature sensor stops reporting

1.9.3 switched to the first thermostat's own temperature after two minutes
without a reading and went back as soon as the room sensor reported again.
With no thermostat temperature either, it kept controlling on the last
reading. 2.0 steps down:

1. After about two minutes without a reading, it controls on the average
   of the thermostats' own temperatures.
2. If no temperature is usable at all, it stops adjusting and keeps the
   last state.
3. Once the room sensor has reported steadily for five minutes, it goes
   back to normal control.

The climate entity shows the current step in `control_mode` (`optimal`,
`sensor_fallback` or `hold`) and how long it has been degraded in
`degraded_for_seconds`. A thermostat's own sensor sits next to the hot valve, so
control is less accurate while the fallback runs.

### Summer mode with an outdoor sensor

1.9 averaged the outdoor sensor's readings per calendar day, for today
and yesterday. Every reading counted once, so a sensor that reports often
while the sun heats it pulled the average up, and the average jumped at
midnight. 2.0 damps the readings by time: each reading counts for as long
as it was current, and older readings fade out with a time constant of 24
hours. A warm afternoon no longer turns the heating off on its own, and a
single warm reading takes hours to show.

Summer mode also has a switch-back margin now. It starts when the outdoor
temperature reaches the threshold and ends once it is 1 °C (1.8 °F) below
it, for the outdoor sensor and the weather entity alike. 1.9 switched
back at the threshold itself. See [Summer mode](https://better-thermostat.org/deep-explanations/summer-mode/).

The weather entity changes the same way. 1.9 compared its current
temperature as it was, so a cold night resumed heating and the afternoon
stopped it again; 2.0 damps it like an outdoor sensor's readings. And
1.9 averaged a daily forecast's highs only, which reads several degrees
too warm; 2.0 takes the mean of each day's high and low. Both numbers now
stand for whole days, nights included, and read several degrees lower than
before. With the threshold you had, summer mode starts later in spring and
ends earlier in autumn. If the room now heats on days you count as warm,
lower the threshold.

### Smaller changes

- **Calibration offsets in °F:** a calibration offset number that Home
  Assistant shows in °F, such as the eQ-3 Bluetooth and Plugwise offsets, is
  now read and written as the offset it is, and the Sonoff TRVZB's external
  temperature input gets the room temperature in the unit it shows. 1.9.3
  converted neither.
- **Z-Wave JS configuration parameters** that count tenths or hundredths of
  a degree Celsius are read and written in that unit. The temperature offset
  of the Eurotronic Spirit and the Aeotec ZWA021, parameter 8, counts tenths
  of a degree, so 1.9.3 applied a tenth of every offset it wrote. Its
  reserved value -128 (external sensor) is read as no offset and never
  written. Home Assistant creates the parameter disabled; enable it and
  reload Better Thermostat to use Offset Based calibration on the Spirit.
- **`min_temp` and `max_temp`** on the climate entity now cover the heating
  and the cooling range together.

## What is new

- **Sensors for MPC v2:** thermostats on the MPC v2 calibration mode get
  four diagnostic sensors: virtual temperature, coupling, disturbance and
  room time constant.
- **Climate attributes:** `control_mode` and `degraded_for_seconds` (see above),
  and `calibrator_health`, which reports per thermostat whether its
  controller is healthy.

## Already in 1.9.3

1.9.3 brought these changes to the 1.9 line. If you upgrade from 1.9.2 or
older, you get them with 2.0.

- **A thermostat in more than one room.** A thermostat (TRV) can belong to
  only one Better Thermostat. Creating a room or adding a thermostat to one
  is refused when another Better Thermostat already controls that
  thermostat. A setup that already shares one keeps running, but Home
  Assistant shows a repair issue, "controlled by more than one Better
  Thermostat". Remove the thermostat from every room but one; the repair
  issue clears by itself.
- **Device triggers fire less often.** "Thermostat switches to heating",
  "Thermostat stops heating", "Window opened" and "Window closed" fire only
  on a real change. A thermostat or sensor that goes unavailable and comes
  back no longer fires them. If an automation relied on that, trigger on
  availability instead.
- **Entities of a calibration mode you no longer use are removed.** When
  you switch a thermostat to another calibration mode, the old mode's
  entities, such as the PID numbers and switches, go away. 1.9.2 left them
  behind as unavailable.
- **The room temperature sensor stops reporting.** After two minutes
  without a reading, the room controls on a thermostat's own temperature.
  1.9.2 kept controlling on the last reading. 2.0 refines this further, see
  [above](#the-room-temperature-sensor-stops-reporting).
- **A thermostat doesn't come back after a restart.** 1.9.2 waited for
  every thermostat, so one that never came back left the whole room
  uncontrolled, windows and sensors included. The room now starts with the
  thermostats that answer after a two-minute grace period; the missing one
  joins when it reports.
- **The weather service fails.** 1.9.2 switched heating on as soon as a
  forecast failed. Better Thermostat now keeps its last decision for three
  hours. If that decision was not to heat, it then resumes heating with the
  logbook entry "resumed heating because the weather forecast is
  unavailable".
- **A thermostat keeps rejecting commands.** 1.9.2 retried a failed control
  cycle right away, over and over. Better Thermostat now doubles the pause
  after each failure, up to five minutes. With the HomematicIP option, its
  ten minutes between writes can make a retry wait longer. A retry that
  gets through, a new target temperature or a new HVAC mode resets the
  pause.
- **Target temperatures** are clamped to the room's range and rounded to
  its step when you set them.
- **Fahrenheit systems** show tenths of a degree, and `target_temp_step` is
  Home Assistant's own attribute, in °F. 1.9.2 overwrote it with the step
  in °C.
- **Direct valve control** is also offered for a Sonoff TRVZB outside
  Zigbee2MQTT, for example one paired through ZHA, as long as its valve
  opening shows up as an enabled number entity on the same device.

## Going back to 1.9

Go back to **1.9.3 or newer**. 2.0 keeps a thermostat's settings in the
entry's options instead of its data, and 1.9.3 is the first 1.9 release that
reads them there. Install it again through HACS and you keep your rooms and
the learned values; if you change a setting in 1.9.3, 2.0 takes the changed
value over when you update again.

1.9.2 and older read the settings from the old place only. They load your
rooms without thermostats or sensors, and saving the settings there replaces
what 2.0 stored.

What you lose by going back:

- **MPC v2 starts learning again.** 1.9 can't read the controller state
  2.0 saves, and also drops the room model and temperature filters that
  only 2.0 keeps. Everything else you learned stays.
- **The behaviour changes on this page are undone.** For example, 1.9
  again treats an unavailable window sensor as open.
