[mynice] Binding for IT4Wifi module (Nice gate doors) (#12940)

Signed-off-by: clinique <gael@lhopital.org>
openhab · Mar 10, 2023 · 3b5dfb1 · 3b5dfb1
1 parent d130595
commit 3b5dfb1
Show file tree

Hide file tree

Showing 31 changed files with 1,887 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -217,6 +217,7 @@
 /bundles/org.openhab.binding.mqtt.homie/ @davidgraeff
 /bundles/org.openhab.binding.mycroft/ @dalgwen
 /bundles/org.openhab.binding.mybmw/ @weymann @ntruchsess
+/bundles/org.openhab.binding.mynice/ @clinique
 /bundles/org.openhab.binding.myq/ @digitaldan
 /bundles/org.openhab.binding.mystrom/ @pail23
 /bundles/org.openhab.binding.nanoleaf/ @raepple @stefan-hoehn

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -1081,6 +1081,11 @@
       <artifactId>org.openhab.binding.mybmw</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.mynice</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.myq</artifactId>

diff --git a/bundles/org.openhab.binding.mynice/NOTICE b/bundles/org.openhab.binding.mynice/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
diff --git a/bundles/org.openhab.binding.mynice/README.md b/bundles/org.openhab.binding.mynice/README.md
@@ -0,0 +1,114 @@
+# MyNice Binding
+
+This binding implements the support of the IT4Wifi module through the NHK protocol and enables management of Nice gates actuators.
+IT4Wifi is a bridge between the TP4 bus of your gate and your Ethernet network.
+
+## Supported Things
+
+- `it4wifi`: The Bridge between openHAB and your module.
+- `swing`: A Thing representing a swinging (two rotating doors) gate.
+- `sliding`: A Thing representing a sliding gate.
+
+## Discovery
+
+The binding will auto-discover (by MDNS) your module, creating the associated `it4wifi` bridge.
+
+Once discovered, a user named “org.openhab.binding.mynice” will be created on it.
+You will have to grant him permissions using the MyNice app (Android or IOS).
+
+Once configuration of the bridge is completed, your gate(s) will also be auto-discovered and added to the Inbox.
+
+## Thing Configuration
+
+First configuration should be done via UI discovery, this will let you get automatically the password provided by the IT4Wifi module.
+Once done, you can also create your things via *.things file.
+
+### `it4wifi` Bridge Configuration
+
+| Name       | Type | Description                                                            | Default | Required | Advanced |
+|------------|------|------------------------------------------------------------------------|---------|----------|----------|
+| hostname   | text | Hostname or IP address of the device                                   | N/A     | yes      | no       |
+| password   | text | Password to access the device                                          | N/A     | yes      | no       |
+| macAddress | text | The MAC address of the IT4Wifi                                         | N/A     | yes      | no       |
+| username   | text | Pairing Key needed to access the device, provided by the bridge itself | N/A     | yes      | no       |
+
+### Gates Thing Configuration
+
+| Name       | Type | Description                                                            | Default | Required | Advanced |
+|------------|------|------------------------------------------------------------------------|---------|----------|----------|
+| id         | text | ID of the gate on the TP4 bus connected to the bridge                  | N/A     | yes      | no       |
+
+## Channels
+
+There is no channel associated with the bridge.
+
+Channels available for the gates are :
+
+| Channel   | Type   | Read/Write | Description                                              |
+|-----------|--------|------------|----------------------------------------------------------|
+| status    | String | R          | Description of the current status of the door (1)        |
+| obstruct  | Switch | R          | Flags an obstruction, blocking the door                  |
+| moving    | Switch | R          | Indicates if the device is currently operating a command |
+| command   | String | W          | Send a given command to the gate (2)                     |
+| t4command | String | W          | Send a T4 Command to the gate                            |
+
+(1) : can be open, closed, opening, closing, stopped.
+(2) : must be "stop","open","close"
+
+### T4 Commands
+
+Depending upon your gate model and motor capabilities, some T4 commands can be used.
+The list of available commands for your model will be automatically discovered by the binding.
+This information is stored in the `allowedT4` property held by the gate Thing itself.
+
+Complete list of T4 Commands :
+
+| Command | Action                     |
+|---------|----------------------------|
+| MDAx    | Step by Step               |
+| MDAy    | Stop (as remote control)   |
+| MDAz    | Open (as remote control)   |
+| MDA0    | Close (as remote control)  |
+| MDA1    | Partial opening 1          |
+| MDA2    | Partial opening 2          |
+| MDA3    | Partial opening 3          |
+| MDBi    | Apartment Step by Step     |
+| MDBj    | Step by Step high priority |
+| MDBk    | Open and block             |
+| MDBl    | Close and block            |
+| MDBm    | Block                      |
+| MDEw    | Release                    |
+| MDEx    | Courtesy ligh timer on     |
+| MDEy    | Courtesy light on-off      |
+| MDEz    | Step by Step master door   |
+| MDE0    | Open master door           |
+| MDE1    | Close master door          |
+| MDE2    | Step by Step slave door    |
+| MDE3    | Open slave door            |
+| MDE4    | Close slave door           |
+| MDE5    | Release and Open           |
+| MDFh    | Release and Close          |
+
+## Full Example
+
+### things/mynice.things
+
+```java
+Bridge mynice:it4wifi:83eef09166 "Nice IT4WIFI" @ "portail" [
+            hostname="192.168.0.198",
+            macAddress="00:xx:zz:dd:ff:gg",
+            password="v***************************zU=",
+            username="neo_prod"] {
+      swing 1 "Nice POA3 Moteur Portail" @ "portail" [id="1"]
+}
+```
+
+### items/mynice.items
+
+```java
+String   NiceIT4WIFI_GateStatus    "Gate Status" <gate>   (gMyniceSwing) ["Status","Opening"]     {channel="mynice:swing:83eef09166:1:status"}
+String   NiceIT4WIFI_Obstruction   "Obstruction" <none>   (gMyniceSwing)                          {channel="mynice:swing:83eef09166:1:obstruct"}
+Switch   NiceIT4WIFI_Moving        "Moving"      <motion> (gMyniceSwing) ["Status","Vibration"]   {channel="mynice:swing:83eef09166:1:moving"}
+String   NiceIT4WIFI_Command       "Command"     <none>   (gMyniceSwing)                          {channel="mynice:swing:83eef09166:1:command"}
+
+```
diff --git a/bundles/org.openhab.binding.mynice/pom.xml b/bundles/org.openhab.binding.mynice/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.0.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.mynice</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: MyNice Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.mynice/src/main/feature/feature.xml b/bundles/org.openhab.binding.mynice/src/main/feature/feature.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.mynice-${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-mynice" description="MyNice Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.mynice/${project.version}</bundle>
+	</feature>
+</features>
diff --git a/...ding.mynice/src/main/java/org/openhab/binding/mynice/internal/MyNiceBindingConstants.java b/...ding.mynice/src/main/java/org/openhab/binding/mynice/internal/MyNiceBindingConstants.java
@@ -0,0 +1,43 @@
+/**
+ * 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.mynice.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link MyNiceBindingConstants} class defines common constants, which are used across the whole binding.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class MyNiceBindingConstants {
+    private static final String BINDING_ID = "mynice";
+
+    // List of all Channel ids
+    public static final String DOOR_STATUS = "status";
+    public static final String DOOR_OBSTRUCTED = "obstruct";
+    public static final String DOOR_MOVING = "moving";
+    public static final String DOOR_COMMAND = "command";
+    public static final String DOOR_T4_COMMAND = "t4command";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID BRIDGE_TYPE_IT4WIFI = new ThingTypeUID(BINDING_ID, "it4wifi");
+    public static final ThingTypeUID THING_TYPE_SWING = new ThingTypeUID(BINDING_ID, "swing");
+    public static final ThingTypeUID THING_TYPE_SLIDING = new ThingTypeUID(BINDING_ID, "sliding");
+
+    // Configuration element of a portal
+    public static final String DEVICE_ID = "id";
+
+    public static final String ALLOWED_T4 = "allowedT4";
+}
diff --git a/...inding.mynice/src/main/java/org/openhab/binding/mynice/internal/MyNiceHandlerFactory.java b/...inding.mynice/src/main/java/org/openhab/binding/mynice/internal/MyNiceHandlerFactory.java
@@ -0,0 +1,61 @@
+/**
+ * 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.mynice.internal;
+
+import static org.openhab.binding.mynice.internal.MyNiceBindingConstants.*;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.mynice.internal.handler.GateHandler;
+import org.openhab.binding.mynice.internal.handler.It4WifiHandler;
+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.Component;
+
+/**
+ * The {@link MyNiceHandlerFactory} is responsible for creating thing handlers.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.mynice", service = ThingHandlerFactory.class)
+public class MyNiceHandlerFactory extends BaseThingHandlerFactory {
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(BRIDGE_TYPE_IT4WIFI, THING_TYPE_SWING,
+            THING_TYPE_SLIDING);
+
+    @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 (BRIDGE_TYPE_IT4WIFI.equals(thingTypeUID)) {
+            return new It4WifiHandler((Bridge) thing);
+        } else if (THING_TYPE_SWING.equals(thingTypeUID)) {
+            return new GateHandler(thing);
+        } else if (THING_TYPE_SLIDING.equals(thingTypeUID)) {
+            return new GateHandler(thing);
+        }
+
+        return null;
+    }
+}
diff --git a/...mynice/src/main/java/org/openhab/binding/mynice/internal/config/It4WifiConfiguration.java b/...mynice/src/main/java/org/openhab/binding/mynice/internal/config/It4WifiConfiguration.java
@@ -0,0 +1,31 @@
+/**
+ * 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.mynice.internal.config;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link It4WifiConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class It4WifiConfiguration {
+    public static final String PASSWORD = "password";
+    public static final String HOSTNAME = "hostname";
+
+    public String username = "";
+    public String hostname = "";
+    public String macAddress = "";
+    public String password = "";
+}