Initial contribution of a Niko Home Control binding. (openhab#1589)

* Initial contribution of Niko Home Control binding. Signed-off-by: Mark Herwege <[email protected]>
jsjames · Jul 1, 2017 · 793c8eb · 793c8eb
1 parent a68cc1a
commit 793c8eb
Show file tree

Hide file tree

Showing 29 changed files with 2,357 additions and 0 deletions.
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/.classpath b/addons/binding/org.openhab.binding.nikohomecontrol/.classpath
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8"/>
+	<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
+	<classpathentry kind="src" path="src/main/java"/>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/.project b/addons/binding/org.openhab.binding.nikohomecontrol/.project
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.nikohomecontrol</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ManifestBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.SchemaBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ds.core.builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.pde.PluginNature</nature>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+	</natures>
+</projectDescription>
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/ESH-INF/binding/binding.xml b/addons/binding/org.openhab.binding.nikohomecontrol/ESH-INF/binding/binding.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<binding:binding id="nikohomecontrol" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xmlns:binding="http://eclipse.org/smarthome/schemas/binding/v1.0.0"
+	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/binding/v1.0.0 http://eclipse.org/smarthome/schemas/binding-1.0.0.xsd">
+
+	<name>Niko Home Control Binding</name>
+	<description>This is the binding for the Niko Home Control system</description>
+	<author>Mark Herwege</author>
+
+</binding:binding>
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/ESH-INF/thing/thing-types.xml b/addons/binding/org.openhab.binding.nikohomecontrol/ESH-INF/thing/thing-types.xml
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<thing:thing-descriptions bindingId="nikohomecontrol" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xmlns:thing="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0"
+	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0 http://eclipse.org/smarthome/schemas/thing-description-1.0.0.xsd"><!--Niko Home Control Gateway Bridge Type -->
+
+	<bridge-type id="bridge">
+		<label>Niko Home Control Bridge</label>
+		<description>This bridge represents a Niko Home Control IP-interface</description>
+		<config-description>
+			<parameter name="addr" type="text" required="true">
+				<label>IP or Host Name</label>
+				<description>IP Address of Niko Home Control IP-interface</description>
+				<advanced>false</advanced>
+				<context>network-address</context>
+			</parameter>
+			<parameter name="port" type="integer" required="false">
+				<label>Bridge port</label>
+				<description>Port to communicate with Niko Home Control IP-interface, default 8000</description>
+				<default>8000</default>
+				<advanced>true</advanced>
+			</parameter>
+			<parameter name="refresh" type="integer" required="false">
+				<label>Refresh interval</label>
+				<description>Refresh interval for connection with Niko Home Control IP-interface (min), default 300. If set to 0 or left empty, no refresh will be scheduled</description>
+				<default>300</default>
+				<advanced>true</advanced>
+			</parameter>
+		</config-description>
+	</bridge-type>
+
+	<thing-type id="onOff">
+		<supported-bridge-type-refs>
+			<bridge-type-ref id="bridge" />
+		</supported-bridge-type-refs>
+		<label>Switch</label>
+		<description>On/Off type action in Niko Home Control</description>
+		<channels>
+			<channel id="switch" typeId="switch" />
+		</channels>
+		<config-description>
+			<parameter name="actionId" type="integer" required="true">
+				<label>Action ID</label>
+				<description>Niko Home Control IP Interface Object ID</description>
+				<advanced>false</advanced>
+			</parameter>
+		</config-description>
+	</thing-type>
+	<thing-type id="dimmer">
+		<supported-bridge-type-refs>
+			<bridge-type-ref id="bridge" />
+		</supported-bridge-type-refs>
+		<label>Dimmer</label>
+		<description>Dimmer type actions in Niko Home Control</description>
+		<channels>
+			<channel id="brightness" typeId="brightness" />
+		</channels>
+		<config-description>
+			<parameter name="actionId" type="integer" required="true">
+				<label>Action ID</label>
+				<description>Niko Home Control IP Interface Object ID</description>
+				<advanced>false</advanced>
+			</parameter>
+			<parameter name="step" type="integer" required="true">
+				<label>Step value</label>
+				<description>Step value used for increase/decrease of dimmer brightness, default 10%</description>
+				<default>10</default>
+				<advanced>true</advanced>
+			</parameter>
+		</config-description>
+	</thing-type>
+	<thing-type id="blind">
+		<supported-bridge-type-refs>
+			<bridge-type-ref id="bridge" />
+		</supported-bridge-type-refs>
+		<label>Shutter</label>
+		<description>Rollershutter type actions in Niko Home Control</description>
+		<channels>
+			<channel id="rollershutter" typeId="rollershutter" />
+		</channels>
+		<config-description>
+			<parameter name="actionId" type="integer" required="true">
+				<label>Action ID</label>
+				<description>Niko Home Control IP Interface Object ID</description>
+				<advanced>false</advanced>
+			</parameter>
+		</config-description>
+	</thing-type>
+
+	<channel-type id="switch">
+		<item-type>Switch</item-type>
+		<label>Switch</label>
+		<description>Switch control for action in Niko Home Control</description>
+		<category>Switch</category>
+	</channel-type>
+	<channel-type id="brightness">
+		<item-type>Dimmer</item-type>
+		<label>Brightness</label>
+		<description>Brightness control for dimmer action in Niko Home Control</description>
+		<category>DimmableLight</category>
+	</channel-type>
+	<channel-type id="rollershutter">
+		<item-type>Rollershutter</item-type>
+		<label>Rollershutter</label>
+		<description>Rollershutter control for rollershutter action in Niko Home Control</description>
+		<category>Blinds</category>
+	</channel-type>
+
+</thing:thing-descriptions>
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/META-INF/MANIFEST.MF b/addons/binding/org.openhab.binding.nikohomecontrol/META-INF/MANIFEST.MF
@@ -0,0 +1,25 @@
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: Niko Home Control Binding
+Bundle-SymbolicName: org.openhab.binding.nikohomecontrol;singleton:=true
+Bundle-Vendor: openHAB
+Bundle-Version: 2.1.0.qualifier
+Bundle-RequiredExecutionEnvironment: JavaSE-1.8
+Bundle-ClassPath: .
+Import-Package: 
+ com.google.common.collect,
+ com.google.gson,
+ com.google.gson.stream,
+ org.eclipse.smarthome.config.core,
+ org.eclipse.smarthome.config.discovery,
+ org.eclipse.smarthome.core.library.types,
+ org.eclipse.smarthome.core.thing,
+ org.eclipse.smarthome.core.thing.binding,
+ org.eclipse.smarthome.core.types,
+ org.openhab.binding.nikohomecontrol,
+ org.openhab.binding.nikohomecontrol.handler,
+ org.osgi.framework,
+ org.slf4j
+Service-Component: OSGI-INF/*.xml
+Export-Package: org.openhab.binding.nikohomecontrol,
+ org.openhab.binding.nikohomecontrol.handler
diff --git a/...s/binding/org.openhab.binding.nikohomecontrol/OSGI-INF/NikoHomeControlBridgeDiscovery.xml b/...s/binding/org.openhab.binding.nikohomecontrol/OSGI-INF/NikoHomeControlBridgeDiscovery.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2010-2017 by the respective copyright holders.
+
+    All rights reserved. This program and the accompanying materials
+    are made available under the terms of the Eclipse Public License v1.0
+    which accompanies this distribution, and is available at
+    http://www.eclipse.org/legal/epl-v10.html
+
+-->
+<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="org.openhab.binding.nikohomecontrol.internal.discovery.NikoHomeControlBridgeDiscoveryService">
+    <implementation class="org.openhab.binding.nikohomecontrol.internal.discovery.NikoHomeControlBridgeDiscoveryService"/>
+    <service>
+        <provide interface="org.eclipse.smarthome.config.discovery.DiscoveryService"/>
+    </service>
+</scr:component>
diff --git a/...ns/binding/org.openhab.binding.nikohomecontrol/OSGI-INF/NikoHomeControlHandlerFactory.xml b/...ns/binding/org.openhab.binding.nikohomecontrol/OSGI-INF/NikoHomeControlHandlerFactory.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2010-2017 by the respective copyright holders.
+
+    All rights reserved. This program and the accompanying materials
+    are made available under the terms of the Eclipse Public License v1.0
+    which accompanies this distribution, and is available at
+    http://www.eclipse.org/legal/epl-v10.html
+
+-->
+<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="openhab.binding.nikohomecontrol.internal.NikoHomeControlHandlerFactory">
+    <implementation class="org.openhab.binding.nikohomecontrol.internal.NikoHomeControlHandlerFactory"/>
+    <service>
+        <provide interface="org.eclipse.smarthome.core.thing.binding.ThingHandlerFactory"/>
+    </service>
+</scr:component>
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/README.md b/addons/binding/org.openhab.binding.nikohomecontrol/README.md
@@ -0,0 +1,133 @@
+# Niko Home Control Binding
+
+The Niko Home Control binding integrates with a [Niko Home Control](http://www.nikohomecontrol.be/) system through a Niko Home Control IP-interface.
+
+The binding has been tested with a Niko Home Control IP-interface (550-00508). This IP-interface provides access on the LAN. The binding does 
+not require a Niko Home Control Gateway (550-00580), but does work with it in the LAN. It will not make a remote connection.
+It has also been confirmed to work with the Niko Home Control Connected Controller (550-00003).
+
+The binding exposes all actions from the Niko Home Control System that can be triggered from the smartphone/tablet interface, as defined in the Niko Home Control programming software.
+
+## Supported Things
+
+The Niko Home Control Controller is represented as a bridge in the binding.
+Connected to a bridge, the Niko Home Control Binding supports on/off actions (e.g. for lights or groups of lights), dimmers and rollershutters or blinds.
+
+## Binding Configuration
+
+The bridge representing the Niko Home Control IP-interface needs to be added first in the things file or through Paper UI. A bridge can be auto-discovered or created manually. No bridge configuration is required when using auto-discovery.
+
+The IP-address and port can be set when manually creating the bridge.
+
+If the IP-address is set, no attempt will be made to discover the correct IP-address. You are responsible to force a fixed IP address on the Niko Home Control IP-interface through settings in your DHCP server.
+
+The port is set to 8000 by default and should match the port used by the Niko Home Control IP-interface.
+
+An optional refresh interval will be used to restart the bridge at regular intervals (every 300 minutes by default). Restarting the bridge at regular times improves the connection stability and avoids loss of connection. It can be turned off completely. 
+
+## Discovery
+
+A discovery scan will first discover the Niko Home Control IP-interface in the network as a bridge. Default parameters will be used. Note that this may fail to find the correct Niko Home Control IP-interface when there are multiple IP-interfaces in the network.
+
+When the Niko Home Control bridge is added as a thing, from the discovery inbox or manually, system information will be read from the Niko Home Control Controller and will be put in the bridge properties, visible through Paper UI.
+
+Subsequently, all defined actions that can be triggered from a smartphone/tablet in the Niko Home Control system will be discovered and put in the inbox.
+It is possible to trigger a manual scan for things on the Niko Home Control bridge.
+
+If the Niko Home Control system has locations configured, these will be copied to thing locations and grouped as such in PaperUI.
+
+## Thing Configuration
+
+Besides using PaperUI to manually configure things or adding automatically discovered things through PaperUI, you can add thing definitions in the things file.
+
+The Thing configuration for the bridge uses the following syntax:
+
+```
+Bridge nikohomecontrol:bridge:<bridgeId> [ addr="<IP-address of IP-interface>", port=<listening port>,
+                                           refresh="<Refresh interval>" ]
+```
+
+`bridgeId` can have any value.
+
+`addr` is the fixed Niko Home Control IP-interface address and is required. `port` will be the port used to connect and is 8000 by default. `refresh` is the interval to restart the communication in minutes (300 by default), if 0 or omitted the connection will not restart at regular intervals.
+
+The thing configuration for the actions has the following syntax:
+
+```
+Thing nikohomecontrol:<thing type>:<bridgeId>:<thingId>
+                        [ actionId=<Niko Home Control action ID>,
+                          step=<dimmer increase/decrease step value> ]
+```
+
+or nested in the bridge configuration:
+
+```
+<thing type> <thingId> [ actionId=<Niko Home Control action ID>,
+                         step=<dimmer increase/decrease step value> ]
+```
+                               
+The following thing types are valid for configuration:
+
+```
+onOff, dimmer, blind
+```
+
+`thingId` can have any value, but will be set to the same value as the actionId parameter if discovery is used.
+
+The `actionId` parameter is the unique ip Interface Object ID (`ipInterfaceObjectId`) as automatically assigned in the Niko Home Control Controller when programming the Niko Home Control system using the Niko Home Control programming software. It is not directly visible in the Niko Home Control programming or user software, but will be detected and automatically set by openHAB discovery. For textual configuration, you can be manually retrieve it from the content of the .nhcp configuration file created by the programming software. Open the file with an unzip tool to read it's content.
+
+The `step` parameter is only available for dimmers. It sets a step value for dimmer increase/decrease actions. The parameter is optional and set to 10 by default.
+
+## Channels
+
+For thing type `onOff` the supported channel is `switch`. OnOff command types are supported.
+
+For thing type `dimmer` the supported channel is `brightness`. OnOff, IncreaseDecrease and Percent command types are supported. Note that sending an ON command will switch the dimmer to the value stored when last turning the dimmer off, or 100% depending on the configuration in the Niko Home Control Controller. This can be changed with the Niko Home Control programming software.
+
+For thing type `blind` the supported channel is `rollershutter`. UpDown, StopMove and Percent command types are supported.
+
+
+## Limitations
+
+The binding has been tested with a Niko Home Control IP-interface (550-00508) and the Niko Home Control Connected Controller (550-00003).
+
+The action events implemented are limited to onOff, dimmer and rollershutter or blinds. Other actions have not been implemented.
+
+It is not possible to tilt the slats of venetian blinds.
+
+Beyond action events, the Niko Home Control communication also supports thermostats, electricity usage data and alarms. This has not been implemented.
+
+## Example
+
+.things:
+
+```
+Bridge nikohomecontrol:bridge:nhc1 [ addr="192.168.0.70", port=8000, refresh=300 ] {
+    onOff 1 [ actionId=1 ]
+    dimmer 2 [ actionId=2, step=5 ]
+    blind 3 [ actionId=3 ]
+}
+
+Bridge nikohomecontrol:bridge:nhc2 [ addr="192.168.0.110" ] {
+    onOff 11 [ actionId=11 ]
+    dimmer 12 [ actionId=12, step=5 ]
+    blind 13 [ actionId=13 ]
+}
+```
+
+.items:
+
+```
+Switch LivingRoom       {channel="nikohomecontrol:onOff:nhc1:1#switch"}          # Switch for onOff type action
+Dimmer TVRoom           {channel="nikohomecontrol:dimmer:nhc1:2#brightness"}     # Changing brightness dimmer type action
+Rollershutter Kitchen   {channel="nikohomecontrol:blind:nhc1:3#rollershutter"}   # Controlling rollershutter or blind type action
+```
+
+.sitemap:
+
+```
+Switch item=LivingRoom
+Slider item=TVRoom
+Switch item=TVRoom          # allows switching dimmer item off or on (with controller defined behavior)
+Rollershutter item=Kitchen
+```
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/about.html b/addons/binding/org.openhab.binding.nikohomecontrol/about.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+<title>About</title>
+</head>
+<body lang="EN-US">
+<h2>About This Content</h2>
+
+<p>April 24, 2017</p> 
+<h3>License</h3>
+
+<p>The openHAB community makes available all content in this plug-in (&quot;Content&quot;).  Unless otherwise 
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 (&quot;EPL&quot;).  A copy of the EPL is available 
+at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+For purposes of the EPL, &quot;Program&quot; will mean the Content.</p>
+
+<p>If you did not receive this Content directly from the openHAB community, the Content is 
+being redistributed by another party (&quot;Redistributor&quot;) and different terms and conditions may
+apply to your use of any object code in the Content.  Check the Redistributor's license that was 
+provided with the Content.  If no such license exists, contact the Redistributor.  Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at <a href="http://www.openhab.org/">openhab.org</a>.</p>
+
+</body>
+</html>
diff --git a/addons/binding/org.openhab.binding.nikohomecontrol/build.properties b/addons/binding/org.openhab.binding.nikohomecontrol/build.properties
@@ -0,0 +1,7 @@
+source.. = src/main/java/
+output.. = target/classes
+bin.includes = META-INF/,\
+               .,\
+               OSGI-INF/,\
+               ESH-INF/,\
+               about.html