[pilight] Pilight Binding initial contribution (openhab#9744)

Signed-off-by: Niklas Dörfler <niklas@doerfler-el.de>
Signed-off-by: John Marshall <john.marshall.au@gmail.com>

CODEOWNERS

@@ -209,6 +209,7 @@
 /bundles/org.openhab.binding.paradoxalarm/ @theater
 /bundles/org.openhab.binding.pentair/ @jsjames
 /bundles/org.openhab.binding.phc/ @gnlpfjh
+/bundles/org.openhab.binding.pilight/ @stefanroellin @niklasdoerfler
 /bundles/org.openhab.binding.pioneeravr/ @Stratehm
 /bundles/org.openhab.binding.pixometer/ @Confectrician
 /bundles/org.openhab.binding.pjlinkdevice/ @nils

bom/openhab-addons/pom.xml

@@ -1031,6 +1031,11 @@
  <artifactId>org.openhab.binding.phc</artifactId>
  <version>${project.version}</version>
  </dependency>
+ <dependency>
+ <groupId>org.openhab.addons.bundles</groupId>
+ <artifactId>org.openhab.binding.pilight</artifactId>
+ <version>${project.version}</version>
+ </dependency>
  <dependency>
  <groupId>org.openhab.addons.bundles</groupId>
  <artifactId>org.openhab.binding.pioneeravr</artifactId>

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

@@ -0,0 +1,119 @@
+# pilight Binding
+
+The pilight binding allows openHAB to communicate with a [pilight](http://www.pilight.org/) instance running pilight
+version 6.0 or greater.
+
+> pilight is a free open source full fledge domotica solution that runs on a Raspberry Pi, HummingBoard, BananaPi, 
+> Radxa, but also on *BSD and various linuxes (tested on Arch, Ubuntu and Debian). It's open source and freely available
+> for anyone. pilight works with a great deal of devices and is frequency independent. Therefor, it can control devices 
+> working at 315Mhz, 433Mhz, 868Mhz etc. Support for these devices are dependent on community, because we as developers 
+> don't own them all.
+
+pilight is a cheap way to control 'Click On Click Off' devices. It started as an application for the Raspberry Pi (using
+the GPIO interface) but it's also possible now to connect it to any other PC using an Arduino Nano. You will need a
+cheap 433Mhz transceiver in both cases. See the [Pilight manual](https://manual.pilight.org/electronics/wiring.html) for
+more information.
+
+## Supported Things
+
+| Thing | Type | Description |
+|-----------|--------|----------------------------------------------------------------------------|
+| `bridge` | Bridge | Pilight bridge required for the communication with the pilight daemon. |
+| `contact` | Thing | Pilight contact (read-only). |
+| `dimmer` | Thing | Pilight dimmer. |
+| `switch` | Thing | Pilight switch. |
+| `generic` | Thing | Pilight generic device for which you have to add the channels dynamically. |
+
+## Binding Configuration
+
+### `bridge` Thing
+
+A `bridge` is required for the communication with a pilight daemon. Multiple pilight instances are supported by creating
+different pilight `bridge` things.
+
+The `bridge` requires the following configuration parameters:
+
+| Parameter Label | Parameter ID | Description | Required |
+|-----------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| IP Address | ipAddress | Host name or IP address of the pilight daemon | yes |
+| Port | port | Port number on which the pilight daemon is listening. Default: 5000 | yes |
+| Delay | delay | Delay (in millisecond) between consecutive commands. Recommended value without band pass filter: 1000. Recommended value with band pass filter: somewhere between 200-500. Default: 500 | no |
+
+Important: you must explicitly configure the port in the pilight daemon config or otherwise a random port will be used
+and the binding will not be able to connect.
+
+### `contact`, `dimmer`, `switch`, `generic` Things
+
+These things have all one required parameter:
+
+| Parameter Label | Parameter ID | Description | Required |
+|-----------------|--------------|------------------------|----------|
+| Name | name | Name of pilight device | yes |
+
+## Channels
+
+The `bridge` thing has no channels.
+
+The `contact`, `dimmer` and `switch` things all have one channel:
+
+| Thing | Channel | Type | Description |
+|-----------|----------|---------|-------------------------|
+| `contact` | state | Contact | State of the contact |
+| `dimmer` | dimlevel | Dimmer | Dim level of the dimmer |
+| `switch` | state | Switch | State of the switch |
+
+The `generic` thing has no fixed channels, so you have to add them manually. Currently, only String and Number channels
+are supported.
+
+## Auto Discovery
+
+### Bridge Auto Discovery
+
+The pilight daemon implements a SSDP interface, which can be used to search for running pilight daemon instances by
+sending a SSDP request via multicast udp (this mechanism may only work if
+the [standalone mode](https://manual.pilight.org/configuration/settings.html#standalone) in the pilight daemon is
+disabled. After loading the binding this bridge discovery is automatically run and scheduled to scan for bridges every
+10 minutes.
+
+### Device Auto Discovery
+
+After a `bridge` thing has been configured in openHAB, it automatically establishes a connection between pilight daemon
+and openHAB. As soon as the bridge is connected, the devices configured in the pilight daemon are automatically found
+via autodiscovery in background (or via a manually triggered discovery) and are displayed in the inbox to easily create
+things from them.
+
+## Full Example
+
+things/pilight.things
+
+```
+Bridge pilight:bridge:raspi "Pilight Daemon raspi" [ ipAddress="192.168.1.1", port=5000 ] {
+ Thing switch office "Office" [ name="office" ]
+ Thing dimmer piano "Piano" [ name="piano" ]
+ Thing generic weather "Weather" [ name="weather" ] {
+ Channels:
+ State Number : temperature [ property="temperature"]
+ State Number : humidity [ property="humidity"]
+ }
+}
+```
+
+items/pilight.items
+
+```
+Switch office_switch "Büro" { channel="pilight:switch:raspi:office:state" }
+Dimmer piano_light "Klavier [%.0f %%]" { channel="pilight:dimmer:raspi:piano:dimlevel" }
+Number weather_temperature "Aussentemperatur [%.1f °C]" <temperature> { channel="pilight:generic:raspi:weather:temperature" }
+Number weather_humidity "Feuchtigkeit [%.0f %%]" <humidity> { channel="pilight:generic:raspi:weather:humidity" }
+
+```
+
+sitemaps/fragment.sitemap
+
+```
+Switch item=office_switch
+Slider item=piano_light
+Text item=weather_temperature 
+Text item=weather_humidity 
+```
+

bundles/org.openhab.binding.pilight/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 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>3.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.openhab.binding.pilight</artifactId>
+
+ <name>openHAB Add-ons :: Bundles :: Pilight Binding</name>
+
+</project>

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

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

bundles/org.openhab.binding.pilight/src/main/java/org/openhab/binding/pilight/internal/IPilightCallback.java

@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) 2010-2021 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.pilight.internal;
+
+import java.util.List;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.pilight.internal.dto.Config;
+import org.openhab.binding.pilight.internal.dto.Status;
+import org.openhab.binding.pilight.internal.dto.Version;
+import org.openhab.core.thing.ThingStatus;
+import org.openhab.core.thing.ThingStatusDetail;
+
+/**
+ * Callback interface to signal any listeners that an update was received from pilight
+ *
+ * @author Jeroen Idserda - Initial contribution
+ * @author Stefan Röllin - Port to openHAB 2 pilight binding
+ * @author Niklas Dörfler - Port pilight binding to openHAB 3 + add device discovery
+ */
+@NonNullByDefault
+public interface IPilightCallback {
+
+ /**
+ * Update thing status
+ *
+ * @param status status of thing
+ * @param statusDetail status detail of thing
+ * @param description description of thing status
+ */
+ void updateThingStatus(ThingStatus status, ThingStatusDetail statusDetail, @Nullable String description);
+
+ /**
+ * Update for one or more device received.
+ *
+ * @param allStatus list of Object containing list of devices that were updated and their current state
+ */
+ void statusReceived(List<Status> allStatus);
+
+ /**
+ * Configuration received.
+ *
+ * @param config Object containing configuration of pilight
+ */
+ void configReceived(Config config);
+
+ /**
+ * Version information received.
+ *
+ * @param version Object containing software version information of pilight daemon
+ */
+ void versionReceived(Version version);
+}

bundles/org.openhab.binding.pilight/src/main/java/org/openhab/binding/pilight/internal/PilightBindingConstants.java

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2010-2021 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.pilight.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link PilightBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Stefan Röllin - Initial contribution
+ * @author Niklas Dörfler - Port pilight binding to openHAB 3 + add device discovery
+ */
+@NonNullByDefault
+public class PilightBindingConstants {
+
+ public static final String BINDING_ID = "pilight";
+
+ // List of all Thing Type UIDs
+ public static final ThingTypeUID THING_TYPE_BRIDGE = new ThingTypeUID(BINDING_ID, "bridge");
+ public static final ThingTypeUID THING_TYPE_CONTACT = new ThingTypeUID(BINDING_ID, "contact");
+ public static final ThingTypeUID THING_TYPE_DIMMER = new ThingTypeUID(BINDING_ID, "dimmer");
+ public static final ThingTypeUID THING_TYPE_SWITCH = new ThingTypeUID(BINDING_ID, "switch");
+ public static final ThingTypeUID THING_TYPE_GENERIC = new ThingTypeUID(BINDING_ID, "generic");
+
+ // List of property names
+ public static final String PROPERTY_IP_ADDRESS = "ipAddress";
+ public static final String PROPERTY_PORT = "port";
+ public static final String PROPERTY_NAME = "name";
+
+ // List of all Channel ids
+ public static final String CHANNEL_STATE = "state";
+ public static final String CHANNEL_DIMLEVEL = "dimlevel";
+}

bundles/org.openhab.binding.pilight/src/main/java/org/openhab/binding/pilight/internal/PilightBridgeConfiguration.java

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2010-2021 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.pilight.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link PilightBridgeConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Stefan Röllin - Initial contribution
+ * @author Niklas Dörfler - Port pilight binding to openHAB 3 + add device discovery
+ */
+@NonNullByDefault
+public class PilightBridgeConfiguration {
+
+ private String ipAddress = "";
+ private int port = 0;
+ private int delay = 500;
+
+ public String getIpAddress() {
+ return ipAddress;
+ }
+
+ public void setIpAddress(String ipAddress) {
+ this.ipAddress = ipAddress;
+ }
+
+ public Integer getPort() {
+ return port;
+ }
+
+ public void setPort(Integer port) {
+ this.port = port;
+ }
+
+ public int getDelay() {
+ return delay;
+ }
+
+ public void setDelay(Integer delay) {
+ this.delay = delay;
+ }
+}

bundles/org.openhab.binding.pilight/src/main/java/org/openhab/binding/pilight/internal/PilightChannelConfiguration.java

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2010-2021 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.pilight.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link PilightChannelConfiguration} class contains fields mapping channel configuration parameters.
+ *
+ * @author Stefan Röllin - Initial contribution
+ * @author Niklas Dörfler - Port pilight binding to openHAB 3 + add device discovery
+ */
+@NonNullByDefault
+public class PilightChannelConfiguration {
+ private String property = "";
+
+ public String getProperty() {
+ return property;
+ }
+
+ public void setProperty(String property) {
+ this.property = property;
+ }
+}