[kermi] Initial contribution

bom/openhab-addons/pom.xml

@@ -816,6 +816,11 @@
       <artifactId>org.openhab.binding.keba</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.kermi</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.km200</artifactId>

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

@@ -0,0 +1,78 @@
+# Kermi Binding
+
+This binding connects to [Kermi x-center controller](https://www.kermi.com/en/de/indoor-climate/products/heat-pumps-and-storage/x-center-controller/ "x-center-controller") for heat pumps.
+
+# Kermi Binding
+
+Current support is developed and tested on 
+
+* a franchised version of the Kermi heatpump, namely the [Heizbösch MOZART13AC-RW60](https://www.boesch.at/produkte/heizen/waermepumpe/luft/modulierende-luft-wasser-waermepumpe-mozart-aussenaufstellung~495589) heatpump manager version  _1.6.0.118_ .
+
+No official documentation could be found or gathered. This plug-in is based
+on reverse engineering the protocol.
+
+## Supported Things
+
+The x-center consists of a heat-pump manager that provides the communication bridge. 
+
+- `bridge`: The communication bridge, provided by the heat pump manager
+- `drinkingwater-heating`: The storage module responsible for heating the drinking water (Default bus address = 51)
+- `room-heating`: The storage module responsible for heating rooms (Default bus address = 50)
+- `heatpump-manager`: As thing
+- `heatpump`: The heatpump element itself (Default bus address = 40)
+
+## Discovery
+
+There is no obvious way to get a listing of all Datapoints for a given Device. Due to this, on first
+connection to a site, the API for the UI User Interface is used, to iterate over all menu entries to
+collect the datapoints - which may take a while.
+
+The gathered data is then stored in `OH_USERDATA/binding.kermi` and loaded on subsequent binding lifecycle
+changes. The cache data is bound to the device-uuid and its serial number. If these values change,
+the datapoints are automatically re-initialized.
+
+## Binding Configuration
+
+The following samples are provided, representing the current state of my usage.
+
+```
+// kermi.things
+Bridge kermi:bridge:heatpumpbridge [hostname="xcenter-url",password="password",refreshInterval=60] {
+    Thing drinkingwater-heating dwheating [ address=51 ]
+    Thing room-heating rheating [ address=50 ]
+    Thing heatpump heatpump [ address=40 ]
+}
+
+```
+
+The plugin is configured to collect all `WellKnownName` datapoints, so generally
+all of them should be supported. At the moment I only test the following items in read-only mode.
+
+```
+// kermi.items
+Number:Temperature Drinking_water_temperature  {channel="kermi:drinkingwater-heating:heatpumpbridge:dwheating:BufferSystem_TweTemperatureActual"}
+
+Number:Temperature Heating_current_temperature_buffer {channel="kermi:room-heating:heatpumpbridge:rheating:BufferSystem_HeatingTemperatureActual"}
+Number:Temperature Cooling_current_temperature_buffer {channel="kermi:room-heating:heatpumpbridge:rheating:BufferSystem_CoolingTemperatureActual"}
+
+Number:Temperature Outside_temperature {channel="kermi:room-heating:heatpumpbridge:rheating:LuftTemperatur"}
+
+Number:Power Current_Power_Inverter {channel="kermi:heatpump:heatpumpbridge:heatpump:Rubin_CurrentPowerInverter"}
+```
+
+# Changelog
+
+20.10.23 
+* Support numeric values for datapointType = 0
+* Support string values for datapointType = 3
+* Support string values for datapointType = 4
+
+# ToDo / Future Tasks
+
+* Change default query time, resemble webinterface behaviour (every 10 seconds to GetFavorites)
+* Support channels for bridge
+* Somehow add DatapointConfigId to channel, seems not supported
+* Collection of statistics providing virtual channels
+    * 24/h power consumption (all, heating, drinking-water)
+    * number of cycles (all, heating, drinking-water)
+    * time between cycles

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

@@ -0,0 +1,26 @@
+<?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.2.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.kermi</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Kermi Binding</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-collections4</artifactId>
+      <version>4.1</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+
+</project>

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

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

bundles/org.openhab.binding.kermi/src/main/java/org/openhab/binding/kermi/internal/KermiBaseDeviceConfiguration.java

@@ -0,0 +1,20 @@
+/**
+ * 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.kermi.internal;
+
+/**
+ * @author Marco Descher - Initial contribution
+ */
+public class KermiBaseDeviceConfiguration {
+    public Integer address;
+}

bundles/org.openhab.binding.kermi/src/main/java/org/openhab/binding/kermi/internal/KermiBindingConstants.java

@@ -0,0 +1,77 @@
+/**
+ * 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.kermi.internal;
+
+import java.io.File;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.OpenHAB;
+import org.openhab.core.thing.ThingTypeUID;
+import org.openhab.core.thing.type.ChannelTypeUID;
+
+/**
+ * The {@link KermiBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Marco Descher - Initial contribution
+ */
+@NonNullByDefault
+public class KermiBindingConstants {
+
+    private static final String BINDING_ID = "kermi";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_BRIDGE = new ThingTypeUID(BINDING_ID, "bridge");
+    public static final ThingTypeUID THING_TYPE_DRINKINGWATER_HEATING = new ThingTypeUID(BINDING_ID,
+            "drinkingwater-heating");
+    public static final ThingTypeUID THING_TYPE_ROOM_HEATING = new ThingTypeUID(BINDING_ID, "room-heating");
+    public static final ThingTypeUID THING_TYPE_HEATPUMP = new ThingTypeUID(BINDING_ID, "heatpump");
+    public static final ThingTypeUID THING_TYPE_HEATPUMP_MANAGER = new ThingTypeUID(BINDING_ID, "heatpump-manager");
+
+    public static final ChannelTypeUID CHANNEL_TYPE_TEMPERATURE = new ChannelTypeUID(BINDING_ID, "temperature");
+    public static final ChannelTypeUID CHANNEL_TYPE_POWER = new ChannelTypeUID(BINDING_ID, "power");
+    public static final ChannelTypeUID CHANNEL_TYPE_NUMBER = new ChannelTypeUID(BINDING_ID, "number");
+    public static final ChannelTypeUID CHANNEL_TYPE_ONOFF = new ChannelTypeUID(BINDING_ID, "onoff");
+    public static final ChannelTypeUID CHANNEL_TYPE_STRING = new ChannelTypeUID(BINDING_ID, "string");
+
+    // Device Constants
+    public static final String DEVICE_ID_HEATPUMP_MANAGER = "00000000-0000-0000-0000-000000000000";
+    public static final int DEVICE_TYPE_HEATING_SYSTEM = 95;
+    public static final int DEVICE_TYPE_HEATPUMP = 97;
+    public static final int DEVICE_TYPE_HEATPUMP_MANAGER = 0;
+
+    public static final String WELL_KNOWN_NAME_BS_TWE_TEMP_ACT = "BufferSystem_TweTemperatureActual";
+    public static final String WELL_KNOWN_NAME_FS_COOL_TEMP_ACT = "BufferSystem_CoolingTemperatureActual";
+    public static final String WELL_KNOWN_NAME_FS_HEAT_TEMP_ACT = "BufferSystem_HeatingTemperatureActual";
+    public static final String WELL_KNOWN_NAME_COMB_HEATPUMP_STATE = "Rubin_CombinedHeatpumpState";
+    public static final String WELL_KNOWN_NAME_COMB_HEATPUMP_CURR_COP = "Rubin_CurrentCOP";
+    public static final String WELL_KNOWN_NAME_CURR_OUT_CAP = "Rubin_CurrentOutputCapacity";
+    public static final String WELL_KNOWN_NAME_HEAT_AIR_TEMPERATURE = "LuftTemperatur";
+
+    // All Urls
+    public static final String HPM_DEVICE_GETDEVICESBYFILTER_URL = "http://%IP%/api/Device/GetDevicesByFilter/00000000-0000-0000-0000-000000000000";
+    public static final String HPM_DEVICE_GETDEVICE_URL = "http://%IP%/api/Device/GetDevice/00000000-0000-0000-0000-000000000000";
+    public static final String HPM_DEVICE_GETALLDEVICES_URL = "http://%IP%/api/Device/GetAllDevices/00000000-0000-0000-0000-000000000000";
+    public static final String HPM_MENU_GETCHILDENTRIES_URL = "http://%IP%/api/Menu/GetChildEntries/00000000-0000-0000-0000-000000000000";
+    public static final String HPM_DATAPOINT_READVALUES_URL = "http://%IP%/api/Datapoint/ReadValues/00000000-0000-0000-0000-000000000000";
+
+    public static String parseUrl(String url, String ip) {
+        return url.replace("%IP%", ip.trim());
+    }
+
+    public static File getKermiUserDataFolder() {
+        File kermiUserDataFolder = new File(OpenHAB.getUserDataFolder(), "binding.kermi");
+        kermiUserDataFolder.mkdir();
+        return kermiUserDataFolder;
+    }
+}

bundles/org.openhab.binding.kermi/src/main/java/org/openhab/binding/kermi/internal/KermiBridgeConfiguration.java

@@ -0,0 +1,22 @@
+/**
+ * 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.kermi.internal;
+
+/**
+ * @author Marco Descher - Initial contribution
+ */
+public class KermiBridgeConfiguration {
+    public String hostname;
+    public String password;
+    public Integer refreshInterval;
+}

bundles/org.openhab.binding.kermi/src/main/java/org/openhab/binding/kermi/internal/KermiCommunicationException.java

@@ -0,0 +1,40 @@
+/**
+ * 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.kermi.internal;
+
+import java.io.IOException;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * Exception for unexpected response from or communication failure with the Kermi controller.
+ *
+ * @author Marco Descher - Initial contribution
+ */
+@NonNullByDefault
+public class KermiCommunicationException extends IOException {
+    private static final long serialVersionUID = 619020705591964155L;
+
+    public KermiCommunicationException(String message) {
+        super(message);
+    }
+
+    public KermiCommunicationException(Throwable ex) {
+        super(ex);
+    }
+
+    public KermiCommunicationException(String message, @Nullable Throwable cause) {
+        super(message, cause);
+    }
+}

bundles/org.openhab.binding.kermi/src/main/java/org/openhab/binding/kermi/internal/KermiThingHandlerFactory.java

@@ -0,0 +1,87 @@
+/**
+ * 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.kermi.internal;
+
+import static org.openhab.binding.kermi.internal.KermiBindingConstants.*;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.kermi.internal.api.KermiHttpUtil;
+import org.openhab.binding.kermi.internal.handler.KermiBaseThingHandler;
+import org.openhab.binding.kermi.internal.handler.KermiBridgeHandler;
+import org.openhab.binding.kermi.internal.model.KermiSiteInfo;
+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 KermiThingHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Marco Descher - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.kermi", service = ThingHandlerFactory.class)
+public class KermiThingHandlerFactory extends BaseThingHandlerFactory {
+
+    private KermiHttpUtil httpUtil;
+    private KermiSiteInfo kermiSiteInfo;
+
+    public KermiThingHandlerFactory() {
+        httpUtil = new KermiHttpUtil();
+        kermiSiteInfo = new KermiSiteInfo();
+    }
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = new HashSet<ThingTypeUID>() {
+
+        private static final long serialVersionUID = 1L;
+        {
+            add(THING_TYPE_BRIDGE);
+            add(THING_TYPE_HEATPUMP_MANAGER);
+            add(THING_TYPE_HEATPUMP);
+            add(THING_TYPE_DRINKINGWATER_HEATING);
+            add(THING_TYPE_ROOM_HEATING);
+        }
+    };
+
+    @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 (thingTypeUID.equals(THING_TYPE_BRIDGE)) {
+            return new KermiBridgeHandler((Bridge) thing, httpUtil, kermiSiteInfo);
+        } else if (thingTypeUID.equals(THING_TYPE_HEATPUMP_MANAGER)) {
+            return new KermiBaseThingHandler(thing, httpUtil, kermiSiteInfo);
+        } else if (thingTypeUID.equals(THING_TYPE_DRINKINGWATER_HEATING)) {
+            return new KermiBaseThingHandler(thing, httpUtil, kermiSiteInfo);
+        } else if (thingTypeUID.equals(THING_TYPE_HEATPUMP)) {
+            return new KermiBaseThingHandler(thing, httpUtil, kermiSiteInfo);
+        } else if (thingTypeUID.equals(THING_TYPE_ROOM_HEATING)) {
+            return new KermiBaseThingHandler(thing, httpUtil, kermiSiteInfo);
+        }
+
+        return null;
+    }
+}