OpenTherm Arduino ESP32/ESP8266 Library

Create your own thermostat with this library and save money on your energy bills while reducing your carbon footprint!

The library complies with the OpenTherm specification. Control any (condensing) boiler or air conditioner (HVAC) that also meets the OpenTherm specification.

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. To connect the boiler, you will need an OpenTherm controller.

Installation

• Download the library from GitHub
• Install the library named EasyOpenTherm-main.zip using the Arduino IDE library manager
• Connect the pins marked 'OT' of the OpenTherm controller 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 interchangeable
• Connect the pins marked '3v3' and 'GND' to the ESP32 pins '3v3; and 'GND'
• 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)

Usage

#include <EasyOpenTherm.h>

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

#define OT_RX_PIN (34)
#define OT_TX_PIN (17)

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 and vice versa! Create an OpenTherm class instance

OpenTherm thermostat(OT_RX_PIN, OT_TX_PIN);

Make sure that only one instance of this object is alive at a time. So make it global or static like in the examples. Start communicating with the boiler (or HVAC) e.g. request activation of the services of the boiler and request it's status flags

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);
uint8_t statusFlags;
thermostat.status(primaryFlags, statusFlags);

This command will return true on success and false otherwise All other interaction with the boiler is done using the read(), write() or readWrite() functions, e.g.

thermostat.write(OpenTherm::WRITE_DATA_ID::CONTROL_SETPOINT_CH, CH_SETPOINT)

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:

• uint16_t marked as u16 in the comments
• sint16_t marked as s16
• float marked as f8.8 (because actually it is a sint_16 / 256)
• 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 STATUSFLAGS```

Remember: the thermostat is always the primary device and the boiler always the secondary.

Glossary

• primary: the device issuing the requests, in this context also called thermostat
• secondary: the device handling the requests and sending responses, also called boiler or HVAC
• CH: Central Heating
• DHW: Domestic Hot Water
• OTC: Outside Temperature Compensation
• HVAC: Heating, Ventilation and Air Conditioning
• setpoint: the desired value of a parameter, e.g. the desired temperature of the temperature of the water of the boiler is called CH (Central Heating) setpoint
• on/off: a non digital control mode switching the boiler on and off (by shortening the thermostat wires and opening them)
• _ modulation_: a technique of lowering the flame when less power is needed
• flow: water leaving the boiler
• return: water returning to the boiler

License

© 2022 Jeroen Döll, licensed under the GNU General Public License. Enjoy using the library, feedback is wellcome!