Heating X2: Schedule Thermostats with Calendars


The Heating X2 blueprint, with the accompanying Code Generator and Zone X2 blueprint, offer comprehensive heating control for systems from a single thermostats up to a full smart home heating system with multiple thermostats grouped by room and zone.

  • Schedule by calendar: set the temperature of each room with a local calendar and as many heating events as you like
  • Multiple thermostats: One or more thermostats per room: multiple thermostats are synchronised together. Works with smart TRVs, any smart thermostat, or Generic Thermostat
  • Manual override: a change on the thermostat, dashboard or by voice assistant remains in effect for a defined period (default 2 hours)
  • Door or window open: heating turns off heating in the room if any door or window is left open for a defined period (default 3 minutes) – optional list of zero or more closure sensors.
  • Occupancy: heating turns off heating if a room is left unoccupied for a defined period (default 1 hour) – optional list of zero or more motion or human presence sensors.
  • Warmup period: occupancy is ignored for a defined period at the start of a calendar event (default 2 hours)
  • Away mode: set all rooms to a temperature specified per room (default 5C) when there is no one at home
  • Background temperature: used when there is no calendar event (default 5C but specified separately from the frost and away temperatures)
  • Zone control: can switch one or multiple heating zone valves, or a boiler that needs a heat demand switch, based on heat demand from a group of thermostats
  • Notifications: if thermostats do not respond to a new setting, go offline, or come back online
  • Robust: Graceful degradation when a thermostat or a sensor is offline
  • Battery-efficient: conserves TRV battery life by only transmitting real changes
  • Code generator: uses mail merge (!) to automatically generate YAML code for helpers, timers, template sensors, groups, automations, and dashboard cards from a single EXEL spreadsheet that lists zones, rooms and thermostats

For one or two thermostats, you can use the Heating X2 blueprint stand-alone and create automations from it in the UI in the usual way.

If you are setting up a complete smart home heating system with multiple rooms, and have WORD and EXCEL, then you should try the accompanying Code Generator. You provide a single EXCEL spreadsheet listing your zones and rooms, possibly with several radiators in each room, as well as other heating devices such as water heaters, underfloor heating and Generic Thermostats created in Home Assistant. The Code Generator uses mail merge to create all the YAML code you need to define the helpers, timers, template sensors, automations and dashboard cards you need. The kit includes a detailed guide on how to set up smart heating and instructions for using the code generator.

If you have multiple heating zones, or a boiler that needs a heat demand signal, code generator created sensors and groups, and the Zone X2 blueprint complete the kit.


Heating X, the first release, was published on the Home Assistant Community Forum and GitHub in February 2023. This new release Heating X2 (Heating X, release 2) follows a year of testing Heating X in two homes with several rooms each, and feedback from users of the first release.


Get the Heating X2 Blueprint

Heating X2 is published separately from Heating X because it is not ‘plug compatible’ – the inputs have changed so it is not just a matter of changing the code.

New users should adopt release 2 straightaway. Existing release 1 users should consider upgrading, but a new install will be required. Note however, that the release 2 code generator now includes the generation of the automations. The new blueprint has a different name Heating X2, so can co-exist with Heating X.

Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.
Or use this link to access the code manually in GitHub.

One instance of Heating X2 is required for each Room in your house that is equipped with smart TRVs, and further instances can be used for other types of thermostat that you want to control with a calendar.

It is designed for HVAC-heating and uses the Centigrade temperature scale, but could doubtlessly be adapted for air conditioning (HVAC-cooling) or to work in Fahrenheit.

Get the Heating X2 Code Generator

Each instance of Heating X2 requires a number of helpers (input texts, input numbers and timers). You can define these by hand (see below), but to help set up a large installation, there is a Code Generator that uses Mail Merge to generate all the YAML code you need to define the helpers and timers required by the Blueprint for any size of installation. You simply list your Rooms and Thermostats in an EXCEL spreadsheet, then use WORD Mail Merge files to create the YAML code. There are additional optional code generators for template sensors, the automations and an example dashboard view.

The Code Generator uses Microsoft Mail Merge, so you will need a system running Microsoft Office (sorry, I could not find a free app for this).

The download includes a detailed guide to setting up a smart home heating system and full instructions on how to use the Code Generator package. Download it from here:

AndySymons / Heating-X-code-generator

Get the Zone X2 Blueprint

If you gave a heating system with multiple zones, of a boiler that requires a heat demand switch, then you need this simple little blueprint to complete the kit.

Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.
Or use this link to access the code manually in GitHub.



Heating X2-based automations can control anything with domain ‘climate’, so physical smart thermostats such as TRVs, water heaters, or Generic Thermostats that for example links a temperature sensor with a heater that has a smart plug.

A room can have more than one Thermostat; multiple thermostats in the same room operate in tandem, synchronised to the same settings.

You can name the thermostats as you wish, but for a large installation you might want to follow the Code Generator’s recommended names.

Door or Window Opening Sensors (optional)

If you have installed contact sensors or similar (with device class ‘opening’), you can list them in the blueprint input.

Then, if any door or window is open for a defined period of time (default 3 minutes), the automation turns the heating to the minimum (frost) setting. When all doors and windows are closed the heating reverts to normal.

If a sensor goes offline, it is treated as showing ‘closed’. If you have no closure sensors at all, Heating X2 automations will act as if all doors and windows are always closed.

Occupancy Sensors (optional)

If you have installed one or more sensors with device class ‘occupancy’, such as PIR motion sensors or human presence sensors, you can list them in the blueprint input.

Then, if all of these report ‘clear’ for a defined period of time (default 1 hour), the room is considered unoccupied. If the room is not in a warmup period (see below) the automation will turn the heating to the background setting. When any one presence sensor reports ‘detected’ the room is considered occupied and the heating reverts to normal.

If a sensor goes offline, it is treated as showing ‘detected’. If you have no sensors at all, Heating X2 automations will act as if the room is always occupied.


Heating X2 uses Local Calendars to program the thermostat(s) for each room, one calendar per room.

For each automation (room or individual device such as water heaters), create a calendar using the Home Assistant Local Calendar integration (you need Home Assistant 2022.12.1 or later).

You can name the Thermostats as you wish, but for a large installation you might want to follow the Code Generator’s recommended names.

Heating X2 will probably also work with external calendars linked to Home Assistant, but I have never tested that.

Add an Event to the calendar for each period that you want to specify a temperature that is different from the background temperature (see below). Take care to put it in the right calendar as the integration tends to give you the wrong one by default.

  • In the Summary field put the title of the event as you want to appear on the dashboard in the reason text – e.g., “ Daytime setting”, “ Night setting”, “ Evening boost”. I recommend including the room name as an aid to picking up errors.

  • In the Description field, add the required temperature for this event anywhere between two hashes: e.g., “Set temperature to #21.5# C”. Do not use another hash before the one that introduces the temperature, or write anything else between the hashes. The value and step size should correspond to the devices you are using. The Blueprint checks that there is a valid temperature and reports any errors in the reason text.

  • Set the Event start and end times as usual. Consecutive events are allowed and the automation will transition directly from one to the other. If the second event overlaps the first, i.e. starts before the first one ends, it will only take effect when the first one ends. If the second one ends before the first one it will not be seen at all (that’s just the way calendars work in HA).

  • Set the events to Repeat daily or on specific days of the week as required.

Helpers and Timers

The blueprint requires a number of helpers and timers, which are used as global variables. The simplest method to set these up for a large installation is to use the Code Generator. If you cannot or do not want to use the Code Generator, you can create the helpers by hand for each automation (Room) that you are going to create with the blueprint.

Input Text

  • Setting reason – into which the automation writes the reason for the current setting for display on dashboards. Make the length 255 characters.


  • Manual temperature – into which the automation writes the temperature specified by manual override.

  • Required temperature – into which the automation writes the temperature currently set for the room (to optimise radio traffic and check response)


  • Manual override timer – which the automation uses for the time remaining for a manual intervention before it reverts to automatic

  • Warmup timer – which the automation uses for the time for the warmup period following a new calendar event

  • Door or window open timer – which the automation uses for the time until the heating will be turned off following a door or window opening (paused when they are all closed)

  • Room unoccupancy timer – which the automation uses to count down the time until the heating will be turned off following the room becoming unoccupied (paused when the room is occupied)

  • Echoblock timer – which the automation uses to time the response from a thermostat before checking its setting, and to distinguish manual changes to the set temperature from those made by the automation.

The Automations

For a large installation this can best be done by using the Code Generator. The automations can (and should) be edited in the UI afterwards.

If you prefer to create the automations by hand, create one automation for each room (or other devices controlled by one calendar) using the UI. Select the Blueprint Heating X2 and specify in the inputs the devices, calendar, helpers and timers described above. There are also some optional parameters…

Blueprint Parameters

At the time of creating the automation you can specify a number of parameters, i.e. fixed values for the Room. They all have defaults (which are also what the code generator will set), so you might want to skip this step at first and come back to them later.

  • Minimum thermostat temperature – the minimum temperature that your thermostat can be set to; a.k.a. frost setting. Default 5C.

  • Maximum thermostat temperature – the maximum temperature that your thermostat can be set to. Default 30C. (Would have to be set higher for a water heater, say 70C).

  • Manual override period – the time period for which a manual intervention will override the schedule. Default 2 hours.

  • Warmup period – the period of time from the start of a new event for which room unoccupancy will be ignored. Default 2 hours.

  • Door or window open delay time – the time for which a door or window can be open before the heating switches off. Default 3 minutes.

  • Room unoccupancy delay time – the time for which no presence in the room is detected before it is consider unoccupied. Default 1 hour.

Additional goodies

Template Sensors for Set and Measured Temperatures

The Code Generator provides optional template sensors for each thermostat to read the Set Temperature and the Measured (ambient) Temperature. The Heating X2 blueprint does not require these, but they are included in the code generator in case you want them for display on dashboards or as inputs to other automations.

There is a new, third template binary sensor called Heat Demand that can be used for zone control…

Zone Control

In some larger installations, the heating in rooms is divided over a number of zones through which hot water passes if an electric zone valve is open. Some boilers need the heating controller to tell it when heat is demanded. If the zone valves or boiler switch are connected to smart switches, then they can be controlled as follows. The code can be created by hand or using the Code Generator version 2.1.

  1. Implement the third template sensor for each thermostat – a ‘heat demand’ binary sensor that is ‘on’ when the set temperature is higher than the measured (ambient) temperature and off if it is not.

  2. Create a binary sensor Group of all the heat demand sensors for the thermostats that belong to the same zone. This Zone Group will be ‘on’ if any one of the thermostats is demanding heat, and off only if none of them are.

  3. Make a simple automation that is triggered by a change in the Heat Demand Group state and turns the zone control switch on or off as applicable.

Starter Dashboard

Dashboards can be complex for a large heating installation. They having nothing to do with the Blueprint, but a starter dashboard for a whole home heating control installation can be created using the Code Generator.

My starter dashboard has a card for each Room that has a vertical stack with the name of the room as its title, the thermostat(s) for that room, the reason text as a markdown card (because the text is too long for a regular text entity) and the manual override timer (so that it can be reset). See the picture at the top of this page.

I use Mushroom Cards and the Better Thermostat card, so if you want to use this card design, you need to import both of them first from HACS or change the dashboard code to use standard cards.

The code generator creates YAML for these example cards for every Room. That code can be used as a whole to make a complete View containing all your Rooms and Thermostats (in the order you listed them for the Code Generator), or you can select the code for each Room individually to place the cards separately on your dashboard. Once pasted in (either way), the dashboard and the card can be edited with the UI.

While testing, you might like to add some more of the helper and timer entities to the dashboard cards, so that you can better see what is going on. Adding timers allows them to be cancelled from the dashboard as well.

More details

A more detailed smart heating setup guide, and instructions for using the code generator are included in the Code Generator download.

Good Luck!


1 Like