Plugin documentation

icon

Last changes

Before installation a new release of this plugin, please check the changelog.

Purpose

Note

Please notice that this plugin is still in development!

If you find any issue, please create a ticket on the Gihub repository : https://github.com/Nico0084/domogik-plugin-ozwave/issues

In the same way, if something is not clear or wrong in this documentation, feel free to open a ticket!

Z-Wave is a wireless ecosystem that lets all your home electronics talk to each other, and to you, via remote control. This plugin allows to control zwave devices.

It uses the open source library openZwave c++ project and python-openzwave as interfacing cython,

The Zwave network manager is directly integrated into the plugin.

Simple action/sensor of devices have access via domogik devices (widgets). Viewing and setting Zwave devices is accessed via a special plugin page from the admin panel.

Development is in progress, features will get gradually added.

Steps to set up your first Zwave device

To set up your first Zwave device, you will have to :

  • install this plugin on domogik
  • install this plugin dependencies
  • create an udev rule for your Zwave controller (the usb device you plug on the computer)
  • configure this plugin
  • create a Domogik device for your Zwave controller
  • start the plugin
  • in the Advanced pages, look for your Zwave device and get informations about it
  • create the Domogik device for your Zwave device

Dependencies

If ou are using a Debian based Linux release, you can install the dependencies with an installation script (in the root of the ozwave package folder) :

$ sudo ./install_dependencies.sh

Options :

  • -LAST : get the last python-openzwave archive from Git repository.
  • -v x.x.x : get a specific python-openzwave archive from Git repository.
  • nothing : get default python-openzwave archive from Git repository.

Else, you can follow the detailed instructions.

Zwave Controller and devices Compatibility List

The following controller interfaces are supported and verified with Domogik:

  • Aeon Labs Z-Stick Series 2

  • Aeon Labs Z-Stick Gen5

  • RaZberry * using rule with /dev/ttyAMA0 instead of /dev/ttyUSBx) * user domogik must have write permission, you can add it in dialout group.

    $ sudo usermod -a -G dialout domogik
    

Other controllers are also supported by openzwave, you can check here

The following devices are supported :

  • Everspring
    • ST814 - Temperature, Humidity Sensor
    • AN158 - Switch Meter Plugin
    • SE812 - Siren
  • Everspring (C.T.)
    • HSM02 - Door windows sensor
  • Fibaro
    • FGS211 - Relay Switch 3KW
    • FGS221 - Double Relay Switch 2x1,5kW
    • FGD211 - Universal Dimmer 500W
    • WallPlug - Meter Switch with leds
  • Aeon Labs
    • HEM - Home Energy Metter
    • DSB05 - Motion Multi Sensor
    • ZW089 - Recessed Door Sensor Gen5
  • Express Controls
    • HSM100 - EZMotion luminosity and temperature sensor
  • Danfoss
    • Living connect (thermost heating)
  • Qubino
    • ZMNHCDx - Flush Shutter

Create the udev rule for the Zwave controller

You may create a udev rule for this device. The rule and filename are given in the Requirements tab of the plugin configuration page.

Currently, your PC controller is known as /dev/ttyUSBx (by default). This is not very convenient nor meaningful.

We will so create a new udev rule that will create a link called /dev/zwave that will point to /dev/ttyUSBx.

Zwave controller model Udev rule file
Aeon Labs Gen4 Zwave gen4 98-usbcp210x.rules
Aeon Labs Gen5 Zwave+ gen5 99-usbzstickgen5.rules

To install a udev rule, copy the appropriate file in the udev rules folder on your system. Example

$ sudo cp udev/98-usbcp210x.rules /etc/udev/rules.d/

Then, you can use the following command to apply the udev rule, or unplug/plug the Zwave controller.

$ sudo udevadm test $(udevadm info --query path --name ttyUSB0)

If your controller is not handled by any of the proposed udev rules, please check the tutorial on how to create your own udev rule.

Plugin configuration

Configuration

In Domogik administration section, go to the plugin ozwave configuration page.

Key Type Description
autoconfpath boolean

If checked, the plugin will try to automatically find the Openzwave library path.

If not checked, you will have to manually set the Openzwave library path with the parameter configpath.

configpath string

If autoconfpath is not checked, set up the Openzwave library path. Example :

/usr/local/lib/python2.7/dist-packages/libopenzwave-0.3.0b7-py2.7-linux-x86_64.egg

In this folder you will find all the Openzwave xml files.

cpltmsg boolean

Notifications when transaction complete is reported.

Note

In any case the value of openzwave option.xml file is the last considered.
If NotifyTransactions is enable in your option.xml comment it to get control by plugin.
ozwlog boolean

If checked, activate the Openzwave logger.

Please do this only for debug purpose as the logs are very verbose!

The file is located in the data folder of the plugin and named OZW_Log.txt.

Note

In any case, if exist, the value of option.xml file is the last considered.
If Logging is enable in your option.xml comment it to get control by plugin.

Now, you will need to create a device for your Zwave controller...

Create a device for the primary Zwave controller

In clients page of admin UI, go to the Domogik devices page.

To create a device, click on Create a new Domogik device

Then, select the device type : Zwave Controller.

creat_ctrldevice

This device will create a link between the controller device and Openzwave. It will also create a link between the Zwave homeId and your networkId used by Domogik for the devices adresses.

You can create the controller device after starting the plugin, so it is possible to find its address in the devices table of the controller and devices.

You can create as many Zwave Controler you have primary controllers.

Note

Creating this device is necessary to handle your zwave network.

Main parameters :

Key Example Description
Device Name MyController The display name for this device.
Description What you want A short descriptionn for this device.
Reference Z-Stick 2 A reference for this device, eg.: manufacturer reference.

Global parameters :

Key Example Description
driver /dev/zwave Z-wave device that you have define in UDEV rule
networkid MyHomeNetwork Home ID name for association with domogik devices

Create a device for a Zwave device

example_device1

Main parameters :

Key Example Description
Device Name MyController The display name for this device.
Description What you want A short descriptionn for this device.
Reference FGWPE Wall Plug A reference for this device, eg.: manufacturer reference.

Global parameters :

example_device2

Key Example Description
networkid MyHomeNetwork Home ID name for association with domogik devices
node 14 Z-wave node id that you can find in the nodes table
instance 1 Zwave node instance id that you can find in the Commands Class table

Extra parameters for some particular zwave device :

Key Example Description
batterycheck True HCheck battery level at zwave device wakeup.

Start the plugin

You can now start the plugin (start button) and use the created devices.

Configure the features widgets on Domoweb

You can now place the widgets of your devices features on Domoweb.