Helios Binding for Modbus TCP


I am using a Helios ventilation system (KWL EC 500W L) which can be controlled via a web interface or via the Modbus. Modbus is supported both via RS485 and TCP.
Not having managed to find a working existing binding or to integrate a few quickly developed Python scripts with openHAB’s exec binding I decided to tackle developing an actual binding.
It’s been a while since I last developed in Java (or developed something bigger at all) - so it’s probably rather quick and dirty but seems to fulfill my basic needs to control a few parameters.

If anybody else is interested I’m happy to share - please see https://github.com/bern77/org.openhab.binding.helios


To play devil’s advocate, what is it about the HTTP binding, TCP binding, or Mobus binding that didn’t work in your case? And is it something that could be added to one of these binding (probably the Mobus binding) rather than creating a whole new binding?

There is already an overwhelming number of bindings. IMHO it is far better to use or expand what is already there where possible rather than creating yet more bindings.

Well, the Modbus binding didn’t work because it apparently doesn’t support holding registers as required for the Helios devices. It might have been a good idea from an architectural perspective to extend the existing Modbus binding but my level of skill in Java and understanding of the openHAB framework is somewhat limited so I thought I’d rather not spoil other people’s implementations…
The code I’ve created consists of separate classes to communicate with the Helios device which are quite detached from the actual binding implementation, so they could probably be integegrated in other bindings rather easily.

@bern77: have you tried setting type=holding in the openhab.cfg? Holding registers should be supported quite well in the binding.

Did you get any errors in teh logs …or?

The Helios implementation requires to use a different number of registers for the different variables to set or request values. It didn’t seem feasible to configure the Modbus binding accordingly. It would have taken a lot of different Modbus configuration sets, but at the same time creating a lot of errors because in order to read a variable value you need to first write the variable’s number into the register, then read from it.

thank you - this the missing bit of my current home automation

Sounds a bit odd to me. Can you post a link to the device’s manual / modbus register summary?

EDIT: I’ve just found this document: http://www.heliosventilatoren.de/mbv/kwl-modbus_gateway_82269_0714_d_e_f.pdf

And I can only say: What the HELL have they been thinking? Implementations like this one are the reason why using Modbus can be such a pain in the a**.

However, the behaviour necessary might be achievable using scripting. One could configure the binding in a way that it constantly polls maybe sth like ten registers. Then use a script to write the variable’s address to the register and wait a while until you can be sure that the registers being polled have been updated. Then read from the corresponding item and copy the value wherever you want it to be.
This is probably failure-prone and zero fun to implement.

I’m glad it is useful to somebody else too.

I’m not really familiar with other implementations, but this one seemed not to work easily with the existing binding.

At some point of playing around with the existing Modbus binding I just gave up and decided to rather do it from scratch… Maybe there is a way to utilise what’s there, but to be honest, I’m not sure whatever the result might be is really maintainable. If I had to look at something like that 2 years from now I would most likely have no idea what I did back then. :wink:

1 Like

Hi Bernhard,

I am using KWL EC 450 PRO, connected to RaspberryPi via RS-485 and USB converter which works fine:
pi@raspberrypi:~ $ ls -l /dev/ttyUSB0 crw-rw---- 1 root dialout 188, 0 Aug 26 14:01 /dev/ttyUSB0

Connection is also fine as python script helios-usb-rs485.py returns (it’s not too hot at the moment):

bypass_disabled = 1 max_fanspeed = 8 inside_temp = 22 incoming_temp = 22 bypass_temp = 10 power_state = 1 exhaust_temp = 23 fanspeed = 1 min_fanspeed = 1 outside_temp = 23

Link to Tagol.de example: http://www.tagol.de/blog/anschluss-raspberry-pi-kwl-helios-pro---rs485

When files are copied I get all frames and items - looks great but no values (screenshot below).

Is it possible to configure your bindig (org.openhab.binding.helios_1.8.0.201601010916.jar) to work over RS-485?
Needs adding anything to openhab.cfg?

Kind regards,

Hi Marjan,

to be honest, I don’t think this will work with anything but TCP/IP. I merely implemented the binding because the standard openHAB binding didn’t seem to work for my device and as TCP/IP is supported this seemed to be the easiest way.

Sorry, but I’m afraid I can*t be of much help in this case…

Best regards,

1 Like

Thanks Bernhard,
I will try to find if there is any other working binding for Helios KWL and openHAB 1.8.3 - via RS-485 and USB .

For now I have found just this one (been made for OH 1.3.1) https://groups.google.com/forum/#!msg/openhab/R2uGyf0jNjE/wni9OzHkAogJ
which unfortunatelly is not working.
2016-08-27 16:31:14.013 [ERROR] [o.u.i.items.ItemUIRegistryImpl] - Cannot retrieve item kwlTempFromInside for widget org.openhab.model.sitemap.Text 2016-08-27 16:31:14.026 [ERROR] [o.u.i.items.ItemUIRegistryImpl] - Cannot retrieve item kwlTempToInside for widget org.openhab.model.sitemap.Text 2016-08-27 16:31:14.041 [ERROR] [o.u.i.items.ItemUIRegistryImpl] - Cannot retrieve item kwlTempToOutside for widget org.openhab.model.sitemap.Text

Maybe I should launch a new topic.

Kind regards,

Hi Bernhard,

I am new to Openhab and tried to install the binding on OH2.
I moved all the files from the release Folder to the appropriate Folder on my OH2 Installation. Unfortunately I don’t know where to configure the IP adress and password for the Helios KWL.
I guess this is necessary, currently I see the Switches in the Basic UI, but they have no function


Hi Kurt,

in OH2 the JAR file needs to go into the openhab/addons directory.
The configuration is done in a file openhab.cfg in the conf/services directory. It should contain the IP address of the KWL device, the rest of the parameters should work based on the default values.
e.g. helios:host=XXX.XXX.XXX.XXX
The password is only required for web access, not the Modbus connection.

Hope that helps…

Best regards,

Great it works! Thanks a lot!

Hi bern77,

i found your code for the helios binding and would try to update the code to the new openhab2 plugin structure. With this update you are able to use the new functionality of items and the plugin will be configurable over the paper-ui gui.

Currently i plan only to use it for my private usage, but maybe someone else is interested in this. The code is based on your code, so i just want to ask if it is ok to use your code, update it to the new plugin structure and publish it.

I will give you an update if a very first version of the new plugin is able to test.

Currently i do not have a running HELIOS system but this will be done in a few days hepefully. So i am able to do some initial tests maybe end of this month.


Hi Susi,

first of all, of course I don’t mind at all - please feel free to use my code in any way helpful for you.
However, I’ve also started some first steps for an OH2 migration of the binding.

To avoid redundant work, I’ve now pushed the status quo to the following repository:

Basically I’ve done the XML files and migrated the internal package. Also the constants class is basically done.
The next step would be the HeliosHandler class…

So far nothing is really tested and the actual binding implementation (marrying my HeliosCommunicator with the new OH structures) is missing.

Maybe it still makes sense to share efforts…
Hope that helps.



If Helios is based on modbus, perhaps it would make sense to use the upcoming/wip modbus transport in openhab2? I have been working with the modbus binding for openhab2 and one of the motivations for me was to separate protocol from the binding.

I would like to hear if you find the current transport layer API suitable for Helios as well . I think it should be possible to make changes easily also at this point.

I’m looking at the code of HeliosCommunicator and I think it should work with the transport layer… The rest of the code would remain quite much unchanged as far as I can tell – after all, there’s no way around building requests or parsing registers the helios way.

The benefit would be that bug fixes and improvements to the protocol would be shared. Ideally, you could focus only on the Helios specifics and how to lay it out as things in openhab2. All modbus variants supported by the transport layer would be supported with hopefully smaller effort. The transport bundle for example contains bug fixes to the modbus library (it’s a forked version), ensures that slaves are not spammed with requests (some slaves cannot handle this, not sure how it is with helios slaves. With Modbus RTU, having silent period between requests is critical. Anyways, this is controllable as well).

See this thread Modbus openHAB2 binding available for alpha testing

For a quick peek at the protocol api, see this https://github.com/ssalonen/openhab2-addons/blob/modbus-openhab2-native-binding/addons/io/org.openhab.io.transport.modbus/src/main/java/org/openhab/io/transport/modbus/ModbusManager.java

I’m happy to answer further questions


Hi Sami,

back when trying to integrate the Helios device with OH1 I did try the existing Modbus implementation. However, for some reasons I have to admit I don’t recall in detail at the moment, using the binding was not really feasible then. Maybe things have changed - I should look into this.
Of course it would be favourable to use existing code rather than implement something from scratch…


This has changed quite significantly, the modbus transport bundle that I am working on is low level API for modbus, and you would have full access to registers etc. You (as binding developer) can control whether to poll periodically, aperiodically or only when needed.

Actually a bit similar to you using the j2mod modbus library, currently.

I can provide some examples (based on your Helios code), if you like as well.

UPDATE: made this small example to illustrate the API: https://github.com/ssalonen/openhab2-addons/commit/5cc5c031b84fd79ddf7a90bfcb7228b5f54062b7