Z Wave Binding - vpjuslin/openhab GitHub Wiki

Documentation of the Z-Wave binding Bundle.

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

HABmin can be used to configure devices (setting configuration parameters and association groups) directly within openHAB. Alternatively 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.

NOTE: There is an issue with using the RPi with the zwave binding - see the known issues below.

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 Do NOT enable Soft Reset
Z-Wave.me Z-StickC No remarks
Sigma UZB ZWave-Plus 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
Option Description
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.
Note that some controllers register themselves as a modem (/dev/ttyACM) on Linux. In this case it is necessary to add user "openhab" to the group "dialout". Else openHAB won't be able to access the controller.
zwave:healtime Sets the time of day when a network heal will be performed.
zwave:pollingQueue Sets the maximum number of frames in th polling queue at once. This avoids swamping the network with poll messages.
zwave:aliveCheckPeriod Sets the time (in milliseconds) between each node health check message. This is used to periodically check if a node is alive.
zwave:softReset Set to true to perform a soft reset on the controller during the heal, and when the binding starts. This can help solve some problems with the stick, but it can also cause some new controllers to lock up (eg the ZWave Plus controllers)
zwave:masterController This option tells the binding that it is the main controller in the network. This isn't necessarily the same as a primary controller - it simply means that your openhab binding is being used as the main network interface. If set to ```true```, the binding will configure devices automatically to send some communications to the binding. This would include setting the wakeup class to send notifications to openhab, and set some associations so that the binding recieves notifications of configuration change or alarms. (being introduced for 1.7)

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 required when using the multi_instance command class. In case a node consists of multiple instances or endpoints, the instance number can be specified using this value. The default value is not to use the multi_instance command class (effectively a default value of 0). An example of a multi-endpoint device is the Fibaro FGS 221 double relay.

PLEASE NOTE THAT THE ENDPOINT NUMBERING CHANGED FOR 1.6 RELEASE. Previously, the default value was 1, but this caused problems with multi-instance devices. This meant that a binding string of zwave=18:1 and zwave=18 was the same - this is now NOT the case.

If you're not sure about endpoint numbering, look in the logs to see if sensor data is being correlated. You may see the following warning -:

2014-12-14 12:51:17.065 WARN  o.o.b.z.i.ZWaveActiveBinding[:459]- NODE 8: No item bound for event, endpoint = 0, command class = SENSOR_MULTILEVEL, value = 51, ignoring.

This indicates that the binding can’t find an item linked to this sensor - often this is because the endpoint numbering is incorrect. If the warning above says endpoint = 0, then the binding string shouldn't include an endpoint number.

The command is optional, but recommended if you have multiple items bound to the same device, or the device reports multiple bits of information. Without the command class, the binding can not unambiguously differentiate different data, so it is recommended to provide a command class. 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 **meter_scale=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_type=value** : optional parameter to select a sensor in case the node supports multiple sensors. Value is one of the following **numerical** values:
1 = General Purpose
2 = Smoke
3 = Carbon Monoxide
4 = Carbon Dioxide
5 = Heat
6 = Water
7 = Freeze
8 = Tamper
9 = Aux
10 = Door/Window
11 = Tilt
12 = Motion
13 = Glass Break
SENSOR_MULTILEVEL Used to bind to e.g. a temperature sensor. Currently only single sensors are supported. **sensor_type=value** : optional parameter to select a sensor in case the node supports multiple sensors. Value is one of the following **numerical** values:
1 = Temperature
2 = General
3 = Luminance
4 = Power
5 = RelativeHumidity
6 = Velocity
7 = Direction
8 = AtmosphericPressure
9 = BarometricPressure
10 = SolarRadiation
11 = DewPoint
12 = RainRate
13 = TideLevel
14 = Weight
15 = Voltage
16 = Current
17 = CO2
18 = AirFlow
19 = TankCapacity
20 = Distance
21 = AnglePosition
22 = Rotation
23 = WaterTemperature
24 = SoilTemperature
25 = SeismicIntensity
26 = SeismicMagnitude
27 = Ultraviolet
28 = ElectricalResistivity
29 = ElectricalConductivity
30 = Loudness
31 = Moisture
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. *alarm_type=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")
SCENE_ACTIVATION Used to respond to Scene events. scene=xx to identify the scene to trigger on
state=xx to set the item to the specified state (xx is an integer)
ALARM
MULTI_CMD Used to send multiple command classes in a single packet.
THERMOSTAT_MODE (since 1.6.0) Used to get and set the mode (of Number type) of the thermostat numeric values translate to the following types
0 = "Off"
1 = "Heat"
2 = "Cool"
3 = "Auto"
4 = "Aux Heat"
5 = "Resume"
6 = "Fan Only"
7 = "Furnace"
8 = "Dry Air"
9 = "Moist Air"
10 = "Auto Changeover"
11 = "Heat Econ"
12 = "Cool Econ"
13 = "Away"
THERMOSTAT_OPERATING_STATE (since 1.6.0) Used to get the operating state (of Number type) of the thermostat numeric values translate to the following types
0 = "Idle"
1 = "Heating"
2 = "Cooling"
3 = "Fan Only"
4 = "Pending Heat"
5 = "Pending Cool"
6 = "Vent / Economizer"
THERMOSTAT_SETPOINT (since 1.6.0) Used to get and set the setpoint of the thermostat **setpoint_type=value** : parameter to select setpoint type, value is one of the following numerical values:
1 = Heat
2 = Cool
*setpoint_scale=value** : optional parameter to select setpoint scale, value is one of the following numerical values:
0 = Celsius
1 = Fahrenheit
THERMOSTAT_FAN_MODE (since 1.6.0) Used to get the fan mode (of Number type) of the thermostat numeric values translate to the following types
0 = "Auto Low"
1 = "On Low"
2 = "Auto High"
3 = "On High"
4 = "Unknown"
5 = "Unknown"
6 = "Circulate"
THERMOSTAT_FAN_STATE (since 1.6.0) Used to get the fan state (of Number type) of the thermostat numeric values translate to the following types
0 = "Idle"
1 = "Running"
2 = "Running High"
CONFIGURATION Used to set configuration parameters. Normally, this is done through HABmin as most configuration is static, but some devices have parameters that need to be changed via a rule or sitemap. Use the "parameter=" option in the binding string to set the parameter number linked to this item.
INFO This is not a 'real' zwave command class, but can be used to get information from the binding about a node and its state. Controller only:
HOME_ID
SOF
CAN
NAK
OOF
ACK
TIME_OUT
TX_QUEUE

All Nodes:
NODE_ID
LISTENING
DEAD
ROUTING
VERSION
BASIC
BASIC_LABEL
GENERIC
GENERIC_LABEL
SPECIFIC
SPECIFIC_LABEL
MANUFACTURER
DEVICE_ID
DEVICE_TYPE
LAST_UPDATE

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.

meter_zero=xx.x can be set when using the Meter command class. If set, anything below the value specified will be considered as 0. This allows the user to account for small power consumption readings even when a device is off.

sensor_scale=X can be set for the multilevel sensor class to force the sensor to be converted to a specific scale. This uses the scale information provided by the device to decide how, or if, the conversion needs to be applied. Currently this is only available for temperature sensors. eg. sensor_scale=0 will ensure that a temperature sensor is always shown in celsius, while sensor_scale=1 will ensure fahrenheit.

invert_state=true can be used to invert the state of a multilevel switch command class. eg this can be used to reverse the direction of a rollershutter.

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 create an issue.

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 and causes considerable problems with the operation of the binding. In large networks, the queue can get extremely long, which can delay initialisation considerably and cause potentially long delays in sending messages. Some time has been spent investigating this issue and a solution has not been found - the issue doesn't appear to be with the binding itself as the problem doesn't manifest itself on an other platform. If anyone with the hardware and programming experience can help with this it would be useful (add information to https://github.com/openhab/openhab/issues/1564).

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:command=info,item=sof"}
Number ZwaveStatsACK "Number of Acknowledgments [%s]" (gZwaveStats) {zwave="1:command=info,item=ack"}
Number ZwaveStatsCAN "Number of CAN [%s]" (gZwaveStats) {zwave="1:command=info,item=can"}
Number ZwaveStatsNAK "Number of NAK [%s]" (gZwaveStats) {zwave="1:command=info,item=nak"}
Number ZwaveStatsOOF "Number of OOF [%s]" (gZwaveStats) {zwave="1:command=info,item=oof"}
Number ZwaveStatsTimeout "Number of Time-outs [%s]" (gZwaveStats) {zwave="1:command=info,item=time_out"}
String ZwaveNode01HomeID	"Home ID [%s]" (gZwaveNode01) {zwave="1:command=info,item=home_id"}
Number ZwaveNode01NetworkID	"Node ID [%s]" (gZwaveNode01) {zwave="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 Everspring ST814 temperature and humidity sensor as example of sensor_multilevel */

Number T_AZH  "Temperature [%.1f °C]" (AZH) {zwave="32:1:command=sensor_multilevel,sensor_type=1" }
Number RH_AZH "Humidity    [%.0f %%]" (AZH) { zwave="32:1:command=sensor_multilevel,sensor_type=5" }

/* 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"} 

/* Honeywell Thermostat with both heating and cooling and in Fahrenheit */

Number Down_HVAC_HeatSetPoint "Heat Set [%.0f F]"	<thermostat>	(Group_HVAC_Downstairs)	{ zwave="7:command=thermostat_setpoint,setpoint_type=1,setpoint_scale=1" }
Number Down_HVAC_CoolSetPoint "Cool Set [%.0f F]"	<thermostat>	(Group_HVAC_Downstairs)	{ zwave="7:command=thermostat_setpoint,setpoint_type=2,setpoint_scale=1" }
Number Down_HVAC_Temperature  "Temperature [%.1f °F]" <thermostat> (Group_HVAC_Downstairs) { zwave="7:command=sensor_multilevel,sensor_type=1" }
Number Down_HVAC_Mode "Mode [%d]"	(Group_HVAC_Downstairs)	{ zwave="7:command=thermostat_mode" }
Number Down_HVAC_Fan_Mode "Fan Mode [%d]"	(Group_HVAC_Downstairs)	{ zwave="7:command=thermostat_fan_mode" }
Number Down_HVAC_Operating_State "Opp State [MAP(thermostatOpState.map):%d]" (Group_HVAC_Downstairs) { zwave="7:command=thermostat_operating_state" }
Number Down_HVAC_Fan_State "Fan State [MAP(thermostatFanState.map):%d]" (Group_HVAC_Downstairs)	{ zwave="7:command=thermostat_fan_state" }

Healing

The binding can perform a nightly heal. This will try to update the neighbor node list, associations and routes. The actual routing is performed by the controller. Two options are possible in the config file to set the healing. healtime sets the time (in hours) that the automatic heal will occur. softReset can also be set to true to perform a soft reset on the controller before the heal. Note that it has been observed that this can cause some zwave-plus sticks to lock up, so you should test this first.

Database

The binding uses a database of devices so that it can work around any quirks, or present information about association groups and configuration data. The format for the database is here.

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.SSS} [%-5level] [%-30.30logger{36}:%-4line]- %msg%n</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.

⚠️ **GitHub.com Fallback** ⚠️