This page is part of archived documentation for openHAB 4.1. Go to the current stable version

# ekey Binding

This binding connects to ekey (opens new window) converter UDP (CV-LAN) using the RARE/MULTI/HOME protocols.

# Supported Things

This binding only supports one thing type:

Thing Thing Type Description
cvlan Thing Represents a single ekey converter UDP

# Thing Configuration

The binding uses the following configuration parameters.

Parameter Description
ipAddress IPv4 address of the eKey udp converter. A static IP address is recommended.
port The port as configured during the UDP Converter configuration. e.g. 56000 (Binding default)
protocol Can be RARE, MULTI or HOME depending on what the system supports. Binding defaults to RARE
delimiter The delimiter is also defined on the ekey UDP converter - use the ekey configuration software to determine which delimiter is used or to change it. Binding default is _ (underscore)
natIp [Optional] IPv4 address of a received eKey udp packet. Can be different from the ipAddress when using NAT. (e.g. in Kubernetes)

# Channels

Channel ID Item Type Protocol Description Possible Values
action Number R/M/H This indicates whether access was granted (value=0) or denied (value=-1). 0,-1 (136 and 137 with RARE protocol
fingerId Number R/M/H This indicates the finger that was used by a person. 0-9,-1
fsName String M This returns the 4-character-long name that was specified on the controller for the specific terminals.
fsSerial Number R/M/H This returns the serial number for the specific terminal.
inputId Number M This indicates which of the four digital inputs was triggered. Value is number of Input. "-1" indicates that no input was triggered. 0-4,-1
keyId Number M This indicates which of the four keys was used. See ekey documentation on "keys". 0-4,-1
relayId Number R/H This indicates which relay has been switched. 0-3,-1
termId Number R This provides the serial number of the packet source. The source can be a fingerprint terminal or the controller (in case of digital inputs). The Serial number has a length of 13. When using RARE mode, only the trailing 8 digits can be returned.
userId Number R/M/H This indicates which user has been detected on the terminal. The value is the numerical order of the user as it was specified on the controller. 0-99,-1
userName String M This returns the ten-character-long name of the person that has been recognized on the terminal. The name that is returned must have been previously specified on the controller.
userStatus Number M This indicates the status of the user (-1=undefined, 1=enabled, 0= disabled) 0,1,-1

# Examples

example.things

Thing ekey:cvlan:de3b8db06e "Ekey Udp Converter" @ "Control Panel" [ ipAddress="xxx.xxx.xxx.xxx", port="56000", protocol="RARE", delimiter="_" ]

rare.items

Number Action "Last action [MAP(ekey_action.map):%d]"                          { channel="ekey:cvlan:de3b8db06e:action" }
Number FingerID "User used finger [MAP(ekey_finger.map):%d]"                   { channel="ekey:cvlan:de3b8db06e:fingerId" }
Number RelayID "Last relay that has been swiched [%d]"                         { channel="ekey:cvlan:de3b8db06e:relayId" }
Number Serialnumber "Serialnumber [%d]"                                        { channel="ekey:cvlan:de3b8db06e:fsSerial" }
Number TerminalID "Last used terminal [MAP(ekey_terminal.map):%d]"             { channel="ekey:cvlan:de3b8db06e:termId" }
Number UserID "Last user that accessed the house was [MAP(ekey_names.map):%d]" { channel="ekey:cvlan:de3b8db06e:userId" }

multi.items

Number Action "Last action [MAP(ekey_action.map):%s]"                          { channel="ekey:cvlan:de3b8db06e:action" }
Number FingerID "User used finger [MAP(ekey_finger.map):%s]"                   { channel="ekey:cvlan:de3b8db06e:fingerId" }
String FsName "Name of Scanner [%s]"                                           { channel="ekey:cvlan:de3b8db06e:fsName" }
Number FsSerial "Serialnumber [%d]"                                            { channel="ekey:cvlan:de3b8db06e:fsSerial" }
Number InputID "Last input that has been triggered [%d]"                       { channel="ekey:cvlan:de3b8db06e:inputId" }
Number KeyID  "Last key that has been used [%d]"                               { channel="ekey:cvlan:de3b8db06e:keyId" }
Number UserID "Last user that accessed the house was [%d]"                     { channel="ekey:cvlan:de3b8db06e:userId" }
String UserName "Name of Last user that accessed the house was: [%s]"          { channel="ekey:cvlan:de3b8db06e:userName" }
Number UserStatus "Last user that accessed the house was [MAP(ekey_status.map):%s]" { channel="ekey:cvlan:de3b8db06e:userStatus" }

home.items

Number Action "Last action [MAP(ekey_action.map):%d]"                          { channel="ekey:cvlan:de3b8db06e:action" }
Number FingerID "User used finger [MAP(ekey_finger.map):%d]"                   { channel="ekey:cvlan:de3b8db06e:fingerId" }
Number RelayID "Last relay that has been swiched [%d]"                         { channel="ekey:cvlan:de3b8db06e:relayId" }
Number Serialnumber "Serialnumber [%d]"                                        { channel="ekey:cvlan:de3b8db06e:fsSerial" }
Number UserID "Last user that accessed the house was [MAP(ekey_names.map):%d]" { channel="ekey:cvlan:de3b8db06e:userId" }

transform/ekey_finger.map [this works for HOME and MULTI protocols, for RARE it's individually defined]

1=leftlittle
2=leftring
3=leftmiddle
4=leftindex
5=leftthumb
6=rightthumb
7=rightindex
8=rightmiddle
9=rightring
0=rightlittle
R=RFID
-1=nofinger

transform/ekey_names.map [NO spaces allowed]

-1=Unspecified
1=JohnDoe
2=JaneDoe

transform/ekey_status.map

-1=undefined
1=enabled
0=disabled

transform/ekey_terminal.map

80156839130911=Front
80156839130914=Back

transform/ekey_multi_action.map

1=open
2=refuseunrecognizedfinger
3=refusetimeslotA
4=refusetimeslotB
5=refusedisabled
6=refuseOnlyalwaysusers
7=fingerscannernotconnectedtocontrolpanel
8=digitalinput
A=codepad1minutelock
B=codepad15minutelock

transform/ekey_rare_action.map

136=granted
137=rejected