diff --git a/_data/bindings.csv b/_data/bindings.csv index f8e73371a..386811a07 100644 --- a/_data/bindings.csv +++ b/_data/bindings.csv @@ -55,3 +55,4 @@ urtsi,Somfy URTSI II,"The addressable Universal RTS Interface II (URTSI II) can vitotronic,Vitotronic,"Viessmann heating systems with Vitotronic has a optolink Interface for maintenance." yamahareceiver,Yamahareceiver,"This binding connects openHAB with Yamaha Receivers of product line CX-A5000, RX-A30xx, RX-A20xx, RX-A10xx, RX-Vxxx, RX-Z7, DSP-Z7, RX-S600, HTR-xxxx." zwave,ZWave,"The ZWave binding supports an interface to a wireless Z-Wave home automation network." +zway,Z-Way,"Z-Way is a software to configure and control a Z-Wave network. The software comes with a full stack from Z-Wave transceiver with certified firmware to a REST API on high level." diff --git a/_data/oh1addons.csv b/_data/oh1addons.csv index 7e9fc4d9b..8afd62ce8 100644 --- a/_data/oh1addons.csv +++ b/_data/oh1addons.csv @@ -39,6 +39,7 @@ binding,Garadget Binding binding,GC100IR Binding binding,GPIO Binding binding,Heatmiser Binding +binding,Horizon Binding binding,HTTP Binding binding,IHC Binding binding,InsteonPLM Binding diff --git a/_repos/openhab b/_repos/openhab index 761fa8562..9dcb63c65 160000 --- a/_repos/openhab +++ b/_repos/openhab @@ -1 +1 @@ -Subproject commit 761fa85629b994ff60b6a2a1aafac31b84c52188 +Subproject commit 9dcb63c65d3cd4fccfc0f82cbd4ec5440af35e9b diff --git a/_repos/openhab-bundles b/_repos/openhab-bundles index 9edf6432b..c692912a6 160000 --- a/_repos/openhab-bundles +++ b/_repos/openhab-bundles @@ -1 +1 @@ -Subproject commit 9edf6432b9302e125c109c54c9b49312f75de48b +Subproject commit c692912a60826b86b41fa79fb3e668b150037238 diff --git a/_repos/openhab2-addons b/_repos/openhab2-addons index ff2b2584f..822298c2d 160000 --- a/_repos/openhab2-addons +++ b/_repos/openhab2-addons @@ -1 +1 @@ -Subproject commit ff2b2584f35783b75ea6d0668795678e34acf3cc +Subproject commit 822298c2d6fe69ac2766754e76ca5fdd65aa8a9a diff --git a/_repos/smarthome b/_repos/smarthome index e4e7df952..1607ae67d 160000 --- a/_repos/smarthome +++ b/_repos/smarthome @@ -1 +1 @@ -Subproject commit e4e7df9528989a5775e813aac2c2f9c8cf2a6c50 +Subproject commit 1607ae67dfd303924b5ec9552ecb42c56bc4c26a diff --git a/addons/bindings/zway/doc/BMWi_4C_Gef_en.jpg b/addons/bindings/zway/doc/BMWi_4C_Gef_en.jpg new file mode 100644 index 000000000..6ef4d8bf3 Binary files /dev/null and b/addons/bindings/zway/doc/BMWi_4C_Gef_en.jpg differ diff --git a/addons/bindings/zway/doc/GETTING_STARTED.md b/addons/bindings/zway/doc/GETTING_STARTED.md new file mode 100644 index 000000000..7b3804362 --- /dev/null +++ b/addons/bindings/zway/doc/GETTING_STARTED.md @@ -0,0 +1,88 @@ +# Getting Started + +# Prepare Z-Way Server + +1. [Download](https://razberry.z-wave.me/z-way-server/) Z-Way v2.2.3 or newer (further information about installing Z-Way you can find [here](http://razberry.z-wave.me/index.php?id=24)) +2. Install openHAB Connector + - via "ZWave.Me App Store" use Token `sse_zwickau_beta` + - via Git + + ```shell + cd /opt/z-way-server/automation/userModules + git clone https://github.com/pathec/ZWay-OpenHABConnector.git OpenHABConnector + service z-way-server restart + ``` + +3. Instantiate the app once (under Configuration - Apps - Local Apps). Important: Change the selection from "Featured Apps" to "All Apps" to make the app visible. It is not necessary to make the configuration manually. + +# Prepare openHAB + +1. [Download](http://www.openhab.org/getting-started/downloads.html) openHAB 2 (further information about installing openHAB you can find [here](http://docs.openhab.org/installation/index.html)) +2. Install Z-Way Binding + - via Extension Manager (not yet available for the Z-Way Binding) + - via Download + + ```shell + cd /opt/openhab2/addons + sudo wget https://github.com/openhab/openhab2-addons/files/636686/org.openhab.binding.zway-2.0.0-SNAPSHOT.zip + sudo unzip org.openhab.binding.zway-2.0.0-SNAPSHOT.zip + sudo rm org.openhab.binding.zway-2.0.0-SNAPSHOT.zip + ``` + +3. Start openHAB by running `start.bat` or `start.sh` +4. The first start may take up to 5 minutes. You should reach openHAB2 at `http://localhost:8080` + +# Configure Z-Way in openHAB + +## Create and configure a Z-Way Bridge + +Open the *PaperUI* + +![openHAB Home](images/getting-started/01-openHAB-Home.png) + +Open the *Inbox* and create a Z-Way Server + +![openHAB Inbox](images/getting-started/02-Inbox.png) + +![openHAB Inbox](images/getting-started/03-Create-bridge.png) + +Open the *Configuration* - *Things* and select Z-Way Server + +![openHAB Thing details](images/getting-started/05-Bridge-details.png) + +Change configuration: In order for the Observer mechanism works, the IP address, port and protocol of both systems are required. + +- **openHAB** + - **openHAB Alias** by default, the alias is generated + - **IP address** (default: localhost) + - **port** (default: 8080) + - **protocol** (default: http) +- **Z-Way Server** + - **IP address** (default: localhost) + - **port** (default: 8083) + - **protocol** (default: http) + - **username** (default: admin) + - **password** must be set (no default value) +- **options** + - **polling interval** (default: 3600) in seconds + - **Observer mechanism** (default: active) + +![openHAB Thing settings](images/getting-started/06-Bridge-settings.png) + +## Create and configure Z-Way Devices + +Open the *Inbox* and start manually the *Discovery* for the Z-Way Binding. The *Discovery* must be started manually at this point, because the *Discovery* is running only every 4 minutes. The start time of the interval is the creation of Z-Way Server, even if the configuration is not yet complete. After the Z-Way Server is fully configured, the interval must be awaited or started manually. + +![openHAB Discovery](images/getting-started/07-Device-discovery.png) + +![openHAB Discovery](images/getting-started/08-Device-discovery.png) + +Create *Things* from the *Discovery Results* + +![openHAB Inbox](images/getting-started/09-Create-device.png) + +Example: openHAB *Thing* compared to the equivalent Z-Way *Devices* + +![openHAB Thing](images/getting-started/10-Z-Way-device.png) + +![Z-Way Devices](images/getting-started/11-Z-Way-device.png) diff --git a/addons/bindings/zway/doc/images/Z-Way-Binding.png b/addons/bindings/zway/doc/images/Z-Way-Binding.png new file mode 100644 index 000000000..548d1e014 Binary files /dev/null and b/addons/bindings/zway/doc/images/Z-Way-Binding.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/01-openHAB-Home.png b/addons/bindings/zway/doc/images/getting-started/01-openHAB-Home.png new file mode 100644 index 000000000..9a38a615b Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/01-openHAB-Home.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/02-Inbox.png b/addons/bindings/zway/doc/images/getting-started/02-Inbox.png new file mode 100644 index 000000000..06d814da7 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/02-Inbox.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/03-Create-bridge.png b/addons/bindings/zway/doc/images/getting-started/03-Create-bridge.png new file mode 100644 index 000000000..8c74a49ae Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/03-Create-bridge.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/04-Open-bridge-details.png b/addons/bindings/zway/doc/images/getting-started/04-Open-bridge-details.png new file mode 100644 index 000000000..eef9a06b7 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/04-Open-bridge-details.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/05-Bridge-details.png b/addons/bindings/zway/doc/images/getting-started/05-Bridge-details.png new file mode 100644 index 000000000..89f6a7802 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/05-Bridge-details.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/06-Bridge-settings.png b/addons/bindings/zway/doc/images/getting-started/06-Bridge-settings.png new file mode 100644 index 000000000..97574dc54 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/06-Bridge-settings.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/07-Device-discovery.png b/addons/bindings/zway/doc/images/getting-started/07-Device-discovery.png new file mode 100644 index 000000000..a225a89a4 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/07-Device-discovery.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/08-Device-discovery.png b/addons/bindings/zway/doc/images/getting-started/08-Device-discovery.png new file mode 100644 index 000000000..949e9f374 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/08-Device-discovery.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/09-Create-device.png b/addons/bindings/zway/doc/images/getting-started/09-Create-device.png new file mode 100644 index 000000000..879b05bac Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/09-Create-device.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/10-Z-Way-device.png b/addons/bindings/zway/doc/images/getting-started/10-Z-Way-device.png new file mode 100644 index 000000000..b70480bf6 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/10-Z-Way-device.png differ diff --git a/addons/bindings/zway/doc/images/getting-started/11-Z-Way-device.png b/addons/bindings/zway/doc/images/getting-started/11-Z-Way-device.png new file mode 100644 index 000000000..36b65ffa2 Binary files /dev/null and b/addons/bindings/zway/doc/images/getting-started/11-Z-Way-device.png differ diff --git a/addons/bindings/zway/readme.md b/addons/bindings/zway/readme.md new file mode 100644 index 000000000..1ac0d9765 --- /dev/null +++ b/addons/bindings/zway/readme.md @@ -0,0 +1,179 @@ +--- +layout: documentation +--- + +{% include base.html %} + +# Z-Way Binding + +Z-Way is a software to configure and control a Z-Wave network. The software comes with a full stack from Z-Wave transceiver with certified firmware to a REST API on high level. + +Z-Way comes in three parts [cf. [Z-Wave.Me]([Z-Wave.Me](https://www.z-wave.me/index.php?id=1))]: + +- a firmware that runs on the Z-Wave transceiver chip +- the communication stack that runs on different host Operating Systems +- an automation engine and optionally a web server to implement a User Interface + +All parts together represents a smart home controller for Z-Wave. + +The entire infrastructure is maintained and developed by [Z-Wave.Me](https://www.z-wave.me/index.php?id=1) with the help of a large community. + +### Approach + +The idea behind is the integration of Z-Wave through a bridge (Z-Way controller). The existing, certified Z-Way stack can be used to build, configure and control the Z-Wave network. By using the REST API all devices are loaded from Z-Way and represented as openHAB elements. The sensor data and actuator states are constantly updated and commands are passed to the Z-Way system. + +The Binding uses the Z-Way library for Java ([Github](https://github.com/pathec/ZWay-library-for-Java)). + +## Supported Things + +The Z-Way Binding provides different thing types. The core component is the bridge which represents the Z-Way server. For the integration of devices, two thing types are available. In Z-Way there are devices which represent physical devices and (virtual) devices which are defined in Apps. The difference is that physical devices usually have several functions. +Z-Way server constructs (virtual) devices for each function, such as motion sensors or door contacts. In openHAB, these functions are bundled into physical devices and represented as things with channels for each function. This type of thing is a *Z-Wave Device*. On the other hand all virtual devices are mapped to *Z-Way Virtual Devices* with exactly one channel. + +- *Z-Way Server* (Bridge) represents a bridge with general settings and communication tasks. +- *Z-Way Virtual Device* represents one (virtual) device with the corresponding channel. A bridge is necessary as an intermediary between openHAB thing and Z-Way device. +- *Z-Wave Device* represents a device of real world. Each device function will be mapped to a separate channel. The bridge is necessary as an intermediary between openHAB thing and Z-Way device. + +## Discovery + +A discovery service for Z-Way servers scans local network and must always be started manually. Z-Way doesn't support any discovery protocol like UPnP for this purpose. That's why first all IP addresses in local network are checked on port 8083. If the server answers, a ZAutomation request (*/ZAutomation/api/v1/status*) is performed to ensure, the found server runs Z-Way. + +Another discovery service provides available devices (a configured bridge is necessary). The device discovery service is performed at a specified interval, but can also be started manually. + +Note: In the Z-Way server device can be disabled or made invisible. Only for active and visible Z-Way devices channels will created. + +## Binding Configuration + +No configuration is necessary. + +## Thing Configuration + +The textual configuration (via \*.thing files) isn't useful because the resulting elements are read-only. But the configuration and properties of things are changed at runtime and channels are dynamically added and removed. + +### Z-Way Server (Bridge) + +The information about accessing openHAB are needed so that the Observer mechanism works. Besides the username and password all required Z-Way information are found during discovery. + +| Configuration Name | Mandatory | Default | Desciption | +| ------------------------- | --------- | ------- | ---------- | +| openHABAlias | | | By default, the alias is generated during initialization or configuration update of thing handler. | +| openHABIpAddress | | localhost | The IP address or hostname of the openHAB server. If Z-Way and openHAB are running on the same machine, the default value can be used. | +| openHABPort | | 8080 | The port of the openHAB server (0 to 65335) | +| openHABProtocol | | http | Protocol to connect to the openHAB server (http or https) | +| zwayServerIpAddress | | localhost | The IP address or hostname of the Z-Way server. If Z-Way and openHAB are running on the same machine, the default value can be used. | +| zwayServerPort | | 8083 | The port of the Z-Way server (0 to 65335) | +| zwayServerProtocol | | http | Protocol to connect to the Z-Way server (http or https) | +| zwayServerUsername | | admin | Username to access the Z-Way server. | +| zwayServerPassword | X | | Password to access the Z-Way server. | +| pollingInterval | | 3600 | Refresh device states and registration from Z-Way server in seconds (at least 60). | +| observerMechanismEnabled | | true | The observer functionality is responsible for the item registration as observer in Z-Way. Attention: if disable this option, you have to setup an other synchronization mechanism like MQTT. | + +Only the Z-Way server can be configured textual (Attention! *openHABAlias* has to be set because the bridge configuration can not be changed at runtime): + +``` +Bridge zway:zwayServer:192_168_2_42 [ openHABAlias="development", openHABIpAddress="localhost", openHABPort=8080, openHABProtocol="http", zwayServerIpAddress="localhost", zwayServerPort=8083, zwayServerProtocol="http", zwayServerUsername="admin", zwayServerPassword="admin", pollingInterval=3600, observerMechanismEnabled=true ] { + // associated things have to be created with the Paper UI +} +``` + +### Z-Way Virtual Device + +| Configuration Name | Mandatory | Default | Description | +| ------------------ | ----------| ------- | ---------- | +| deviceId | X | | Device ID of virtual device | +| bridge reference | X | | || + +### Z-Wave Device + +| Configuration Name | Mandatory | Default | Description | +| ------------------ | ----------| ------- | ---------- | +| nodeId | X | | Node ID of the Z-Wave device | +| bridge reference | X | | || + +## Channels + +### Channels with detailed information for the devices + +The following channels are currently supported. + +| Channel Type ID | Item Type | Category | Asssigned for Z-Way device type and probe type | +| --------------- | --------- | -------- | ---------------------------------------------- | +| sensorTemperature | Number | Temperature | SensorMultilevel - temperature | +| sensorLuminosity | Number | Light | SensorMultilevel - luminosity | +| sensorHumidity | Number | Humidity | SensorMultilevel - humidity | +| sensorBarometer | Number | Pressure | SensorMultilevel - barometer | +| sensorUltraviolet | Number | Light | SensorMultilevel - ultraviolet | +| sensorCO2 | Number | CarbonDioxide | SensorMultilevel - *Special case:* no probe type for carbon dioxide sensors available - probe title *CO2 Level* acts as selection criterion | +| sensorEnergy | Number | Energy | SensorMultilevel - energy | +| sensorMeterKWh | Number | Energy | SensorMultilevel - meterElectric_kilowatt_per_hour | +| sensorMeterW | Number | Energy | SensorMultilevel - meterElectric_watt | +| sensorSmoke | Switch | Smoke | SensorBinary - smoke | +| sensorCo | Switch | Gas | SensorBinary - co | +| sensorFlood | Switch | Water | SensorBinary - flood | +| sensorTamper | Switch | Alarm | SensorBinary - tamper | +| sensorDoorWindow | Contact | Contact | SensorBinary - door-window | +| sensorMotion | Switch | Motion | SensorBinary - general_purpose, motion | +| switchPowerOutlet | Switch | PowerOutlet | SwitchBinary - *Special case:* no probe type for power outlet available - icon *switch* acts as selection criterion +| switchColorTemperature | Dimmer | ColorLight | SwitchMultilevel - switchColor_soft_white, switchColor_cold_white | +| thermostatMode | Switch | Temperature | SwitchBinary - thermostat_mode | + +Currently unsupported Z-Way probe types: + +- SwitchMultilevel: motor (selection criterion for rollershutter - will be implemented soon) +- SensorBinary: cooling, all alarm types (resulting from Z-Wave command class AlarmSensor(deprecated) and Alarm) +- SensorMultilevel: meterElectric_pulse_count, meterElectric_voltage, meterElectric_ampere, meterElectric_power_factor + +### Universial channels for the devices + +The following channels represent universial channels if no further device information are available, only depending on the Z-Way device types (for available device types see [Z-Way Documentation](http://docs.zwayhomeautomation.apiary.io/#reference/devices/device)). + +| Channel Type ID | Item Type | Category | Assigned for Z-Way device type | +| --------------- | --------- | -------- | ------------------------------ | +| battery | Number | Battery | Battery | +| doorlock | Switch | Door | Doorlock | +| sensorBinary | Switch | Switch | SensorBinary | +| sensorMultilevel | Number | - | SensorMultilevel | +| switchBinary | Switch | Switch | SwitchBinary | +| switchMultilevel | Number | - | SwitchMultilevel | +| switchColor | Color | ColorLight | SwitchRGBW | +| switchControl | Switch | Switch | SwitchControl | +| thermostat | Number | Temperature | Thermostat | + +Currently unsupported Z-Way device types: SwitchToggle, ToggleButton. + +### Channels for the Z-Way Server (Bridge) + +| Channel Type ID | Item Type | Category | Description | +| --------------- | --------- | -------- | ----------- | +| actions | String | - | It is currently possible to update all devices. | +| secureInclusion | Switch | Switch | Change inclusion type for further inclusions. | +| inclusion | Switch | Switch | Start inclusion mode (after a timeout the inclusion will be automatically finished). | +| exclusion | Switch | Switch | Start exclusion mode (after a timeout the exclusion will be automatically finished). || + +## Locations + +The locations of the Z-Way devices are loaded during the discovery. Based on the location ID of Z-Way device, the name of the Z-Way room is then allocated to the location property of the thing. + +## Full Example + +Because textual configuration isn't useful, follow the instructions in the [Getting Started](doc/GETTING_STARTED.md) document. + +## Developer stuff + +### Structure of Z-Way Binding + +![Z-Way Binding](doc/images/Z-Way-Binding.png) + +### Features + +- Discovery of the Z-Way server and devices +- Control of the Z-Wave devices in openHAB +- Receive updates of sensor data and actuator states in openHAB + +### Restrictions + +- Z-Way device types (especially the probe types) supported by openHAB channels with detailed information (scale types and so on) are not complete. +- Configuration of the Z-Wave network by the binding is currently not possible (device inclusion or physical device configuration) +- Z-Way App "OpenHAB Connector" is required. Further versions will contain other mechanisms under usage of the WebSocket implementation of Z-Way or MQTT. + +
+