Z Wave Binding - vpjuslin/openhab GitHub Wiki
Documentation of the Z-Wave binding Bundle.
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.
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 |
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) |
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:
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 |
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.
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.
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).
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" }
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.
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.
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.