Skip to content

Commit 9415a2f

Browse files
michpromichpro
committed
readme file added
1 parent 59d8588 commit 9415a2f

File tree

2 files changed

+217
-0
lines changed

2 files changed

+217
-0
lines changed

‎README.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# **Arduino UNO OpenTherm Shield**
2+
3+
- [**Arduino UNO OpenTherm Shield**](#arduino-uno-opentherm-shield)
4+
- [**Overview**](#overview)
5+
- [**Features**](#features)
6+
- [**Schematic diagram**](#schematic-diagram)
7+
- [**Module visualisation**](#module-visualisation)
8+
- [**Assembly**](#assembly)
9+
- [**Production files**](#production-files)
10+
- [**Testing out the hardware**](#testing-out-the-hardware)
11+
- [Prerequisites](#prerequisites)
12+
- [Instructions](#instructions)
13+
- [Notes](#notes)
14+
- [**Software**](#software)
15+
- [**Reporting bugs**](#reporting-bugs)
16+
- [**License**](#license)
17+
- [**Hardware**](#hardware)
18+
- [**Software**](#software-1)
19+
- [**Support**](#support)
20+
21+
---
22+
23+
## **Overview**
24+
The Arduino OpenTherm Shield is an open-source hardware interface designed to enable an Arduino microcontroller to communicate with heating systems using the OpenTherm protocol.
25+
OpenTherm is a point-to-point communication protocol commonly used in modern heating systems for efficient control and monitoring.
26+
This shield provides the necessary voltage conversion, electrical isolation, and signal conditioning to interface the Arduinos 5V or 3.3V logic
27+
with the OpenTherm bus, which typically operates at higher voltages (24V).
28+
29+
### **Features**
30+
* OpenTherm slave interface to communicate with a boiler
31+
* OpenTherm master interface to communicate with a thermostat
32+
* can implement master, slave and gateway modes
33+
* built-in (3.3-5V) to 24V DC-DC step up converter
34+
* Arduino UNO compatible shield
35+
36+
This work is based on [otgw.tclcode.com](https://otgw.tclcode.com) project.
37+
38+
---
39+
40+
## **Schematic diagram**
41+
<p align="center"><img src="./docs/schematic.png" alt="wiring diagram" width="80%"/></p>
42+
43+
44+
## **Module visualisation**
45+
(click on the image to see the 3D model)
46+
<p align="center"><a href="https://3dviewer.net/#model=https://github.com/michpro/Arduino_OpenTherm_shield/blob/master/docs/Arduino_OpenTherm_shield.wrl"><img src="./docs/Arduino_OpenTherm_shield.png" alt="Arduino UNO OpenTherm Shield" width="50%"/></a></p>
47+
48+
## **Assembly**
49+
[Interactive BOM and placement](https://michpro.github.io/Arduino_OpenTherm_shield/ibom.html)
50+
51+
For Arduino UNO:
52+
* JP1 jumper – leave in the Auto position (V<sub>cc</sub> from IOREF).
53+
54+
For WeMos D1 UNO:
55+
* JP1 jumper - this board is not fully compatible with Arduino specifications - the IOREF pin on this board should have a voltage of 3.3V, but it has 5V. Therefore, cut the default jumper between the Auto and V<sub>cc</sub> pads and use a drop of tin to connect the V<sub>cc</sub> pad to 3.3V.<br>*You can also modify the WeMos D1 UNO so that the IOREF pin has the correct voltage of 3.3V*.
56+
57+
Other boards:
58+
* This shield should also be compatible with other boards. You only need to check the correct voltage on the IOREF pin (and possibly make a change as for WeMos D1 UNO) and, if necessary, adjust the software to the board definition.
59+
60+
## **Production files**
61+
Production files can be found [**here**](./production/).
62+
63+
---
64+
65+
## **Testing out the hardware**
66+
Below are the start-up instructions for the ["shield_test.ino"](./software/shield_test/shield_test.ino) Arduino program, a diagnostic tool designed to test and validate the electrical and communication integrity between a boiler and thermostat circuits on the OpenTherm shield. These instructions guide you through the process step-by-step, ensuring you can verify your hardware setup correctly.
67+
68+
### Prerequisites
69+
- **Arduino Board**: Use an AVR family board (e.g., Arduino UNO).
70+
- **OpenTherm Shield**: Ensure it is properly connected to the Arduino.
71+
- **Computer**: Equipped with Arduino IDE or a serial monitor software.
72+
- **Multimeter**: Required for measuring voltages and currents.
73+
- **Two Wires**: Needed to connect the BOILER and THERM terminals during testing.
74+
75+
### Instructions
76+
77+
1. **Upload the Program**
78+
- Load the ["shield_test.ino"](./software/shield_test/shield_test.ino) program onto your Arduino board (Arduino UNO preffered) using the Arduino IDE.<br>
79+
*If necessary, adjust the pins used in the programme.*
80+
81+
2. **Open Serial Monitor**
82+
- Launch the serial monitor in the Arduino IDE or your preferred serial terminal software.
83+
- Set the baud rate to **115200**.
84+
85+
3. **Initial Setup**
86+
- Disconnect the 'THERM' and 'BOILER' terminals from each other if they are connected.
87+
- Check the LEDs on the shield:
88+
- **'PWR'** and **'RxT'** LEDs should be lit.
89+
- **'RxB'** LED should be off.
90+
- The serial monitor will display a prompt. If the LED statuses match, type **`y`** and press Enter to proceed.
91+
92+
4. **Voltage Measurement 1**
93+
- Use a multimeter to measure the voltage between the **+24V test point** and **GND**.
94+
- Expected range: **23.5V to 24.5V**.
95+
- If within range, type **`y`** in the serial monitor to proceed.
96+
97+
5. **Voltage Measurement 2**
98+
- Measure the voltage between the **T+ test point** and **GND**.
99+
- Expected value: Approximately **24V**.
100+
- If correct, type **`y`** to proceed.
101+
102+
6. **Current Measurement 1**
103+
- Measure the current flowing between **T+** and **GND**.
104+
- Expected range: **5mA to 9mA**.
105+
- Verify that the **RxT LED** is **not lit** during this measurement.
106+
- If correct, type **`y`** to proceed.
107+
108+
7. **Activate MASTER-OUT and Current Measurement 2**
109+
- The program will activate the 'MASTER-OUT' line (you’ll see a message in the serial monitor).
110+
- Measure the current between **T+** and **GND** again.
111+
- Expected range: **17mA to 23mA**.
112+
- Ensure the **RxT LED** remains **not lit**.
113+
- If correct, type **`y`** to proceed.
114+
115+
8. **Connect Terminals and Voltage Measurement 3**
116+
- Connect the **BOILER** and **THERM** terminals using two wires (polarity does not matter).
117+
- Measure the voltage between test points **B1** and **B2**.
118+
- Expected range: **15V to 18V**.
119+
- If within range, type **`y`** to proceed.
120+
121+
9. **Check RxB LED**
122+
- The program will activate 'MASTER-OUT' again.
123+
- Observe the **'RxB' LED**; it should **light up**.
124+
- If it does, type **`y`** to proceed.
125+
126+
10. **Activate SLAVE-OUT and Voltage Measurement 4**
127+
- The program will activate the 'SLAVE-OUT' line.
128+
- Check that the **RxT LED** **stops lighting up**.
129+
- Measure the voltage between **B1** and **B2** again.
130+
- Expected range: **5V to 7V**.
131+
- If correct, type **`y`** to proceed.
132+
133+
11. **Test Result**
134+
- If all steps are completed successfully, the serial monitor will display:
135+
```
136+
*****************
137+
* TEST PASSED *
138+
*****************
139+
```
140+
- If any step fails, it will show:
141+
```
142+
*****************
143+
* TEST FAIL !!! *
144+
*****************
145+
```
146+
147+
12. **Continuous Testing (if passed)**
148+
- If the test passes, the program will enter a continuous testing mode.
149+
- It will repeatedly check communication between the boiler and thermostat, printing:
150+
- **"Boiler inbound, thermostat outbound ... OK"** or **"Failed"** with a reason.
151+
- **"Boiler outbound, thermostat inbound ... OK"** or **"Failed"** with a reason.
152+
153+
### Notes
154+
- **Test Points and LEDs**: Ensure you correctly identify the test points (+24V, T+, GND, B1, B2) and LEDs (PWR, RxT, RxB) on the OpenTherm shield.
155+
- **Safety**: Exercise caution when measuring voltages and currents to avoid short circuits.
156+
- **Troubleshooting**: If a measurement falls outside the expected range:
157+
- Double-check your connections and multimeter settings.
158+
- Retry the step. Persistent issues may indicate a problem with the shield or setup.
159+
160+
<br>
161+
162+
***Follow these instructions carefully to test and validate your OpenTherm shield setup. Each step requires confirmation via the serial monitor, so keep it open and active throughout the process. Successful completion ensures your boiler and thermostat circuits are functioning correctly.***
163+
164+
---
165+
166+
## **Software**
167+
- Recommended library for use in your OpenTherm projects:
168+
[https://github.com/ihormelnyk/opentherm_library](https://github.com/ihormelnyk/opentherm_library)
169+
170+
---
171+
172+
## **Reporting bugs**
173+
174+
[Create an issue on GitHub](https://github.com/michpro/Arduino_OpenTherm_shield/issues)
175+
176+
---
177+
178+
## **License**
179+
Copyright © 2025 Michal Protasowicki
180+
181+
### **Hardware**
182+
* Hardware part of this project is released under CERN Open Hardware Licence Version 2 - Permissive.
183+
184+
[![License: CERN-OHL-P-2.0](https://img.shields.io/badge/License-CERN--OHL--P--2.0-blue.svg)](./LICENSE)
185+
186+
### **Software**
187+
* Software part of this project is released under MIT Licence.
188+
189+
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./software/shield_test/LICENSE)
190+
191+
---
192+
193+
## **Support**
194+
If You find my projects interesting and You wanted to support my work, You can give me a cup of coffee or a keg of beer :)
195+
196+
[![PayPal Direct](https://badgen.net/badge/icon/Support%20me%20by%20PayPal?icon=kofi&label&scale=1.5&color=blue)](https://www.paypal.me/michpro)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[![ko-fi](https://badgen.net/badge/icon/Support%20me%20on%20Ko-fi?icon=kofi&label&scale=1.5&color=red)](https://ko-fi.com/F1F24CEW1)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[![Coinbase](https://badgen.net/badge/icon/Support%20me%20with%20cryptocurrencies?icon=kofi&label&scale=1.5&color=blue)](https://commerce.coinbase.com/checkout/ec299320-cbed-475d-976e-fdf37c1ac3d0)

‎software/shield_test/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Michal Protasowicki
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)