ZWave Binding

The ZWave binding supports an interface to a wireless Z-Wave home automation network.

ZWave is a wireless home automation protocol with reliable two way communications between nodes. It supports a mesh network where mains powered nodes can route messages between nodes that could otherwise not communicate with each other. The network supports hop distances of up to four hops.

A wide range of devices are supported from lights, switches and sensors to smoke alarms, window coverings and keyfobs. Z-Wave certification guarantees that certified devices will be compatible with each other and the network.

The binding uses a standard Z-Wave serial stick to communicate with the Z-Wave devices. There are many sticks available, and they all support the same interface so the binding does not distinguish between them.

Supported Things

The ZWave binding provides support for a large number of devices (currently 802 devices from 114 manufacturers). See the full list of supported things. Note: As of OpenHAB 4.1 700 chip Controllers are fully supported. 800 chip controllers and 800 chip devices are supported for "Classic" inclusion (node numbers 1-232), but not for Long Range (LR) inclusion (node numbers over 255).

ZWave Serial Adapter

Before the binding can be used, a serial adapter must be added. This needs to be done manually. Select Serial ZStick, and enter the serial port.

Discovery

Once the binding is authorized, and an adapter is added, it automatically reads all devices that are included into the network. This is read directly from the Z-Wave controller and new things are added to the Inbox. When the discovery process is started, the binding will put the controller into inclusion mode for a defined period of time to allow new devices to be discovered and added to the network. Device discovery occurs in two phases - first the device is added to the inbox as an Unknown Device to provide the user immediate feedback that the device has been discovered. Once the device type is known, the inbox entry is updated with the actual device name and manufacturer.

In particular the following properties will be automatically populated: | Property | Description | |--------------------|----------------------------------------------| | zwave_nodeid | Node id of the node within the network | | zwave_manufacturer | Manufacturer ID for this device (as decimal) | | zwave_deviceid | Device ID for this device (as decimal) | | zwave_devicetype | Device type for this device (as decimal) | | zwave_version | Application version for this device |

Binding Configuration

There is no binding level configuration required for the Z-Wave binding. All configuration is performed on the devices, or the controller. This allows the system to support multiple controllers.

Controller Configuration

The following section lists the controller configuration. If using manual configuration in text files, the parameter names are given in the square brackets.

Serial Port [port]

Sets the serial port name for the controller.

Controller Is Master [controller_master]

When Controller Is Master is true, the binding expects to be the main Z-Wave controller in the system. This is not related to the type of controller (Primary or Secondary), but is related to how devices will be configured. This will instruct the binding to perform configuration of the device to send network related information such as device wakeup to the binding.

Many functions in Z-Wave only allow a single node to be set, and this is normally reserved for the main system controller. For example, battery device Wakeup Node, and Lifeline association groups usually only allow a single device to be set.

For most systems, this should be set to true - the only time when it should be false is if you normally control your Z-Wave network through a different system.

Controller Is SUC [controller_suc]

Sets the controller as a Static Update Controller within the network

Heal Time [heal_time]

Sets the nightly heal time (in hours).

Inclusion Mode [inclusion_mode]

The inclusion mode setting allows the user to set how the controller will initiate inclusion when discovery is initiated. There are three options available -:

[0] Low Power Inclusion: In this mode devices must be within 1 meter of the controller to be included.
[1] High Power Inclusion: In this mode devices must be able to communicate directly with the controller, so can be 10 to 15 meters from the controller under most conditions.
[2] Network Wide Inclusion: In this mode devices can be anywhere in the network. This mode

Secure Inclusion Mode [security_inclusionmode]

The secure command classes allow you to secure communications between devices in your network. Secure communications is a good thing, and for devices such as locks that protect the security of your property, it's mandatory. However, most devices support the same communications and functions over the standard communication classes, without security. The secure classes come with some negative points - they communicate more slowly, and consume more power in battery devices. This is because there is roughly twice as much communication required for the security classes. You should therefore consider if you need all devices secured, or if it is acceptable for your system to only secure entry devices.

This option allows you to select which classes will be configured to use security - you can elect to use security on all devices that support it, or only on entry control devices.

Inclusion Mode Timeout [controller_inclusiontimeout]

This sets the maximum time that the controller will remain in inclusion or exclusion mode. Once inclusion is enabled, it will be disabled either when the first device is discovered, or when the timeout occurs. Generally this should be kept to a minimum as it increases the opportunity for unwanted nodes to be included into the network.

Note that updating this value will cause the controller to be reinitialised which will take all your Z-Wave devices offline for a short period.

Battery Device Awake Duration [controller_maxawakeperiod]

This sets the maximum awake time for battery nodes (in seconds). This should be set high enough to allow initialization and healing to proceed uninterupted by a "Go to Sleep" command. The "Go to Sleep" will normally be sent much earlier (when the device is fully initializated and no messages remain in the device queue). This is just a backstop for when Zwave communications breakdown between the controller and the device. (see #### Message Routing)

It is defined in seconds.

Default Wakeup Period [controller_wakeupperiod]

This sets the system wide default wakeup period. If a battery device does not have the wakeup period set to a value, then the system will configure it to use this value during the device configuration.

It is defined in seconds.

Network Security Key [security_networkkey]

This sets the network security key used in your network for securing communications using the secure command classes. It is a 16 byte value, specified in hexadecimal. The following formats -:

00112233445566778899AABBCCDDEEFF
00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF
00,11,22,33,44,55,66,77,88,99,AA,BB,CC,DD,EE,FF
0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x99 0xAA 0xBB 0xCC 0xDD 0xEE 0xFF

Thing Configuration

There are a large number of things supported by the Z-Wave binding, so configuration can not be covered here and you should refer to the device manual. A summary of supported devices can be found here and this links to the list of configuration parameters the binding provides.

Textual Thing Configuration

To configure things manually via a .things file you need to configure a Bridge for the controller and then configure devices under that bridge. Follow this sample format:

Bridge zwave:serial_zstick:controller "ZWave Controller" [ port="/dev/ttyACM0", controller_softreset="false", controller_master="true", heal_enable="true", security_networkkey="XXX" ]
{
	aeon_zw100_01_008 sensor1 "Sensor 1" [ node_id=1 ]
	august_asl03_00_000 frontDoor "Front Door Lock" [ node_id=2 ]	
}

Adjust the bridge details as needed, where:

serial_zstick represents the thing type UID of the controller
controller defines the controller's thing name
XXX is a placeholder for the controller's network key

Adjust the details for each device as needed as well, where:

The first value (e.g. aeon_zw100_01_008) specifies the device's thing type UID. You can find this value in the documentation page for all supported Z-Wave devices. Note that the thing type UID has a firmware version appended (e.g. 01_008). Some devices use different thing type UIDs for different firmware versions. You need to make sure to pick the thing type UID that supports your device's firmware. If you don't know your device's firmware version discover the device dynamically and find the firmware version under Properties - zwave_version.
The second value (e.g. sensor1) defines the thing name
node_id is the device's Z-Wwave node id

Define items via a .items file leveraging the channel details documented for your device, for example:

Switch Sensor1 "Motion Sensor" {channel="zwave:aeon_zw100_01_008:controller:sensor1:alarm_motion"}

A note on thing UIDs:

All things are assigned a unique id following the format binding:device type:bridge:id and Z-Wave devices are no different. The above sample for example would be assigned the UID zwave:aeon_zw100_01_008:controller:sensor1.

You might have

Org.openhab.binding.zwave

Install / Use

README