Ekey integration into openHAB3 (as ekey binding is deprecated and won't be available for OH3)

Hallo @hmerk ,
ich schätze sehr welche Arbeit die Community leistet. Deshalb bitte nicht falsch verstehen:
Gibt es eventuell schon ein Update zum Ekey Binding - dies hält mich aktuell leider davon ab auf OpenHAB 3 zu migrieren.

No worries, but first of all, this is an international community, so english please.

Unfortunately I did not find the time to start. Still have to get my cv lan to work.

But in the meantime, you could use the python script posted here, so no reason to not upgrade to openHAB 3.

Sorry @hmerk for writing in German
I will have a look in the meantime - thanks :+1:t2:

Hi all,
just to let you know, openHAB 3 ekey binding is nearly finished, testversion will be published in the next two weeks.
HOME and MULTI protocol have been tested against ekey docs demo UDP packets, RARE protocol might need some more work.
Would be great is someone could send me some raw RARE UDP packets with explanation (user, finger, etc…) so I could do some tests. (The test version will log the packets on info log level, just copy and paste and give some explanation…

EDIT : For everyone who does not want to wait, early test version can be found here:

1 Like

To whom it may concern :
I have created a Pull-Request at the openHAB-addons repo to get the binding into the distro.

Latest compiled version can still be found at

Readme :

I still need to document the mappings and create somme examples for the doku …

Thanks to @binderth for testing and feedback :+1:


For anybody reading this and planning to buy an ekey fingerprint solution.
Do yourself a favour and don‘t buy an ekey Arte fingerprint scanner. The Arte controller cannot send data via RS485 to any kind of CV Lan converter (Net or Home). Therefore a connection to openHAB or any other smarthome solution is not possible.

1 Like

Hello Hans-Jörg,
I tried your binding and it showed up for installation once I copied it into the folder “/usr/share/openhab/addons” and changing ownership to “openhab:openhab”.
Then I was able to add an ekey CV RS-485 as thing as described and also I was able to add items linked to the channels of the ekey CV RS-485.
The ekey CV RS-485 is set to multi mode, delimiter is set to “_”. So far, so good and a great work of yours :slight_smile:
When my finger print is scanned and regognized and my door opens due to this event, no one of the items I created and linked to the ekey CV RS-485’s channels is filled with data…
So my question:
Is there something I have not considered? Unfortunately I have to run openHAB 3 behind a NGINX-instance. Do I have to do some settings to that NGINX-instance? Maybe you have a preconfigured configuration file?
Regards from Germany


the NGINX shouldn’t do anything - unless it’s blocking UDP - or some kind of firewall or iptables does this… Are you sure, you have the right UDP ports configured both in the CV RS-485 and openHAB configuration?

Please enter the following on openHAB Karaf console

log:set TRACE org.openhab.binding.ekey

and post all ekey related log entries here.

As Thomas already wrote, please check the config.
Your CV-LAN converter has to be configured with your openHAB server IP as target.
In openHAB you need to enter your CV-LAN IP-Address and the same UDP port as configured in the CV-LAN. Additionally, check the LEDs on your CV-LAN. Does it show packets can be converted ?

Hi Hans-Jörg, hi Thomas,
thanks for immediate reply. I checked port and IP address settings of both (ekey thing and CV-LAN) more than twice. But I’ll do again today after returning home, as well as I’ll log the ekey binding activities and post the log file :slight_smile:

Regards from Germany and have a good start into rthe new week


Hi Hans-Jörg, hi Thomas,
I did as you suggested, did a

log:set TRACE org.openhab.binding.ekey

and checked my CV-LAN configuration:

  • The IP-address of the CV-LAN is the same I set in the ekey-thing’s IP-address configuration
  • The port the CV-LAN sends to is the same as in the ekey-thing’s receiver port configuration
  • The openHAB’s IP-address was set in the CV-LAN
  • The delimiter is “_” in both the ekey-things delimiter configuration and the CV-LAN

The CV-LAN is connected via an 100 MBit/s connection and shows network activity. And when scanning a finger with success, the corresponding LED on the ekey control unit (“ekey home SE REG 1”) lights up.
But there are no entries in the logs except the following:

21:24:38.427 [DEBUG] [ding.ekey.internal.EkeyHandlerFactory] - bundle org.openhab.binding.ekey: (281)[org.openhab.binding.ekey.internal.EkeyHandlerFactory(332)] : Querying state active
21:24:38.428 [DEBUG] [l.EkeyDynamicStateDescriptionProvider] - bundle org.openhab.binding.ekey: (281)[org.openhab.binding.ekey.internal.EkeyDynamicStateDescriptionProvider(331)] : Querying state active

And openHAB 3 is running behind nginx and I don’t know how to find out if it blocks UDP traffic…

Hmmm. You did set up the nginx, didn’t you?

Try listening on the OH3 pi:

sudo nc -ul 2222

Use your UDP port for 2222. This should listen to UDP packets send to the port. If there’s nothing, you have to dig a bit deeper in your nginx or iptables or network configuration.

A quick google search showed that nginx does block udp traffic if not routed by a rule.
Is I am not using nginx, you need to check with an advanced nginx user.

Other option would be to temporary disable nginx and see in the loggs if something changes.

Hi Thomas, hi Hans-Jörg,
I do not want to use nginx but I think I was forced to because it seems to be mandatory to use the openHAB app on my smartphone to control openHAB from outside via OpenVPN tunnel.
Or do you have made other experiences concerning the smartphone app?

sorry Ansgar, but never heard of such.
I am still using the IOS app in combination with BasiUI sitmaps through mypenHAB, which is working excellent, even for notifications.
On the other hand, I use a VPN tunnel into my network setup within my FritzBox, so no need to secure anything within my local network.

1 Like

nope. you don’t need nginx to use the smartphone app.

  1. you can use openHAB Cloud for use without VPN
  2. you can just VPN in your network and use the App with “local” server settings.

long version:
ngingx as a reverse proxy is

  1. mostly used as a more secure way to expose your JAVA Application Server, which normally aren’t supposed to be directly exposed to a network - especially the internet. Thus, an reverse proxy only exposes “his” services and routes them to the AppServer and back
  2. also used as load balancer, if you have a cluster of JAVA AppServers running in High Availabilty.

As I think, you’re neither running openHAB in HA, nor do you have a local network full of possible attackers, you’re fine in using openHAB as is.

1 Like

Hi Thomas,
thanks for the nginx information. As I read from your words I really don’t have a reason to run openHAB 3 behind a nginx server and I deinstalled it.
But it changed nothing concerning the CV-LAN device:
The items doesn’t change their states and still remain in NULL, no matter how ofen I scan my fingers successfully :frowning:
And although I set the log of the ekey binding to TRACE there are no entries in the log…

Please post a screenshot of your CV-LAN config and the thing config in openHAB.
You did not clearly answer my question on the LED‘s:
Do you see a green LED on the side of the CV-LAN when a finger slides over the scanner ?
If not but it stays blinking red, the packets from the scanner can not be translated by the CV-LAN und thus will not be sent to openHAB.

Hi Hans-Jörg,
the CV-LAN blinks slowly in green color indicating normal operation (see manual page “de | 7”). So I think the data packages are sent to openHAB…
And here are the requested screenshots (including an item list of items linked to the CV-LAN’s channels):

OK, that’s fine. Now please enter the following command in a terminal on your openHAB Server :

sudo lsof -i -P -n |grep 51000

it should show the following output :

java      42209           openhab   113u  IPv6 1704455      0t0  UDP *:51000

Just ignore PID and TYPE etc.

Now try to send a test packet from your terminal to openhab:

openhab@openNUC:~$ echo "1_0003_-----JOSEF_1_7_2_80131004120001_-GAR_1_-" | socat - udp:

You should see the following entries in your log :

2021-09-01 11:43:28.713 [INFO ] [y.internal.api.EkeyUdpPacketReceiver] - Packet received -  [packet tremoved]
2021-09-01 11:43:28.714 [WARN ] [y.internal.api.EkeyUdpPacketReceiver] - Packet received from unknown source- 
2021-09-01 11:43:28.715 [TRACE] [y.internal.api.EkeyUdpPacketReceiver] - Listen for incoming packet

The unknown source is correct, as you are sending from a different IP…