This repository contains a heating control system built for Home Assistant with the app (add-on) AppDaemon.
Why AppDaemon? Well, AppDaemon has been chosen for its ability for using Python virtually without restrictions (other than PyScript), including its ability to create (multiple) instances. This makes it possible to create an instance of RoomDemandCalculator for each room to be heated, allowing for efficient and straightforward code.
The heating automation is split into three specialized layers:
(1) Room Level: RoomDemandCalculator
(2 Central Heating Control: HeatSupplyManager
(3) Hardware Interface: connects to the actual hardware, for example, a Froeling SP Dual
-
RoomDemandCalculator(The Brain): An instance of this app runs for every room. It handles schedules, hysteresis, solar gain compensation, boost demands, and calculates the heat claim for the room. -
HeatSupplyManager(The Muscle): HeatSupplyManager acts as control center for juggling the heating demands for all rooms combined. Heating is initiated by writing the target flow temperature to the HA Helperinput_number.target_flow_temp. which then is to be connected to whatever means of heating your house has; this can be another AppDeamaon class controlling the actual hardware or, as in my case, an ESP32 that pokes a Froeling SP Dual (see further down). -
The hardware interface "listens" to
input_number.target_flow_tempand initiates heating in accordance with the value ininput_number.target_flow_temp. Wheninput_number.target_flow_tempis set to0, the hardware interface stops heating.
Each room functions as an independent agent. It monitors its own temperature and decides whether to "request" heat from the boiler.
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 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: RoomDemandCalculator
solar_activation_temp: 15
solar_peak_temp: 25
heating_pump_control:
module: heating_pump_control
class: HeatSupplyManager
dependencies:
- global_config
- heating_livingroom
- heating_bedroom
telegram_id: "-100123456788"
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 |
The central controller monitors all heating_claim_... entities. If at least one room is claiming heat, heating starts.
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 principle is simple: HA's helper input_number.target_flow_temp signals heating demand when it contains the required flow temperature (not 0); it signals no heating demand if it is set to 0. This respository contains two examples how this can be used.
(a) Using GyroGearl00se's HA integration for Froeling ha_froeling_lambdatronic_modbus.
An example can be seen here.
(b) Using an ESP32
The ESP is programmed to listen to changes to HA's input_number.hk2.target_flow_temp and starts (value changes from 0 to the required flow temp) and stops (value changes to 0) heating accordingly. The ESP is connected to HA via ethernet (also Wifi or other wireless communication will work) and to the Froeling boiler via Modbus.
The firmware for the ESP WT32-ETH01 can be found in this repository and can easily be adapted to quite every ESP; however, for reliability reasons, it is recommended to use one with ethernet connection.
To connect to the aforementioned Froeling SP Dual, a TTL to RS232 converter is needed; I have chosen the Waveshare Rail-Mount TTL To RS232 Galvanic Isolated Converter.
Additionally, the ESP's firmware can be extended with 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, e.g., during a reboot. It then calculates the heating flow temperature according to the settings in its own web interface (in case heating was on when the connection got disrupted heating continues for 20 minutes with the last set flow temperature) and starts and stops the heating according to its schedule ('#' ignores anything afterwards; '8-10' determines the heating period, and '@', if present, stands for the increased (or decreased in case of a negative value) flow temperature; this can be used when the delta between room temp and target temp is bigger, for example, in the morning)
As can be seen in the screenshot, the first seven slots are for the heating schedule in Master mode (ESP Status), i.e., in case the ESP is disconnected from Home Assistant. AppDaemon Status, ESP HA API Status, and ESP Modbus Status show whether AppDaemon, Home Assistant, and the boiler are connected.
HK2 Enabled signalls that heating circuit 2 is potentially activated; however, a value of not 0 in HK2 Flow Target Temp (ESP) activates heating, which is then reflected in Heating On.
HK2 Flow Temp +10 (Master) and HK2 Flow Temp -10 (Master) are used in Master mode to determine the flow temp, which is based on the boiler's outside temperature sensor, unless Outside Temp, which is based on a dallas temperature sensor connected to GPIO 54, is in place, then the latters's value is used. Room Temp is for an additional dallas temperature sensor, also connected to GPIO 54 (and distinguished by its address -> both need to be changed to the ones of the dallas sensors used).
Time (Manual Override), as already mentioned, allows for the manual adjustment of date and time in case of missing internet connection.
One of the reasons for using an ESP is Froeling having made it possible to write the target flow temperature into the RAM of the boiler, avoiding having to write to EEPROM registers, the lifetime of which is limited. However, this register (48001-48018 for Froeling's 18 heating circuits) needs to be updated within two minutes, otherwise heating stops, and the ESP automatically takes care of that - as long as the value in input_number.target_flow_temp is not 0, the ESP keeps poking the boiler.
Other than that, the ESP makes the boiler smart in the sense that its entities 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.
In this repo there is also a firmware file for the Waveshare ESP32-P4-NANO; compiling requires ESPHome 2026.2.0 or newer.
Below you can see a comparison between the two boards:
The firmware in the two examples forwards a range of entities from Froeling to HA; they can easily be changed or extended by consulting Froeling's Modbus documentation
This is the AppDaemon code that connects the heating automation to the ESP, i.e., listens to changes to input_number.target_flow_temp and writes input_number.hk2_target_flow_temp that in turn triggers the ESP to start and stop heating.