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

• Install the EasyOpenTherm library directly 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 sint16_t / 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 ending in FLAG, e.g. ```enum class STATUSFLAGS```

Error handling

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 error occurred in the communication between thermostat (primary) and boiler or HVAC (secondary). These functions return true if everything is fine, but also upon an error on application level. You will get this error if e.g. you read out your boiler or HVAC with a DATA-ID that is not supported. Also, if you write data to your boiler or HVAC, the value can be out of range, e.g. a setpoint is to low or to high. In this case error() will return INVALID_DATA.

All error codes:

• OK: everything is fine!
• UNKNOWN_DATA_ID: your boiler or HVAC does not support the DATA-ID you requested.
• INVALID_DATA: the DATA-ID you sent with write() or readWrite() is correct but the value you sent is out of bounds
• SEND_TIMEOUT: a timeout occurred while sending the request to the boiler or HVAC. Check if the timeout value in the OpenTherm constructor is OK (should be less than 1,000 ms, defaults to 900 ms)
• RECEIVE_TIMEOUT: a timeout occurred while sending the request to the boiler or HVAC. Most of the time this indicates problems with wiring. If wiring is OK, did you check if your boiler actually does support the OpenTherm protocol?
• PARITY_ERROR: the parity check failed.

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 welcome!