Introduction
The Heating X2 blueprint, with the accompanying optional Code Generator, offers comprehensive heating control for systems from a single thermostat up to a full smart home heating system with multiple thermostats grouped by room and zone.
Heating X2 can stand alone or be used as part of the suite that includes Calendar switch Y2: switch a device using a calendar, and Zone Switch Z2: operate a heating zone valve from a heat demand sensor
Features
- 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: 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: 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: sets 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
- Logging: optional recording of key events from the heating automations into a log file
- 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 Microsoft WORD Mail Merge to automatically generate YAML code for all the required helpers, timers, log files, template sensors, groups, automations, and dashboard cards from a single EXCEL spreadsheet that lists your 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 â see below.
If you have multiple heating zones, or a boiler that needs a heat demand signal, code generator created sensors and groups, and the Zone Switch Z2 blueprint complete the kit.
History
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.
Installation
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.
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 XYZ Log File Entry script
The blueprint requires a script that facilitates the formatting and writing of the log file(s). (More on logging below). It is mandatory, even if you do not want logging, because the test for logging required is included in the script to declutter the blueprint.
It is not a blueprint, just a script, so the recommended installation method is:
- Create the file
scripts.yamlin/CONFIG/if you do not already have it - In
configuration.yamladd the following line if you do not already have it
script: !include scripts.yaml
- Copy the heating_xyz_logfile_entry code from GitHub
- Paste the code into
scripts.yaml
The same script is used by Heating X2, Calendar Switch Y2, and Zone Switch Z2, so you only need do this once.
Devices
Thermostats
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.
Calendars
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. Overlapping events are allowed. The event with the latest start time takes precedence.
-
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.
Input_numbers
-
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)
Timers
-
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.
Logging
Logging is optional, so skip this step if you do not want it. The default blank in the blueprint logging service name indicates that no logging is required.
To enable logging
- If you want to keep your log fles in a folder, then add the folder to /CONFIG/ â in my example it is called
log_files. - In
configuration.yamladd an entry for each automation like this
notify:
- name: immersion_heater_log
platform: file
filename: log_files/immersion_heater_log.txt
timestamp: true
- Specify the service name (not the file name), exactly as defined, in the blueprint parameters (below). In my example the name is
immersion_heater_log
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.
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
The guide âSmart Heat Your Home with Heating XYZâ, with hardware and software configuration tips and detailed instructions for using the code generator, is bundled with the Code Generator download.
Good Luck!
If you use this blueprint, please âŠ
I would ask you to consider changing that.
