[heliosventilation] Initial contribution (openhab#7858)

* add new binding HelioVentilation Signed-off-by: Raphael Mack <[email protected]>
andrewfg · Aug 31, 2020 · a6fc499 · a6fc499
1 parent e9dd670
commit a6fc499
Show file tree

Hide file tree

Showing 19 changed files with 1,620 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -73,6 +73,7 @@
 /bundles/org.openhab.binding.hdanywhere/ @kgoderis
 /bundles/org.openhab.binding.hdpowerview/ @beowulfe
 /bundles/org.openhab.binding.helios/ @kgoderis
+/bundles/org.openhab.binding.heliosventilation/ @ramack
 /bundles/org.openhab.binding.heos/ @Wire82
 /bundles/org.openhab.binding.homeconnect/ @bruestel
 /bundles/org.openhab.binding.homematic/ @FStolte @gerrieg @mdicke2s

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -359,6 +359,11 @@
       <artifactId>org.openhab.binding.helios</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.heliosventilation</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.heos</artifactId>

diff --git a/bundles/org.openhab.binding.heliosventilation/.classpath b/bundles/org.openhab.binding.heliosventilation/.classpath
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" output="target/classes" path="src/main/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
+		<attributes>
+			<attribute name="test" value="true"/>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry exported="true" kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>
diff --git a/bundles/org.openhab.binding.heliosventilation/.project b/bundles/org.openhab.binding.heliosventilation/.project
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.heliosventilation</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.m2e.core.maven2Builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.m2e.core.maven2Nature</nature>
+	</natures>
+</projectDescription>
diff --git a/bundles/org.openhab.binding.heliosventilation/NOTICE b/bundles/org.openhab.binding.heliosventilation/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.heliosventilation/README.md b/bundles/org.openhab.binding.heliosventilation/README.md
@@ -0,0 +1,111 @@
+# HeliosVentilation Binding
+
+This is the binding for Helios Ventilation Systems KWL EC 200/300/500 Pro.
+It requires a connection to the RS485 bus used by the original remote controls KWL-FB (9417) and does not use the Modbus/TCP interface of the newer EasyControl devices.
+
+For electrical connection it is recommended to use an USB-RS485 interface, but any RS485 interface that shows up as a serial port will do.
+Setup the device as described in https://www.openhab.org/docs/administration/serial.html.
+
+The binding will use the remote control address 15 for communication, so make sure that this is not assigned to a physically present remote control.
+
+## Supported Things
+
+There is only one thing type supported by this binding: a Helios Ventilation System KWL EC 200/300/500 Pro from Helios.
+The binding was developed and test on a KWL EC 200 Pro device.
+
+## Binding Configuration
+
+The binding requires access to the serial device connecting to the RS485 bus as described in https://www.openhab.org/docs/administration/serial.html.
+Otherwise only thing configuration is needed.
+
+## Thing Configuration
+
+The binding supports only one thing and requires the configuration of the serial port (typically /dev/ttyUSB0 on Linux and COM3 on Windows) and optionally the polling time which is the cycle time after which the binding tries to reconnect to the bus and requests data updates.
+
+## Channels
+
+Supported operation channels:
+
+| channel            | type                 | description                                   |
+|--------------------|----------------------|-----------------------------------------------|
+| outsideTemp        | Number:Temperature   | Temperature sensor in the outside air flow    |
+| outgoingTemp       | Number:Temperature   | Temperature sensor in the outgoing air flow   |
+| extractTemp        | Number:Temperature   | Temperature sensor in the extract air flow    |
+| supplyTemp         | Number:Temperature   | Temperature sensor in the supply air flow     |
+| setTemp            | Number:Temperature   | Set temperature for supply (not always used)  |
+| fanspeed           | Number               | Level of the fanspeed (1-8)                   |
+| powerState         | Switch               | Main power switch                             |
+| co2State           | Switch               | Switch for CO2 regulation                     |
+| rhState            | Switch               | Switch for humidity regulation                |
+| winterMode         | Switch               | Switch to set winter mode                     |
+
+Supported configuration channels:
+
+| channel            | type                 | description                                   |
+|--------------------|----------------------|-----------------------------------------------|
+| bypassTemp         | Number:Temperature   | Temperature to disable the bypass function    |
+| supplyStopTemp     | Number:Temperature   | Temperature to stop supply fan for defrosting |
+| preheatTemp        | Number:Temperature   | Temperature to enable the preheater           |
+| minFanspeed        | Number               | Minimal level of the fanspeed (1-8)           |
+| maxFanspeed        | Number               | Maximal level of the fanspeed (1-8)           |
+| rhLimit            | Number:Dimensionless | Limit for relative humidity sensor            |
+| hysteresis         | Number:Temperature   | Hysteresis on defroster temperature           |
+| DCFanExtract       | Number:Dimensionless | Speed reduction for the extract fan           |
+| DCFanSupply        | Number:Dimensionless | Speed reduction for the supply fan            |
+| maintenanceInterval| Number:Dimensionless | Maintenance interval in months                |
+| adjustInveral      | Number:Dimensionless | Adjust interval in minutes for air quality    |
+| RHLevelAuto        | Switch               | Automatic base humidity determination         |
+| switchType         | Switch               | External Switch type (Boost or Fireplace)     |
+| radiatorType       | Switch               | Use water (ON) or electric (OFF) radiator     |
+| cascade            | Switch               | System is cascaded                            |
+
+Note: the configuration channels are not intended to be written regularly.
+
+## Full Example
+
+Things:
+
+```
+heliosventilation:ventilation:MyKWL  [ serialPort="/dev/ttyUSB0" ]
+```
+
+Items:
+
+```
+Switch KWLOnOff { channel="heliosventilation:ventilation:MyKWL:powerState" }
+Switch KWLWinter { channel="heliosventilation:ventilation:MyKWL:winterMode" }
+
+Group VentilationTemp "Measured Temperatures in Ventilation System"
+
+Number:Temperature Outside_Temperature "Outside Temperature [%.1f °C]" <temperature> (VentilationTemp) { channel="heliosventilation:ventilation:MyKWL:outsideTemp" }
+Number:Temperature Outgoing_Temperature "Outgoing Temperature [%.1f °C]" <temperature> (VentilationTemp) { channel="heliosventilation:ventilation:MyKWL:outgoingTemp" }
+Number:Temperature Extract_Temperature "Extract Temperature [%.1f °C]" <temperature> (VentilationTemp) { channel="heliosventilation:ventilation:MyKWL:extractTemp" }
+Number:Temperature Supply_Temperature "Supply Temperature [%.1f °C]" <temperature> (VentilationTemp) { channel="heliosventilation:ventilation:MyKWL:supplyTemp" }
+
+Number Fan_Speed "Fan Speed" <fan> { channel="heliosventilation:ventilation:MyKWL:fanspeed" }
+Number Min_Fan_Speed "Min Fan Speed" <fan> { channel="heliosventilation:ventilation:MyKWL:minFanspeed" }
+Number Max_Fan_Speed "Max Fan Speed" <fan> { channel="heliosventilation:ventilation:MyKWL:maxFanspeed" }
+
+```
+
+Sitemap:
+
+```
+sitemap helios_kwl label="Helios Ventilation" {
+        Frame label="Temperatures" {
+              Text item=Outside_Temperature
+              Text item=Outgoing_Temperature
+              Text item=Extract_Temperature
+              Text item=Supply_Temperature
+        }
+        Frame label="Control" {
+              Switch item=KWLOnOff
+              Switch item=KWLWinter
+              Slider item=Fan_Speed icon="fan" minValue=1 maxValue=8 step=1
+        }
+        Frame label="Configuration" {
+              Slider item=Min_Fan_Speed
+              Setpoint item=Max_Fan_Speed icon="fan"
+        }
+}
+```
diff --git a/bundles/org.openhab.binding.heliosventilation/pom.xml b/bundles/org.openhab.binding.heliosventilation/pom.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  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>2.5.7-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.heliosventilation</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: HeliosVentilation Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.heliosventilation/src/main/feature/feature.xml b/bundles/org.openhab.binding.heliosventilation/src/main/feature/feature.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.heliosventilation-${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-heliosventilation" description="HeliosVentilation Binding" version="${project.version}">
+        <feature>openhab-runtime-base</feature>
+        <feature>openhab-transport-serial</feature>
+        <bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.heliosventilation/${project.version}</bundle>
+    </feature>
+</features>
diff --git a/.../java/org/openhab/binding/heliosventilation/internal/HeliosPropertiesFormatException.java b/.../java/org/openhab/binding/heliosventilation/internal/HeliosPropertiesFormatException.java
@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2010-2020 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.heliosventilation.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link HeliosPropertiesFormatException} class defines an exception to describe parsing format errors
+ *
+ * @author Raphael Mack - Initial contribution
+ */
+@NonNullByDefault
+public class HeliosPropertiesFormatException extends Exception {
+    private static final long serialVersionUID = 8051109351111509577L;
+    private final String channelName;
+    private final String fullSpec;
+    private final String reason;
+
+    public HeliosPropertiesFormatException(String reason, String channelName, String fullSpec) {
+        this.channelName = channelName;
+        this.fullSpec = fullSpec;
+        this.reason = reason;
+    }
+
+    public String getChannelName() {
+        return channelName;
+    }
+
+    public String getFullSpec() {
+        return fullSpec;
+    }
+
+    @Override
+    public String getMessage() {
+        return "Cannot parse '" + fullSpec + "' for datapoint '" + channelName + "': " + reason;
+    }
+}
diff --git a/...ava/org/openhab/binding/heliosventilation/internal/HeliosVentilationBindingConstants.java b/...ava/org/openhab/binding/heliosventilation/internal/HeliosVentilationBindingConstants.java
@@ -0,0 +1,90 @@
+/**
+ * Copyright (c) 2010-2020 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.heliosventilation.internal;
+
+import java.io.IOException;
+import java.net.URL;
+import java.util.Enumeration;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Properties;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The {@link HeliosVentilationBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Raphael Mack - Initial contribution
+ */
+@NonNullByDefault
+public class HeliosVentilationBindingConstants {
+
+    public static final String BINDING_ID = "heliosventilation";
+
+    public static final String DATAPOINT_FILE = "datapoints.properties";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_HELIOS_VENTILATION = new ThingTypeUID(BINDING_ID, "ventilation");
+
+    public static final Map<Byte, HeliosVentilationDataPoint> DATAPOINTS;
+
+    private static final Logger LOGGER;
+    static {
+        /* logger is used by readChannelProperties() so we need to initialize logger first. */
+        LOGGER = LoggerFactory.getLogger(HeliosVentilationBindingConstants.class);
+        DATAPOINTS = readChannelProperties();
+    }
+    // List of all Channel ids
+    // Channel ids are only in datapoints.properties and thing-types.xml
+
+    /**
+     * parse datapoints from properties
+     *
+     */
+    private static Map<Byte, HeliosVentilationDataPoint> readChannelProperties() {
+        HashMap<Byte, HeliosVentilationDataPoint> result = new HashMap<Byte, HeliosVentilationDataPoint>();
+
+        URL resource = Thread.currentThread().getContextClassLoader().getResource(DATAPOINT_FILE);
+        Properties properties = new Properties();
+        try {
+            properties.load(resource.openStream());
+
+            Enumeration<Object> keys = properties.keys();
+            while (keys.hasMoreElements()) {
+                String channel = (String) keys.nextElement();
+                HeliosVentilationDataPoint dp;
+                try {
+                    dp = new HeliosVentilationDataPoint(channel, properties.getProperty(channel));
+                    if (result.containsKey(dp.address())) {
+                        result.get(dp.address()).append(dp);
+                    } else {
+                        result.put(dp.address(), dp);
+                    }
+                } catch (HeliosPropertiesFormatException e) {
+                    LOGGER.warn("could not read resource file {}, binding will probably fail: {}", DATAPOINT_FILE,
+                            e.getMessage());
+                }
+            }
+        } catch (IOException e) {
+            LOGGER.warn("could not read resource file {}, binding will probably fail: {}", DATAPOINT_FILE,
+                    e.getMessage());
+        }
+
+        return result;
+    }
+
+}