Peter M. Groen / EasyOpenTherm

Commit 0e34c6ab9330975484e176985671232767152215

Authored by Jeroen88
1 parent a73d7a6d

Reviewed and updated the both README.md's

Inline Side-by-side
Showing 2 changed files with 35 additions and 17 deletions
README.md
  View file @0e34c6a
1 1 # OpenTherm Arduino ESP32/ESP8266 Library
2 2 Was already working on an ESP32, now ready for an ESP8266 too!
3 3  
4   -Create your own thermostat with this library and save money on your energy bills while reducing your carbon footprint!
  4 +Create your own thermostat with this library and save money on your energy bills while reducing your carbon footprint! Or use a home automation system like Home Assistant and smart thermostatic valves to heat up each room individually.
5 5  
6 6 The library complies with the OpenTherm specification. Control any (condensing) boiler or air conditioner (HVAC) that also meets the OpenTherm specification.
7 7  
... ...
examples/README.md
  View file @0e34c6a
1 1 # Examples for OpenTherm Arduino ESP32 Library
2 2  
3   -Several examples are given, all fully functional, from very basic to advanced. The first thing you should always do is to run Test_Boiler_Communication.ino or Test_HVAC_Communication.ino, to make sure your [OpenTherm controller](https://www.tindie.com/products/jeroen88/opentherm-controller/) or [OpenTherm controller Shield](https://www.tindie.com/products/jeroen88/opentherm-shield/) is correctly wired, the right GPIO pins are configured and the secondary boiler or HVAC is responding to the requests of the primary thermostat.
  3 +Several examples are given, all fully functional, from very basic to advanced. The **first thing you should always do** is to run Test_Boiler_Communication.ino or Test_HVAC_Communication.ino, to make sure your [OpenTherm controller board](https://www.tindie.com/products/jeroen88/opentherm-controller/) or [OpenTherm controller Shield](https://www.tindie.com/products/jeroen88/opentherm-shield/) is correctly wired, the right GPIO pins are configured and the 'secondary', i.e. the boiler or HVAC, is responding to the requests of the 'primary', i.e. the thermostat.
4 4  
5 5 ## Test_Boiler_Communication.ino and Test_HVAC_Communication.ino
6 6 Basic test of your setup. If everything is OK, you will see:
7 7 ```
8 8 Your setup is working! A frame was send to the boiler and the boiler responded with a valid frame.
9 9 ```
10   -together with some more information.\
11   -The Test_HVAC_Communication.ino program is **not tested** because I do not own such a device.
  10 +together with some more information.
  11 +If you do not see this line:
  12 +- Is the EasyOpenTherm board correctly wired? Is the pin you defined with ```#define OT_RX_PIN``` connected to **TxD** of the board? Is the pin you defined ```#define OT_TX_PIN``` connected to **RxD** of the board? Is GND of the EasyOpenTherm your connected to a GND pin of your ESP32 or ESP8266 board? Is 3v3 of the EasyOpenTherm board connected to 3v3 of your ESP32 or ESP8266 board? For an EasyOpenTherm shield you can skip this step.
  13 +- For the EasyOpenTherm board, are the pins marked OT connected to the thermostat wires of your boiler? For the EasyOpenTherm shield, are the thermostat wires of your boiler connected to the green screw terminal?
  14 +- Did you _remove_ the "normal" thermostat? (The OpenTherm protocol supports _only one_ thermostat on the bus)
  15 +- Does the pin you selected with ```#define OT_RX_PIN``` support interrupts?
  16 +- Does the pin you selected with ```#define OT_TX_PIN``` support ```OUTPUT``` (not input only)
  17 +- Does your boiler support the OpenTherm protocol?
  18 +
  19 +The Test_HVAC_Communication.ino program is **not tested** because I do not own such a device. You should see:
  20 +```
  21 +Your setup is working! A frame was send to the HVAC and the HVAC responded with a valid frame.
  22 +```
  23 +If you do not see this line do the same checks as above for the boiler.
12 24  
13 25 ## MQTT_Advanced_Thermostat.ino
14 26 ![Home Assistant logo](https://raw.githubusercontent.com/home-assistant/assets/master/logo/logo-small.png)
15   -![MQTT logo](https://brands.home-assistant.io/_/mqtt/logo.png)\
  27 +![Home Assistant Thermostat Card](https://www.home-assistant.io/images/dashboards/thermostat_card.gif)
  28 +![MQTT logo](https://brands.home-assistant.io/_/mqtt/logo.png)
  29 +
  30 +**If you already know how to flash an microcontroller from the Arduino IDE and already have Home Assistant installed with the MQTT integration, the thermostat should be up and running in minutes!**
16 31  
17 32 The Advanced_Thermostat.ino example is specially designed for Home Assistant with a MQTT integration. This example can also be used with other home automation software that supports MQTT. although auto discovery of the thermostat and the sensors will not work in this case.
18 33 ### Prerequisites
19   -- An OpenTherm controller connected to the thermostat wires
  34 +- An OpenTherm controller board or shield correctly connected to the thermostat wires
20 35 - Home Assistant installed
21 36 - A MQTT broker, preferably [Mosquitto](https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md)
22 37 - The [MQTT integration](https://www.home-assistant.io/integrations/mqtt/) added to Home Assistant
23   -- An ESP32, e.g. an ESP32-S2 mini, flashed with Advanced_Thermostat.ino. Before flashing, first set your WiFi network name and password, and your MQTT broker hostname or IP address, MQTT user name and MQTT password
24   -- A thermometer in Home Assistant and an automation to forward the room temperature to the Thermostat using a Home Assistant Automation (Settings -> Automations & Scenes -> + Create Automation. Start with an empty automation, click the three dots in the upper right corner and select: Edit in YAML). Add:
  38 +- The [Arduino IDE installed](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-downloading-and-installing) on your computer
  39 +- An ESP32, e.g. an ESP32-S2 mini, flashed with Advanced_Thermostat.ino (can be opened from the examples: File -> Examples, scroll all the way down to 'EasyOpenTherm' and select 'Advanced_Thermostat'). Before flashing, first set your WiFi network name and password in the progam, and your MQTT broker hostname or IP address, MQTT user name and MQTT password
  40 +- A thermometer in Home Assistant, and an automation to forward the room temperature to the Thermostat using a Home Assistant Automation (Settings -> Automations & Scenes -> + Create Automation. Start with an empty automation, click the three dots in the upper right corner and select: Edit in YAML). Add:
25 41 ```
26 42 alias: Publish room temperature
27 43 description: Publish room temperature to MQTT Climate state
... ... @@ -40,12 +56,13 @@ Replace the entity_id with the id of your thermometer and replace '22b5ea03f784'
40 56 The thermostat (Climate) integration is automatically added to Home Assistant, together with several sensors.
41 57 ### Thermostat behaviour
42 58 - The thermostat is enabled in Home Assistant if it communicates with an OpenTherm boiler
43   -- The thermostat shows the room temperature if it receives temperature updates over MQTT
  59 +- The thermostat shows the room temperature if it receives temperature updates over MQTT (and is enabled, see previous step)
44 60 - The desired room temperature, the room temperature setpoint, can be set by turning the dial
45 61 - As long as the thermostat is switched off it will never start heating
46 62 - Press the flame below the dial to turn the thermostat on
47 63 - If the room temperature is below setpoint (minus a 0.1 ºC deadzone) the boiler will start heating
48 64 - If the boiler switches off after running for a while, it will stay off for at least 10 minutes (Anti Hunting interval)
  65 +- If the thermostat does not receive temperature updates for more than 15 minutes, it will switch to 'idle', to prevent your house from being heated if the thermometer fails
49 66  
50 67 ### Sensors
51 68 The following sensors are always added:
... ... @@ -75,25 +92,26 @@ Message 42 received on Metriot/EasyOpenTherm/cc031c4e76a0/climate/state at 6:22
75 92 You could blow into the thermometer to force a temperature update from the thermometer, that should inmediately appear in the MQTT messages.
76 93  
77 94 ### Saving energy and money
78   -The intention of the thermostat is to save energy and to save money. I can not guarantee though that this will also be the case in your setup. The thermostat can be tweaked to serve your needs by setting the options, most of these ```#defines``` are found in the main program and in ThermoStateMachine.cpp. Wrting your own thermostat software from scratch is also an option ofcourse.\
79   -Home Assistant can be used for geo fencing and smart schemes to switch the boiler on and off.
  95 +The intention of the thermostat is to save energy and to save money. I can not guarantee though that this will also be the case in your setup. The thermostat can be tweaked to serve your needs by setting the options, most of these ```#defines``` are found in the main program and in ThermoStateMachine.cpp. Wrting your own thermostat software from scratch is also an option ofcourse.
  96 +
  97 +Home Assistant can be used for geo fencing, smart schemes to switch the boiler on and off, or e.g. to control the temperature in each of your rooms individually!
80 98  
81 99 ### Using Advanced_Thermostat.ino in other MQTT enabled home automation systems
82   -The Advanced_Thermostat.ino can also be used in other MQTT enabled home automation systems. In this case the auto discovery of the Thermostat and the sensors will not work. But the thermostat can be controlled by publishing and subscribing to the right topics. In all below topics the hex number 22b5ea03f784 needs to be changed into the right number for your ESP32 (all small caps)
  100 +The Advanced_Thermostat.ino can also be used in other MQTT enabled home automation systems. In this case the auto discovery of the Thermostat and the sensors will not work. But the thermostat can be controlled by publishing and subscribing to the right topics. In all below topics the hex number 22b5ea03f784 needs to be changed into the right number for your ESP32 or ESP8266 (all small caps)
83 101  
84 102 Topics to publish to:
85 103 - Metriot/EasyOpenTherm/22b5ea03f784/climate/state: publish the room temperature in JSON format ```{"temperature": 19.8}```
86   -- Metriot/EasyOpenTherm/22b5ea03f784/mode/set: publish ```off``` to switch the thermostat off, ```heat``` to switch it on
  104 +- Metriot/EasyOpenTherm/22b5ea03f784/mode/set: publish ```off``` to switch the thermostat off, ```heat``` to switch it on (on means: the thermostat is running and decides upon various parameters to switch your boiler on. It does not mean: start the boiler inmediately)
87 105 - Metriot/EasyOpenTherm/22b5ea03f784/setpoint/set: publish the desired room temperature (room temperature setpoint) in plain text format, e.g. ```20.8```
88 106  
89 107 Topics to subscribe to:
90 108 - Metriot/EasyOpenTherm/22b5ea03f784/flame/state: to receive 'flame' updates of the format ```{"flame":"OFF"}```
91 109 - Metriot/EasyOpenTherm/22b5ea03f784/RSSI/state: to receive 'RSSI' updates of the format ```{"RSSI":-57}```
92 110 - Metriot/EasyOpenTherm/22b5ea03f784/ch_setpoint/state: to receive 'central heating setpoint' updates of the format ```{"ch_setpoint":10.0}```
93   -- Metriot/EasyOpenTherm/22b5ea03f784/flow_temperature/state: to receive 'flow temperature' updates of the format ```{"flow_temperature":25.7}```
94   -- Metriot/EasyOpenTherm/22b5ea03f784/return_temperature/state: to receive 'return temperature' updates of the format ```{"return_temperature":25.5}```
95   -- Metriot/EasyOpenTherm/22b5ea03f784/relative_modulation/state: to receive 'relative modulation' updates of the format ```{"relative_modulation":0.0}```
96   -- Metriot/EasyOpenTherm/22b5ea03f784/water_pressure/state: to receive 'water pressure' updates of the format ```{"water_pressure":2.2}```
  111 +- Metriot/EasyOpenTherm/22b5ea03f784/flow_temperature/state: to receive 'flow temperature' updates of the format ```{"flow_temperature":25.7}``` (if supported by your boiler)
  112 +- Metriot/EasyOpenTherm/22b5ea03f784/return_temperature/state: to receive 'return temperature' updates of the format ```{"return_temperature":25.5}``` (if supported by your boiler)
  113 +- Metriot/EasyOpenTherm/22b5ea03f784/relative_modulation/state: to receive 'relative modulation' updates of the format ```{"relative_modulation":0.0}``` (if supported by your boiler)
  114 +- Metriot/EasyOpenTherm/22b5ea03f784/water_pressure/state: to receive 'water pressure' updates of the format ```{"water_pressure":2.2}``` (if supported by your boiler)
97 115  
98 116 ### Modifing Advanced_Thermostat.ino for HVACs
99 117 It should be possible to modify the program to work with HVACs. It should be relatively straight forward (maybe a flag can_heat must be added, the right status should be used, the flags need adaptations and the DATA-IDs need to be changed, to name a few). I do not have a HVAC, but maybe I can help and publish a HVAC example too.
... ...