[freeathomesystem] Initial contribution (openhab#13703)

Signed-off-by: Andras Uhrin <[email protected]>
matchews · Oct 18, 2024 · f5b54a6 · f5b54a6
1 parent fc1a100
commit f5b54a6
Show file tree

Hide file tree

Showing 38 changed files with 5,761 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -114,6 +114,7 @@
 /bundles/org.openhab.binding.folderwatcher/ @goopilot
 /bundles/org.openhab.binding.folding/ @fa2k
 /bundles/org.openhab.binding.foobot/ @airboxlab @Hilbrand
+/bundles/org.openhab.binding.freeathomesystem/ @andrasU
 /bundles/org.openhab.binding.freebox/ @lolodomo
 /bundles/org.openhab.binding.freeboxos/ @clinique
 /bundles/org.openhab.binding.freecurrency/ @J-N-K

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -561,6 +561,11 @@
       <artifactId>org.openhab.binding.foobot</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.freeathomesystem</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.freebox</artifactId>

diff --git a/bundles/org.openhab.binding.freeathomesystem/NOTICE b/bundles/org.openhab.binding.freeathomesystem/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.freeathomesystem/README.md b/bundles/org.openhab.binding.freeathomesystem/README.md
@@ -0,0 +1,143 @@
+# ABB/Busch-free@home Smart Home binding
+
+openHAB ABB/Busch-free@home binding based on the offical free@home local API.
+
+# Description
+
+This binding allows you to connect your free@home Smart Home system from ABB / Busch-Jaeger to openHAB and to control and observe most of the components.
+It requires a System Access Point with version 2.6.1 or higher.
+
+# Supported Devices
+
+**Network Gateway / System Access Point**
+
+ - ABB / Busch-Jaeger System Access Point 2.0
+
+**Sensors and Actuators**
+
+ - Switch Actuator Sensor with single and multiple channels (wired and wireless)
+ - Dimming Actuator Sensor with single and multiple channels (wired, wireless and flex)
+ - Motion detection with and without actuator (wired, wireless and flex)
+ - Switch Actuator 4-channel
+ - Dimming Actuator 4- and 6-channel
+ - Door opener actuator
+ - Door ring sensor
+ - Hue devices (untested)
+
+**Blinds and Windows**
+
+ - Shutter Actuator with single and multiple channels (wired and wireless)
+ - Blind Actuator  with single and multiple channels (wired and wireless)
+ - Attic window actuator
+ - Awning actuator
+
+**Room Temperature Control**
+
+ - Room temperature controller master without fan
+ - Room temperature controller master with fan
+ - Room temperature controller slave
+
+**Other devices** (e.g. movement detector, ring sensor and door opener)
+
+ - IP-touch panel (function: door opener, door ring sensor)
+ - Virtual devices (e.g. virtual switch, RTC and detectors)
+
+**Information about virtual devices**
+Virtual device in the free@home smart-home system needs continuous keep-alive signal otherwise the free@home device is marked as unresponsive.
+This keep-alive signal must be provided by a user script or set the TTL value of the virtual device to "-1" during the creation of the virtual device.
+
+# Tested SysAP Versions
+
+| Version | Supported |
+|---------|-----------|
+| 2.6.1   | yes       |
+| 2.6.3   | yes       |
+| 3.1.1   | yes       |
+
+# Setup / Installation
+
+## Prerequisites
+
+To make use of this Binding first the local free@home API has to be activated.
+The API is disabled by default.
+
+1. Open the free@home next app
+1. Browse to "Settings ⇨ free@home settings ⇨ local API and activate the checkbox
+
+## Setup and Discovery
+
+The free@home bridge shall be added manually.
+Once it is added as a Thing with correct credentials, the scan of free@home devices will be possible.
+
+## free@home components as openHAB Things
+
+The ABB/Busch free@home system is calling its smart home components as free@home devices.
+The free@home system devices can have one or multiple channels depending the device's features.
+During the scanning process the openHAB binding will detect only the devices IDs.
+The device features will be detected at the point in time, when a openHAB Thing is created.
+At the of the creation the free@home binding will automatically create the relevant channels without any further configuration.
+If a free@home system device has multiple smart-home channels (e.g. 4x DIN/rail Actuator), the newly created Thing will get all relevant channels to operate all actuators existing inside the free@home device.
+
+## Sensors and Actuators of free@home Devices as Things in openHAB
+
+The free@home system supports sensors and actuators.
+The connection of sensors and actuators are done on the free@home system dashboard.
+If a Thing channel is a free@home device sensor channel, this channel is read only.
+
+## Bridge Configuration
+
+There are several settings for a bridge:
+
+| Parameter                | Description                             |
+|--------------------------|-----------------------------------------|
+| **ipAddress** (required) | Network address of the free@home SysAP  |
+| **username** (required)  | Valid user name for the free@home SysAP |
+| **password** (required)  | Password of the user                    |
+
+## Examples for .things
+
+Things are all discovered automatically and visible on the openHAB UI after pushing the scan button
+
+In order to manually configure a Thing:
+
+```java
+Bridge freeathomesystem:bridge:mysysap [ ipAddress="...", username="...", password="..." ]
+{
+    Thing device    ABB700000001
+    Thing device    ABB700000012
+}
+```
+
+The only parameter needed to create a Thing is the free@home device ID, which you can find as sticker on the device.
+The creation of the openHAB channels to operate the free@home device is happening automatically based on the device features detected online.
+
+## Examples for .items
+
+Sample for the free@home thermostat device
+
+```java
+Switch Livingroom_Thermostat_Switch                       "Thermostat Siwtch"               <temperature>  (Livingroom)                              { channel="freeathomesystem:device:312095ad75:ABB700000001:ch0000#controller-on-off-request" }
+Switch LivingRoom_Thermostat_EcoOnOff                     "Thermostat Eco Activation"       <switch>       (Livingroom)                              { channel="freeathomesystem:device:312095ad75:ABB700000001:ch0000#eco-mode-on-off-request" }
+Number LivingRoom_Thermostat_MeasuredTemperature          "Measured Temperature"            <temperature>  (Livingroom)  ["Temperature"]             { channel="freeathomesystem:device:312095ad75:ABB700000001:ch0000#measured-temperature" }
+Number LivingRoom_Thermostat_SetpointTemperature          "Setpoint Temperature"            <temperature>  (Livingroom)  ["Setpoint", "Temperature"] { channel="freeathomesystem:device:312095ad75:ABB700000001:ch0000#absolute-setpoint-temperature" }
+Number LivingRoom_ThermostatHeatingActive                 "Thermostat Heating Active"       <temperature>  (Livingroom)  ["Status"]                  { channel="freeathomesystem:device:312095ad75:ABB700000001:ch0000#heating-active" }
+Number LivingRoom_ThermostatHeatingDemand                 "Thermostat Heating Demand"       <temperature>  (Livingroom)  ["Status"]                  { channel="freeathomesystem:device:312095ad75:ABB700000001:ch0000#status-indication" }
+```
+
+Sample for the free@home device for switch
+
+```java
+Switch Livingroom_Switch                    "Livingroom Switch"       <switch>  (Livingroom)  ["Light"]   { channel="freeathomesystem:device:312095ad75:ABB700000012:ch0000#switch-on-off" }
+Switch Livingroom_Lamp                      "Livingroom Lamp"         <switch>  (Livingroom)  ["Light"]   { channel="freeathomesystem:device:312095ad75:ABB700000012:ch0006#switch-on-off" }
+Switch Livingroom_Aux                       "Livingroom Aux Switch"   <switch>  (Livingroom)  ["Light"]   { channel="freeathomesystem:device:312095ad75:ABB700000012:ch000b#switch-on-off" }
+```
+
+# Communities
+
+[openHAB community of this binding](https://community.openhab.org/t/abb-busch-jager-free-home-official-rest-api/141698)
+
+[Busch-Jaeger Community](https://community.busch-jaeger.de/)
+
+[free@home user group Facebook DE](https://www.facebook.com/groups/738242583015188)
+
+[free@home user group Facebook EN](https://www.facebook.com/groups/452502972031360)
diff --git a/bundles/org.openhab.binding.freeathomesystem/pom.xml b/bundles/org.openhab.binding.freeathomesystem/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 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.freeathomesystem</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: FreeAtHomeSystem Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.freeathomesystem/src/main/feature/feature.xml b/bundles/org.openhab.binding.freeathomesystem/src/main/feature/feature.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.freeathomesystem-${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-freeathomesystem" description="FreeAtHomeSystem Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.freeathomesystem/${project.version}</bundle>
+	</feature>
+</features>
diff --git a/.../java/org/openhab/binding/freeathomesystem/internal/FreeAtHomeSystemBindingConstants.java b/.../java/org/openhab/binding/freeathomesystem/internal/FreeAtHomeSystemBindingConstants.java
@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2010-2024 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.freeathomesystem.internal;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link FreeAtHomeSystemBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Andras Uhrin - Initial contribution
+ */
+@NonNullByDefault
+public class FreeAtHomeSystemBindingConstants {
+
+    public static final String CONFIG_DESCRIPTION_URI_THING_PREFIX = "thing-type";
+
+    public static final String BINDING_ID = "freeathomesystem";
+
+    // List of all Thing Type UIDs
+    public static final String BRIDGE_TYPE_ID = "gateway";
+    public static final String DEVICE_TYPE_ID = "device";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID BRIDGE_TYPE_UID = new ThingTypeUID(BINDING_ID, BRIDGE_TYPE_ID);
+    public static final ThingTypeUID DEVICE_TYPE_UID = new ThingTypeUID(BINDING_ID, DEVICE_TYPE_ID);
+
+    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(BRIDGE_TYPE_UID, DEVICE_TYPE_UID);
+}
diff --git a/.../java/org/openhab/binding/freeathomesystem/internal/FreeAtHomeSystemDiscoveryService.java b/.../java/org/openhab/binding/freeathomesystem/internal/FreeAtHomeSystemDiscoveryService.java
@@ -0,0 +1,136 @@
+/**
+ * Copyright (c) 2010-2024 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.freeathomesystem.internal;
+
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.TimeUnit;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.freeathomesystem.internal.datamodel.FreeAtHomeDeviceDescription;
+import org.openhab.binding.freeathomesystem.internal.handler.FreeAtHomeBridgeHandler;
+import org.openhab.binding.freeathomesystem.internal.util.FreeAtHomeHttpCommunicationException;
+import org.openhab.core.config.discovery.AbstractThingHandlerDiscoveryService;
+import org.openhab.core.config.discovery.DiscoveryResult;
+import org.openhab.core.config.discovery.DiscoveryResultBuilder;
+import org.openhab.core.thing.ThingTypeUID;
+import org.openhab.core.thing.ThingUID;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The {@link FreeAtHomeSystemDiscoveryService} is responsible for performing discovery of things
+ *
+ * @author Andras Uhrin - Initial contribution
+ */
+@NonNullByDefault
+public class FreeAtHomeSystemDiscoveryService extends AbstractThingHandlerDiscoveryService<FreeAtHomeBridgeHandler> {
+
+    private final Logger logger = LoggerFactory.getLogger(FreeAtHomeSystemDiscoveryService.class);
+    private @Nullable ScheduledFuture<?> backgroundDiscoveryJob = null;
+
+    private static final long BACKGROUND_DISCOVERY_DELAY = 1L;
+    private boolean isScanTerminated;
+
+    Runnable runnable = new Runnable() {
+        @Override
+        public void run() {
+            ThingUID bridgeUID = thingHandler.getThing().getUID();
+
+            List<String> deviceList;
+
+            try {
+                deviceList = thingHandler.getDeviceDeviceList();
+
+                for (int i = 0; (i < deviceList.size()) && !isScanTerminated; i++) {
+                    FreeAtHomeDeviceDescription device = thingHandler.getFreeatHomeDeviceDescription(deviceList.get(i));
+
+                    ThingUID uid = new ThingUID(FreeAtHomeSystemBindingConstants.DEVICE_TYPE_UID, bridgeUID,
+                            device.deviceId);
+                    Map<String, Object> properties = new HashMap<>(1);
+                    properties.put("deviceId", device.deviceId);
+                    properties.put("interface", device.interfaceType);
+
+                    String deviceLabel = device.deviceLabel;
+
+                    DiscoveryResult discoveryResult = DiscoveryResultBuilder.create(uid).withLabel(deviceLabel)
+                            .withRepresentationProperty("deviceId").withBridge(bridgeUID).withProperties(properties)
+                            .build();
+
+                    thingDiscovered(discoveryResult);
+
+                    logger.debug("Thing discovered - DeviceId: {} - Device label: {}", device.getDeviceId(),
+                            device.getDeviceLabel());
+                }
+
+                stopScan();
+            } catch (FreeAtHomeHttpCommunicationException e) {
+                logger.debug("Communication error in device discovery with the bridge: {}",
+                        thingHandler.getThing().getLabel());
+            } catch (RuntimeException e) {
+                logger.debug("Scanning interrupted");
+            }
+        }
+    };
+
+    public FreeAtHomeSystemDiscoveryService(int timeout) {
+        super(FreeAtHomeBridgeHandler.class, FreeAtHomeSystemBindingConstants.SUPPORTED_THING_TYPES_UIDS, timeout,
+                false);
+    }
+
+    public FreeAtHomeSystemDiscoveryService() {
+        this(90);
+    }
+
+    @Override
+    public Set<ThingTypeUID> getSupportedThingTypes() {
+        return Set.of(FreeAtHomeSystemBindingConstants.BRIDGE_TYPE_UID);
+    }
+
+    @Override
+    protected void startScan() {
+        if (backgroundDiscoveryJob == null) {
+            this.removeOlderResults(Instant.now().toEpochMilli());
+
+            isScanTerminated = false;
+            backgroundDiscoveryJob = scheduler.schedule(runnable, BACKGROUND_DISCOVERY_DELAY, TimeUnit.SECONDS);
+        }
+    }
+
+    @Override
+    protected synchronized void stopScan() {
+        super.stopScan();
+
+        isScanTerminated = true;
+
+        ScheduledFuture<?> localDiscoveryJob = backgroundDiscoveryJob;
+
+        if (localDiscoveryJob != null) {
+            localDiscoveryJob.cancel(true);
+        }
+
+        backgroundDiscoveryJob = null;
+
+        removeOlderResults(Instant.now().toEpochMilli());
+    }
+
+    @Override
+    public void deactivate() {
+        removeOlderResults(Instant.now().toEpochMilli());
+    }
+}