The code in this repository is production-ready; however, the documentation below just covers some basics ATM. I might improve it at a later stage should there be sufficient user interest.
This repository contains a demand-driven heating control system built for Home Assistant with the app (add-on) AppDaemon.
Why AppDaemon? It has been chosen for its advanced possibilities of using Python virtually without restrictions (other than PyScript), including being able to create (multiple) instances of a class. This feature allows creating instances of HeatingAutomation for each room of the house, allowing for efficient and straightforward coding.
The class HeatingPumpControl acts as control center for determining a room's heating demands and controlling whatever means of heating a house has. Heating starts by writing the target flow temperature to the HA Helper input_number.target_flow_temp (done by HeatingPumpControl), which in turn can be picked up by the actual code controlling the heating (pump), in this case by the ESP WT32-ETH01. Heating is stopped by writing "0" to the HA Helper input_number.target_flow_temp.
In my setup, the ESP WT32-ETH01 listens to HA's input_number.target_flow_temp and starts/stops heating accordingly, alongside setting the correct flow temp. This is done via Modbus connection to a dual firewood and wood pellets boiler (Froeling SP Dual), but the firmware should work with some adjustments with a range of heating devices with serial interface and potentially others.
The firmware for the ESP can be found in this repo and can easily be adjusted to quite any ESP; however, for reliability reasons it is recommended to use one with ethernet.
To connect to the aforementioned Froeling SP Dual, a TTL to RS232 converter is needed; in my setup the Waveshare Rail-Mount TTL To RS232 Galvanic Isolated Converter does the job.
The web interface for the ESP has the additional ability to work independently from HA in a so called Master mode, to which it switches if the connection to HA breaks down (due to software or hardware failure). It then calculates the heating flow temperature according to the settings in the web interface and starts and stops the heating according to the schedule in the web interface ('#' ignores anything afterwards; '8-10' determines the heating perdiod, and '@', if present, stands for the increased (or decreased) flow temp - for example, this can be interesting in the morning when the delta between room temp and target temp is bigger)
The ESP gets its time from a time server; in case of offline mode it can also be entered manually (will be overriden when the NTP server becomes available) for scheduled heating to work.
As will be discussed below, special strengths of this heating automation are the ability to adjust the flow temperature according to the amount of rooms currently heating, and the already mentioned delta temperature between current and target temperature)
Additionally, optional sun compensation is available, which can be set up with a brightness sensor (code has to be adjusted for that) or, in my case, by utilizing the current temperature of a close-by greenhouse.
The main reason for this whole undertaking is Froeling Lambdatronic's ability to write the target flow temp into the RAM of the boiler, avoiding having to change EEPROM registers, the lifetime of which is limited. The catch is that this register (48001-48018 for Froeling's 18 heating circuits) needs to be updated once every other minute. A restart of Home Assistant might thus result in a disruption of heating. The ESP resolves this and offers additional benefits, some of which have already been discussed.
Other than that, the ESP makes the boiler smart also in the sense that it can be directly integrated into Home Assistant via ESPHome (already integrated into HA, so all entities the ESP is set up for are instantaneously writable and/or readable in HA). However, if that is the only thing one wants, then GyroGearl00se's HA integration might be the preferrable option.
The automation is split into two specialized layers to separate room logic from boiler hardware control:
HeatingAutomation(The Brain): An instance runs for every room. It handles schedules, hysteresis, solar gain compensation, and calculates the "claim" for heat.HeatingPumpControl(The Muscle): A single central instance that monitors
all room claims, calculates the optimal flow temperature, and interfaces with the boiler via Modbus.
Each room functions as an independent agent. It monitors its own temperature and decides whether to "request" heat from the boiler.
To prevent the boiler from cycling on and off too rapidly (which reduces hardware lifespan), the system uses a dual-threshold logic:
-
Upper Bound:
$Target - Margin$ (Default margin:$0.5^\circ C$ ) -
Lower Bound:
$Target - \Delta$ (User-defined hysteresis)
| State | Condition | Result |
|---|---|---|
| Heating Start | Current Temp < Lower Bound |
Claim → ON |
| Maintaining | Lower Bound < Current Temp < Upper Bound |
State Persistent |
| Heating Stop | Current Temp >= Upper Bound |
Claim → OFF |
If a room has high solar gain (e.g., south-facing windows), the automation proactively reduces the target temperature when it's warm outside.
- Activation: Triggers when outdoor temperature exceeds a defined threshold.
- Dynamic Offset: As outdoor heat increases, a percentage of the compensation factor is subtracted from the target.
If a room temperature is significantly below the target (e.g., after a window was left open), the room calculates a Boost Factor. This tells the boiler to provide much hotter water temporarily to recover the room temperature as fast as possible.
The central controller monitors all heating_claim_... entities. If at least one room is claiming heat for longer than the heating_claim_duration, the boiler fires up.
The system doesn't use a fixed water temperature. It calculates the Flow Target using a linear heating curve:
-
Baseline: The required flow temperature when it is
$0^\circ C$ outside. - Adjustment: The "slope" of the curve.
- Multi-room Offset: For every additional room asking for heat, the flow temperature is nudged higher to account for increased thermal load.
The system dynamically generates status messages for your Home Assistant UI:
- “Heating starts at 06:00”
- “Heating stops at 22:30 tomorrow.”
- “Heating stops at next power cut ;)” (For continuous 24/7 schedules).
- Modbus Health Check: If the connection to the boiler's ESP32 Gateway fails, the system sends an emergency Telegram notification.
- Auto-Revert: If Party Mode is active but all radiator valves have closed (meaning the house is warm), the system automatically reverts to Auto to save fuel.
For the code to function, your Home Assistant instance must have the following entities configured per room:
| Entity Type | Naming Convention |
|---|---|
input_boolean |
heating_claim_{location} |
input_number |
target_temp_{location} |
input_select |
heating_schedule_{location} |
schedule |
standard_{location}, holiday_{location}, etc. |
heating_livingroom:
module: heating_automation
class: HeatingAutomation
solar_activation_temp: 15
solar_peak_temp: 25
heating_pump_control:
module: heating_pump_control
class: HeatingPumpControl
dependencies:
- global_config
- heating_livingroom
- heating_bedroom
telegram_id: "-100123456789"This guide covers the configuration and operation of the Smart Heating System, from global boiler settings to individual room controls.
These settings control the overall behavior of the central heating pump and flow temperature calculations.
- Main Switch: Global toggle to enable or disable the entire heating automation.
-
Heating Margin: Defines the stop trigger. Heating stops when
Current Temp >= Target Temp - Heating Margin. - Cooldown: Minimum time between switching the heating pump on or off (protects mechanical components from wear).
- Claim Duration: Delay before a dashboard change takes effect (filters out temporary temperature "jitter").
-
Boost Threshold: Activation trigger for high-output heating. Boost starts if
Current Temp < Target Temp - Boost Threshold. -
Boost Factor: Determines the flow temperature increase:
$$Flow\ Increase = (Target\ Temp - Current\ Temp) \times Boost\ Factor$$
-
Baseline at
$0^\circ C$ : The base flow temperature when the outside temperature is exactly$0^\circ C$ . - Curve Adjustment: The factor by which flow temperature is increased or decreased relative to changes in outside temperature.
- Max Flow Temp: The safety ceiling for water temperature (prevents damage to floor plaster/screed).
Each room is managed via a dedicated dashboard view containing the following data points:
- Live Metrics: Current temperature, heating valve opening percentage, and humidity.
- Target temp: Current heating target temperature and the name of the currently active schedule.
- Event Info: Swipe horizontally to view detailed information regarding the current or next heating event.
- Boost Status: Displays if boost is active and how many degrees the flow temperature is being increased by this specific room.
-
Heating Delta (
$\Delta$ ): The "Start" trigger. Heating turns on when the temperature drops belowTarget Temp - Delta.- Control: Tap the card/icon to adjust; long-tap for larger increments.
- Base Temp: The "Background" temperature used outside of scheduled heating events. This allows for passive heating to prevent the room from getting too cold.
- Heat Temp: The default target temperature used during active schedule events if no specific temperature is defined within the schedule itself.
---
The schedules are the heart of the automation. The system follows the logic of the currently selected schedule to determine if heating is allowed.
- Standard: Your everyday routine.
- Holiday: Energy-saving mode for when you are away.
- Party: Overrides timers for extended comfort.
- Temporary: Short-term adjustments.
-
Off: Frost protection only (Target set to
$5^\circ C$ ).
- Cycle Schedules: Tap the main schedule card to cycle forward; tap the icon to cycle backward.
- Activation: Swipe to a schedule and long-tap to make it active.
- Quick Toggle: * Long-tap the main card to switch to Off.
- If already Off, long-tap to return to Standard.
- Shortcuts: Long-tap on temperature, valve state, or humidity to jump directly to Holiday, Party, or Temporary modes.
- Visual Indicators: A green icon signifies the schedule is currently active; a gray icon signifies it is inactive.
The dashboard uses color-coding to signal the current state of the heating demand and the central pump (HK2) status.
| Color | Logic / Condition | System State |
|---|---|---|
| Red | Heating Claim Active | Boiler in Party or Extra-Heating mode |
| Purple | Heating Claim Active | Boiler is currently OFF |
| Orange | No Claim + Temp < Target - 0.5 | Boiler in Party or Extra-Heating mode |
| Green | No Claim + Temp < Target - 0.5 | Boiler in Automatic mode |
| Blue | No Claim + Temp < Target - 0.5 | Boiler is currently OFF |
| Yellow | Current Temp > Target - 0.5 | Room is warm (Target > 5) |
| Gray | "No" in next_event text |
No future heating planned (Schedule Off) |
| Light Blue | Else | Standby / Neutral |