Troubleshooting

If you have built the Opentherm Gateway and it doesn't work, or you are the cautious type and prefer to check the device step by step before hooking everything up, here are some suggestions on things you can check. For most of these checks you will need at least a multimeter capable of measuring voltage, current and resistance. You will also need a program to communicate with the gateway. This guide assumes you will use my Opentherm Monitor utility for that.

Power supply

The first thing to check is the power supply. Start out with the gateway unplugged from mains power and the thermostat and boiler disconnected. Do not yet install any WiFi or LAN module. Remove the PIC from its socket. Then connect the OTGW to your PC with a USB cable. The LEDs for the different supply voltages should light up: 3.3V (green), 5V (red) and 24V (yellow). Check for 3.3V +/- 1% between pins 5 and 14 of the PIC socket. Also make sure the polarity is correct. You should get a positive voltage if you put the black probe on pin 5 and the red probe on pin 14.

Opentherm interfaces

Next measure the voltage on the two contacts of the green or grey connector nearest to the "Therm" label. This should produce a value somewhere between 18V and 24V. The polarity is not important. If the voltage is correct you can measure the current between the same two contacts. It should be between 5mA and 9mA. If you don't have a current setting on your multimeter you can hook up a 100Ω resistor to the connector and measure the voltage. If you remember your high school physics you have probably already figured out that the voltage should be between 0.5V and 0.9V.

If you connect pin 3 of the PIC socket to ground (e.g. pin 5), the current between the two "Therm" contacts should be between 17mA and 23mA (1.7V and 2.3V across a 100Ω resistor). Now use two pieces of wire to connect the "Therm" contacts to the "Boiler" contacts . You should now find a voltage between 15V and 18V on both sets of contacts. If you connect pin 2 of the PIC socket to VDD (e.g. pin 14), the voltage on both interfaces should drop to between 5V and 7V.

Measure the voltage on pin 18 of the PIC socket with pin 3 left open and again when it is connected to ground. In the former case the voltage should be below 1.47V (it is actually expected to be 0V). In the latter case the voltage must be above 1.47V (in practice it's usually around 3V).

When finished, remove the wires between the "Therm" and "Boiler" contacts. Do not continue until all of the above checks have passed. When some of the tests did not produce the expected result and you are convinced you performed the test correctly, contact the Nodo shop for assistance.

Serial interface

Temporarily disconnect the OTGW from your PC and place the PIC into its socket. Make sure it is oriented the right way around. The notch on the chip must match the notch of the outline on the circuit board. You can install a PIC16F1847 or PIC16LF1847. Do not use a PIC16F88. It does not run on 3.3V. Connect the gateway to your PC using a USB cable.

Start the OTmonitor program and configure the connection via Options → Connection. You should choose "Serial port" and then select the correct serial port. Then click connect. Make sure the icon in the bottom right-hand corner of the main window shows an active connection: Note that the icon only shows that the program has successfully accessed the serial port/USB device. It provides no proof that the whole path to the gateway is in working order. Close the configuration window and access the Log tab. If for some reason you can't use the OTmonitor program, you may use some terminal emulator program on your computer (like hypertherm or minicom) and configure it for the serial port the gateway is connected to at 9600 baud, 8 bits, no parity.

If your PIC has been loaded with the latest gateway firmware, it should detect that no thermostat is connected and start generating R00000000 messages, repeated about once a second. OTmonitor will report those messages as:
    15:19:41.689448 R00000000  Read-Data  Status: 00000000 00000000
    
If you see only garbage appearing on the screen, there may be a baud rate mismatch. Make sure you have configured your terminal emulator program correctly.

If you see none of the above and you have checked your connection to the PC, verify that the PIC is really running. You should measure the following voltages on the pins of the PIC: pin2=3V, pin3=3.3V, pin4=3.3V, pin8=3.3V, pin9=3.3V, pin10=3.3V, pin11=3.3V, pin12=3.3V, pin13=3.3V, pin17=2.9V. The voltages on pin 10 and 11 may not be steady. They can briefly drop once a second. If you are running the gateway firmware, you should see the A, B, C, and D LEDs flash briefly about a second after applying power to the gateway. Subsequently, LED B flashes every second.

When serial transmission from the gateway to the PC is working, you can try to send a free format command to the gateway via Options → Miscellaneous (also accessible with the F7 key). If you type and enter "PR=B" you should get the date and time the firmware was built. For version 6.5 that is supposed to be "17:52 12-03-2023".

The remainder of these troubleshooting instructions presume that the gateway is running the latest gateway firmware. If you have the diagnostics firmware loaded, you can take this opportunity to run a few of the diagnostics (and note down the results in case you need to report them later). When you are happy with the results, obtain the latest version of the gateway firmware for your PIC and load it into the gateway using the File → Firmware upgrade option of OTmonitor.

Network interface

If you bought a WiFi or LAN module for your OTGW from the Nodo shop, this may be a good time to get it working. The USB interface may no longer be convenient when you move the gateway to the location where you can connect the thermostat and boiler. Configure and install the WiFi or LAN module (see below for details). You will need to reconfigure the connection parameters in OTmonitor to be able to connect again. Select "TCP connection" and enter the IP address that was assigned to the LAN or WiFi module, and the appropriate port. Make sure you have two way communication before moving the OTGW to its designated location.

WiFi interface

There are several choices of firmware you can install on the WiFi module:
  • ESPEasy: Follow the "OpenTherm Gateway NodeMCU" instructions available on the "Downloads" page of the Nodo shop site.
  • OTGWMCU: Instructions are available on the MCU firmware page. When using this firmware, you should connect to port 25238.
  • OTGW-firmware: The installation procedure is documented on the github wiki. This firmware also uses port 25238.

LAN Module

Configure the interface according to the "OpenTherm Gateway & USR-TCP232-T2" instructions available on the "Downloads" page of the Nodo shop site. Use port 23 to connect to the LAN module, unless you specified a different port than suggested in the instructions.

Slave interface

With the communications between the OTmonitor program and your OTGW working, connect your Opentherm thermostat to the "Therm" contacts of the OTGW. In the Log area you should see "Thermostat connected", indicating that the gateway has detected the presence of an opentherm thermostat. After a short while you should start to see messages like "T80190000" every second or faster. The exact message depends on the thermostat, but it should be a literal "T", followed by eight hexadecimal digits. Once again, OTmonitor will add a time stamp and translate the message to a slightly more human readable form.

If you see nothing, or things like "Error 01" or "Error 03", the reference voltage may be wrong. You can modify it via Options → Settings (F5) or with the VR=X command. where X is a number between 0 and 9. The normal value is 1.472V (X=5). But due to variations in the used components you may have to change it. Don't forget to click the Set button after every adjustment to actually make the change in the gateway.

It is also possible that your thermostat doesn't produce a perfect opentherm signal. Some users have reported that the Remeha Celcia 20 thermostat suffers from this defect. You can make the gateway less sensitive to some forms of this problem by switching on the "Ignore multiple mid-bit transitions" option ("IT=1" serial command). On a brand new gateway this option should already be on. You may need to set it when upgrading from an older firmware version.

With the thermostat connected, the voltage on the "Therm" connector should have dropped below 7V, with short bursts upward once a second. During these bursts the voltage jumps to values between 15V and 18V, but you won't be able to register that with a simple multimeter. If you have an oscilloscope you should see pulses of 500µS and 1mS wide.

If you can't get anything other than errors, see if you can get your hands on a different brand or type of thermostat, if only for testing. Perhaps the thermostat does not follow the Opentherm specifications closely enough for the gateway to accept.

Master interface

Before connecting the boiler, make sure it is actually providing a signal that conforms to the Opentherm specifications. Other types of interfaces may damage the OTGW. If you are unsure, check the voltage on the wires from the boiler. You should see a DC voltage below 30V. If you find a considerably higher voltage, or the boiler is providing an AC voltage, do not connect it to the OTGW. If the voltage looks fine, connect a 1k8 resistor (or two 1k resistors in series) between the wires. The voltage should drop to somewhere between 9V and 18V. If it remains higher, that still indicates this is not an Opentherm interface.

When you don't find the right signal levels, you may have to change a setting on the boiler to switch to Opentherm. Or you may need to use a different connection on the boiler. Some boilers may need an Opentherm converter. Check the boiler manual for more information.

Once you have determined that you have a compatible boiler, connect the Opentherm signal from the boiler to the "Boiler" contacts of the OTGW, polarity does not matter. You should now see alternating TXXXXXXXX and BXXXXXXXX reports. After a while you may start seeing RXXXXXXXX and AXXXXXXXX reports as well.

If you don't see any BXXXXXXXX reports, you can determine whether it is a hardware or firmware problem by switching the gateway to monitor mode via Options → Miscellaneous (F7) or using the "GW=0" serial command. In monitor mode, the firmware doesn't have to be able to decode the opentherm messages in order to pass them on. So, if things start working in monitor mode, there is a firmware problem. If the thermostat is still unable to communicate with the boiler in this mode, you should focus your debugging efforts on the hardware of the opentherm line drivers. Test #4 of the diagnostic firmware may be of help with that.