openhab/openhab — pull request #778 by plschlgtwt (2014-01-22 16:45:32+00:00)
Title: Implemented a new binding for the eKey HOME and MULTI fingerprint authentication solution

Hi everyone!
I would like to share my work with you...
(I hope I am doing this right :D )

First some basic words about this binding:

*** What is eKey: ***
eKey is an austrian company that provides biometric access-control-solutions.
Their main focus is on fingerprint readers.
eKey provides the stand-alone solutions MULTI and HOME.
Both consist of one or more fingerprint reader and a controller.
The Controller is responsible for the enrollment, and the identification of the
various fingerprints. It also is able to switch relays according to the recognized
person. It may also be albe to recognize digital inputs that occur when a switch
is applied.
The MULTI and the HOME solution differ in their functionality - MULTI offers more

The fingerprint sensors and the controller communicate on a RS485 bus and since
it is a stand-alone system. Nothing else is mandatory for its operation.

*** How does this binding come into play: ***
eKey offers additionally a UDP converter that is connected serially into the bus.
This converter sends small packets about the actions that have been made in the
eKey system. So packets are sent when someone pulls his finger over the scanner
or if a digital input is done.

*** Usually the packet contains at least the following information: ***
userID - the index of the detected user that is stored on the controller
fingerID - the finger that the user had used
terminalID - the serial number of the fingerprint reader that was used
action - this tells whether the user was recognized successfully and access
was granted or access was rejected

Note that the MULTI offers more information than HOME such as inputID and a full
username.

*** What are "Modes"? ***
The Converter is capable of up to three different packet-types. I will call them
Modes.
First and default mode is RARE. This delivers a bytecoded packet with very little
information. But additionally to the 4 datafields that i announced before this
will provide also information about the relay that was triggerd on the controller
Anyway this is a bit cumbersome but there are more modes...

Besides the RARE mode there exist a HOME and a MULTI mode. Both are stringcoded
packets and therefore 'human readable' the datafields are separated by a certain
delimiter. Both are quite similar but MULTI offers much more information.

*** How to the converter whicht mode to use? ***
Well, eKey delivers a tiny windows-tool with that it is possible to configure
this converter:
You can set the IP Address of the converter, the Port that is used for sending
packets and the receiver IP Address.
And furthermore you can set the packet-type (mode) and the delimiter.
According to your hardware you may select RARE, HOME or MULTI if you have one

*** What does the binding do? ***
The binding now listens to a defined udp port and waits for packets from the
converter. If it receives one, it tries to parse it and informs all items that
are interested in a previously subscribed information-field.

To subscribe to an interesting field, an item has to define the following
binding configuration:
{ekey="interest"}
possible values for "interest" are:
ACTION|USERNAME|USERID|USERSTATUS|TERMINALID|TERMINALNAME|FINGERID|KEYID|
INPUTID|MODE

All of type Number but USERNAME, TERMINALID and TERMINALNAME are String

*** What is the goal of this: ***
Well usually the eKey controller is able to recognize a fingerprint and do
just one defined thing.
With this you have completely new options. For example you can let ekey unlock
the door and let openhab switch off the alarm-system or switch on a light...
You can define rules according to every single finger that a person may use
or refer to the terminals that were used... etc.

*** A few notes about myself: ***
My name is Paul Schlagitweit I am studying "mobile computing" on the
FH Hagenberg (University of applied sciences Hagenberg) in Austria.
I am doing this as part of my bachelor thesis. And it is the very
first time I actively contribute to an opensource project.

So I am very glad for any kind of feedback or criticism!
All the hardware that I used (eKey Multi + 2 Terminals + converter) for
implementing and testing, I loaned from eKey and I have to return it as
soon as this project is done (within the next month).

I hope that you can make use of this and I hope it fulfilles your needs.
If you have any question, you can contact me at plschlgtwt (at) gmail .com
cheers!