UPB Binding

Signed-off-by: Marcus Better <marcus@better.se>

CODEOWNERS

@@ -182,6 +182,7 @@
 /bundles/org.openhab.binding.tplinksmarthome/ @Hilbrand
 /bundles/org.openhab.binding.tradfri/ @cweitkamp @kaikreuzer
 /bundles/org.openhab.binding.unifi/ @mgbowman
+/bundles/org.openhab.binding.upb/ @marcusb
 /bundles/org.openhab.binding.urtsi/ @OLibutzki
 /bundles/org.openhab.binding.valloxmv/ @bjoernbrings
 /bundles/org.openhab.binding.vektiva/ @octa22

bom/openhab-addons/pom.xml

@@ -899,6 +899,11 @@
       <artifactId>org.openhab.binding.unifi</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.upb</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.urtsi</artifactId>

bundles/org.openhab.binding.upb/.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="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="test" 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 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>

bundles/org.openhab.binding.upb/.project

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.upb</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>

bundles/org.openhab.binding.upb/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/openhab2-addons

bundles/org.openhab.binding.upb/README.md

@@ -0,0 +1,100 @@
+# UPB Binding
+
+Universal Powerline Bus (UPB) is a protocol for communication over household electrical wiring.
+
+## Supported Things
+
+The binding has not yet been tested with a variety of devices, so specific device support is limited.
+Instead the binding provides some generic devices, and allows adding channels that match the type of device.
+
+* `serial-pim` - Serial PIM
+* `generic` - Generic UPB device
+* `virtual` - "Virtual" device that allows scene selection
+
+Specific devices that are supported:
+
+ * `leviton-38a00-1` - 6-button scene switch
+
+## Binding Configuration
+
+The following binding configuration parameters are supported:
+
+| Parameter                | Description                                    | Config   | Default |
+| ------------------------ | ---------------------------------------------- |--------- | ------- |
+| networkId                | Default UPB network ID (0-255)                 | Optional | -       |
+
+## Thing Configuration
+
+### Serial PIM
+
+You need a Powerline Interface Module (PIM) for the binding to work. This is a piece of equipment
+that connects a computer to the powerline. There are a few different PIM interfaces but this binding
+only supports serial PIMs
+
+The `serial-pim` takes the following configuration parameters:
+
+| Parameter                | Description                                    | Config   | Default |
+| ------------------------ | ---------------------------------------------- |--------- | ------- |
+| port                     | Serial port where the PIM is connected         | Required | -       |
+
+### Generic device
+
+The `generic` thing type supports most UPB devices such as dimmers, light switches,
+and appliance modules. It has the following configuration parameters:
+
+| Parameter                | Description                                    | Config   | Default |
+| ------------------------ | ---------------------------------------------- |--------- | ------- |
+| networkId                | ID of the UPB network (0-255)                  | Optional | binding config |
+| unitId                   | Unit ID (unique address) of the device (1-250) | Required | -       |
+
+### Virtual device
+
+The `virtual` pseudo-device does not correspond to any real device on the UPB network. It is
+nevertheless useful for reading and setting the current scene. The device has two channels,
+`linkActivated` and `linkDeactivated`. If a device on the UPB network activates or de-activates
+a scene by broadcasting a link activation command, the link ID (or scene number) can be read from
+the corresponding channel. Similarly, updating the channel with a link ID will send out the
+corresponding link command on the UPB network.
+
+## Channels
+
+
+These channels are available for generic devices:
+
+| Channel Type | Item type | Description                                     |
+| ------------ | --------- | ----------------------------------------------- |
+| switch       | Switch    | On/off switch for lights and appliance switches |
+| dimmer       | Dimmer    | Dimmer brightness                               |
+| scene-selection | -      | Trigger channel for scene selection             |
+
+The virtual device supports the `link` channel type:
+| Channel Type | Item type | Description                            |
+| ------------ | --------- | -------------------------------------- |
+| link         | Number    | A scene to activate or deactivate      |
+
+## Full Example
+
+Here is a sample `.things configuration file:
+
+```
+Bridge upb:serial-pim:pim "UPB PIM" @ "Basement" [port="/dev/ttyUSB0"] {
+  Thing generic light-switch "Living Room Light" [networkId=1, unitId=1] {
+    Channels:
+      Type switch : power
+      Type dimmer : level
+  }
+
+  Thing virtual upb-scene "UPB Scene Control" [networkId=1, unitId=250]
+
+  Thing leviton-38a00-1 scene-switch "Scene Switch" @ "Bedroom" [networkId=1, unitId=2] {
+    Channels:
+      Type scene-selection : btnOn [linkId=1]
+      Type scene-selection : btnOff [linkId=2]
+      Type scene-selection : btnA [linkId=3]
+      Type scene-selection : btnB [linkId=4]
+      Type scene-selection : btnC [linkId=5]
+      Type scene-selection : btnD [linkId=6]
+  }
+}
+
+```

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

@@ -0,0 +1,16 @@
+<?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>2.5.1-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.upb</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: UPB Binding</name>
+
+</project>

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

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.upb-${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-upb" description="UPB 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.upb/${project.version}</bundle>
+    </feature>
+</features>

bundles/org.openhab.binding.upb/src/main/java/org/openhab/binding/upb/Constants.java

@@ -0,0 +1,54 @@
+/**
+ * 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.upb;
+
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+import org.eclipse.smarthome.core.thing.type.ChannelTypeUID;
+
+/**
+ * Common constants used in the binding.
+ *
+ * @author Marcus Better - Initial contribution
+ */
+public final class Constants {
+    public static final String BINDING_ID = "upb";
+    public static final ThingTypeUID PIM_UID = new ThingTypeUID(BINDING_ID, "serial-pim");
+    public static final ThingTypeUID GENERIC_DEVICE_UID = new ThingTypeUID(BINDING_ID, "generic");
+    public static final ThingTypeUID VIRTUAL_DEVICE_UID = new ThingTypeUID(BINDING_ID, "virtual");
+    public static final ThingTypeUID LEVITON_38A00_1_UID = new ThingTypeUID(BINDING_ID, "leviton-38a00-1");
+    public static final String SCENE_CHANNEL_TYPE_ID = "scene-selection";
+    public static final String LINK_CHANNEL_TYPE_ID = "link";
+    public static final String SWITCH_TYPE_ID = "switch";
+    public static final String DIMMER_TYPE_ID = "dimmer";
+    public static final ChannelTypeUID SCENE_CHANNEL_TYPE_UID = new ChannelTypeUID(BINDING_ID, SCENE_CHANNEL_TYPE_ID);
+    public static final ChannelTypeUID LINK_CHANNEL_TYPE_UID = new ChannelTypeUID(BINDING_ID, LINK_CHANNEL_TYPE_ID);
+    public static final String LINK_ACTIVATE_CHANNEL_ID = "linkActivated";
+    public static final String LINK_DEACTIVATE_CHANNEL_ID = "linkDeactivated";
+
+    public static final String CONFIGURATION_PORT = "port";
+    public static final String CONFIGURATION_UNIT_ID = "unitId";
+    public static final String CONFIGURATION_NETWORK_ID = "networkId";
+    public static final String CONFIGURATION_LINK_ID = "linkId";
+
+    public static final String OFFLINE_CTLR_OFFLINE = "@text/upb.thingstate.controller_offline";
+    public static final String OFFLINE_NODE_DEAD = "@text/upb.thingstate.node_dead";
+    public static final String OFFLINE_NODE_NOTFOUND = "@text/upb.thingstate.node_notfound";
+    public static final String OFFLINE_SERIAL_EXISTS = "@text/upb.thingstate.serial_notfound";
+    public static final String OFFLINE_SERIAL_INUSE = "@text/upb.thingstate.serial_inuse";
+    public static final String OFFLINE_SERIAL_UNSUPPORTED = "@text/upb.thingstate.serial_unsupported";
+    public static final String OFFLINE_SERIAL_LISTENERS = "@text/upb.thingstate.serial_listeners";
+
+    private Constants() {
+        // static class
+    }
+}

bundles/org.openhab.binding.upb/src/main/java/org/openhab/binding/upb/UPBDevice.java

@@ -0,0 +1,57 @@
+/**
+ * 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.upb;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * A device on the UPB network.
+ *
+ * @author Marcus Better - Initial contribution
+ *
+ */
+@NonNullByDefault
+public class UPBDevice {
+    private final byte networkId;
+    private final byte unitId;
+
+    private DeviceState state = DeviceState.INITIALIZING;
+
+    public enum DeviceState {
+        INITIALIZING,
+        ALIVE,
+        DEAD,
+        FAILED
+    }
+
+    public UPBDevice(final byte networkId, final byte unitId) {
+        this.networkId = networkId;
+        this.unitId = unitId;
+    }
+
+    public byte getNetworkId() {
+        return networkId;
+    }
+
+    public byte getUnitId() {
+        return unitId;
+    }
+
+    public DeviceState getState() {
+        return state;
+    }
+
+    public void setState(final DeviceState state) {
+        this.state = state;
+    }
+}

bundles/org.openhab.binding.upb/src/main/java/org/openhab/binding/upb/handler/MessageListener.java

@@ -0,0 +1,25 @@
+/**
+ * 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.upb.handler;
+
+import org.openhab.binding.upb.internal.message.UPBMessage;
+
+/**
+ * Callback interface for received UPB messages.
+ *
+ * @author Marcus Better - Initial contribution
+ *
+ */
+public interface MessageListener {
+    void incomingMessage(UPBMessage msg);
+}