Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[plugwiseha] Initial contribution #6775

Closed
wants to merge 1 commit into from
Closed

[plugwiseha] Initial contribution #6775

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
49 changes: 49 additions & 0 deletions bundles/org.openhab.binding.plugwiseha/.classpath
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<?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="src" path="target/generated-sources/annotations">
<attributes>
<attribute name="optional" value="true"/>
<attribute name="maven.pomderived" value="true"/>
<attribute name="ignore_optional_problems" value="true"/>
<attribute name="m2e-apt" value="true"/>
</attributes>
</classpathentry>
<classpathentry kind="src" output="target/test-classes" path="target/generated-test-sources/test-annotations">
<attributes>
<attribute name="optional" value="true"/>
<attribute name="maven.pomderived" value="true"/>
<attribute name="ignore_optional_problems" value="true"/>
<attribute name="m2e-apt" value="true"/>
<attribute name="test" value="true"/>
</attributes>
</classpathentry>
<classpathentry kind="output" path="target/classes"/>
</classpath>
23 changes: 23 additions & 0 deletions bundles/org.openhab.binding.plugwiseha/.project
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>org.openhab.binding.plugwiseha</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>
13 changes: 13 additions & 0 deletions bundles/org.openhab.binding.plugwiseha/NOTICE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
138 changes: 138 additions & 0 deletions bundles/org.openhab.binding.plugwiseha/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# PlugwiseHA Binding

The Plugwise Home Automation binding adds support to openHAB for the [Plugwise Home Automation ecosystem](https://www.plugwise.com/en_US/adam_zone_control). This system is built around a gateway from Plugwise called the 'Adam' which incorporates a ZigBee controller to manage thermostatic radiator valves, room thermostats, floor heating pumps, et cetera.

Users can manage and control this system either via a web app or a mobile phone app developed by Plugwise. The (web) app allows users to define heating zone's (e.g. rooms) and add radiator valves to those rooms to manage and control their heating irrespective of other rooms.

Using the Plugwise Home Automation binding you can incorporate the management of these devices and heating zones into openHAB. The binding uses the same RESTfull API that both the mobile phone app and the web app use.

The binding requires users to have a working Plugwise Home Automation setup consisting of at least 1 gateway device (the 'Adam') and preferably 1 radiator valve as a bare minimum. The 'Adam' (from hereon called the gateway) needs to be accessible from the openHAB instance via a TCP/IP connection.

## Supported Things

| Device Type | Description | Thing Type |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------- |
| - | A Plugwise heating zone configured with at least 1 of the devices below | zone |
| [Adam](https://www.plugwise.com/en_US/products/adam-ha) | The Plugwise Home Automation Bridge is needed to connect to the Adam boiler gateway | gateway |
| [Tom](https://www.plugwise.com/en_US/products/tom) | A Plugwise Home Automation radiator valve | appliance_valve |
| [Floor](https://www.plugwise.com/en_US/products/floor) | A Plugwise Home Automation radiator valve specificaly used for floor heating | appliance_valve |
| [Circle](https://www.plugwise.com/en_US/products/circle) | A power outlet plug that provides energy measurement and switching control of appliances (e.g. floor heating pump) | appliance_pump |
| [Lisa](https://www.plugwise.com/en_US/products/lisa) | A room thermostat (also supports the 'Anna' room thermostat) | appliance_thermostat |


## Discovery

After setting up the Plugwise Home Automation bridge you can start a manual scan to find all devices registered on the gateway. You can also manually add things by entering the corresponding device id as a configuration parameter. The device id's can be found be enabling TRACE logging in the Karaf console.

## Thing Configuration

You must define a Plugwise Home Automation gateway (Bridge) before defining zones or appliances (Things) for this binding to work.

#### Plugwise Home Automation gateway (Bridge):

| Parameter | Description | Config | Default |
| --------- | ----------------------------------------------------------------------- | -------- | ------- |
| host | The IP address or hostname of the Adam HA gateway | Required | 'adam' |
| username | The username for the Adam HA gateway | Optional | 'smile' |
| smileID | The 8 letter code on the sticker on the back of the Adam boiler gateway | Required | - |
| refresh | The refresh interval in seconds | Optional | 15 |

#### Plugwise Home Automation zone (`zone`):

| Parameter | Description | Config | Default |
| --------- | ------------------------- | -------- | ------- |
| id | The unique ID of the zone | Required | - |

#### Plugwise Home Automation appliance (`appliance_valve`):

| Parameter | Description | Config | Default |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
| id | The unique ID of the radiator valve appliance | Required | - |
| lowBatteryPercentage | Battery charge remaining at which to trigger battery low warning. (*Only applicable for battery operated devices*) | Optional | 15 |

#### Plugwise Home Automation appliance (`appliance_thermostat`):

| Parameter | Description | Config | Default |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
| id | The unique ID of the room thermostat appliance | Required | - |
| lowBatteryPercentage | Battery charge remaining at which to trigger battery low warning. (*Only applicable for battery operated devices*) | Optional | 15 |


#### Plugwise Home Automation appliance (`appliance_pump`):

| Parameter | Description | Config | Default |
| --------- | ----------------------------------- | -------- | ------- |
| id | The unique ID of the pump appliance | Required | - |

## Channels

| channel | type | Read-only? | description |
| ------- | ------ | ------------ | --------------- |
| temperature | Number:Temperature | Yes | This channel is used to read the temperature of an appliance that supports the thermostat functionality |
| setpointTemperature | Number:Temperature | No | This channel is used to read or write the setpoint temperature of an appliance that supports the thermostat functionality |
| power | Switch | No | This channel is used to toggle an appliance ON/OFF that supports the relay functionality |
| lock | Switch | No | This channel is used to toggle an appliance lock ON/OFF that supports the relay functionality.(*When the lock is ON the gateway will not automatically control the corresponding relay switch depending on thermostat mode*) |
| powerUsage | Number | Yes | This channel is used to read the current power usage in Watts of an appliance that supports this |
| batteryLevel | Number | Yes | This channel is used to read the current battery level of an appliance that is battery operated |
| batteryLevelLow | Switch | Yes | This channel will switch ON when the battery level of an appliance that is battery operated drops below a certain threshold |

## Full Example

**things/plugwiseha.things**

```
Bridge plugwiseha:gateway:home "Plugwise Home Automation Gateway" [ smileId="abcdefgh" ] {
Thing zone living_room_zone "Living room" [ id="$device_id" ]
Thing appliance_valve living_room_radiator "Living room radiator valve" [ id="$device_id" ]
Thing appliance_thermostat living_room_thermostat "Living room thermostat" [ id="$device_id" ]
Thing appliance_pump living_room_pump "Floor heating pump" [ id="$device_id" ]
}
```

Replace `$device_id` accordingly.

**items/plugwiseha.items**

```
Number living_room_zone_temperature "Zone temperature" {channel="plugwiseha:zone:home:living_room_zone:temperature"}
Number living_room_zone_temperature_setpoint "Zone temperature setpoint" {channel="plugwiseha:zone:home:living_room_zone:setpointTemperature"}

Number living_room_radiator_temperature "Radiator valve temperature" {channel="plugwiseha:appliance_valve:home:living_room_radiator:temperature"}
Number living_room_radiator_temperature_setpoint "Radiator valve temperature setpoint" {channel="plugwiseha:appliance_valve:home:living_room_radiator:setpointTemperature"}

Number living_room_thermostat_temperature "Room thermostat temperature" {channel="plugwiseha:appliance_valve:home:living_room_thermostat:temperature"}
Number living_room_thermostat_temperature_setpoint "Room thermostat temperature setpoint" {channel="plugwiseha:appliance_valve:home:living_room_thermostat:setpointTemperature"}

Switch living_room_pump_power "Floor heating pump power" {channel="plugwiseha:appliance_pump:home:living_room_pump:power"}
Switch living_room_pump_lock "Floor heating pump lock [MAP:(plugwiseha.map):%s]" {channel="plugwiseha:appliance_pump:home:living_room_pump:lock"}
Number living_room_pump_power_usage "Floor heating pump power [%0.2fW]" {channel="plugwiseha:appliance_pump:home:living_room_pump:powerUsage"}
```

**transform/plugwiseha.map**

```
ON=Locked
OFF=Unlocked
```

**sitemaps/plugwiseha.sitemap**

```
sitemap plugwiseha label="PlugwiseHA Binding"
{
Frame {
Text item=living_room_zone_temperature
Setpoint item=living_room_zone_temperature_setpoint label="Living room [%.1f °C]" minValue=5.0 maxValue=25 step=0.5

Text item=living_room_radiator_temperature
Setpoint item=living_room_radiator_temperature_setpoint label="Living room [%.1f °C]" minValue=5.0 maxValue=25 step=0.5

Text item=living_room_thermostat_temperature
Setpoint item=living_room_thermostat_temperature_setpoint label="Living room [%.1f °C]" minValue=5.0 maxValue=25 step=0.5

Number item=living_room_pump_power_usage
Switch item=living_room_pump_power
Switch item=living_room_pump_lock
}
}
```
16 changes: 16 additions & 0 deletions bundles/org.openhab.binding.plugwiseha/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/maven-v4_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.plugwiseha</artifactId>

<name>openHAB Add-ons :: Bundles :: PlugwiseHA Binding</name>

</project>
9 changes: 9 additions & 0 deletions bundles/org.openhab.binding.plugwiseha/src/main/feature/feature.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<features name="org.openhab.binding.plugwiseha-${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/${project.version}/xml/features</repository>

<feature name="openhab-binding-plugwiseha" description="PlugwiseHA Binding" version="${project.version}">
<feature>openhab-runtime-base</feature>
<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.plugwiseha/${project.version}</bundle>
</feature>
</features>