Z Wave Binding Snapshot

Documentation of the Z-Wave binding Bundle for the Snapshot release.

Introduction

The OpenHAB Z-Wave binding allows you to connect to your Z-Wave wireless mesh network. A Z-Wave network typically consists of one primary controller “stick”, zero or more additional controllers and zero or more Z-Wave enabled devices, e.g. dimmers, switches, sensors et cetera. Connection to the Z-Wave controller is done through the serial port of your host system. USB controllers typically create a virtual COM port to connect to the stick. Please write down the port name before configuring this binding. In case your port name changes dynamically and you want to use a symlink, see Tricks. A list of supported controllers is listed below.

Initialization of the binding typically takes several seconds to minutes depending on the number of devices in the network. When battery operated devices are used the binding tries to reach the device first. After one minute the node is marked sleeping. On wake up of the device initialization will continue.

Please make sure that you have a functioning Z-Wave network prior to using this binding. The binding currently provides no functionality to add or remove devices etc. The open-zwave control panel is a good choice to set up your network. Commercial software like Homeseer can be used as well.

For installation of the binding, please see Wiki page Bindings.

The snapshot version of the binding can be downloaded, together with the rest of openhab, from the cloudbees page.

Supported controllers

The binding supports all controllers that implement the Z-Wave Serial API. A list of confirmed supported controllers is

Aeon Labs USB Z-Stick	No remarks
The Razberry-Zwave-Daughterboard	See known issues
Vision USB stick Z-wave	No remarks

Binding Configuration

First of all you need to introduce the port settings of your Z-Wave controller in the openhab.cfg file (in the folder '${openhab_home}/configurations'). The refresh interval and the refresh delay can be specified optionally.

############################## Z-Wave  Binding ###################################

# Z-Wave controller port
# Valid values are e.g. COM1 for Windows and /dev/ttyS0 or /dev/ttyUSB0 for Linux
zwave:port=COM1

The zwave:port value indicates the serial port on the host system to which the Z-Wave controller is connected, e.g. "COM1" on Windows, "/dev/ttyS0" or "/dev/ttyUSB0" on Linux or "/dev/tty.PL2303-0000103D" on Mac.

Item configuration

In order to bind an item to a Z-Wave device, you need to provide configuration settings. The easiest way to do so is to add some binding information in your item file (in the folder configurations/items`). The syntax for the Z-Wave binding configuration string is explained here: The format of the binding configuration is simple and looks like this:

zwave="<nodeId>[:<endpointId>][:command=<command>[,parameter=<value>][,parameter=<value>]...]"

where parts in brackets indicate an optional item. Usually only one item is bound to a device, but more items can be bound to a device as well, either for reporting variables, or in case the device consists of multiple endpoints / instances.

The node ID indicates the number (in decimal notation) of the node, to which this item is bound. To find out your devices nodeIds either look at the startup log of openhab or use other Z-Wave configuration programs like openzwave control panel to detect and configure your setup.

The endpoint ID is optional. In case a node consists of multiple instances or endpoints, the instance number can be specified using this value. The default value is 1. An example of a multi-endpoint device is the Fibaro FGS 221 double relay.

The command is optional. Z-Wave nodes support functionality through command classes. A specific command class can be specified to use that specific functionality of the node. A node can contain multiple supported command classes. If the command is omitted, the best suitable command class for the item / node combination is automatically chosen.

Command classes may support parameters. A parameter is a name=value pair that configures some aspect of the command class on the node or in the binding.

A list with command classes and parameter values is provided below:

Supported Command Classes

Each node in the network provides functionality in the form of Command Classes. The OpenHAB Z-Wave binding implements the same Command Classes to be able to use the nodes in the network. Not all Z-Wave Command classes are currently supported by the binding. The supported command classes are listed in the table below.

**Command Class**	** Remarks **	**Supported parameters**
NO_OPERATION	Used by the binding during initialization
BASIC	Provides basic SET and GET of the default node value
HAIL	Used by nodes to indicate that they want to be polled. The binding handles this automatically
METER	Used to get measurements from a node	*meterScale=value* : optional parameter to select the meter scale in case the meter supports multiple scales (and types). Value is one of the following textual values: E_KWh (0, MeterType.ELECTRIC, "kWh", "Energy") E_KVAh (1, MeterType.ELECTRIC, "kVAh", "Energy") E_W(2, MeterType.ELECTRIC, "W", "Power") E_Pulses (3, MeterType.ELECTRIC, "Pulses", "Count") E_V (4, MeterType.ELECTRIC, "V", "Voltage") E_A (5, MeterType.ELECTRIC, "A", "Current") E_Power_Factor (6, MeterType.ELECTRIC, "Power Factor", "Power Factor") G_Cubic_Meters (0, MeterType.GAS, "Cubic Meters", "Volume") G_Cubic_Feet (1, MeterType.GAS, "Cubic Feet", "Volume") G_Pulses(3, MeterType.GAS, "Pulses", "Count") W_Cubic_Meters (0, MeterType.WATER, "Cubic Meters", "Volume") W_Cubic_Feet (1, MeterType.WATER, "Cubic Feet", "Volume") W_Gallons (2, MeterType.WATER, "US gallons", "Volume") W_Pulses (3, MeterType.WATER, "Pulses", "Count")
SWITCH_BINARY	Used to bind directly to a SWITCH
SWITCH_MULTILEVEL	Used to bind directly to a DIMMER	_restore_last_value=true_ : restores the dimmer to it's last value if an ON command is sent to the dimmer (as opposed to setting it's value to 100%)
SENSOR_BINARY	Used to bind to a sensor.
SENSOR_MULTILEVEL	Used to bind to e.g. a temperature sensor. Currently only single sensors are supported.	*sensorType=value* : optional parameter to select a sensor in case the node supports multiple sensors. Value is one of the following numerical values: TEMPERATURE(1,"Temperature") GENERAL(2,"General") LUMINANCE(3,"Luminance") POWER(4,"Power") RELATIVE_HUMIDITY(5,"RelativeHumidity") VELOCITY(6,"Velocity") DIRECTION(7,"Direction") ATMOSPHERIC_PRESSURE(8,"AtmosphericPressure") BAROMETRIC_PRESSURE(9,"BarometricPressure") SOLAR_RADIATION(10,"SolarRadiation") DEW_POINT(11,"DewPoint") RAIN_RATE(12,"RainRate") TIDE_LEVEL(13,"TideLevel") WEIGHT(14,"Weight") VOLTAGE(15,"Voltage") CURRENT(16,"Current") CO2(17,"CO2") AIR_FLOW(18,"AirFlow") TANK_CAPACITY(19,"TankCapacity") DISTANCE(20,"Distance") ANGLE_POSITION(21,"AnglePosition") ROTATION(22,"Rotation") WATER_TEMPERATURE(23,"WaterTemperature") SOIL_TEMPERATURE(24,"SoilTemperature") SEISMIC_INTENSITY(25,"SeismicIntensity") SEISMIC_MAGNITUDE(26,"SeismicMagnitude") ULTRAVIOLET(27,"Ultraviolet") ELECTRICAL_RESISTIVITY(28,"ElectricalResistivity") ELECTRICAL_CONDUCTIVITY(29,"ElectricalConductivity") LOUDNESS(30,"Loudness") MOISTURE(31,"Moisture") MAX_TYPE(32,"MaxType")
MULTI_INSTANCE	Used to channel commands to the right endpoint on multi-channel devices. See item configuration.
MANUFACTURER_SPECIFIC	Used to get manufacturer info from the device
BATTERY	Used to get the battery level from battery operated devices. See item configuration.
WAKE_UP	Used to respond to wake-up signals of battery operated devices.
VERSION	Used to get version info from a node.
SENSOR_ALARM	Used to get alarm info from sensors.	*alarmType=value* : optional parameter to select an alarm type in case the node supports multiple alarms. Value is one of the following numerical values: GENERAL(0, "General") SMOKE(1, "Smoke") CARBON_MONOXIDE(2, "Carbon Monoxide") CARBON_DIOXIDE(3, "Carbon Dioxide") HEAT(4, "Heat") FLOOD(5, "Flood")

= Parameters that can be added to any item

There are some general parameters that can be added to any command class in an item string. These are refresh_interval=value and respond_to_basic=true

refresh_interval=value sets the refresh interval to value seconds. 0 indicates that no polling is performed and the node should inform the binding itself on value changes. This is the default value.

respond_to_basic=true indicates that the item will respond to basic reports. Some Fibaro contacts and universal sensors report their values as BASIC reports instead of a specific command class. You can add this parameter to an item to indicate that this item should respond to those reports.

Basic command class

The basic Command Class is a special command class that almost every node implements. It provides functionality to set a value on the device and/or to read back values. It can be used to address devices that are currently not supported by their native command class like thermostats.

When the basic command class is used, devices support setting values and reporting values when polling. Direct updates from the device on changes will fail however.

You can force a device to work with the basic command set (or any specific command set for that matter using a syntax like:

Switch    ZwaveDevice        { zwave="3:1:command=BASIC" }

To find out which command classes are supported by your Z-Wave device, you can look in the manual or use the list at http://www.pepper1.net/zwavedb/ or http://products.z-wavealliance.org/. In case your command class is supported by the device and binding, but you have a problem, you can create an issue at: https://github.com/openhab/openhab/issues. In case you want a command class implemented by the binding, please add it to issue 431.

Known Issues

There seems to be an issue with the binding running on the latest oracle VM Beta, on ARM based architectures (e.g. raspberry PI). It manifests itself as messages being received multiple times. This issue is currently under investigation.

Examples

Here are some examples of valid binding configuration strings, as defined in the items configuration file:

/* Some statistics */

Number ZwaveStatsSOF "Number Start of Frames[%s]" (gZwaveStats) {zwave="1:1:command=info,item=sof"}
Number ZwaveStatsACK "Number of Acknowledgments [%s]" (gZwaveStats) {zwave="1:1:command=info,item=ack"}
Number ZwaveStatsCAN "Number of CAN [%s]" (gZwaveStats) {zwave="1:1:command=info,item=can"}
Number ZwaveStatsNAK "Number of NAK [%s]" (gZwaveStats) {zwave="1:1:command=info,item=nak"}
Number ZwaveStatsOOF "Number of OOF [%s]" (gZwaveStats) {zwave="1:1:command=info,item=oof"}
Number ZwaveStatsTimeout "Number of Time-outs [%s]" (gZwaveStats) {zwave="1:1:command=info,item=time_out"}
String ZwaveNode01HomeID	"Home ID [%s]" (gZwaveNode01) {zwave="1:1:command=info,item=home_id"}
Number ZwaveNode01NetworkID	"Node ID [%s]" (gZwaveNode01) {zwave="1:1:command=info,item=node_id"}

/* A dimmer and a contact */

Dimmer Light_Corridor_Dimmer "Hallway Dimmer [%d %%]" (GF_Corridor) {zwave="6"}
Contact Door_Corridor_Switch "Front door sensor [MAP(nl.map):%s]" (GF_Corridor) {zwave="21:command=sensor_binary,respond_to_basic=true"} 
Number Door_Corridor_Battery "Front door sensor battery level [%d %%]" (GF_Corridor) { zwave="21:command=battery" }

/* A node with multiple endpoints */

Switch Mech_Vent			"Mechanical ventilation middle."	(GF_Kitchen) {zwave="11:1"}
Switch Mech_Vent_High		"Mechanical ventilation high."	(GF_Kitchen) {zwave="11:2"}

/* A fibaro wall plug with energy meter. */

Switch Coffee_Kitchen_Switch "Coffee machine" (GF_Cellar) {zwave="18:command=switch_binary"} 
Number Coffee_Kitchen_Power "Coffee machine power consumption [%.1f W]" (GF_Cellar,GF_Energy) { zwave="18:command=sensor_multilevel" }
Number Coffee_Kitchen_Energy "Coffee machine total energy usage  [%.2f KWh]" (GF_Cellar) { zwave="18:command=meter" }

/* A six node power bar with integrated energy and power meter and different intervals. */

Switch Switch_Powerbar_Subwoofer "Subwoofer" (GF_Living) {zwave="26:1:command=switch_binary"} 
Switch Switch_Powerbar_Reiceiver "Receiver" (GF_Living) {zwave="26:2:command=switch_binary"} 
Switch Switch_Powerbar_DVD "DVD" (GF_Living) {zwave="26:3:command=switch_binary"} 
Switch Switch_Powerbar_TV "TV" (GF_Living) {zwave="26:4:command=switch_binary"} 
Switch Switch_Powerbar_Xbox "XBOX-360" (GF_Living) {zwave="26:5:command=switch_binary"} 
Switch Switch_Powerbar_PC "Mediacenter" (GF_Living) {zwave="26:6:command=switch_binary"} 

Number Power_Powerbar_Subwoofer "Subwoofer power consumption  [%d W]" (GF_Living,GF_Energy) {zwave="26:1:command=meter,meter_scale=E_W,refresh_interval=60"} 
Number Power_Powerbar_Reiceiver "Receiver power consumption  [%d W]" (GF_Living,GF_Energy) {zwave="26:2:command=meter,meter_scale=E_W,refresh_interval=70"} 
Number Power_Powerbar_DVD "DVD power consumption [%d W]" (GF_Living,GF_Energy) {zwave="26:3:command=meter,meter_scale=E_W,refresh_interval=60"} 
Number Power_Powerbar_TV "TV power consumption [%d W]" (GF_Living,GF_Energy) {zwave="26:4:command=meter,meter_scale=E_W,refresh_interval=70"} 
Number Power_Powerbar_Xbox "XBOX-360 power consumption [%d W]" (GF_Living,GF_Energy) {zwave="26:5:command=meter,meter_scale=E_W,refresh_interval=80"} 
Number Power_Powerbar_PC "Mediacenter power consumption [%d W]" (GF_Living,GF_Energy) {zwave="26:6:command=meter,meter_scale=E_W,refresh_interval=80"} 

Number Energy_Powerbar_Subwoofer "Subwoofer total energy usage  [%.4f KWh]" (GF_Living) {zwave="26:1:command=meter,meter_scale=E_KWh,refresh_interval=300"} 
Number Energy_Powerbar_Reiceiver "Receiver total energy usage  [%.4f KWh]" (GF_Living) {zwave="26:2:command=meter,meter_scale=E_KWh,refresh_interval=310"} 
Number Energy_Powerbar_DVD "DVD totaal total energy usage  [%.4f KWh]" (GF_Living) {zwave="26:3:command=meter,meter_scale=E_KWh,refresh_interval=320"} 
Number Energy_Powerbar_TV "TV total energy usage [%.4f KWh]" (GF_Living) {zwave="26:4:command=meter,meter_scale=E_KWh,refresh_interval=330"} 
Number Energy_Powerbar_Xbox "XBOX-360 total energy usage  [%.4f KWh]" (GF_Living) {zwave="26:5:command=meter,meter_scale=E_KWh,refresh_interval=340"} 
Number Energy_Powerbar_PC "Mediacenter total energy usage  [%.4f KWh]" (GF_Living) {zwave="26:6:command=meter,meter_scale=E_KWh,refresh_interval=350"} 

Logging

The ZWave binding can generate a lot of debug/trace logging when enabled so it is advisable to generate a separate log file for this binding. This also makes it easier for analysis since there is nothing from other bindings/openHAB polluting the logs.

In order to configure logging for this binding to be generated in a separate file add the following to your /configuration/logback.xml file;

        <appender name="ZWAVEFILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
                <file>logs/zwave.log</file>
                <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                        <!-- weekly rollover and archiving -->
                        <fileNamePattern>logs/zwave-%d{yyyy-ww}.log.zip</fileNamePattern>
                        <!-- keep 30 days' worth of history -->
                        <maxHistory>30</maxHistory>
                </rollingPolicy>
                <encoder>
                        <pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{30}[:%line]- %msg%n%ex{5}</pattern>
                </encoder>
        </appender>

        <!-- Change DEBUG->TRACE for even more detailed logging -->
        <logger name="org.openhab.binding.zwave" level="DEBUG" additivity="false">
                <appender-ref ref="ZWAVEFILE" />
        </logger>

It is highly recommended to turn on at least DEBUG logging whilst setting up and configuring your ZWave network for the first time.