diff --git a/bundles/binding/org.openhab.binding.ekey/README.md b/bundles/binding/org.openhab.binding.ekey/README.md index 9c40fb18076..349435f0a26 100644 --- a/bundles/binding/org.openhab.binding.ekey/README.md +++ b/bundles/binding/org.openhab.binding.ekey/README.md @@ -1,73 +1,63 @@ # ekey Binding -[ekey](http://ekey.net/) is an Austrian company that provides biometric access-control solutions, more precisely fingerprint readers and corresponding controllers. This binding extends the functionality of the products [ekey home](http://ekey.net/ekey-home-en) and [ekey multi](http://ekey.net/ekey-multi-en). +[ekey](http://ekey.net/) is an Austrian company that provides biometric +access-control solutions, more precisely fingerprint readers and +corresponding controllers. This binding extends the functionality of the +products [ekey home](http://ekey.net/ekey-home-en) and +[ekey multi](http://ekey.net/ekey-multi-en). -To use this binding, one needs to have either the _home_ or the _multi_ solution of ekey. Note that the _multi_ version provides much more functionality than the _home_ version. +## Setup -Additionally the _ekey UDP converter_ is needed. This module provides an interface by converting the internal RS485 signals to Ethernet. Connecting this to the local network enables ekey to communicate to the ekey binding. +To use this binding, one needs to have either the _home_ or the _multi_ +solution of ekey. Note that the _multi_ version provides much more +functionality than the _home_ version. + +Additionally the _ekey UDP converter_ is needed. This module provides an +interface by converting the internal RS485 signals to Ethernet. Connecting +this to the local network enables ekey to communicate to the ekey binding. ![example](http://ekey.net/media/W/720/bilder/automatisierung/example_E.jpg) -The ekey binding translates information that comes from the ekey controller and makes it usable to openHAB. Usually ekey sends packets with information on each user input. This might be every time a person pulls their finger over the terminal or if a digital input occurs. +The ekey binding translates information that comes from the ekey controller and +makes it usable to openHAB. Usually ekey sends packets with information on +each user input. This might be every time a person pulls their finger over the +terminal or if a digital input occurs. The information consists at least of these types: -**userID** - the index of the detected user that is stored on the controller - -**fingerID** - the finger that the person 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 denied - -The amount of information depends on whether _ekey home_ or _ekey multi_ is used and which protocol is used by the converter. But the previously mentioned 4 are supported in any case. - -The converter knows up to three different protocols. The _RARE_ protocol that is enabled by default, the _HOME_ protocol which is very similar to the _RARE_ and finally the _MULTI_ protocol which is fairly powerful compared to the other ones. The binding uses the term "mode" instead of "protocol". - -The type of protocol that is used by the converter can be changed with a small tool (unfortunately Windows only). This tool is called _ConfigConverterUDP_ and can be downloaded from the [ekey website](http://www.ekey.net/downloads-en/cat/Software). - -### Available Types of Information - -**Action** This indicates whether access was granted (Value: 0) or denied (Value: -1). According to the ekey documentation there are six more values possible as you can see in the .map file below. (Item Type Number, Modes: R/H/M) +* **userID** - the index of the detected user that is stored on the controller +* **fingerID** - the finger that the person 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 denied -**Finger ID** This indicates the finger that was used by a person. The value consists of 2 digits. The first one specifies the hand (left hand: 1, right hand: 2) and the second digit specifies the finger from left to right. To get a feeling see the .map file below. (Item Type Number, Modes: R/H/M) +The amount of information depends on whether _ekey home_ or _ekey multi_ is +used and which protocol is used by the converter. But the previously mentioned +4 are supported in any case. -**Input ID** This indicates which of the four digital inputs was triggered. Value is number of Input. "-1" tells that no input was triggered. (Item Type Number, Modes: M) +The converter knows up to three different protocols. The _RARE_ protocol that +is enabled by default, the _HOME_ protocol which is very similar to the _RARE_, +and finally the _MULTI_ protocol which is fairly powerful compared to the other +ones. The binding uses the term "mode" instead of "protocol". -**Key ID** This indicates which of the four keys was used. See ekey documentation on "keys". (Item Type Number, Modes: M) +The type of protocol that is used by the converter can be changed with a small +tool which is only available for Windows systems. This tool is called +_ConfigConverterUDP_ and can be downloaded from the [ekey website](https://www.ekey.net/en/media_center/). -**Mode** This simply returns the mode that was used 1=RARE, 2=MULTI, 3=HOME (Item Type Number, Modes: R/H/M) - -**Relay ID** This indicates which relay has been switched. (Item Type Number, Modes: R/H) - -**Terminal ID** 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 tailing 8 digits can be returned.(Item Type Number, Modes: R/H/M) - -**Terminal name** This returns the 4 characters long name that was specified on the controller for the specific terminals. (Item Type String, Modes: M) - -**User ID** 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. Mapping the numbers to names make sense. (Item Type Number, Modes: R/H/M) - -**Username** This returns the ten characters long name of the person that has been recognized on the terminal. The name that is returned must have been specified on the controller before. (Item Type String, Modes: M) - -**User status** This indicates the status of the user: -1 = undefined, 1 = enabled, 0 = disabled (Item Number, Modes: M) - -As you can see, in many cases it makes sense to map the number values to some more meaningful strings. -See the mapping examples on the bottom. ## Binding Configuration This binding can be configured in the file `services/ekey.cfg`. -| Property | Default | Required | Description | -|----------|---------|:--------:|-------------| -| ip | | No | IPv4 address of the eKey udp converter. A static IP address is recommended. | -| port | | Yes | port as you configured during the UDP Converter configuration. For example, 51000 | -| mode | RARE | No | can be RARE, MULTI or HOME depending on what your system supports | -| delimiter | ` ` (space) | No | 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. Another option is `_` (underscore) | +| Property | Default | Required | Description | +|-----------|---------|:--------:|-------------| +| ip | | No | IPv4 address of the eKey udp converter. A static IP address is recommended. | +| port | | Yes | The port as configured during the UDP Converter configuration. e.g. 51000 | +| mode | RARE | No | Can be RARE, MULTI or HOME depending on what the system supports | +| delimiter | ` ` (space) | No | 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. Another option is `_` (underscore) | -## Items Configuration - -This is quite simple. It depends on the type of information someone is interested in. +## Item Configuration The syntax is: @@ -75,23 +65,74 @@ The syntax is: ekey="" ``` -Where `` is one of the following: +where `` is one of the following: * action -* username -* userid -* userstatus -* terminalid -* terminalname * fingerid -* keyid * inputid +* keyid * mode -* relay +* relayid +* terminalid +* terminalname +* userid +* username +* userstatus -## Full Example -Here is an example that demonstrates a simple rule that feeds the openHAB TTS-engine and welcomes the user when he or she enters the house. +### interestname Definitions + +* **Action** + This indicates whether access was granted (value=0) or denied (value=-1). + According to the ekey documentation there are six more values possible as you + can see in the .map file below. (Item Type: Number, Modes: R/H/M) +* **Finger ID** + This indicates the finger that was used by a person. The value consists of 2 + digits. The first one specifies the hand (left hand=1, right hand=2) and + the second digit specifies the finger from left to right. (see the .map file + below). (Item Type: Number, Modes: R/H/M) +* **Input ID** + This indicates which of the four digital inputs was triggered. Value is + number of Input. "-1" indicates that no input was triggered. (Item Type: + Number, Modes: M) +* **Key ID** + This indicates which of the four keys was used. See ekey documentation on + "keys". (Item Type: Number, Modes: M) +* **Mode** + This simply returns the mode that was used (1=RARE, 2=MULTI, 3=HOME) (Item + Type: Number, Modes: R/H/M) +* **Relay ID** + This indicates which relay has been switched. (Item Type: Number, Modes: R/H) +* **Terminal ID** + 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. (Item Type: Number, Modes: R/H/M) +* **Terminal name** + This returns the 4-character-long name that was specified on the controller + for the specific terminals. (Item Type: String, Modes: M) +* **User ID** + 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. (Item + Type: Number, Modes: R/H/M) +* **Username** + 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. (Item Type String, Modes: M) +* **User status** + This indicates the status of the user (-1=undefined, 1=enabled, 0= disabled) + (Item Type: Number, Modes: M) + +In many cases it makes sense to map the number values to more meaningful +strings. See the mapping examples below. + + +## Examples + +### Full Example + +Here is an example that demonstrates a simple rule that feeds the openHAB +TTS-engine and welcomes the user when he or she enters the house. items/ekey.items @@ -105,7 +146,7 @@ Number Action "Last action [MAP(ekey_action.map):%d]" { rules/ekey.rules -``` +```java rule Welcome when Item Action received update @@ -124,7 +165,7 @@ end transform/ekey_finger.map -``` +```javascript 11=leftlittle 12=leftring 13=leftmiddle @@ -140,7 +181,8 @@ transform/ekey_finger.map transform/ekey_names.map -``` + +```javascript -1=Unspecified 1=John Doe 2=Jane Doe @@ -148,14 +190,14 @@ transform/ekey_names.map transform/ekey_terminal.map -``` +```javascript 80156839130911=frontdoor 80156839130914=backdoor ``` transform/ekey_action.map -``` +```javascript 0=granted -1=rejected 1=timeoutA @@ -166,7 +208,6 @@ transform/ekey_action.map 6=digitalinput ``` -## Further Examples - -* eKey binding demo config (may be specific to openHAB 1.x)(http://pastebin.com/fjXkFbiq) +### Further Examples +* [ekey binding demo config](http://pastebin.com/fjXkFbiq) (may be specific to openHAB 1.x) diff --git a/bundles/binding/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EKeyGenericBindingProvider.java b/bundles/binding/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EKeyGenericBindingProvider.java index 13d5688b9ca..30c5de6cf60 100644 --- a/bundles/binding/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EKeyGenericBindingProvider.java +++ b/bundles/binding/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EKeyGenericBindingProvider.java @@ -1,97 +1,97 @@ -/** - * Copyright (c) 2010-2016 by the respective copyright holders. - * - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * which accompanies this distribution, and is available at - * http://www.eclipse.org/legal/epl-v10.html - */ -package org.openhab.binding.ekey.internal; - -import org.openhab.binding.ekey.EKeyBindingProvider; -import org.openhab.binding.ekey.internal.EKeyBindingConfig.InterestType; -import org.openhab.core.items.Item; -import org.openhab.core.library.items.NumberItem; -import org.openhab.core.library.items.StringItem; -import org.openhab.model.item.binding.AbstractGenericBindingProvider; -import org.openhab.model.item.binding.BindingConfigParseException; - -/** - * This class is responsible for parsing the binding configuration. - * Every Item can be interested in ONE information that is received with the eKey UDP-packet - * Each time a new packet arrives, all items will be informed with the latest values - * - * bindingconf: ekey= - * "ACTION|USERNAME|USERID|USERSTATUS|TERMINALID|TERMINALNAME|FINGERID|KEYID|INPUTID|MODE" - * - * @author Paul Schlagitweit - * @since 1.5.0 - */ -public class EKeyGenericBindingProvider extends AbstractGenericBindingProvider implements EKeyBindingProvider { - - /** - * {@inheritDoc} - */ - @Override - public String getBindingType() { - return "ekey"; - } - - /** - * @{inheritDoc - */ - @Override - public void validateItemType(Item item, String bindingConfig) throws BindingConfigParseException { - if (!(item instanceof NumberItem || item instanceof StringItem)) { - throw new BindingConfigParseException( - "item '" + item.getName() + "' is of type '" + item.getClass().getSimpleName() - + "', only Number- and StringItems are allowed - please check your *.items configuration"); - } - } - - /** - * {@inheritDoc} - */ - @Override - public void processBindingConfiguration(String context, Item item, String bindingConfig) - throws BindingConfigParseException { - super.processBindingConfiguration(context, item, bindingConfig); - EKeyBindingConfig config = new EKeyBindingConfig(); - - if (bindingConfig == null) { - throw new BindingConfigParseException("Your binding configuration is illegal!\n" - + "Possible values are: ACTION, USERNAME, USERID, TERMINALID, TERMINALNAME, " - + "FINGERID, KEYID, INPUTID, RELAISID, MODE\nExample: {ekey=\"ACTION\"}"); - } - - config.itemType = item.getClass(); - - // format the passed config parameter - String value = bindingConfig.trim().toUpperCase(); - - try { // try to convert the parameter to one of the predefined enum - // types - config.interestedIn = EKeyBindingConfig.InterestType.getType(value); - } catch (Exception e) { // throw exception - parameter was illegal - throw new BindingConfigParseException("eKey does not know the configuration value " + "'" + value - + "' that you passed in the item binding configuration!\n" - + "Possible values are: ACTION, USERNAME, USERID, TERMINALID, TERMINALNAME, " - + "FINGERID, KEYID, INPUTID, RELAISID, MODE\nExample: {ekey=\"ACTION\"}"); - } - - addBindingConfig(item, config); - } - - @Override - public InterestType getItemInterest(String itemName) { - EKeyBindingConfig config = (EKeyBindingConfig) bindingConfigs.get(itemName); - return config != null ? config.interestedIn : null; - } - - @Override - public Class getItemType(String itemName) { - EKeyBindingConfig config = (EKeyBindingConfig) bindingConfigs.get(itemName); - return config != null ? config.itemType : null; - } - -} +/** + * Copyright (c) 2010-2016 by the respective copyright holders. + * + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + */ +package org.openhab.binding.ekey.internal; + +import org.openhab.binding.ekey.EKeyBindingProvider; +import org.openhab.binding.ekey.internal.EKeyBindingConfig.InterestType; +import org.openhab.core.items.Item; +import org.openhab.core.library.items.NumberItem; +import org.openhab.core.library.items.StringItem; +import org.openhab.model.item.binding.AbstractGenericBindingProvider; +import org.openhab.model.item.binding.BindingConfigParseException; + +/** + * This class is responsible for parsing the binding configuration. + * Every Item can be interested in ONE information that is received with the eKey UDP-packet + * Each time a new packet arrives, all items will be informed with the latest values + * + * bindingconf: ekey= + * "ACTION|USERNAME|USERID|USERSTATUS|TERMINALID|TERMINALNAME|FINGERID|KEYID|INPUTID|MODE" + * + * @author Paul Schlagitweit + * @since 1.5.0 + */ +public class EKeyGenericBindingProvider extends AbstractGenericBindingProvider implements EKeyBindingProvider { + + /** + * {@inheritDoc} + */ + @Override + public String getBindingType() { + return "ekey"; + } + + /** + * @{inheritDoc + */ + @Override + public void validateItemType(Item item, String bindingConfig) throws BindingConfigParseException { + if (!(item instanceof NumberItem || item instanceof StringItem)) { + throw new BindingConfigParseException( + "item '" + item.getName() + "' is of type '" + item.getClass().getSimpleName() + + "', only Number- and StringItems are allowed - please check your *.items configuration"); + } + } + + /** + * {@inheritDoc} + */ + @Override + public void processBindingConfiguration(String context, Item item, String bindingConfig) + throws BindingConfigParseException { + super.processBindingConfiguration(context, item, bindingConfig); + EKeyBindingConfig config = new EKeyBindingConfig(); + + if (bindingConfig == null) { + throw new BindingConfigParseException("Your binding configuration is illegal!\n" + + "Possible values are: ACTION, USERNAME, USERID, TERMINALID, TERMINALNAME, " + + "FINGERID, KEYID, INPUTID, RELAYID, MODE\nExample: {ekey=\"ACTION\"}"); + } + + config.itemType = item.getClass(); + + // format the passed config parameter + String value = bindingConfig.trim().toUpperCase(); + + try { // try to convert the parameter to one of the predefined enum + // types + config.interestedIn = EKeyBindingConfig.InterestType.getType(value); + } catch (Exception e) { // throw exception - parameter was illegal + throw new BindingConfigParseException("eKey does not know the configuration value " + "'" + value + + "' that you passed in the item binding configuration!\n" + + "Possible values are: ACTION, USERNAME, USERID, TERMINALID, TERMINALNAME, " + + "FINGERID, KEYID, INPUTID, RELAYID, MODE\nExample: {ekey=\"ACTION\"}"); + } + + addBindingConfig(item, config); + } + + @Override + public InterestType getItemInterest(String itemName) { + EKeyBindingConfig config = (EKeyBindingConfig) bindingConfigs.get(itemName); + return config != null ? config.interestedIn : null; + } + + @Override + public Class getItemType(String itemName) { + EKeyBindingConfig config = (EKeyBindingConfig) bindingConfigs.get(itemName); + return config != null ? config.itemType : null; + } + +}