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]:

  • 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 with the help of a large community.

Please note the known issues below.

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).

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)

Besides the username and password all required Z-Way information are found during discovery.

Configuration NameMandatoryDefaultDesciption
zwayServerIpAddresslocalhostThe 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.
zwayServerPort8083The port of the Z-Way server (0 to 65335)
zwayServerProtocolhttpProtocol to connect to the Z-Way server (http or https)
zwayServerUsernameadminUsername to access the Z-Way server.
zwayServerPasswordXPassword to access the Z-Way server.
pollingInterval3600Refresh device states and registration from Z-Way server in seconds (at least 60).

Only the Z-Way server can be configured textual:

Bridge zway:zwayServer:192_168_2_42 [ zwayServerIpAddress="localhost", zwayServerPort=8083, zwayServerProtocol="http", zwayServerUsername="admin", zwayServerPassword="admin", pollingInterval=3600 ] {
    // associated things have to be created with the Paper UI
}

Z-Way Virtual Device

Configuration NameMandatoryDefaultDescription
deviceIdXDevice ID of virtual device
bridge referenceX

Z-Wave Device

Configuration NameMandatoryDefaultDescription
nodeIdXNode ID of the Z-Wave device
bridge referenceX

Channels

Channels with detailed information for the devices

The following channels are currently supported.

Channel Type IDItem TypeCategoryAsssigned for Z-Way device type and probe type
sensorTemperatureNumberTemperatureSensorMultilevel - temperature
sensorLuminosityNumberLightSensorMultilevel - luminosity
sensorHumidityNumberHumiditySensorMultilevel - humidity
sensorBarometerNumberPressureSensorMultilevel - barometer
sensorUltravioletNumberLightSensorMultilevel - ultraviolet
sensorCO2NumberCarbonDioxideSensorMultilevel - Special case: no probe type for carbon dioxide sensors available - probe title CO2 Level acts as selection criterion
sensorEnergyNumberEnergySensorMultilevel - energy
sensorMeterKWhNumberEnergySensorMultilevel - meterElectric_kilowatt_per_hour
sensorMeterWNumberEnergySensorMultilevel - meterElectric_watt
sensorSmokeSwitchSmokeSensorBinary - smoke
sensorCoSwitchGasSensorBinary - co
sensorFloodSwitchWaterSensorBinary - flood
sensorTamperSwitchAlarmSensorBinary - tamper
sensorDoorWindowContactContactSensorBinary - door-window
sensorMotionSwitchMotionSensorBinary - general_purpose, motion
switchPowerOutletSwitchPowerOutletSwitchBinary - Special case: no probe type for power outlet available - icon switch acts as selection criterion
switchColorTemperatureDimmerColorLightSwitchMultilevel - switchColor_soft_white, switchColor_cold_white
thermostatModeSwitchTemperatureSwitchBinary - thermostat_mode

Currently unsupported Z-Way probe types:

  • 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).

Channel Type IDItem TypeCategoryAssigned for Z-Way device type
batteryNumberBatteryBattery
doorlockSwitchDoorDoorlock
sensorBinarySwitchSwitchSensorBinary
sensorMultilevelNumber-SensorMultilevel
switchBinarySwitchSwitchSwitchBinary
switchMultilevelDimmer-SwitchMultilevel
switchColorColorColorLightSwitchRGBW
switchControlSwitchSwitchSwitchControl, ToggleButton, SwitchToggle
thermostatNumberTemperatureThermostat
sensorDiscreteNumber-SensorDiscrete

Unsupported Z-Way device types: Camera, SensorMultiline, Text. The integration of these types isn't planned.

Channels for the Z-Way Server (Bridge)

-Channel Type IDItem TypeCategoryDescription
-actionsString-It is currently possible to update all devices.
-secureInclusionSwitchSwitchChange inclusion type for further inclusions.
-inclusionSwitchSwitchStart inclusion mode (after a timeout the inclusion will be automatically finished).
-exclusionSwitchSwitchStart 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.

Example

Because textual configuration isn't useful, follow the instructions in the Getting Started document.

Developer stuff

Known issues

  • The Z-Way Binding only works, when simple mode of item linking is enabled during thing creation.

Structure of Z-Way Binding

Z-Way Binding

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 (physical device configuration)
  • Only polling is available. Further versions will contain other mechanisms under usage of the WebSocket implementation of Z-Way or MQTT.