Commit 2ef2e0f74300967c47d0e1ddc5c00a9966d0d62e
1 parent
a775dc71
First commit README.md
Showing
1 changed file
with
50 additions
and
0 deletions
README.md
| 1 | # OpenTherm Arduino ESP32/ESP8266 Library | 1 | # OpenTherm Arduino ESP32/ESP8266 Library |
| 2 | 2 | ||
| 3 | +Create your own thermostat with this library and save money on your energy bills while reducing your carbon footprint! | ||
| 3 | 4 | ||
| 5 | +The library complies with the OpenTherm specification. Control any (condensing) boiler or air conditioner (HVAC) that also meets the OpenTherm specification. | ||
| 6 | + | ||
| 7 | +The library can be easily installed in the Arduino IDE. It has been tested on an ESP32 microcontroller and will also work on an ESP8266. | ||
| 8 | +To connect the boiler, you will need an [OpenTherm controller](https://www.tindie.com/products/jeroen88). | ||
| 9 | + | ||
| 10 | +## Installation | ||
| 11 | +- Download the library from [GitHub](https://github.com/Jeroen88/EasyOpenTherm/archive/refs/heads/main.zip) | ||
| 12 | +- Install the library named EasyOpenTherm-main.zip using the Arduino IDE library manager | ||
| 13 | +- Connect the pins marked 'OT' of the [OpenTherm controller](https://www.tindie.com/products/jeroen88) with two wires to the boiler. You can use the existing wires from your current thermostat. The order of the wires is not important, they are interchangable | ||
| 14 | +- Connect the pins marked '3v3' and 'GND' to the ESP32 pins '3v3; and 'GND' | ||
| 15 | +- Connect the pin marked 'RxD' to a pin supporting OUTPUT of the ESP32 and the pin marked 'TxD'to a pin supporting interrupts. The pins you use should be defined in the program (see below) | ||
| 16 | + | ||
| 17 | +## Usage | ||
| 18 | +```cpp | ||
| 19 | +#include <EasyOpenTherm.h> | ||
| 20 | +``` | ||
| 21 | +Select two free GPIO pins, one to send data to the boiler and one to receive data. The pin receiving data must support interrupts. For the pin that sends data, do not use a 'read only' GPIO. Define these pins in the program | ||
| 22 | +```cpp | ||
| 23 | +#define OT_RX_PIN (34) | ||
| 24 | +#define OT_TX_PIN (17) | ||
| 25 | +``` | ||
| 26 | +In this case GPIO34 is used for receiving and GPIO17 is used for sending data. Note that the Rx pin is connected to the TxD pin of the [OpenTherm controller](https://www.tindie.com/products/jeroen88) and vice versa! | ||
| 27 | +Create an OpenTherm class instance | ||
| 28 | +```cpp | ||
| 29 | +OpenTherm thermostat(OT_RX_PIN, OT_TX_PIN); | ||
| 30 | +``` | ||
| 31 | +Make sure that only one instance of this object is alive at a time. So make it global or ```static``` like in the examples | ||
| 32 | +Start communicating with the boiler (or HVAC) e.g. request activation of the services of the boiler and request it's status flags | ||
| 33 | +```cpp | ||
| 34 | +uint8_t primaryFlags = uint8_t(OpenTherm::STATUS_FLAGS::PRIMARY_DHW_ENABLE) | uint8_t(OpenTherm::STATUS_FLAGS::PRIMARY_CH_ENABLE) | uint8_t(OpenTherm::STATUS_FLAGS::PRIMARY_COOLING_ENABLE) | uint8_t(OpenTherm::STATUS_FLAGS::PRIMARY_OTC_ENABLE); | ||
| 35 | +uint8_t statusFlags; | ||
| 36 | +thermostat.status(primaryFlags, statusFlags); | ||
| 37 | +``` | ||
| 38 | +This command will return _true_ on success and _false_ otherwise | ||
| 39 | +All other interaction with the boiler is done using ```read()```, ```write()``` or ```readWrite()``` functions, e.g. | ||
| 40 | +```cpp | ||
| 41 | +thermostat.write(OpenTherm::WRITE_DATA_ID::CONTROL_SETPOINT_CH, CH_SETPOINT) | ||
| 42 | +``` | ||
| 43 | +All these functions take an OpenTherm DATA-ID as _first_ parameter. The DATA-ID refers to the action requested from the boiler. All known DATA-ID's are defined in _EasyOpenTherm.h_. The DATA-IDs for reading data from the boiler are defined in ```enum class READ_DATA_ID```, DATA-IDs for writing data to the boiler are defined in ```enum class WRITE_DATA_ID``` and DATA-IDs for writing and reading data to and from the boiler are defined in ```enum class READ_WRITE_DATA_ID```. The _second_ parameter and sometimes _third_ parameter defines the value _written to_ the boiler or _read from_ the boiler. The data types are: | ||
| 44 | +- uint16_t marked as u16 in the comments | ||
| 45 | +- sint16_t marked as s16 | ||
| 46 | +- float marked as f8.8 (because actually it is a sint_16 / 256) | ||
| 47 | +- Two times a uint8_t marked as flag8, u8 or s8. If it is a flag the meaning of bits is defined in an enum class with a name inding in _FLAG, e.g. ```enum class STATUS_FLAGS``` | ||
| 48 | + | ||
| 49 | +## License | ||
| 50 | +© 2022 Jeroen Döll, licensed under the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html) | ||
| 51 | + | ||
| 52 | + | ||
| 53 | +Remember: the thermostat is always the _primary_ device and the boiler always the _secondary_. |