[thekeys] Initial binding contribution

Binding for the smartlock TheKeys
Signed-off-by: Jordan Martin <jo69270@gmail.com>

CODEOWNERS

@@ -348,6 +348,7 @@
 /bundles/org.openhab.binding.teleinfo/ @Nokyyz @olivierkeke
 /bundles/org.openhab.binding.tellstick/ @openhab/add-ons-maintainers
 /bundles/org.openhab.binding.tesla/ @kgoderis
+/bundles/org.openhab.binding.thekeys/ @jordanmartin
 /bundles/org.openhab.binding.tibber/ @kjoglum
 /bundles/org.openhab.binding.tivo/ @mlobstein
 /bundles/org.openhab.binding.touchwand/ @roieg

bom/openhab-addons/pom.xml

@@ -1726,6 +1726,11 @@
       <artifactId>org.openhab.binding.tesla</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.thekeys</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.tibber</artifactId>

bundles/org.openhab.binding.thekeys/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.thekeys/README.md

@@ -0,0 +1,100 @@
+# The Keys Binding
+
+This is the binding for [TheKeys Smartlock](https://www.the-keys.eu/fr/produits/8-serrure-connectee.html).  
+This binding allows you to integrate, view, control and configure TheKeys Gateway and TheKeys Smartlock.
+
+![The Keys smartlock](doc/thekeys-smartlock.png)
+![The Keys gateway](doc/thekeys-gateway.png)
+
+## Prerequisites
+
+At least one TheKeys Smartlock which is associated with a The Keys Gateway. The Gateway must be paired with the Sartlock
+via the android/ios app. It is recommended to configure static IP addresses for the Gateway.
+
+### Setup
+
+- Create access for the Gateway from the app or from https://api.the-keys.fr
+- Open the share on https://api.the-keys.fr to get the share code
+
+## Supported Bridges
+
+### `gateway` Bridge Thing Configuration
+
+This binding supports just one bridge type: The Keys Gateway (`thekeys:gateway`). The following configuration options
+are available:
+
+| Name            | Type    | Description                           | Default | Required | Advanced |
+|-----------------|---------|---------------------------------------|---------|----------|----------|
+| host            | text    | Host or IP address of the device      | N/A     | yes      | no       |
+| code            | text    | The gateway access code               | N/A     | yes      | no       |
+| refreshInterval | integer | Interval the device is polled in sec. | 5       | yes      | no       |
+| apiTimeout      | integer | Interval the device is polled in sec. | 30      | yes      | yes      |
+
+### Discovery
+
+The bridge can't be discoverd automatically. The `host` must be provided. You can find it from the ios/android app :
+Home Page > Accessories > TK Gateway > Configure > IP
+
+### Supported Channels
+
+| Channel       | Type   | Read/Write | Description                                 |
+|---------------|--------|------------|---------------------------------------------|
+| version       | Number | R          | Firmware version                            |
+
+## Supported Things
+
+### `smartlock` Thing Configuration
+
+This thing allows to control the smartlock and check its state
+
+| Name            | Type    | Description                           | Default | Required | Advanced |
+|-----------------|---------|---------------------------------------|---------|----------|----------|
+| lockId          | integer | Identifier of the smartlock           | N/A     | yes      | no       |
+
+### Discovery
+
+The smartlock can be discovered when the Gateway is configured and online. Hit the "scan" button when you add the thing
+througth the UI
+
+### Supported Channels
+
+| Channel       | Type   | Read/Write | Description                                |
+|---------------|--------|------------|--------------------------------------------|
+| status        | String | R          | Status of the smartlock                    |
+| batteryLevel  | Number | R          | Current battery level                      |
+| lowBattery    | Switch | R          | Low battery warning                        |
+| rssi          | Number | R          | Bluetooth Signal strength with the gateway |
+| position      | Number | R          | Position of the lock                       |
+| version       | Number | R          | Firmware version                           |
+| lastSync      | Switch | R          | Last success sync with the lock            |
+| lock          | Switch | RW         | Switch to open and close the lock          |
+
+## Full Example
+
+A manual setup through files could look like this:
+
+### things/thekeys.things
+
+```
+Bridge thekeys:gateway:tk-gateway [ host="192.168.1.50", code="secretcode", refreshInterval="5", apiTimeout="30" ] {
+    Thing smartlock tk-smartlock [ lockId="1234" ]
+}
+```
+
+### items/thekeys.item
+
+```
+// Equipment representing thing
+Group Smartlock "Smartlock" ["Equipment"]
+
+// Points
+String   Smartlock_Lock_status                 "Lock status"                                    (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:status" }         
+Number   Smartlock_Niveau_Batterie             "Battery level"               <Battery>          (Smartlock) ["Measurement", "Energy"]  { channel="thekeys:smartlock:tk-gateway:1234:batteryLevel" }   
+Switch   Smartlock_Batterie_Faible             "Low battery"                 <LowBattery>       (Smartlock) ["Energy", "LowBattery"]   { channel="thekeys:smartlock:tk-gateway:1234:lowBattery" }     
+Number   Smartlock_Bluetooth_rssi              "Bluetooth rssi"              <QualityOfService> (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:rssi" }           
+Number   Smartlock_Smartlock_position          "Smartlock position"                             (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:position" }       
+Number   Smartlock_Firmware_version            "Firmware version"                               (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:version" }        
+Switch   Smartlock_Synchronization_in_progress "Synchronization in progress"                    (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:syncInProgress" } 
+DateTime Smartlock_Last_sync                   "Last sync"                                      (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:lastSync" }       
+Switch   Smartlock_Lock                        "Lock"                        <Door>             (Smartlock) ["Point"]                  { channel="thekeys:smartlock:tk-gateway:1234:lock" }           
+```

bundles/org.openhab.binding.thekeys/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 https://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>4.1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.thekeys</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: TheKeys Binding</name>
+
+</project>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.thekeys-${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-thekeys" description="TheKeys Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.thekeys/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.thekeys/src/main/java/org/openhab/binding/thekeys/internal/TheKeysBindingConstants.java

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2010-2023 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.thekeys.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link TheKeysBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Jordan Martin - Initial contribution
+ */
+@NonNullByDefault
+public class TheKeysBindingConstants {
+
+    public static final String BINDING_ID = "thekeys";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_GATEWAY = new ThingTypeUID(BINDING_ID, "gateway");
+    public static final ThingTypeUID THING_TYPE_SMARTLOCK = new ThingTypeUID(BINDING_ID, "smartlock");
+
+    // List of all Channel ids
+    public static final String CHANNEL_VERSION = "version";
+    public static final String CHANNEL_STATUS = "status";
+    public static final String CHANNEL_BATTERY_LEVEL = "batteryLevel";
+    public static final String CHANNEL_LOW_BATTERY = "lowBattery";
+    public static final String CHANNEL_RSSI = "rssi";
+    public static final String CHANNEL_POSITION = "position";
+    public static final String CHANNEL_LOCK = "lock";
+    public static final String CHANNEL_LAST_SYNC = "lastSync";
+    public static final String CHANNEL_SYNC_IN_PROGRESS = "syncInProgress";
+
+    // List of thing configuration
+    public static final String CONF_SMARTLOCK_LOCKID = "lockId";
+
+    // List of property
+    public static final String PROPERTY_VERSION = "version";
+}

bundles/org.openhab.binding.thekeys/src/main/java/org/openhab/binding/thekeys/internal/TheKeysHandlerFactory.java

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2010-2023 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.thekeys.internal;
+
+import static org.openhab.binding.thekeys.internal.TheKeysBindingConstants.THING_TYPE_GATEWAY;
+import static org.openhab.binding.thekeys.internal.TheKeysBindingConstants.THING_TYPE_SMARTLOCK;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.thekeys.internal.gateway.TheKeysGatewayHandler;
+import org.openhab.binding.thekeys.internal.provider.TheKeyTranslationProvider;
+import org.openhab.binding.thekeys.internal.smartlock.TheKeysSmartlockHandler;
+import org.openhab.core.thing.Bridge;
+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.annotations.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+
+/**
+ * The {@link TheKeysHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Jordan Martin - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.thekeys", service = ThingHandlerFactory.class)
+public class TheKeysHandlerFactory extends BaseThingHandlerFactory {
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(THING_TYPE_GATEWAY,
+            THING_TYPE_SMARTLOCK);
+    private final TheKeyTranslationProvider translationProvider;
+
+    @Activate
+    public TheKeysHandlerFactory(@Reference TheKeyTranslationProvider translationProvider) {
+        this.translationProvider = translationProvider;
+    }
+
+    @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_GATEWAY.equals(thingTypeUID)) {
+            return new TheKeysGatewayHandler((Bridge) thing, translationProvider);
+        } else if (THING_TYPE_SMARTLOCK.equals(thingTypeUID)) {
+            return new TheKeysSmartlockHandler(thing);
+        }
+
+        return null;
+    }
+}