search

jpraus / arduino-opentherm

Arduino library and hardware shield to send and receive data from Opentherm devices
Other
164 stars 42 forks source link

readme

Opentherm IO library for Arduino

Have you ever wondered when and why is your boiler running and heating your home? Do you want to automate your heating system with Arduino? The OpenTherm IO library together with an Arduino OpenTherm shield is designed for you. It will allow you to monitor and control your OpenTherm device with Arduino.

Connect Your Central Heating to Arduino - article describing the use of shield and library.

This repository contains both Arduino library and hardware adapter for OpenTherm protocol 2.2 - see specification.

Arduino UNO OpenTherm shield

What is it good for?

Arduino shield

In order to connect your Arduino board to Opentherm device, you need to create a special hardware interface to convert voltage and current levels for Arudino to be able to handle. Voltage on Opentherm bus rises as high as 24V which would easily burn up your Arduino if connected to wires directly.

Buy or DIY

The easiest way to get the hardware is to purchase a Arduino shield kit from my Tindie store. On the other hand the shield is Open Source so you can manufacture and buy all the components on your own!

Features

interface schmetics

Based on otgw.tclcode.com project.

Fabrication files

Are you able to manufacture the PCB yourself? There are Gerber files included in the repository. Or you can get the DIY KIT from my Tindie store.

Parts list

How it is wired up with Arduino

Testing out the hardware

It's not wise to plug the shield with your thermostat or boiler until you test it out. Follow the checks below to make sure your shield is properly assembled. For most of these checks, you will need at least a multimeter capable of measuring voltage, current, and resistance.

The following test works only for 5V version of the board. 3.3V version (Wemos D1) lacks the 3.3V power supply so it does not pass the test without the Arduino board attached. So if you are looking for a 3.3V please build the 5V version first, test out and then update to 3.3V version.

Power supply

  1. Check whether there is no short circuit between two pins on the 24V RED terminal. Use the continuity function of your multimeter.
  2. Connect the 24V power supply, keep in mind the polarity of the red connector. Connect the positive voltage wire to + pin (left) and ground wire to - pin (right). Red LED next to the RED terminal will now light up.
  3. Blue RxT LED will also light up, but don't mind it now. It's perfectly fine.
  4. Check for 5V between +5V pin (fifth from the bottom on the right side) and ground pin (next one above +5V pin)

Interfaces

Keep the 24V power supply connected.

  1. Measure voltage on BLUE THERM terminal with a multimeter. It should read 24V. Polarity is not important.
  2. Next measure current on the same BLUE terminal. It should read a value between 5mA and 9mA. This means a low state of the line.
  3. If you connect MASTER-OUT pin (digital pin 4 / fifth pin from the top on the left side) to the any of the ground pins, the current on BLUE terminal should increase to a value between 17mA and 23mA. This is a high state of the transceiver line. Outbound thermostat communication is working. Disconnect the pin from the ground.
  4. Interconnect BLUE THERM and GREEN BOILER terminals with each other with 2 wires. Polarity does not matter at all. This will simulate a boiler for thermostat interface and thermostat for a boiler interface. Measure now voltage on GREEN terminal, it should read a value between 15V and 18V.
  5. If you re-connect MASTER-OUT pin to the ground again (same as in step 3 above), green RxB LED should light up. Inbound boiler communication is working. Disconnect the pin from the ground.
  6. If you connect SLAVE-OUT pin (digital pin 5 / sixth pin from the top on the left side) to +5V pin, the blue RxT LED should go off. The voltage on the GREEN terminal should drop to a value between 5V and 7V. This verifies that both outbound boiler and inbound thermostat communication is working.
  7. Mount the shield on Arduino UNO (disconnected from the computer). It should power up.
  8. Well done! You are now ready to have some fun with the shield.

Self-test

I've also prepared a self-test program that will test the hardware interface. Download selftest.ino and upload it to your Arduino board. Setup the shield:

  1. Attach shield to Arduino
  2. Connect 24V power supply
  3. Interconnect BLUE THERM and GREEN BOILER terminals with each other with 2 wires.

Self-test result should be:

OpenTherm gateway self-test

Boiler inbound, thermostat outbound .. OK
Boiler outbound, thermostat inbound .. OK

If it's not, do full hardware test above to identify the cause.

Compatibility with Wemos D1 (ESP8266)

The shield and library code are compatible with a Wemos D1 development board which is using ESP8266 instead of AVR chips. However, ESP8266 is using 3.3V logic so to make the shield work, you need to alter it.

Rev4 boards

Rev3 boards

Rev2 boards

Working with library

Library contains 3 examples to test out your setup. These examples are configured to use pins defined above, but library will allow you to change pins to your custom ones.

These examles should give you enough information to build your own code using Opentherm library. Check out header file of library source code to see methods documentation.

Behind the scenes

Library uses following Arduino resources:

Note that you won't be able to use libraries that are using Timer2 or pin changed interrupt together with this library (for example Servo library).

Tested with Arduino Nano and Arduino Uno boards.

Arduino UNO OpenTherm shield

Warning

Please be aware that using this hardware can damage your boiler or thermostat. You may also void your boiler warranty by installing this hardware. Please consult with your boiler manufacturer. I am not responsible for any damage caused by this shield.