Helios Binding for Modbus TCP

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

Hi Sami,

thanks for the code example! It looks like it shouldn’t be too hard to switch to the Modbus binding instead of the external library I currently use.
At the moment I can’t really sacrifice much time to continue with the migration to OH2. But once I have an OH2 version up and running a switch to the Modbus binding would be a good next step.

Thanks again & best regards,

Great! If you like and you think it would make sense, I can extend the api to have synchronous methods as well, compared to current async methods with callbacks.

On the other hand, with async api, you would probably get the most performance as there are no blocking calls anywhere.

Let me know if you want to improve something in the api.

I experienced a strange behaviour of the binding.
Once i set the mode to manual and changed the fan speed, the KWL works in the correct manual mode, but the item is set back to automatic. Can anybody confirm this?

Hi, i forked your repo and did an update a few seconds ago. I only added some code to get the external libraties running on OH2. I only add some code to get the date from the helios but currently i am not able to get the value. I got an exception while setting the register to read.

I just want to get the current code running before change the Modbus libraries and so one, but currently it does not work and i currently have no idea. Maybe one of the developers who know something about the modbus connection is able to sind me a tip why the connectino currently fails.

This version is miles away from a version who is able to use for a normal user. But i just want to give you an update and send a alive message. I also have a runnig system meanwhile so i am able to test the code.

Here is my location:


I found the error i missed the setUnit command with the offset of 180. Now the communication is working on my local environment. I will now try to use the openHab internal lib to communicate with modbus. After get this running i will implement all the values which are able to load via modbus. After that i will do an commit and it will be free for public testing.


Hey, did you notice the discussion related to modbus transport bundle I have been working on. You can find the pull request here.

The transport bundle is made exactly for cases like this, to support development of protocols and devices that are based on modbus protocol. I am also working on plain modbus binding for openhab2 (using the transport bundle) but it’s quite clear that it’s not suitable for Helios . See above posts for some motivation and crude example of using the ModbusManager from modbus transport.

I am happy to help if you need support, I think it should be pretty similar to using low level modbus library like jamod, but with more safety features (correct handling of serial modbus, ensuring single connection at a time to a particular slave) and features (e.g. retry).


P.s. Not sure exact details of Helios but you might be able to reuse quite much stuff from the binding as well. With modbus binding there are two things, one for the endpoint (ip/port or serial and some connection settings), one for the data (instructions how to convert value to in modbus to number or value in openhab and vice versa)

Thank you very much. Now i am able to read all the values with the current implementation. I have seen pull request, next step will be change the code in that way. Now i have a running impmenentation and now it will be easier to find an error.


1 Like


I have been thinking how the Helios use case would look like with the API in reality.

Helios has some specialties that might need some work on the binding side, especially the fact that one “Helios transaction” consists of many modbus requests (e.g. write followed by read). Say you have two transactions, both consisting of write followed by read: write1-read1 & write2-read2. We probably want to ensure the nice order (write1 -> read1 -> write2 -> read2) instead of mixed order (write1 -> write2 -> read1 -> read2). The safest in this case would be to “synchronize transactions” on the binding side.

In the below example (implemented as unit test), Striped from Guava library is used to “lock” the endpoint for single transaction at once. Note that the ModbusSlaveEndpoint interface provided by the modbus transport guarantees that equals and hashing is implemented correctly as required by Striped.

In case you want to abort ongoing requests, you can fire off a thread and interrupt it (see below how interruption has been handled).

I have been experimenting with CompletableFuture as well but I think it might be overengineering and the below code is actually pretty readable.

import com.google.common.util.concurrent.Striped;

    // locks for "Helios transactions"
    Striped<Lock> locks = Striped.lazyWeakLock(5);

    public void test() throws InterruptedException {
        Manager modbusManager = new Manager();
        ModbusTCPSlaveEndpoint endpoint = new ModbusTCPSlaveEndpoint("localhost", 55502);
        Lock endpointLock = locks.get(endpoint);
        try {
            // submit first
                final AtomicBoolean success = new AtomicBoolean();
                final CountDownLatch completed = new CountDownLatch(1);
                WriteTask write = new WriteTaskImpl(endpoint,
                        new ModbusWriteRegisterRequestBlueprintImpl(0, 0, new ModbusRegisterArrayImpl(2), true, 15),
                        new ModbusWriteCallback() {

                            public void onWriteResponse(ModbusWriteRequestBlueprint request, ModbusResponse response) {

                            public void onError(ModbusWriteRequestBlueprint request, Exception error) {
                ScheduledFuture<?> writeFuture = modbusManager.submitOneTimeWrite(write);
                try {
                } catch (InterruptedException e) {
                    // TODO Auto-generated catch block
                    throw e;

                if (!Boolean.TRUE.equals(success)) {
                    // failure, abort?
                    // TODO: log
            // submit second
                final AtomicBoolean success = new AtomicBoolean();
                final CountDownLatch completed = new CountDownLatch(1);
                // Proceed with next query
        } finally {

Do you think something like this would work for you?

Btw, please note that helios-based-on-modbus2-transport is already obsolete. The latest Modbus binding and transport code can be found from modbus-openhab2-native-binding branch. I suggest you build Helios binding on top of that branch, using the transport bundle. Prepare to rebase your changes on top of my changes if necessary.

Please note that the new transport contains the implementations for requests, previously my example included implementation for WriteTask. Check all the public implementations and interfaces from source code: java/org/openhab/io/transport/modbus.

Finally, should you post a “WIP” PR (see here for motivation) to Github?


I wanted to thank you for your efforts. - I have an Helios KWL EC 200 Pro with an RS485 interface, how do I find out whether it is also the modbus you are mentioning? It would be great to have this integrated into my virgin openhab installation.

If it helps I can offer some testing…

@bern77 and @ssalonen what is the status with your work? Is the modbus transport stable and usable? Is there some progress about the helios binding on top of that?

Hi @ramack,

sorry for not getting back to you after the last post. The RS485 interface is a different physical interface than the Modbus/TCP interface used in the binding discussed here. While the protocol implementation might be reusable, the current implementation (at least mine) wouldn’t support RS385 as the transportation layer I’m afraid.

But your KWL containing “EC” in the name should suggest there is the Modbus/TCP option available… I think “EC” stands for Easy Control which should be the web interface to control the KWL. At least in my case this means that the Modbus protocol is also available via the TCP connection… in this case I think the binding implementations should work.


I think the transport is stable in the sense that there have been many positive experiences from the community.

I think the code can be considered stable, no large changes recently…

The pull request is still pending merge, waiting time for the maintainers to review the code. No ETA on that.

When it comes to Helios, my recent post shows one way for the implementation, and suggestions for going forward. However, that’s all from my side, not planning to develop anything for Helios specifically. Naturally if changes are needed from modbus transport, I am very willing to help!