Openhab-addons: [EnOcean] Implement EnOcean binding for OH2

[VanHogan]

Enhancement issue to implement the EnOcean binding for OH2.

[VanHogan]

Implementation will be done with the EnJ-Lib which is developed by the folks over at The Dog Gateway.

Snip from thier docu:
The library currently supports a subset of profiles defined in the EEP2.6 specifications but a progressive increase of supported profiles is envisioned. Supported profiles include:

• all A5-02-XX profiles (Temperature Sensors)
• A5-07-01 (Occupancy Sensor)
• all D5-00-XX profiles (Single Contact Switch)
• D2-01-08 (Metering Plug)
• D2-01-06 (Metering Plug) - thanks to @rdruilhe
• F6-02-01 and F6-02-02 (Rocker Switches)

[xxorde]

Any news here?

[winnall]

Kai, what does the "help wanted" label mean in this context?

[kaikreuzer]

It means that we are looking for a volunteer to do this implementation as mentioned here.

[dominikkv]

Hi, just found another enocean library, based on node.js: https://github.com/node-enocean/node-enocean

[kungfoolfighting]

Hello everyone!
Quick update on my work:
I have added system channels and profiles that will be used by the EnOcean plugin.
I have implemented support for rocker switch items.

What I have done in the last few weeks, whenever I had the time to work on it, was to contribute code to the enj library so that it would support more actors. Currently it really only supports control of power meter switch actors.

I must say I am a bit disappointed by the number of supported devices by this library, but now I have chosen to simply stay with it and implement any lacking profiles into the library myself.

The problem I am facing right now is, that I can't seem to get direct control of my own device to work.
I own an Eltako FUD61NPN. The sticker on it says that it was produced in week 25 of 2009, I think.
Perhaps this means that it does not support the A5-38-08 profile that I have implemented in the enj library now. At least I am unable to teach-in my PC into the actor.
Now I am a bit undecided on how to proceed.
The wall rocker switches work and for anything else I don't seem to have the hardware.
Any input for me?

[xxorde]

Hi @kungfoolfighting I do not know if you are interested in adding support for hardware you do not own yourself and do not plan to use in the future.

I have a little self contained laboratory setup of the following components, with some connected switches and lights.

• FTS14KS
• FTS14EM
• FGW14-USB
• FSR14-4x

I could grant you access if you are really interested. But do not expect to much development help from me. Java is not my domain and I am building a house at the moment ;)

[kungfoolfighting]

@xxorde
In principle I don't mind getting my hands dirty with hardware I don't plan on using myself, but I am not sure how that would work.
I can for example not start teach-ins on your hardware. Also the stuff you have seems pretty uncommon.
I wouldn't even know how to start supporting gateways and the like.

[kungfoolfighting]

@xxorde
I have spent some time looking at the devices you are looking to use.
I am not sure that it would even make sense to develop anything specifically for these devices.
As far as I can tell you have one device that basically acts just like the USB gateway but via a different protocol. I am currently not looking to support another gateway other than the USB300, since that is what the library that I am using supports, It seems like a major change in the library would be necessary unless you can use the gateway via the serial port just like the USB300 and with the same protocol.

Then you have one device that seems to be able to convert non-enocean device signals (like motion detectors etc) into EnOcean wireless telegrams.
This sort of device does not need to be explicitly supported, as supporting the telegrams it sends (like rocker switch telegrams or motion sensor telegrams) would already be enough to support all telegrams that this device sends. In effect you would be adding the individual EnOcean devices that this FTS14EM "emulates".
The one device that I find interesting is the FSR14-4x as it is an actual actor that could be controlled by sending telegrams from any EnOcean gateway (like the USB300).
For now, you can check which profiles are supported by the enj library and if your device(s) support any of those profiles, I could have a try at implementing that.
For all other non-supported profiles I think the library developers would be the better people to talk to about supporting your devices.
Sorry to be of so little help.

[xxorde]

@kungfoolfighting thx for your answer.
The FTS14KS is the power supply and did the initial address distribution (you could do that by hand) and I configured it to pull states periodic. It can although be used for other stuff but is not so important for me.

The FGW14-USB acts (almost) like an USB300, it uses the same chip inside I guess.
In FHEM I can use it as one and the other components than appear as std. EnOcean devices.
There is one magic flag that needs to be set in FHEM ("comType RS485").
In openHAB it didn't worked out of the box and I did not had the time to investigate why.
A good start should be to check what the flag in FHEM does and try to get the functionality to openHAB.

My impression was that all of the wired devices are using the EnOcean protocol and that just the underlying physical layer is different.

For all other non-supported profiles I think the library developers would be the better people to talk to about supporting your devices. Sorry to be of so little help.

You don't need to be sorry. I was just hoping some else working on Eltako devices would solve my problem "drive by" as well.

github.com/dog-gateway/enj-library is the next place to go. But I will not go there in the next weeks, I am still busy with my building project and I am waiting for my windows at the moment ;)
The good thing with the Eltako wired devices is that you can hard code the basic actions and there needs to be no computer or other device alive and working other than sensor + actor + power supply.
So I can set everything up and implement the high level automation later, I just hope I do not have to do it over FHEM as another layer of indirection.

[fruggy83]

Hello everybody. I also developed an enocean binding and want to share it with you, too. Main features of my bindings are

• No dependency to any third party lib. Enocean transceiver fully implemented in binding
• Binding can also receive messages to update state of items (rollershutters, switches, dimmers etc.)
• Automatic discover of things (rocker switches, UTE devices, response to teach in queries) and sending teach in queries
• Developed on USB300 and running on a raspi with enoceanpi
• (bidirectional) support for following devices: Eltako FSB14, FSR14, FUD14, NodOn smart plug, Permundo PC234 (smart plug with metering), Thermokon SR04 (room operating panel), Hoppe window handle
• Following EEPs implemented: A5-10, A5-38 (dimming and switching), A5-37, D2-01, D5-00, F6-02, F6-10
• Unknown EEPs can be used with transformation service (for example simple mapping), not well tested

Next steps:

• Implementing profiles for rocker switches, currently they just emit events
• Support and test with other devices
• EEPs, EEPs, EEPs

My questions are:

• Who wants to support me in testing my binding
• How can/should I share my binding with you (fork openhab2-addons and push into a new branch or use an independent repo)

[kaikreuzer]

I also developed an enocean binding

@fruggy83 Are you aware of https://github.com/openhab/openhab2-addons/pull/2838?
I general, the community tries to collaborate on a single implementation and make that perfect and not have multiple ones developed in parallel - especially if it is such a complex one as EnOcean.

[fruggy83]

@kaikreuzer Sorry for that. Indeed I was not aware of #2838. I started my work on this binding in Feb 17 and did not checked the pull requests in a regular manner. My fault.

[kaikreuzer]

Ok, no worries, it is good to know that you didn't deliberately ignore it :-)

So my question would be: How shall we proceed? Do you think your binding is already much ahead of #2838? Or could you migrate your additional device support into #2838?

[fruggy83]

If I did not missed something you can only receive rocker switch messages with #2838 (handleCommand of EnOceanRockerSwitchHandler is empty). So I would say that my binding is quite ahead of the other. Furthermore the other binding depends on the EEPs implemented in the enj lib. I am not sure if it is possible to get a raw stream of the enocean messages from the enj lib to implement your own EEPs. So I am unsure if I can migrate my work into the other binding.
However you all already invested quite some time into the other binding, so I think we should go further with the other binding and stay with it.

[kaikreuzer]

Well, you also probably invested a lot of time in your binding and it would be painful to just discard this. I really wonder, how we could better avoid such situations in future...

Wrt #2838, yes, as far as I know, it started with support for Rockers only - but that is mainly due to the fact that we first wanted to evaluate how the recently introduced ESH profiles can be best used for such devices. The EnJ library also supports other EnJ, so adding support for further devices shouldn't be too hard.

Although I am often not a big fan of integrating 3rd party libraries, there were 2 reasons why I thought that building on top of EnJ is a good idea:

1. It is an active project and thus we can benefit from the work of others here and collaborate with them on a common EnOcean Java library.
2. EEPs are a bit tricky wrt intellectual property: You require the EnOcean specification for implementing those, but the EnOcean Alliance might not allow you to actually use this specification for publishing source code under an Open Source license as the EPL. When merely using EnJ as a binary in our binding, these legal aspects are something the EnJ project has to deal with, but not us.

[fruggy83]

Well, my time is not discarded. I started this project to get more into JAVA and drive my enocean home. Both goals are fully reached. However to give something back to the openhab community I should try to migrate my EEP implementations to the EnJ lib. So you can still use my work through #2838. Thanks a lot for your explanations and all your work done for the openhab project.

[kaikreuzer]

Sounds good! Thanks for your work and welcome to the openHAB community 😄

[fruggy83]

Is it ok for you if I present my binding in the openHAB community as an intermediate solution as long as the official binding is not finished yet? I would clarify that I am not a member of or related to the openHAB staff for legal concerns.

[kungfoolfighting]

@fruggy83 : I am the guy who is working on the other binding.
I am sad to see that I didn't know about your project when I started working on this, I would have loved to collaborate with you.
I am also excited to see that you have already implemented a lot of stuff that I have not yet.
TBH I am a bit frustrated right now, because I would really like to continue working on the binding but it is difficult to do so without the proper hardware. It seems that the hardware I have is party so old, that It is incompatible with what I want to do.
I have already written some contributing stuff to the enj library and it is not difficult at all to implement more profiles than what is already there.
I think using a library for communicating with the EnOcean hardware just also makes sense from an architectural standpoint.

I would love to see if we can't create one unified great binding. In order to do that I would love to look at your code and maybe have an in-depth talk with you.
Are you available to chat anytime soon?

[fruggy83]

@kungfoolfighting Nice to hear from you. There is no reason to be sad, you could not know my project because I didn't publicly announced it when I started my work. I just wanted to get more into java and didn't thought to make it public.

If had a short looked at the EnJ Lib. Maybe it is not your hardware but the lib. If I understand it correctly, I don't think this lib is really prepared to send messages to devices. When you look at EnJConnection.sendRadioCommand, you will see that each message is send with a hard coded senderId 0x00ffffff. I think the whole concept of sending devices is missing in this lib. Furthermore I cannot see a way to send a teach in message to an enocean device to controll it. So this lib is ok for enocean sensors but not for actuators. Maybe this is the reason your enocean devices do not work with this lib. What sort of devices do you own?

I totally agree with you, that using a library for communication with enocean devices makes sense from an architectural standpoint. However I could find an active lib which fullfils all my needs (receiving, sending, all teach in variants, config of gateway (enable repeater for exp) etc.) It was a lot easier for me to not encapsulate all the enocean stuff in an external lib. If you look at my code, you will see that most of the logic is handled by the EEPs. My ThingHandlers just hand over the item commands to the EEP and let them do all the magic :) I know this could have been done differently but I found it very clever to handle different devices of the same type but with different EEPs this way (dynamic channel creation).

Just click on my name to look at my code. I have only one repo - openocean. Documentation is not very well. Fell free to ask me what you want. You find me at skype (same nick as on github), too.

[fruggy83]

@kungfoolfighting: By the way your FUD61NPN should work out of the box with my binding (found your pull req for the EnJ lib). My FUD14 dimmer sends and receives the same messages.

@kaikreuzer: You can download a document from the Eltako website which describes the contents of their enocean telegrams in detail. Is it allowed to use this document for implementing a binding?

[kaikreuzer]

Hi @fruggy83 & @kungfoolfighting, it is good to have you all in the loop here - I think we should really try to figure out the best way forward together.

If I understand it correctly, I don't think this lib is really prepared to send messages to devices. [...] I think the whole concept of sending devices is missing in this lib.

If this isn't considered in the architecture of EnJ, this would indeed be major issue for us. Maybe it is worth to enter an issue and ask about that at EnJ?

However I could [not] find an active lib which fullfils all my needs (receiving, sending, all teach in variants, config of gateway (enable repeater for exp) etc.)

Right, but all of this also sounds like a lot of effort for which you need a lot of time and expertise - I just had a short glance at your code, you at least seem to have the expertise ;-) How many of your own requirements would you say you have already implemented?
I agree that also has benefits when you not try to keep the protocol code fully independent from ESH/openHAB code - it can make the binding indeed better readable and maintainable. I'd therefore definitely not veto against that approach.
What I like is that you have also already covered features like device discovery and similar, so from the functional completeness, your binding already seems to be more advanced than #2838 (not meaning to play down your work, though, @kungfoolfighting!).

Is it allowed to use this document for implementing a binding?

IANAL, but at least this one does not have any warnings or disclaimers on it, so that's indeed good.
If we all agree that the best way would be to deal with the implementation ourselves and not use EnJ, I'd be ok with that.

[kungfoolfighting]

@fruggy83 By now you have found my pull request and you can see that sending telegrams is absolutely possible with the architecture of the enj library, as I implemented exactly that.

I don't think that my hardware is compatible with your code, because the hardware revision is so old that it does not support the gateway protocol (at least that is what I think). Otherwise I think my code would already work.
The code that I wrote for the enj library also handles the teach-in telegrams.

So in principle the enj library should be fine, they have simply not done a lot of sending (they do have sending telegrams for switching power meters though.)

Do you think it might be feasible to add the additional device support you implemented to the enj library? That way you would be supporting an existing project and the architectural benefit of having a library layer would also be fulfilled.

My PR for the enj library demonstrates how implementing sending would work. Or do you see a general deficit in the library's architecture?

I will go and have a look at your code this weekend.

[fruggy83]

@kungfoolfighting I further analysed the EnJ-Lib and your pull req to this lib.

The EnOcean documentation clearly states that each device should have an unique (sender) Id. To generate such an Id, each gateway (for ex USB300) has a so called base Id. This base Id and the following 127 Ids are guaranteed to be unique. Because of that (and for security reasons) I thought (and hopped) that a gateway would not accept messages with other sender ids (ids which do not fall in its range of Ids). However this assumption is not true. Each gateway (or at least the USB300) can send messages with any sender id. So it is really easy to simulate rocker switch pushes of your neighbour (I hope you will not do evil things with this power ;).

So sending messages with this lib is possible. However as most of the enocean messages are broadcast messages (in particular EEP A5-38 or rocker switch messages (by nature)), they must contain an unique sender id. If all messages are send with the same sender id, you will not be able to control your devices individually, as they ignore the optional data part with the destination Id. ALL your EEP A5-38 devices will react on your message at the same time. That is the reason why I said

the whole concept of sending devices is missing in this lib

Switching power meters can be _individually_ controlled with the EnJ-lib because of using the D2-01 EEP. This EEP is a variable lenght telegram (VLD). For performance reasons these devices first evaluate the optional data part of each message. If this part contains their Id as the destination Id, they will further analyse the VLD part and evaluate the sender id. So only VLD actuators can be handled by this lib. 4BS/RPS actuators cannot be handled individually.

By the way, have a look at your A53808.switching func. I think you are missing a data byte. A switching message should look like this 0xA5 | 0x01 | 0x00 | 0x00 | 0x09 for switch on or 0xA5 | 0x01 | 0x00 | 0x00 | 0x08 for switch off.

[fruggy83]

Hi all,

any new thoughts on this topic?
@kungfoolfighting: Are you able to control you Enocean devices with openhab now? Thanks a lot for your work on the system profiles On/Off and dimmer (eclipse/smarthome#4541). I adapted my rocker switch implementation to these profiles and implemented also a Play/Pause profile, to control my sonos (Play/pause, volume up/down). Works really well.

@kaikreuzer
Maybe I found another solution to these IP problems. I implemented a GenericThing which provides channels for each item type. A transformation function (e.g. MAP) can be set for each of these channels to specify the Enocean <-> Openhab conversion. The binding takes care of receiving, sending, check sum calculation and so on and the user just has to provide a conversion function. For example a mapping file for an A5-38-08 switching EEP must look like (these hex numbers can be found in the Eltako docs e.g.)

 genericLightSwitch|70=OnOffType|ON
 genericLightSwitch|50=OnOffType|OFF
 genericLightSwitch|ON=01000009
 genericLightSwitch|OFF=01000008

Basic EEPs (or EEPs defined by Enocean) like rocker switches, temperature sensors and so on can be directly implemented in the binding, manufacturer specific EEPs can be used with this GenericThing approach.

[kaikreuzer]

@fruggy83 Using MAP transformations sounds like a terrible workaround to me...
As you had referenced the document from the Eltako website above, I don't really see the IP topic that critical anymore, so I'd prefer a clean approach for the implementation.

I have no strong opinion whether or not we should use EnJ, hence I'd rather leave such a decision to you and @kungfoolfighting, as you both have had a closer look into the details already.

[wborn]

There is a bounty on this issue in Bountysource.

[kaikreuzer]

@fruggy83 I see from the community thread and your repo at https://github.com/fruggy83/openocean that you are making great progress on EnOcean support - this is nice to see!

As there weren't many news over here, I wonder how we shall proceed? Imho it would be ideal to move towards official EnOcean support in openHAB - and as we didn't hear back from @kungfoolfighting, I'd assume that you should create a PR sooner or later that replaces https://github.com/openhab/openhab2-addons/pull/2838, wdyt?

[kungfoolfighting]

@kaikreuzer We have been in contact and talked about how to progress quite a while ago.
Since the OpenOcean binding he wrote is so far progressed and has so much thing support already it was a logical conclusion to continue with his project.
There was only the lingering question of IP-rights in regards to implementing into openHAB. What is the current status there?

[kaikreuzer]

Hi @kungfoolfighting, Thanks for your quick feedback and great to hear that you are still on board and came to an agreement with @fruggy83.

There was only the lingering question of IP-rights in regards to implementing into openHAB. What is the current status there?

As I stated in https://github.com/openhab/openhab2-addons/issues/2261#issuecomment-362671169:

Is it allowed to use this document for implementing a binding?

IANAL, but at least this one does not have any warnings or disclaimers on it, so that's indeed good.
If we all agree that the best way would be to deal with the implementation ourselves and not use EnJ, I'd be ok with that.

If those documents that @fruggy83 referred to are good enough as a basis for the implementation, I'd suggest that we close this PR here and let @fruggy83 create a new one from his branch. One wish though: I'd very much prefer if the binding could be renamed to simple "EnOcean" instead of "OpenOcean".

[fruggy83]

Hi @kaikreuzer, sorry for my late answer. In general I do not see a problem to go official.

If those documents that @fruggy83 referred to are good enough as a basis for the implementation

Currently all EEPs which are actively used by community members are based on the official Eltako documents or support answers from NodOn. For the other implemented EEPs I just used the scaling information from the enocean docs (for example Eltako describes A5-02-05 a temperature sensor for temperatures ranging from 0-40 degree, all other EEPs from this EEP family have other temperature scalings like 20-60 degree and so on). What do you think about these EEPs? Should I remove them before doing a PR to be on the safe side?

However before I create a PR I would like to solve some issues (esp. fruggy83/openocean#13 and fruggy83/openocean#16) together with @kungfoolfighting.

Best regards
Daniel

[kaikreuzer]

I just used the scaling information from the enocean docs

I'd claim that this isn't any "sophisticated intellectual depth", so this information should be safe to use and I'd suggest that you keep those EEPs.

However before I create a PR I would like to solve some issues (esp. fruggy83/openocean#13 and fruggy83/openocean#16) together with @kungfoolfighting.

Sure, absolutely no rush from my side, I just wanted to agree with you on the overall direction. Thanks!

[kaikreuzer]

@fruggy83 Any updates on this binding? Would really love to see this being merged some day!

[fruggy83]

Hi @kaikreuzer,

sorry for my late answer, I somehow missed your message in this thread. Overall progess is fine. As you know nrjavaserial made some problems but my solution works for me now. I used the chance to do some last breaking changes before doing the PR. I asked the current users of my binding to test these last changes. During these tests I am preparing the PR. If everything is going well, I will do the PR this weekend or next Monday. I hope this is not too late for 2.4.

[kaikreuzer]

Sounds great, thanks for the update! 👍

[fruggy83]

Hi @kaikreuzer,

I finally created the PR for the enocean binding. This PR is based on my last OpenOcean commit. I mainly refactored the name of the binding, added some more comments and polished some code blocks.

Best regards
Daniel

Sry for beeing late, I forgot the FC football match yesterday

[kaikreuzer]

Excellent, thanks! I hope to soon find time to review it!