Warning
Experimental, AI-written, unverified code. Use at your own risk.
The additions in this fork (versions with a fourth number, such as 5.2.0.5) were written by
Claude, an AI model by Anthropic, in a conversation with the fork's owner.
They pass the automated test suite (unit tests, ruff, ty, hassfest), but they have not been
reviewed by a person or run on a real boiler for any length of time. They control a gas
boiler: a mistake can mean a cold house, wasted gas, an overheated floor or a boiler lockout.
Read the code before you use it, keep a backup, watch your boiler closely after installing, and
keep the original SAT v2 at hand to go back to. Nothing
here is endorsed by the authors of SAT.
Kod eksperymentalny, napisany przez AI i niesprawdzony. Używasz na własne ryzyko. Polski opis: README.pl.md.
SAT is a smart thermostat for Home Assistant that controls your boiler.
A regular thermostat turns the boiler on and off, and the boiler heats its water to a fixed, often high, temperature. SAT works out the lowest water temperature that keeps your home at the target, from the outside temperature and how far each room is from its target, and sends that to the boiler. Cooler water means less gas and fewer on/off cycles.
This fork builds on SAT v2 by Thiago Bellini Ribeiro, itself a fork of the original Smart Autotune Thermostat by Alex Wijnholds. It was written for an oversized condensing combi boiler (De Dietrich Lumea, 33 kW, minimum about 5 kW) on screed underfloor heating behind an OpenTherm Gateway, and adds what such a setup needs to stop short cycling and save gas. Everything new is off, or only informs, until you turn it on.
All of it is described in MPX additions.
Control (off by default)
- 🔋 Heat budget: learns the heat loss of the house and burns the heat each hour needs in one long block at minimum power, instead of several short PWM cycles. Hands back to normal modulation when the house needs more than the minimum power.
- 🌤️ Weather forecast and sun: the forecast trend and the sun's height and cloud cover enter the heat budget.
- ⏰ Comfort schedule with learned early recovery (optimum start) and an early stop.
- ☀️ Warm weather shutdown on the daily mean outside temperature.
- 🚿 Hot water schedule with an eco temperature and a weekly legionella boost.
- 🏃 Presence: Away preset when nobody is home, back early within a return distance.
- 🪟 Open window detection from fast temperature drops, without contact sensors.
- ⚙️ Boiler-specific settings: anti-cycling time, valve opening time, cut-short burns per PWM phase, keep heating enabled between PWM phases, learned overshoot protection value.
Monitoring (on, only informs)
- 📈 Running totals for the Energy dashboard: burner starts and hours, heat for heating and hot water, gas, heating degree days, gas cost.
- 🍃 Estimated boiler efficiency from the flue gas or return temperature.
- 💧 Estimated water flow, open loops and a per-room rotameter hint;
sat.measure_loopsmeasures each loop's flow. - 🚨 Repair issues: low or falling water pressure, boiler fault, dirty heat exchanger, screed overheat, too little water flow, service due, gas use up.
- 📐 A suggested heating curve coefficient from what was learned.
- Home Assistant 2026.11 or newer.
- A boiler that Home Assistant can talk to through one of:
- OpenTherm Gateway (OTGW), over MQTT or serial
- ESPHome OpenTherm
- EMS-ESP, over MQTT
- OpenTherm adapters such as the DIYLess Master OpenTherm Shield, Ihor Melnyk's adapter or Jiří Praus' Arduino shield
- Or any
switch,valveorinput_booleanthat turns your heating on and off. SAT then works as a smart on/off thermostat (most additions need a boiler that takes a setpoint). - A room temperature sensor and an outside temperature sensor or weather entity.
The additions were developed against an OTGW in serial mode. The other connections share the same code paths but have had even less testing.
Make a backup of Home Assistant first, and note your current SAT settings.
- If SAT or SAT v2 is already installed through HACS, open it in HACS and choose ⋮ → Remove. This removes the files, not your SAT entry and its settings. Do not restart yet.
- In HACS choose ⋮ → Custom repositories, add
https://github.com/alnamics/satwith the type Integration. - Open Smart Autotune Thermostat v2 (MPX) in HACS and choose Download. While the fork has no releases, HACS installs the latest state of the
mainbranch and shows its commit as the version. - Restart Home Assistant.
The integration domain is still sat, so an existing entry keeps its settings and the MPX edition takes the place of the SAT you had. HACS can hold only one of them at a time.
Download the repository (Code → Download ZIP on GitHub), copy its custom_components/sat folder into your custom_components folder, replacing an existing SAT, and restart Home Assistant.
A new install is then added under Settings → Devices & services → Add integration → Smart Autotune Thermostat; the setup guide walks through each step.
- Run a day or two with all new options off. SAT then controls the boiler as upstream SAT v2 does; only the new sensors and repair issues are added. Check the logs for
satand your boiler's graphs. - Turn on the boiler settings you know (anti-cycling time, valve opening time).
- Set the heat budget to Learn only (shadow) for two or three days. Once
heat_budget_readyis true andheat_loss_w_per_khas settled, switch it to On. - Add the other features one at a time, so you can tell what each one does.
In HACS remove the MPX edition and download SAT v2 again (or copy the original over custom_components/sat by hand), then restart. This fork adds no config entry migration of its own, so SAT v2 5.2.0 or newer loads the entry again; an older SAT cannot, because Home Assistant does not load an entry saved by a newer version. The extra options are ignored and the extra entities become orphaned (remove them under Settings → Entities).
- MPX additions: every addition of this fork, what it does, its defaults and limits
- Example: how SAT runs an 87 m² flat with screed heating and an oversized boiler
- Setup: what each setup step asks for
- Options: every setting, tab by tab
- How SAT works: heating curve, room feedback, low-load control, heat budget and calibration
- Differences from the original SAT
SAT is the work of Alex Wijnholds and Thiago Bellini Ribeiro and contributors. The MPX additions were written by Claude for alnamics; report problems with them here, not upstream.