foltymat
commented
1 year ago Right, as long as nobody responds, I'll keep this as an archive of what I found during testing, how all of this works, and share this with everyone who might be struggling like I did (and do :) )
All of these notes are based on v0.4 released on January 6th 2022. It seems that @rsciriano IS still working on this as there are a lot of builds being made in the meantime; so there may be some light at the end of the tunnel and some more functionality coming.
As I am the n00b in all of this let me start from the beginning.
The BASICS
This sketch allows you to have a bridge between ESPhome (including Home Assistant) and your OpenTherm enabled boiler. In my case, that is a Viessmann Vitodens 100-w b1hc-35, but many others support it.
If you're just starting out, start by looking at the compatibility matrix here. What you will be looking at is a page made by the creator of the original OpenTherm Gateway. If I understood correctly, this is the backbone of any OpenTherm implementation we see today - even in this ESPhome version.
Provided you are using Home Assistant like I am, there is a great alternative approach on the DIYLESS website, if you ultimately fail to establish this code. The difference is, the underlying code and the method of communication. Using this method, you will be using Arduino code and MQTT to communicate with either Home Assistant, or a system of your choice (I haven't tried this code at all, though. At least not yet.)
The ESPversion like this one, however, is using the native ESPhome API to communicate with Home Assistant and I am much more comfortable with YAML, so that's why I decided to try this first.
What I bought
My biggest worry was the definition between the three options presented to me. That would be: 1) OpenTherm Gateway, 2) OpenTherm Master Shield, 3) OpenTherm Slave Shield.
Honestly, I'm still not sure I got this 100% correct so take it with a grain of salt. (All links are to the DIYLESS website where I got my Master shield)
You use master shield in order to have a full control over your boiler. You get access to all of these fun parameters of your heater and you can fiddle with almost anything - that's why I went this way. Remember, your boiler has a mind of its own, so there is almost zero chance you would break something.
The Slave shield would be used to connect to your existing OpenTherm thermostat. Honestly, I still haven't figured ouut how would you use this on its own.
The OpenTherm Gateway combines the Master and the Slave into a single device. Meaning you would connect to your boiler AND to your existing Thermostat.
After reading all of this, my original thought was "I need to get that Gateway." But since my use case will be using smart Zigbee TRVs on my Radiators, the Thermostat portion will be done completely inside Home Assistant.
The INSTALLATION
I cannot say much about the installation part as that is extermely simple! As the Readme states, you just copy the repository into your esphome folder and you're off to the races. Just make sure you open the opentherm.yaml file and change the devicename (line 2) to your liking.
Now, my personal issue was that instead of using a Wemos D1 mini (like recommended), I used a generic NodeMCU board. It works, but make sure you change the board type on line 8 to nodemcuv2
Here's the original:
substitutions:
devicename: opentherm
upper_devicename: Opentherm
esphome:
name: $devicename
platform: ESP8266
board: d1_mini
platformio_options:
lib_deps:
- ihormelnyk/OpenTherm Library @ 1.1.3
includes:
- esphome-opentherm/Here's mine: (Yes, for some reason, it wouldn't compile with the board indented inside esphome so I moved it)
substitutions:
devicename: 0p-kotelna-opentherm
upper_devicename: Opentherm
esphome:
name: $devicename
platformio_options:
lib_deps:
- ihormelnyk/OpenTherm Library @ 1.1.3
includes:
- esphome-opentherm/
esp8266:
board: nodemcuv2I'm not going to explain how to work with ESPhome or upload a sketch - there are a lot of great tutorials for that! :)
The Actual temperature
If you plan on using the same logic like I did, you will need to be able to tell the sketch your actual temperature of the room. The answer lies on line 82 of the opentherm.yaml file. There, you can place your entity if from Home Assistant and that will tell the sketch the feedback.
My biggest mistake was using a Zigbee temperature sensor from Sonoff - not because it's bad, but because the update interval is inconsistent and often just wrong. You will understand why the update frequency is important later on. I ended up using a different ESP board with a temperature sensor attached to that.
So, we have a thing running, how does it all work?
First of all, you will be greeted with three climate controls (thermostats) and a bunch of sensors (in here, if you see values of -1, don't panic and first consult the compatibility matrix we've talked about at the beginning. There is a chance your device doesn't support some of them - for me, it was Returning temperature and Water Pressure).
So let's dig in and explore what all of this means.
Sensors
- Boiler Modulation - How hot is the flame burning in percentage
- Boiler Temperature - Actual temperature inside the heating chamber of your boiler
- External temperature - Self explanatory, if you have it, you can see the temperature outside!
- Flame - A binary sensor telling you if the flame is on or off
- Heating Target temperature - VERY important sensor. This is a calculated value based on the back-end code. It tells us what the Boiler Temperature SHOULD be.
- PID Climate ERROR - Value based on the difference between a Desired temperature and Actual temperature (If Actual is hotter, the value will be negative, if it will be colder, positive.
- PID Climate HEAT - An interesting value telling how hot should the water be. If 100%, the boiler will try to reach the High Limit you set in Heating Water climate/thermostat (will be explained).
- PID Climate Result - My theory is that THIS value should be used insted of the HEAT one. It may as well be as they are usually the same. Not really sure about this one.
Climate/Thermostats
-
Heating Water - This is where you will set up how hot should the water be in your radiators. Can (and should) be a range. The idea in the ling run is that, if there is a big difference between the Actual temperate of the room and what you want (the set point), the boiler will attack the high limit of this setting and dump a lot of heat in. Once you get close, the PID HEAT should lower from 100% and the Heating water should be targeting a lower target of your set range. (Side note, if this is left on, the pump in your system will keep going, indefinitely circulating the water in your radiators. Even @rsciriano said that this was a bad move and will be changed in the future. For now, I use a Home Assistant automation to turn it off after a set time to avoid unnecessary power consumption and wear of the pump).
-
Hot Water - This is your setpoint for the water temperature in your faucet. From my testing, this is a 'set is and forget it.' Once the water temperature drops, the heating will kick in and bring the temperature roughly 4 degreees above the setpoint.
-
PID Climate Controller - The Alpha Omega controlling your system. This should be the only place you will control once everything is set up properly. The problem is, it probably won't work for you from the start (if it does, I'm jelaous!). Once you set your desired temperature here, you will have to wait for an 'actual temperature' change. Only then, does the calculation for the ERROR, HEATING and RESULT parameters kick in (that's why I had so many issues with the zigbee thermometer).
Once the parameters get calculated, the system will decide on a 'Heating target temperature' which is the main parameter that the boiler needs! So, if you need heat, the target will be set to the high point of your 'Heating water.' If you need a bit of heat it should hover between the low and the high of your 'Heating water.' If you have reached your target, the 'Targer temperature' will drop to 10 degrees. Essentially turning off the flame, and just keeps the pump running through the radiators. (But like I said, you will need to turn off the pump yourself - by automation, or manually).
Last but not leat, the PID values
Now you should be a familiar with the general "how all of this works." But we haven't talked about an important step in the back-end! And that is the kp, ki, and kd values. I'm not going to dive into what they mean (because I don't know), but whenever someone tries to explain, it's just a mess. If you are really interested to learn how it works, you can read this page here, here or here.
To help us with this shenanigans, ESPhome has a built in function called autotune. It took me way too long to figure out it's not part of the original code, but rather a built-in functionality.
I urge you to read a proper how-to on the ESPhome website, but here's the jist.
First, make sure your system is doing something! Only then, set a temperature on the PID Controller to something you can reach and then turn on the 'PID Climate Autotune' switch that you will see in there as well.
To see progress of the autotune, you will need to see the logs of the ESPhome device. You will be looking at something like this:
PID Autotune:
Autotune is still running!
Status: Trying to reach 24.25 °C
Stats so far:
Phases: 4
Detected 5 zero-crossings
# ...For example, in the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C.
This will continue for some time until data for 6 phases (or a bit more, depending on the data quality) have been acquired.
For me, in a big house and old heavy radiators, this took almost 24 hours! So just be patient. In the end, it will spit out values based on the algorith you should copy to your yaml file at the very end, recompile and upload.
Summary
And that's it. This has been a chore to write down but I hope someone in the future will find this and appreciate at least the bit of work I did to find this out! 👍
rsciriano
spasayrim
craigsbits
straaat
aistodorescu
Chupaka
Hi, let me start by saying THANKS for your work! I was looking for an ESPhome based system to use with OpenTherm and this seems to be the one.
Honestly, I'm not sure how often you read these, so my hopes are not that high :)
I need to address this issue with the lack of documentation of this whole program. I'd consider myself an advanced beginner when it comes to code, but figuring out how this works was a chore and a half.
My main issue is that I still haven't figures out how to properly control the boiler after everything has been connected. In my case, my Viessmann boiler does not support 'Returning temperarure' nor 'Heating water pressure.' But I imagnine that some parameters are crucial for the thing to work and some are not...
The three climate controls
So how exactly am I supposed to know the difference between 'Heating water' 'How water' and 'PID Climate control' ? Through testing I did figure the most basic things out, but not really with a lot of details.
In the end, my hope would be that after setting the PID Climate Control, stuff would begin to happen. But no, I had to figure out that you can change the entity ID of the actual temperature to a one from Home Assistant - but even then, nothing happened.
Disable PID and Autotune
No idea what disable PID does (from my testing - nothing) And I had to learn about the Autotune from ESPhome documentation - which, fair enough, but there's no reference to it anywhere.
Summary
In the end, I'm just frustrated. I WANT this to work so badly but with no real documentation I don't know how. And with my limited knowledge in coding it's virtually impossible to find this out on my own.