OpenTherm Gateway binding (test version available)

Tags: #<Tag:0x00007fe05e0ab428> #<Tag:0x00007fe05e0ab0b8> #<Tag:0x00007fe05e0aa7d0>

(Arjen Korevaar) #5

Ok, a little status update on this…

I’ve read through the OpenTherm specifications and wrote a Java program that connects to the serial to ethernet converter and reads and parses messages sent by the thermostat, boiler and gateway. So I guess all the ingredients are there to create an openHAB binding.

I tried to fork the openhab repo, but only found the openhab2-addons repo. However, when I create a fork and clone it, I can open the projects in Eclipse but get compile errors on missing openHAB classes (such as BaseThingHandler, ThingTypeUID etc).

Earlier, I followed the IDE setup guide, which gives me a working environment with everything in it and no compile errors, but then it’s not based on my own fork :S so I’m not completely sure how to set things up.

Update: never mind, found out that after importing Existing projects into Workspace, I had to also import Oomph projects into Workspace and then add the openHAB Development and openHAB2 Add-ons. Still getting to know this environment…

Another thing would be threads. I need a TCP socket listener (or in a future version Serial port comm) and in my tryout app I run this on a background thread. I read that starting own threads need to be avoided and instead schedulers need to be used. I don’t see how to run a continously running process such as a TCP socket on a scheduled task though. I did see quite a few other bindings use threads, but if there is a better way of running this socket, I would gladly use that.

(Joe) #6

@Mephix, @Dim


I’ve found three reports of successful open therm solutions:


Perhaps it helps a little bit.


(Arjen Korevaar) #7

Hi Joe,

Thanks for response. The solutions you refer to are all based on using an MQTT broker which is something I try to avoid by creating a native openHAB binding for the OpenTherm Gateway.

Regarding that binding… I’ve made some very good progress up untill a couple of weeks ago, but I’m having difficulties finding the time to finish it up. I will definitely continue to work on it though.

(Joe) #8

Hi @Mephix,

have you seen this Link?

Based on an Arduino this guys try to encode the opentherm-protocol.


(Arjen Korevaar) #9

Hi Joe,

I’m using the OpenTherm Gateway to handle all the sending and recieving of signals on the line. So I don’t really need to worry about voltages, length of pulses etc.

Communicating with the gateway is all about reading and writing bytes to the serial interface. A specification of what each byte (or bit) does, is available at

Since the OpenTherm Gateway adds information to the frames, a binding that is written to work with this gateway will probably not work with other solutions such as using an arduino. At least, not without some modifications to deal with the differences in frames.

That said, if I can isolate the added frames into the implementaion of the connector interface and have it return just the OpenTherm information, it wouldn’t be too difficult to write different connectors for other solutions, making the binding eventually a more generic “OpenTherm” binding instead of a specific “OpenTherm Gateway” binding. I will keep this in mind when designing the interface.


(Daniel) #10

Cool, my link is up there too ( :stuck_out_tongue:

The reason I went the MQTT route is that I wanted to decouple my logic and transport as much as possible. I’m currently in the process of migrating the transport of all my components to MQTT and have my applications consume the data from there.

The fact that there has been an attempt in the past to write a binding for OTGW but it kinda died in the process didn’t really help…

(Han) #11

any progress on the binding?

(Arjen Korevaar) #12

I haven’t felt much need to work on the binding during the summer months, but now that temperatures are slowly dropping I started working on it again…

The connection to the opentherm gateway is working now, the logs shows all the messages received from the gateway. The next step is to define all the channels in the binding and have them updated with the correct values from the gateway. I kinda struggle to have the channels defined correctly. This should be pretty straight forward, but for some reason the channels don’t show up in OH. Anyway, hope to have that fixed soon.

So… got that fixed as well. Turns out you really need to remove the binding and add it again to update the channels in OH. It’s now a matter of adding all the channels needed and the option to set values such as the room temperature setpoint.

You’re welcome to have a look at and provide me with some feedback :wink:

(Arjen Korevaar) #13

So, I’ve got a first version running and I’ve included a screenshot in the readme at (scroll down to Channels)

I also have a snapshot package available for testing. If you’re interested please send me a message. Would really like to have some feedback to further develop the binding.

(Stuart Hanlon) #14


Do you have a compiled Jar of your binding?

I’ve looked and can’t seem to find one.

Many thanks.


(Arjen Korevaar) #15

I’m not sure how this is normally done, but I have published the jar file in a separate repository.

Please have a look at

As stated before, this binding currently only supports connecting to the OTGW through a TCP socket connection, since that’s what I am using. If you use a different way of connecting to the OTGW, please let me know so that I can add support for that as well.

(Ikke) #17

Hi Arjen,

Are you using this OTGW: with the Ethernet Module?


(Arjen Korevaar) #18

Hi Micha,

Yes, I am using the OpenTherm Gateway designed by Schelte Bron. The link you posted seems to be the SMD version of the print, with the option to add an ethernet module directly onto the pcb. Mine is the normal (non-SMD) version and I use it with a Moxa NPort serial to ethernet converter.

The two versions of the OTGW use the same type of components and PIC controller, so I would expect them to work in exactly the same way.

Also, the ethernet module simply converts between TCP/IP and RS232 and so it should not matter which converter is used.

Of course the only way to really tell is to test it. So if you have this SMD version running, I am very interested in your findings when trying to control it through the OpenTherm Gateway Binding!


(Peter) #19

Hello Arjen,

Thanks for your great work !
The binding works perfect, I can monitor all the items in OpenHAB.

I use the original OTGW with a serial to ethernet converter for more than a year without any problem.

Unfortunately the (temporary) setpoint override function doesn’t work jet in my configuration.
Any suggestion how to manage this feature in OpenHAB ?

It would be also nice to override the domestic hot water (DHW) setpoint
I have a solar boiler and heating up the boiler with the gas burner is always disabled, except when the DHW temperature drops and there is no sun …
Is it possible to add the DHW setpoint and the override function for the DHW in the binding ?
This nice function is available in the original otmonitor software.

Kind regards and thanks in advance !

(Arjen Korevaar) #20

Hi Peter,

Thank you for your reply. This kind of feedback is exactly what I need to further develop the binding! Changing the override room setpoint using the same channel as the current room setpoint turned out to be difficult, because it takes a while before the TT (or TC) command overrides the actual setpoint. By then, the original value is re-read from the gateway and updated (so basically ‘resetted’) in the binding. Therefor, in the new version of the binding the override setpoint is available as a separate channel. Once you update that, it takes a couple of seconds (to max a minute or so) before the actual setpoint is updated by the gateway and reported back to the binding.

Regarding the DHW setpoint, I have added two channels, one for reading the current DHW setpoint and one to override it (for the same reason as above). I have tested it up to the point where I can see the commands being sent and received by the gateway, but my boiler doesn’t seem to actually support it so please give it a try and let me know if it works correctly. Also, I found that if you set the DHW override setpoint to values lower than 40 or higher than 60, I get a BV (bad value) response. Not sure if this is standard or just my setup. I haven’t yet found this min/max in OpenTherm specifications or OTGW documentation. If you can let me know the min/max your setup supports (easily verified by looking at the actual DHW setpoint being updated or not) I can perhaps add a min/max value restriction on this channel to prevent out of bounds values to be entered.

The new version of the binding is available at:


(Arjen Korevaar) #21

Hmm re-reading your post (and looking at the screenshot) I guess the version of the binding you use already has the split room temperature setpoint channels. One for reading, one for overriding. I did however change a few things in the way the commands are sent to the gateway, so please try the latest version.

If it still doesnt work, can you enable debug logging for “org.openhab.binding.openthermgateway” and set the override setpoint again? In the log, you should see something like:

Sending message: TT=21
Received message: TT: 21.00

(Peter) #22

Hi Arjen,

Thank you so much for your quick reply and updating the binding !

I understand the difference between the read actual setpoint on the thermostat and the override setpoint.
But the setpunt doesn’t change on my system.

When becomes the setpoint override active ? By a value different from zero ?

Here you see a piece of the log :

2018-10-04 23:19:59.499 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.640625 to 26.5
2018-10-04 23:20:04.505 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.5 to 26.640625
2018-10-04 23:20:09.527 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.640625 to 26.5
2018-10-04 23:20:13.952 [vent.ItemStateChangedEvent] - OpenThermGateway_OutsideTemperature changed from 15.140625 to 15.25
2018-10-04 23:20:14.555 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.5 to 26.640625
2018-10-04 23:20:23.741 [ome.event.ItemCommandEvent] - Item 'OpenThermGateway_OverrideRoomSetpoint' received command 28.0
2018-10-04 23:20:23.759 [vent.ItemStateChangedEvent] - OpenThermGateway_OverrideRoomSetpoint changed from 20 to 28.0
2018-10-04 23:20:24.501 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.640625 to 26.5
2018-10-04 23:20:29.529 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.5 to 26.640625
2018-10-04 23:20:30.331 [ome.event.ItemCommandEvent] - Item 'OpenThermGateway_DomesticHotWaterOverrideSetpoint' received command 55
2018-10-04 23:20:30.343 [vent.ItemStateChangedEvent] - OpenThermGateway_DomesticHotWaterOverrideSetpoint changed from 50 to 55
2018-10-04 23:20:39.475 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.640625 to 26.5
2018-10-04 23:20:44.498 [vent.ItemStateChangedEvent] - OpenThermGateway_BoilerWaterTemperature changed from 26.5 to 26.640625

The override value don’t change the setpoint in both room and DHW situation.

I still missing the actual DHW temperature in the new binding.

But that’s a detail …

Kind regards and thanks,


(Arjen Korevaar) #23

Hi Peter, indeed setting the value of the override setpoint to anything other than 0 should do the trick. The override setpoint value is then updated immediately, the actual setpoint is updated a couple of seconds later.

Can you try to enable debug logging as I mentioned earlier ? Because that should show the actual writing to the opentherm gateway and the response from the gateway which should tell us if the command was received succesfully.

To enable debug logging, in short: log in to your device running openhab and SSH into localhost port 8101 (thats the openhab console) with username openhab and password habopen:

$ ssh -p 8101 openhab@localhost
Password: habopen

Then issue the following commands

openhab> log:set DEBUG org.openhab.binding.openthermgateway
openhab> log:tail

This should give you a rolling log screen displaying everything regarding the opentherm gateway binding in high detail. Please look for a combination of something like:

Sending message: TT=21
Received message: TT: 21.00

This should appear directly after you set the room temperature override value in the UI (or any other way).

To quit the rolling log screen, hit Ctrl + C

You may want to set the loglevel for opentherm gateway binding back to ERROR level to prevent loads of log entries to be generated:

openhab> log:set ERROR org.openhab.binding.openthermgateway

Please let me know what you find.


(Peter) #24

Hi Arjen,

Thanks for your reaction and the explanation about the logging of the binding.

Here’s the log :

20:30:54.880 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received message: T00120000
20:30:55.176 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received message: BC012019D
20:30:55.399 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received message: T80000200
20:30:55.416 [INFO ] [smarthome.event.ItemCommandEvent ] - Item 'OpenThermGateway_OverrideRoomSetpoint' received command 21
20:30:55.430 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received channel: openthermgateway:otgw:6a3a0fc5:overridesetpoint, command: 21
20:30:55.434 [INFO ] [smarthome.event.ItemStateChangedEvent] - OpenThermGateway_OverrideRoomSetpoint changed from 26.0 to 21
20:30:55.445 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Sending message: TT=21
20:30:55.779 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received message: B40000200
20:30:55.785 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received update for channel 'ch_enable': OFF
20:30:55.792 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received update for channel 'dhw_enable': ON
20:30:55.798 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received update for channel 'ch_mode': OFF
20:30:55.807 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received update for channel 'dhw_mode': OFF
20:30:55.817 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received update for channel 'flame': OFF
20:30:55.979 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received message: T80000200
20:30:56.281 [DEBUG] [teway.handler.OpenThermGatewayHandler] - Received message: B40000200

I see the sending message: TT=21, but don’t get a Receiving message of TT …
So, no response from the gateway. Strange !

Hopefully can you find a solution.
I’m curious.

Are you able to override your setpoint with the current binding ?
I was able to override the setpoint of my Honeywell Chronotherm Touch thermostat in otmonitor.

Is it also possible to add a channel for the actual DHW value in your next revision ?

Kind regards and have a nice week-end !

(Arjen Korevaar) #25

Hi Peter,

I have made some changes after I found differences in how writing to the socket works on my dev/test machine (windows) and the raspberry pi running openhab. If anyone could explain why autoflush + println doesn’t work on linux, but adding a newline to the message and explicitly calling flush does work… i’d be happy to hear :wink:

Also I added a DHW temperature channel and a version property (currently 0.2.0) to the OpenTherm Gateway thing.

Please download the latest jar file from and give it another try. On my setup, everything seems to be working, except that I don’t get DHW temp and Return water temp values from OTGW… but that’s probably due to my boiler, since I don’t get those values on otmonitor either.

After using the new version, please verity that the version property of the Thing shows 0.2.0. And again, if anything doesn’t seem to work, use the debug logging to provide me with details.