Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
This page describes Z-Wave support in OpenRemote. Z-Wave is a proprietary protocol for wireless sensor networks. Wireless sensors are often battery-powered devices that are particularly useful for retro-fitting automation to existing and difficult-to-wire buildings and spaces.
Following hardware is required for OpenRemote Z-Wave integration:
- Aeon Z-Stick Series 2 or Razberry.
- Z-Wave devices linked to AEON Z-Stick Series 2 or Razberry controller.
Although we support many devices, the following devices have been tested:
- Aeon Labs (Aeotec), Z-Stick Series 2
- Z-Wave.Me, ZME_UZB1
- Z-Wave.Me, Z-StickC
- Z-Wave.Me, Razberry
- Z-Wave.Me, Razberry 2
- Danfoss, LC-13 Living Connect Radiator Thermostat
- Fibaro, Relay Switch FGS-211, Switch, multi instance association
- Fibaro, Double Relay Switch FGS-221, Switch, multi instance association
- Fibaro, Double Switch 2 FGS-223
- Fibaro, Universal Dimmer FGD-211, Dimmer, multi instance association
- Fibaro, Roller Shutter 2 FGRM-222, Roller shutter, meter
- Fibaro, Wall Plug FGWPE-101, Switch, meter
- Fibaro, Door/Window Sensor FGK-101-107, Sensor, battery
- Fibaro, Motion Sensor FGMS-001, Sensor (motion, temperature, light intensity), tamper alarm, battery, multi instance association
- Fibaro, Flood Sensor FGFS-101, Alarm (water leak, tamper), temperature, battery, multi instance association
- Fibaro, Flood Sensor FGFS-101 ZW5 (Z-Wave Plus)
- Fibaro, Smoke Sensor FGSS-001, Alarm (smoke, heat, tamper), temperature, battery, multi instance association
- Fibaro, Button FGPB-101
- Aeon Labs (Aeotec), Micro Smart Dimmer (2nd edition), Dimmer, meter
- Aeon Labs (Aeotec), 4-in-1 MultiSensor, Sensor (motion, temperature, light intensity, humidity)
- Aeon Labs (Aeotec), MultiSensor 6 GEN5
- Aeon Labs (Aeotec), Range Extender
- Aeon Labs (Aeotec), Recessed Door Sensor GEN5
- Aeon Labs (Aeotec), Led Bulb GEN5
- Aeon Labs (Aeotec), Siren GEN5
- Qubino, Flush 1 Relay, Switch, meter, sensor(temperature, binary)
- Qubino, Flush Dimmer, Dimmer, meter, sensor(temperature, binary)
- Qubino, Flush Shutter, Roller shutter
- Zipato, RGBW Bulb
- Radio Thermostat Company of America, Thermostat CT100
- Kwikset, SmartCode 916 Touchscreen Electronic Deadbolt
- Schlage, BE469 Touchscreen Deadbolt with Alarm
Configuration of System
Important Configuration Notes
- Aeon Z-Wave USB stick must be the primary controller of your Z-Wave installation. If you already have your devices linked to another controller (eg. a remote control or panel), you have to exclude them before using OpenRemote. Including Aeon Z-Wave USB stick as a secondary controller in an already existing Z-Wave network has not been implemented yet.
MAC OS X Users
For latest drivers to Aeon Labs Z-Stick Series 2 controller, install the software package available here: USB to UART Bridge VCP Drivers
Install the drivers and reboot your machine. A USB serial port should appear as a link named /dev/tty.SLAB_USBtoUART. You can confirm this by opening a console on OSX and typing 'ls /dev/ | more'. From the list of devices check that SLAB_USBtoUART (or a similar name) is present._
To activate the OpenRemote Z-Wave implementation you need to modify the controller configuration in OpenRemote Designer. In the designer navigate to the "Building Modeler -> Config for Controller -> z-wave". In the drop-down selection for communication layer, select RXTX, see Image 1 below.
Figure 1: Change Controller Configuration in OpenRemote Designer
Below the communication layer setting, configure the serial port which is used by Aeon Labs Z-Stick. Do not remove or change the other settings in this screen.
Serial Port Configuration
Mac OS X: typically the Aeon Labs USB dongle can be found in /dev/tty.SLAB_USBtoUART -- see note on installing Aeon Labs drivers for Mac OS X above.
Microsoft Windows: On Windows, the serial port identifier is typically assigned automatically when the USB dongle is inserted -- check the Device Manager/Ports for the port identifier (COM2, COM3, etc.) as shown in Image 2 below.
Figure 2: Serial Port Identifier (COM3) on Microsoft Windows Device Manager
Linux: the Silicon Labs USB to UART bridge can be found under /dev directory.
Razberry Serial Port Configuration
Note that the following description assumes that you’ve installed Raspbian Jessie as operating system.
For more information on how to install the OpenRemote Controller software see the following page : Raspberry Pi.
Deactivate Serial Console (Raspberry Pi 1, 2, 3)
The serial GPIO pins of the Raspberry Pi are used for the serial console by default. In order to use these pins in combination with the Razberry you have to deactivate the serial console. In the terminal type the following command:
In the Advanced Options select Serial and deactivate the login shell.
Advanced Options > Serial > Would you like a login shell to be accessible over serial ? > No
Disable Bluetooth (Raspberry Pi 3)
On the Raspberry Pi 3 you have to reassign the hardware UART from the Bluetooth chip to the serial GPIO pins. Note that this step is only necessary for the Raspberry Pi 3. It’s not needed for the other Raspberry Pi's. There are solutions that try to do this without loosing Bluetooth functionality. However, the simplest solution is to disable Bluetooth.
sudo nano /boot/config.txt
At the end of the file add the following:
Edit or add the following setting in the file /boot/config.txt:
Execute the following command:
sudo systemctl disable hciuart
Finally reboot the system:
Define Raspberry Pi Serial Port (Raspberry Pi 1, 2, 3)
The serial library that is used for the OpenRemote Z-Wave protocol implementation doesn't recognize
/dev/ttyAMA0 as a serial port. In order to make sure that the serial library accepts
/dev/ttyAMA0 as a serial port edit the file <OpenRemote Controller>/bin/openremote.sh
and add the following export:
... # ===== OPENREMOTE SETUP ============================================================== export JAVA_OPTS=-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0 ...
Z-Wave Node Inclusion
Each Z-Wave device in a Z-Wave network is uniquely addressed by means of a so called Home ID (4 bytes) and Node ID (1 byte). All nodes in the same Z-Wave network have the same Home ID but different Node IDs. Nodes with different Home IDs cannot communicate with each other.
At inclusion time of a Z-Wave device the unique Home ID and Node ID is assigned to the device by the primary Z-Wave controller. The Z-Wave interface acts as the primary controller and has to be put in inclusion mode in order to add a Z-Wave device to the network.
Initiate Inclusion Mode
There are two options to initiate inclusion mode of the primary Z-Wave controller.
Unplug the Aeon Labs Z-Stick and press the action button shortly (the blue LED will blink slowly).
Activate inclusion mode by means of software commands. The following commands are used to create a switch that can be used to turn on/off inclusion mode. See Z-Wave Device Inclusion & Exclusion for more details.
|Use node ID 1 in the online Designer|
Use node ID 1 in the online Designer when you create the Z-Wave commands.
Note that security enabled devices can only be included with option 2. Most modern Z-Wave devices with the
Z-Wave PlusTM label and door locks are security enabled. Only old devices that do not support
COMMAND_CLASS_SECURITY can be included with the action button of the Aeon Labs Z-Stick (option 1).
Z-Wave Node Exclusion
Sometimes it's necessary to remove a Z-Wave device form a Z-Wave network because of the following reasons:
- You want to add a device to another Z-Wave network (different Home ID). Note that a Z-Wave device can only be part of a single Z-Wave network.
- Device should be reset to factory defaults (parameter, wakeup and association configurations settings are reset)
- The device could not be successfully added to the Z-Wave network.
Initiate Exclusion Mode
There are two options to initiate exclusion mode of the primary Z-Wave controller.
Unplug the Aeon Labs Z-Stick and press the action button for approximately 2 seconds (the orange LED will blink fast).
Activate exclusion mode by means of software commands. The following commands are used to create a switch that can be used to turn on/off exclusion mode. See Z-Wave Device Inclusion & Exclusion for more details.
|Use node ID 1 in the online Designer|
Use node ID 1 in the online Designer when you create the Z-Wave commands.
Option 1 and Option 2 can be used to exclude devices from a Z-Wave network no matter if it's a security enabled device, a modern device with the
Z-Wave PlusTM label or an old Z-Wave device.
Z-Wave Device Configuration
After a device has been included to a Z-Wave network, it works with reasonable default device configuration settings. To further adjust the operation of the device, the following customization options are available.
- Wake up interval
An association links two devices, enabling them to communicate without the need for a central controller. It’s also necessary to create an association from the device to the controller if the device should send a status update to the controller asynchronously. Associations are part of a certain association group and each device may have several association groups. If an association group is triggered, all devices that are association targets of the group are receiving the same command. The device manual lists all available association groups and the maximum number of associations in each group.
Parameters are used to configure the functionality of Z-Wave devices. The size of a parameter is 1, 2 or 4 bytes. The device manual lists all available parameters.
Battery powered device are in sleep mode most of the times to save battery life. In sleep mode it’s not possible to initiate a communication with the device. In order to enable communication with the device it wakes up from time to time. The wake up interval parameter of the Z-Wave command class
COMMAND_CLASS_WAKEUP is used to configure this behaviour. Note that the wake up interval setting is always a compromise of power consumption and responsiveness.
Manual Configuration Procedure
Currently there is no graphical user interface for configuring Z-Wave devices, instead an XML file has to be edited manually with a text editor. The mentioned XML file is created for each device after is has been successfully included to the Z-Wave network and is located in the directory <OpenRemote Controller>/webapps/controller/zwave. Each device is represented by a node<nodeID>.xml file which contains a
<configuration> section that has to be edited manually.
Please proceed as follows when you configure associations, parameters or the wake up interval:
- Open the node<nodeID>.xml file in a text editor
- Edit the association, parameter or the wake up interval within the
- Restart the OpenRemote controller
- Watch the
hashattribute of the
<configuration hash="78F0...">element - the hash value will be changed after the configuration has been successfully written to the device.
In order to configure an association add an
<association> element to the
<association-group> element and follow the Manual Configuration Procedure.
Note that the
capacityattribute of the
<association-group capacity="..">element indicates the maximum number of associations in the association group.
In the following example an association that points to the primary controller (nodeID 1) has been added to the third association group.
<node id="6"> ... ... <configuration hash="FA035ACF6EC2AF7CD89543A422425087"> <associations> <association-group id="1" capacity="5" /> <association-group id="2" capacity="5" /> <association-group id="3" capacity="1"> <association> <node>1</node> </association> </association-group> </associations> ... ... </configuration> </node>
Multi Channel Association Configuration
There are devices that are composed of sub devices like a power strip that is composed of multiple switchable power outlets. In this context Z-Wave uses the terms endpoint, channel or instance when it comes to addressing sub devices. If a device supports
COMMAND_CLASS_MULTI_INSTANCE_ASSOCIATION it’s possible to create associations that address sub devices.
In order to configure an association add an
<association> element to the
<association-group> and follow the Manual Configuration Procedure. The
<association> element has in addition to the
<node> element an
<endpoint> child element.
In the following example an association that points to the third sub device of the Z-Wave device with node ID 7 has been created. If the Z-Wave device with ID 7 is a power strip, the association is used to turn on/off the third power outlet.
<node id="6"> ... ... <configuration hash="FA035ACF6EC2AF7CD89543A422425087"> <associations> <association-group id="1" capacity="5" /> <association> <node>7</node> <endpoint>3</endpoint> </association> </association-group> </associations> ... ... </configuration> </node>
Parameters are used to program a device’s behaviour.
In order to configure a parameter add a
<parameter> element to the
<parameters> collection and follow the Manual Configuration Procedure. The
<parameter> element consists of the
<size> sub elements. The
<number> element contains the parameter number. The
<size> element contains the size of the parameter which can be 1, 2 or 4 bytes. The
<value> element contains the parameter value which can be a positive or negative number without fractional digits.
In the following example parameter number 14 with size 1 byte and the value 24 has been added to the configuration.
<node id="6"> ... ... <configuration hash="FA035ACF6EC2AF7CD89543A422425087"> ... ... <parameters> <parameter> <number>24</number> <value>1</value> <size>1</size> </parameter> </parameters> ... ... </configuration> </node>
Wake Up Interval Configuration
In order to configure the wake up interval of a battery powered device edit the
interval attribute value of the existing
<wake-up interval=".."> element within the
<configuration> element and follow the Manual Configuration Procedure. If the device supports
COMMAND_CLASS_WAKE_UP Version 2, you’ll find the constraints
<step> for valid wake up interval values within the related Z-Wave command class element (see following example). Version 1 of
COMMAND_CLASS_WAKE_UP doesn’t have these constraints.
A wake up interval value of 0 means that the device doesn’t wake up if not necessary. It does not mean that the device never wakes up. A door/windows sensor will always send a status update even if the wake up interval is 0.
Note that a wake up interval value of 0 could be a reasonable setting if you have problems with power consumption of your battery powered device. Writing a new configuration to a device with this interval setting could be a problem because it never wakes up. In this case you have to wake it up manually (see device manual).
In the following example a wake up interval of 240 seconds has been configured. Valid values would be 0, 60, 120, 180, 240, 300, ... .
<node id="5"> ... ... <command-classes> ... ... <command-class id="0x84" version="2" name="COMMAND_CLASS_WAKE_UP_V2" type="supported"> <wake-up-interval>0</wake-up-interval> <notification-node-id>1</notification-node-id> <wake-up-interval-capabilities> <min>0</min> <max>64800</max> <default>0</default> <step>60</step> </wake-up-interval-capabilities> </command-class> ... ... </command-classes> <configuration hash="782580EF72691946A6F2D3327D91B9ED"> ... ... <wake-up interval="240" /> ... ... </configuration> </node>
Security Key Configuration
Security enabled devices like door locks or new products with the
Z-Wave PlusTM logo use symmetrical AES128 encryption to secure data transmission. Symmetrical means that the controller and the device have a private key that is used to encrypt data communication. There is only a single 128 bit network wide key in a Z-Wave network that means all devices use the same encryption key and as a result can communicate securely with each other. At inclusion time of a security enabled device the controller transmits the encryption key from the controller to the device. The encryption key has to be configured in the file <OpenRemote Controller>/webapps/controller/WEB-INF/classes/zwave.properties.
# # Z-Wave security layer network key (128 bit key --> 16 bytes) # # Note that this is a secret key that is used for symmetric encryption. An attacker with access to this key # is able to decrypt Z-Wave commands and also send encrypted Z-Wave commands (e.g. send the encrypted # unlock command to a door lock device). zwave.networkKey=0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10
Note that this key should be stored in a safe place after it has been modified because you’ll need it if you want to install a new controller version. If you loose this key you have to exclude and re-include all security enabled devices again.
Designer Z-Wave Commands
In order to configure a Z-Wave command in the OpenRemote Designer information about the Z-Wave node ID and a Z-Wave command string is needed (see Image 3 below).
Figure 3: Create Z-Wave Command
Z-Wave Node ID
At inclusion time of a Z-Wave device to a Z-Wave network a so called node ID is allocated for each new device. The node ID is unique within the Z-Wave network. In order to determine the node ID of the new Z-Wave device take a look into the directory <OpenRemote Controller>/webapps/controller/zwave. There you’ll find node<nodeID>.xml files for all devices that have been successfully included. If the highest node ID was 7 before you’ve added a new device you’ll find the file node8.xml after a new device has been included. In this example 8 is the node ID of the new Z-Wave device.
Z-Wave Command String
The functionality of a Z-Wave device is composed of several so called Z-Wave command classes. You’ll find all command classes of a Z-Wave device in the node<nodeID>.xml file. These Z-Wave command classes determine which command strings can be used in the OpenRemote Designer. The following example is an excerpt of the node<nodeID>.xml file of a Z-Wave switch. The device supports
<?xml version="1.0" encoding="UTF-8"?> <node id="8"> <manufacturer id="271">Fibargroup</manufacturer> <basic-device-class id="0x04">BASIC_TYPE_ROUTING_SLAVE</basic-device-class> <generic-device-class id="0x10">GENERIC_TYPE_SWITCH_BINARY</generic-device-class> <specific-device-class id="0x01">SPECIFIC_TYPE_POWER_SWITCH_BINARY</specific-device-class> <product-type id="0x0203" /> <product id="0x1000" /> <listening>true</listening> <routing>true</routing> <command-classes> ... ... <command-class id="0x25" version="1" name="COMMAND_CLASS_SWITCH_BINARY" type="supported" security="secured_only" /> ... ... </command-classes> </node>
In the Supported Z-Wave Command Classes table you’ll find all command strings that can be used in combination with each Z-Wave command class. In this example the command strings
STATUS can be used with
Some Devices are composed of multiple sub-devices that are addressed by so called endpoints. You’ll also find the terms multi instance and multi channel in this context. A typical representative of this device category is a power strip or a double relay switch. There are also sensor devices that are composed of sub devices like a flood sensor that has also a temperature sensor. All these devices support
The following example is an excerpt of the node<nodeID>.xml file that describes the capabilities of a double relay switch. The important part of this example is the
<endpoints> section. The
<endpoints> element contains an
<endpoint> element for each sub-device. In this example there is an
<endpoint> element for each relay.
<?xml version="1.0" encoding="UTF-8"?> <node id="9"> <manufacturer id="271">Fibargroup</manufacturer> <basic-device-class id="0x04">BASIC_TYPE_ROUTING_SLAVE</basic-device-class> <generic-device-class id="0x10">GENERIC_TYPE_SWITCH_BINARY</generic-device-class> <specific-device-class id="0x01">SPECIFIC_TYPE_POWER_SWITCH_BINARY</specific-device-class> ... <command-classes> ... <command-class id="0x60" version="2" name="COMMAND_CLASS_MULTI_CHANNEL_V2" type="supported" /> ... </command-classes> ... <endpoints> <endpoint number="1"> <command-classes> ... <command-class id="0x25" version="1" name="COMMAND_CLASS_SWITCH_BINARY" type="supported" /> ... </command-classes> </endpoint> <endpoint number="2"> <command-classes> ... <command-class id="0x25" version="1" name="COMMAND_CLASS_SWITCH_BINARY" type="supported" /> ... </command-classes> </endpoint> </endpoints> ... </node>
In order to configure a Z-Wave command in the OpenRemote Designer that addresses a sub-device you have to append the endpoint number to the Z-Wave node ID separated by a colon (see image 4 below). Valid endpoint numbers are 1, 2, 3,.. and so on. This example shows the configuration of a sensor command that is used to read the status update of the second relay.
Figure 4: Create Z-Wave Sub-Device Command
Supported Z-Wave Command Classes
|Z-Wave Command Class||Designer Commands|
SET_COLOR_CHANNEL_<channel name>, SET_COLOR (color picker), STATUS_COLOR_CHANNEL_<channel name>
Channel Names : [RED, GREEN, BLUE, AMBER, CYAN, PURPLE, WARM_WHITE, COLD_WHITE]Examples : SET_COLOR_CHANNEL_BLUE, STATUS_COLOR_CHANNEL_WARM_WHITE
|DOOR_LOCK||LOCK, UNLOCK, STATUS_DOOR_LOCK|
|SWITCH_BINARY||ON, OFF, STATUS|
|SWITCH_MULTI_LEVEL||DIM, ON, OFF, STATUS|
|SWITCH_MULTI_LEVEL_V3||UP, DOWN, STOP, DIM, STATUS, STATUS_TARGET|
Create Z-Wave User Interface
Once your Z-Wave building objects like commands, sensors, switches and sliders are in place in OpenRemote Designer you can start binding the Z-Wave objects to user interface elements. See the documentation on User Interface Design to learn how to bind building objects to user interface widgets.