[ekey] initial contribution / oh1 migration

CODEOWNERS

@@ -73,6 +73,7 @@
 /bundles/org.openhab.binding.dwdunwetter/ @limdul79
 /bundles/org.openhab.binding.ecobee/ @mhilbush
 /bundles/org.openhab.binding.ecotouch/ @sibbi77
+/bundles/org.openhab.binding.ekey/ @hmerk
 /bundles/org.openhab.binding.elerotransmitterstick/ @vbier
 /bundles/org.openhab.binding.energenie/ @hmerk
 /bundles/org.openhab.binding.enigma2/ @gdolfen

bom/openhab-addons/pom.xml

@@ -351,6 +351,11 @@
       <artifactId>org.openhab.binding.ecotouch</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.ekey</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.elerotransmitterstick</artifactId>

bundles/org.openhab.binding.ekey/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

bundles/org.openhab.binding.ekey/README.md

@@ -0,0 +1,135 @@
+# ekey Binding
+
+This binding connects to [ekey](https://ekey.net/) 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)  |
+
+## 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):%d]"                          { channel="ekey:cvlan:de3b8db06e:action" }
+Number FingerID "User used finger [MAP(ekey_finger.map):%d]"                   { 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 [MAP(ekey_names.map):%d]" { channel="ekey:cvlan:de3b8db06e:userId" }
+String UserName " Name of Last user that accessed the house was : [%d]"        { channel="ekey:cvlan:de3b8db06e:userName" }
+Number UserStatus "Last user that accessed the house was [MAP(ekey_names.map):%d]" { 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 is just an example, as there is no strict rule what finger belongs to what number]
+
+```javascript
+0=leftlittle
+1=leftring
+2=leftmiddle
+3=leftindex
+4=leftthumb
+5=rightthumb
+6=rightindex
+7=rightmiddle
+8=rightring
+9=rightlittle
+-1=unknown
+```
+
+transform/ekey_names.map [NO spaces allowed]
+
+```javascript
+-1=Unspecified
+1=JohnDoe
+2=JaneDoe
+```
+
+transform/ekey_terminal.map
+
+```javascript
+80156839130911=Front
+80156839130914=Back
+```
+
+transform/ekey_multi_action.map
+
+```javascript
+0=granted
+-1=rejected
+1=timeoutA
+2=timeoutB
+3=inactive
+4=alwaysuser
+5=notcoupled
+6=digitalinput
+```
+
+transform/ekey_rare_action.map
+
+```javascript
+136=granted
+137=rejected
+```
+
+
+

bundles/org.openhab.binding.ekey/pom.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>3.2.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.ekey</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Ekey Binding</name>
+
+</project>

bundles/org.openhab.binding.ekey/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.ekey-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-ekey" description="Ekey Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.ekey/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EkeyBindingConstants.java

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.ekey.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link EkeyBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Hans-Jörg Merk - Initial contribution
+ */
+@NonNullByDefault
+public class EkeyBindingConstants {
+
+    public static final String BINDING_ID = "ekey";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_CVLAN = new ThingTypeUID(BINDING_ID, "cvlan");
+
+    // List of all Channel ids
+    public static final String CHANNEL_TYPE_USERID = "userId";
+    public static final String CHANNEL_TYPE_USERNAME = "userName";
+    public static final String CHANNEL_TYPE_USERSTATUS = "userStatus";
+    public static final String CHANNEL_TYPE_FINGERID = "fingerId";
+    public static final String CHANNEL_TYPE_KEYID = "keyId";
+    public static final String CHANNEL_TYPE_FSSERIAL = "fsSerial";
+    public static final String CHANNEL_TYPE_FSNAME = "fsName";
+    public static final String CHANNEL_TYPE_ACTION = "action";
+    public static final String CHANNEL_TYPE_INPUTID = "inputId";
+    public static final String CHANNEL_TYPE_RELAYID = "relayId";
+    public static final String CHANNEL_TYPE_TERMID = "termId";
+    public static final String CHANNEL_TYPE_RESERVED = "relayId";
+    public static final String CHANNEL_TYPE_EVENT = "event";
+    public static final String CHANNEL_TYPE_TIMESTAMP = "timestamp";
+}

bundles/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EkeyConfiguration.java

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.ekey.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link EkeyConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Hans-Jörg Merk - Initial contribution
+ */
+@NonNullByDefault
+public class EkeyConfiguration {
+
+    public String ipAddress = "";
+    public int port;
+    public String protocol = "";
+    public String delimiter = "";
+}

bundles/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EkeyDynamicStateDescriptionProvider.java

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.ekey.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.events.EventPublisher;
+import org.openhab.core.thing.binding.BaseDynamicStateDescriptionProvider;
+import org.openhab.core.thing.i18n.ChannelTypeI18nLocalizationService;
+import org.openhab.core.thing.link.ItemChannelLinkRegistry;
+import org.openhab.core.thing.type.DynamicStateDescriptionProvider;
+import org.osgi.service.component.annotations.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+
+/**
+ *
+ * @author Hans-Jörg Merk - Initial contribution
+ */
+@Component(service = { DynamicStateDescriptionProvider.class, EkeyDynamicStateDescriptionProvider.class })
+@NonNullByDefault
+public class EkeyDynamicStateDescriptionProvider extends BaseDynamicStateDescriptionProvider {
+
+    @Activate
+    public EkeyDynamicStateDescriptionProvider(final @Reference EventPublisher eventPublisher, //
+            final @Reference ItemChannelLinkRegistry itemChannelLinkRegistry, //
+            final @Reference ChannelTypeI18nLocalizationService channelTypeI18nLocalizationService) {
+        this.eventPublisher = eventPublisher;
+        this.itemChannelLinkRegistry = itemChannelLinkRegistry;
+        this.channelTypeI18nLocalizationService = channelTypeI18nLocalizationService;
+    }
+}

bundles/org.openhab.binding.ekey/src/main/java/org/openhab/binding/ekey/internal/EkeyHandlerFactory.java

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.ekey.internal;
+
+import static org.openhab.binding.ekey.internal.EkeyBindingConstants.THING_TYPE_CVLAN;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.ekey.internal.handler.EkeyHandler;
+import org.openhab.core.thing.Thing;
+import org.openhab.core.thing.ThingTypeUID;
+import org.openhab.core.thing.binding.BaseThingHandlerFactory;
+import org.openhab.core.thing.binding.ThingHandler;
+import org.openhab.core.thing.binding.ThingHandlerFactory;
+import org.osgi.service.component.ComponentContext;
+import org.osgi.service.component.annotations.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+
+/**
+ * The {@link EkeyHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Hans-Jörg Merk - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.ekey", service = ThingHandlerFactory.class)
+public class EkeyHandlerFactory extends BaseThingHandlerFactory {
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(THING_TYPE_CVLAN);
+
+    private final EkeyDynamicStateDescriptionProvider ekeyStateDescriptionProvider;
+
+    @Activate
+    public EkeyHandlerFactory(ComponentContext componentContext,
+            final @Reference EkeyDynamicStateDescriptionProvider dynamicStateDescriptionProvider) {
+        this.ekeyStateDescriptionProvider = dynamicStateDescriptionProvider;
+    }
+
+    @Override
+    public boolean supportsThingType(ThingTypeUID thingTypeUID) {
+        return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
+    }
+
+    @Override
+    protected @Nullable ThingHandler createHandler(Thing thing) {
+        ThingTypeUID thingTypeUID = thing.getThingTypeUID();
+
+        if (THING_TYPE_CVLAN.equals(thingTypeUID)) {
+            return new EkeyHandler(thing, ekeyStateDescriptionProvider);
+        }
+        return null;
+    }
+}