Peter M. Groen / EasyOpenTherm

Commit 33283daabee5068c387bb4a483b5bbf6039e114a

Authored by Jeroen88
1 parent aedbed70

Textual changes in primary README.md

Inline Side-by-side
Showing 1 changed file with 11 additions and 10 deletions
README.md
  View file @33283da
1 1 # OpenTherm Arduino ESP32/ESP8266 Library
  2 +Was already working on an ESP32, now ready for an ESP8266 too!
2 3  
3 4 Create your own thermostat with this library and save money on your energy bills while reducing your carbon footprint!
4 5  
5 6 The library complies with the OpenTherm specification. Control any (condensing) boiler or air conditioner (HVAC) that also meets the OpenTherm specification.
6 7  
7   -The library can be easily installed in the Arduino IDE. It has been tested on an ESP32 microcontroller and may also work on an ESP8266.
8   -To connect the boiler, you will need an [OpenTherm controller](https://www.tindie.com/products/jeroen88/opentherm-controller/) or an [OpenTherm controller Shield](https://www.tindie.com/products/jeroen88/opentherm-shield/).
  8 +The library can be easily installed in the Arduino IDE. It has been tested on an ESP32-S2, ESP32-C3, ESP32 NodeMCU and an ESP8266 NodeMCU microcontroller and may also work on other MCU's.
  9 +To connect the boiler, you will need an [OpenTherm controller board](https://www.tindie.com/products/jeroen88/opentherm-controller/) or an [OpenTherm controller Shield](https://www.tindie.com/products/jeroen88/opentherm-shield/).
9 10  
10 11 ## Fully functioning Home Assistant Boiler Thermostat in examples
11 12 ![Home Assistant logo](https://raw.githubusercontent.com/home-assistant/assets/master/logo/logo-small.png)
12 13 ![MQTT logo](https://brands.home-assistant.io/_/mqtt/logo.png)\
13 14  
14   -The Advanced_Thermostat.ino example is specially designed for [Home Assistant](https://www.home-assistant.io/)
  15 +The **Advanced_Thermostat.ino** example is specially designed for [Home Assistant](https://www.home-assistant.io/)
15 16 - Setup the MQTT integration in Home Assistant, if not already done
16 17 - Set your WiFi network name and password in Advanced_Thermostat.ino
17 18 - Set your MQTT broker hostname or IP address, MQTT user name and MQTT password in Advanced_Thermostat.ino
18   -- Compile and flash to an ESP32-S2 with an [OpenTherm controller Shield](https://www.tindie.com/products/jeroen88/opentherm-shield/)
  19 +- Compile and flash to an ESP32-S2 or an ESP32-C3 with an [OpenTherm controller Shield](https://www.tindie.com/products/jeroen88/opentherm-shield/) or any other ESP32 or ESP8266 with an [OpenTherm controller board](https://www.tindie.com/products/jeroen88/opentherm-controller/)
19 20 - Forward the temperature of a room thermometer to the Thermostat using a Home Assistant Automation
20 21 The thermostat (Climate) integration is **automatically added to Home Assistant**, together with several sensors. More information in [the examples directory](https://github.com/Jeroen88/EasyOpenTherm/tree/main/examples).
21 22  
22 23 ## Installation
23   -- Install the EasyOpenTherm library directly using the Arduino IDE library manager
  24 +- Install the EasyOpenTherm library directly using the Arduino IDE library manager (search for 'EasyOpenTherm')
24 25 - Connect the pins marked 'OT' of the [OpenTherm controller](https://www.tindie.com/products/jeroen88/opentherm-controller/) with two wires to the boiler or use the screw terminals on the [OpenTherm controller shield](https://www.tindie.com/products/jeroen88/opentherm-shield/). You can use the existing wires from your current thermostat. The order of the wires is not important, they are interchangeable
25 26 - If using the _board_ connect the pins marked '3v3' and 'GND' to the ESP32 pins '3v3; and 'GND'. For the _shield_ these pins are already connected
26 27 - If using the _board_ connect the pin marked 'RxD' to a pin supporting OUTPUT of the ESP32 and the pin marked 'TxD' to a pin supporting interrupts. For the _shield_ these pins are already connected. The pins used you use should be defined in the program (see below). In Advanced_Thermostat.ino they default to the right pins for the shield and either an ESP32-S2 mini or an ESP32-C3 mini.
... ... @@ -31,10 +32,10 @@ The thermostat (Climate) integration is **automatically added to Home Assistant*
31 32 ```
32 33 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
33 34 ```cpp
34   -#define OT_RX_PIN (34)
35   -#define OT_TX_PIN (17)
  35 +#define OT_RX_PIN (35)
  36 +#define OT_TX_PIN (33)
36 37 ```
37   -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/opentherm-controller/) and vice versa!
  38 +In this case GPIO34 is used for receiving and GPIO33 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/opentherm-controller/) and vice versa!
38 39  
39 40 Create an OpenTherm class instance
40 41 ```cpp
... ... @@ -53,13 +54,13 @@ thermostat.status(primaryFlags, statusFlags);
53 54 This command will return _true_ on success and _false_ otherwise
54 55 All other interaction with the boiler is done using the ```read()```, ```write()``` or ```readWrite()``` functions, e.g.
55 56 ```cpp
56   -thermostat.write(OpenTherm::WRITE_DATA_ID::CONTROL_SETPOINT_CH, CH_SETPOINT)
  57 +thermostat.write(OpenTherm::WRITE_DATA_ID::CONTROL_SETPOINT_CH, 40.0); // This will start up the boiler to heat up the boiler water to 40 degrees
57 58 ```
58 59 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:
59 60 - ```uint16_t``` marked as u16 in the comments
60 61 - ```int16_t``` marked as s16
61 62 - ```float``` marked as f8.8 (because actually it is an ```int16_t / 256.0```)
62   -- Two times an ```uint8_t``` marked as flag8 or u8, or an ```int8_t``` as s8. If it is a flag the meaning of bits is defined in an enum class with a name ending in _FLAG, e.g. ```enum class STATUS_FLAGS```
  63 +- Two times an ```uint8_t``` marked as flag8 or u8, or an ```int8_t``` as s8. If it is a flag the meaning of bits is defined in an enum class with a name ending in _FLAGS, e.g. ```enum class STATUS_FLAGS```
63 64  
64 65 ## Error handling
65 66 The function ```error()``` is used to get information about the last call to one of the functions ```read()```, ```write()``` or ```readWrite()```. All these functions return ```false``` if an
... ...