Table of content¶

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

Configuration¶

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

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

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.

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.

Main parameters :

Global parameters :

Create a device for a Zwave device¶

Main parameters :

Global parameters :

Extra parameters for some particular zwave device :

Stop and Start driver (controller)¶

TODO :

Driver automatically starts and start/stop button automatically changes depending on the state of the driver.

• You can stop it when it’s possible :

confimation dialog aks you to continue.

• You can Start it when it’s possible :

Initialization process running, you must be patient ....

Controller commands and actions¶

• You access to dialog box by button

Reset controller¶

• Two mode possible with acces by buttons :

how to use management associations¶

• An icon indicates the status of the device in the group, it may be :

  • unknown
  • confirmed
  • to confirm
  • to update

• The operations are performed by simply drag and drop.

• After making the changes click on OK to send at the device.

• To quit dialog box click Cancel.

• Actually button Reset is not handled.

Example	Description
	If you drop at bad placement a icon forbidden is show.
	When you drop in a group who device ins’it to add it, a icon plus is show.
	After adding device in group, a icon to update is show.
	If you drop at bad placement a icon forbidden is show.

Display commands class list¶

• All command class are listed in a table.

Change values of command class¶

• You can edit the values that are in writing, if the value is changed one “Edit” button appears, you must click it to send change at device
• If exist, pointing the mouse over icon “i” give information about command-class.

• When a value of command class is updated, she his tagged during 5 secondes. Pointing the mouse over value give date of update.

Poll service¶

• Modern devices will not require polling. Some old devices need to be polled as the only way to detect status changes.
• Due to patent concerns, some devices do not report state changes automatically to the controller.

These devices need to have their state polled at regular intervals. The length of the interval is the same for all devices. To even out the Z-Wave network traffic generated by polling, OpenZWave divides the polling interval by the number of devices that have polling enabled, and polls each in turn. It is recommended that if possible, the interval should not be set shorter than the number of polled devices in seconds (so that the network does not have to cope with more than one poll per second).

Stop and Start driver (controller)¶

Driver automatically starts and start/stop button automatically changes depending on the state of the driver.

• You can stop it when it’s possible :

confimation dialog aks you to continue.

• You can Start it when it’s possible :

Initialization process running, you must be patient ....

Controller commands and actions¶

• You access to dialog box by button

Reset controller¶

• Two mode possible with acces by buttons :

Representation of the node according to the initialisation state.¶

Node awake	Init state	node sleeping
	Uninitialized
	Initialized - not known
	In progress - Devices initializing
	In progress - Linked to controller
	In progress - Can receive messages
	In progress - Can receive messages (Not linked) Means that node probably sleeping during init process, at his wake-up initialization will be completed.
	Completed
	Out of operation (failed)

Historical for domogik version 0.3.x¶

• 0.2c4 : (31-01-2014) Compatibily library : OpenZwave >= 1.0.711 (/branches/2013-11-13_release_testing), python_openzwave >= 0.2.5 (rev >= 3bef0f1cb27f)

  • Target : python-openzwave, domogik (0.2c4), domoweb (0.2c3)

  • An insert_data or a reinstall is necessary.

  • Update, compile and install python_openzwave.

    • checkout openzwave branch : goto python-openzwave/openzwave,
    • do command: svn checkout http://open-zwave.googlecode.com/svn/branches/2013-11-13_release_testing

  • Change log :

    • Add heal node/network functions.
    • Add command_class_sensor_alarm.
    • Add auto battery level request at wakeup node.
    • Update doc

• 0.2c3 : (06-01-2014) Compatibily library : OpenZwave >= 1.0.706, python_openzwave >= 0.2.5 (rev >= 75d9b6a8dd77), Compatibilty with ws4py last update >= 0.3.3

  • Target : OpenZwave, python-openzwave, ws4py, domogik (0.2c3), domoweb (0.2c2)

  • Update ws4py with pip or easy_install or update source and compile it.

  • Update, compile and install python_openzwave.

  • Change log :

    • GetPollIntensity add in openzwave lib.
    • Add log debug information for wsServer.
    • Fix auto-startup failure (rest no response).
    • Fix automatique COMMAND_CLASS_SENSOR_BINARY type set for xpl (recreate devices and widget for changes).
    • Fix issue in monitornodes xpl-report if no conforme xpl_msg.
    • Fix wsClient error if ack = undefined (domoweb).
    • Force default name for controler device if not defined (CtrlMustBeCreate.1.1).
    • Update doc

• 0.2c2 : (30-10-2013) Compatibily library : The same, Warning in case of ws4py install or update use >= 0.3.0-beta rev eec3a7dcb33b322eac598f5125425e62c0050969, see instructions in dependencies page.

  • Target : domogik (0.2c2), domoweb (0.2c1)

  • An insert_data or a reinstall is necessary.

  • Knows issue : At auto start plugin fail sometimes, stop it or kill process ($ps -ef | grep ozwave) and restart it.

  • Change log :

    • Add individual monitoring node(s) in log file for debugging and helper develop device compatibilities.
    • Add removing ghost node from groups capability.
    • Add Dimmer multi-controls (FGD211) and bright/dim commands.
    • Add Thermostat setpoint (Danfos living-connect)
    • Add NotifyTransactions option (You must probably modify openzwave lib to fix issues failling plugin start, see doc section options .)
    • Fix wsServer fail connection some time.
    • Fix memory change during websocket sending Broadcast and Ack Message.
    • Fix no display “Support tools” page with some browsers versions.
    • Fix select last controleur action in reopen dialog box.
    • Graph neighbors code improved.
    • Update doc

• 0.2c1 : (15-09-2013) Compatibily library : The same, Warning in case of ws4py install or update use >= 0.3.0-beta rev eec3a7dcb33b322eac598f5125425e62c0050969, see instructions in dependencies page.

  • Target : domogik.

  • Change log :

    • Retrieve domogik device zwave ctrl address from rest.
    • Update doc

• 0.2b5 : (29-07-2013) Compatibily library : OpenZwave >= 1.0.663, python_openzwave >= 0.2.5 (rev >= 18832df1dd95).

  • Target : python_openzwave, domogik and domoweb.

  • Update, compile and install python_openzwave.

  • An insert_data or a reinstall is necessary.

  • Change log :

    • Fix some report controller action.
    • Fix accent on node name and location.
    • Fix display update name and location name just after sended.
    • Fix some actions bug.
    • Fix some Exception error.
    • Forced unit conversion F -> °C for temperature device in F.
    • Double xPL message for switch multi-level. (for testing-not sure it’s a good idea !)
    • UI dialog node associations improvement.
    • Add device motion binary multi sensor 4-in-1.
    • Add polling command_class. Some limitations : there is an issue with getPollIntensity openzwave lib so for moment function is deactivated and value 1 is always received. Some command class like COMMAND_CLASS_POWERLEVEL seem to enable but the polling is not in effect.
    • Add timer reporting controller status on widget (every 60s) and report status “started plugin, started, init, lock, no-ctrl, ok, stop”.
    • Add list of recognized manufacturers and products by openzwave in “support tools” tab.
    • Add force refresh node.
    • Add openzwave log report in “support tools” tab.
    • Add Battery status in tab nodes.
    • Update doc.

• 0.2b4 : (05-28-2013) Compatibily library : the same.

  • Target : domogik and domoweb

  • Change log :

    • Fixe bug plugin starting with package installation
    • Add Domoweb version. (first 0.2.b4)
    • Add support tools, memory usage and log report to UI.
    • Change websocket server private plugin to generic usage.
    • Add load xml open-zwave usage, don’t finish coding.

• 0.2b3 : Compatibily library : python_openzwave >= 0.2.5 (rev : b434c50b795b), tailer >=0.2.1

  • Target : python_openzwave, domogik and domoweb

  • Update, compile and install python_openzwave

  • Install tailer : “sudo pip install tailer” or “sudo easy_install tailer”

  • Change log :

    • Add test network and node
    • Add id message req-ack

• 0.2b2 : Compatibily library : the same.

  • Target : domogik and domoweb

  • An insert_data or a reinstall is necessary

  • Change log :

    • Check user directory and config directory acces
    • Realtime improvements for graph neighbors
    • Add Start/Stop driver function
    • Add zwave device switch with power meter (Everspring (C.T.) - AN158 full handling)
    • Fixe ON/OFF sensor return status

• 0.2b1 : Compatibily library : OpenZwave >= 1.0.645, python_openzwave >= 0.2.5, ws4py >= 0.3.0-beta

  • Target : domogik and domoweb
  • Install new dependency ws4py 0.3.0-beta
  • An insert_data or a reinstall is necessary
  • Enter new wsportserver key (Plugin configuration) and save the config (necessary to restart plugin if is started)

• 0.1b8 :

  • An insert_data or a reinstall is necessary.
  • Created primary controller device for domogik and traced back to the state it to domogik.

Purpose¶

This not a plugin, but an external library for zwave plugin, is based on python-openzwave software.

python-openzawe and openzawe are in high development, by two different teams, so installing it can be sometimes not so easy. So we propose you different methods to install it.

For the operation of ozwave domogik plugin there is only need part python-openzwave Lib.

Of course you can install part python-openzwave API

Get information from bibi21000 home site form more python-openzwave details.

All information are extracted from the git repository https://github.com/OpenZWave/python-openzwave

Installing python-openzwave from archive¶

This is the simplest (and the fastest) way to install python- openzwave. It cames with openzwave source files and is already cythonized.

This is surely the best solution to install python-openzwave on a raspberry pi.

tar xvzf python-openzwave-X.Y.Z.tar.gz

cd python-openzwave-X.Y.Z

sudo make deps

make build

sudo make clean
make build

sudo make install

sudo make uninstall

Installing python-openzwave from repository¶

sudo apt-get install -y git make

git clone https://github.com/OpenZWave/python-openzwave

sudo make repo-deps

cd python-openzwave

make update

make build

sudo make clean

sudo make install

sudo make uninstall

make tests

Static vs dynamic (or shared)¶

The openzwave (c++) lib needs to run as a singleton : it means that it MUST have only one instance of the manager running on your computer.

There is 2 ways of linking libraries with a program :

static : includes a copy of the library in your binary program. This means

that your program has its own instance of the library. This the way the install.sh runs. So you CAN’T have another program (like the control-panel) running when using the python-openzwave library

dynamic or shared : includes a link to the library in your binary program.

This means that your program share the library with other programs. In this case, the instance is owned directly by the library. This the way the debian package works. So you CAN have another program running when using the python-openzwave library. Of course, this program MUST use the shared library.

Creating the zwave device controller¶

We need to create an udev rule in order to create the device /dev/zwave - check your device It’s suppose your zwave controller is at /dev/ttyUSB0

$ udevadm info --name=/dev/ttyUSB0 --attribute-walk

• locate your idVendor and idProdroduct

In /etc/udev/rules.d, create a file zwave.rules, and write the following rule

Example, for aeon stick

| SUBSYSTEMS=="usb", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60",
               SYMLINK+="zwave", MODE="0666"

Other zwave tool¶

git pull

sudo make uninstall

sudo pip uninstall Cython

$ python
Python 2.7.6 (default, Jun 22 2015, 17:58:13)
[GCC 4.8.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.

wget https://launchpad.net/ubuntu/+archive/primary/+files/python2.7_2.7.6-8.dsc https://launchpad.net/ubuntu/+archive/primary/+files/python2.7_2.7.6.orig.tar.gz https://launchpad.net/ubuntu/+archive/primary/+files/python2.7_2.7.6-8.diff.gz

dpkg-source -x python2.7_2.7.6-8.dsc

sudo apt-get build-dep python2.7

cd python2.7-2.7.6

dpkg-buildpackage

cd ..

sudo dpkg -i *.deb

sudo apt-mark hold idle-python2.7 libpython2.7-minimal python2.7-dbg python2.7-minimal libpython2.7 libpython2.7-stdlib python2.7-dev libpython2.7-dbg  libpython2.7-testsuite python2.7-doc libpython2.7-dev python2.7 python2.7-examples

Developer resources¶

For developing you can access to python-openzwave dev, instructions here :

http://bibi21000.gallet.info/index.php/en/component/sphinxdoc/documentation/4-python-openzwave-lib.html

http://bibi21000.gallet.info/index.php/en/component/sphinxdoc/documentation/3-python-openzwave-api.html

Gather information about your device controller (USB)¶

• Example using Aeon Stick2 on USB port. For ohter model it’s should different.

• Use lsusb command for listing of USB devices, check before and after plug your USB controller.

$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 007 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 008 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 009 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 002: ID 0040:073d
Bus 004 Device 002: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x Composite Device
Bus 004 Device 006: ID 0403:6001 Future Technology Devices International, Ltd FT232 USB-Serial (UART) IC
Bus 007 Device 002: ID 0b05:179c ASUSTek Computer, Inc.

• Use ls /dev/ttyUSB* to check your num USB, check before and after plug your USB controller.
• Before

$ ls /dev/ttyUSB*
/dev/ttyUSB2

• After USB plug

$ ls /dev/ttyUSB*
/dev/ttyUSB0  /dev/ttyUSB2

• Use udevadm command to gather information about your device :

$ udevadm info  -a -n /dev/ttyUSB0

Udevadm info starts with the device specified by the devpath and then
walks up the chain of parent devices. It prints for every device
found, all possible attributes in the udev rules key format.
A rule to match, can be composed by the attributes of the device
and the attributes from one single parent device.

  looking at device '/devices/pci0000:00/0000:00:12.0/usb4/4-3/4-3:1.0/ttyUSB0/tty/ttyUSB0':
    KERNEL=="ttyUSB0"
    SUBSYSTEM=="tty"
    DRIVER==""

  looking at parent device '/devices/pci0000:00/0000:00:12.0/usb4/4-3/4-3:1.0/ttyUSB0':
    KERNELS=="ttyUSB0"
    SUBSYSTEMS=="usb-serial"
    DRIVERS=="cp210x"
    ATTRS{port_number}=="0"

  looking at parent device '/devices/pci0000:00/0000:00:12.0/usb4/4-3/4-3:1.0':
    KERNELS=="4-3:1.0"
    SUBSYSTEMS=="usb"
    DRIVERS=="cp210x"
    ATTRS{bInterfaceNumber}=="00"
    ATTRS{bAlternateSetting}==" 0"
    ATTRS{bNumEndpoints}=="02"
    ATTRS{bInterfaceClass}=="ff"
    ATTRS{bInterfaceSubClass}=="00"
    ATTRS{bInterfaceProtocol}=="00"
    ATTRS{supports_autosuspend}=="1"
    ATTRS{interface}=="CP2102 USB to UART Bridge Controller"

  looking at parent device '/devices/pci0000:00/0000:00:12.0/usb4/4-3':
    KERNELS=="4-3"
    SUBSYSTEMS=="usb"
    DRIVERS=="usb"
    ATTRS{configuration}==""
    ATTRS{bNumInterfaces}==" 1"
    ATTRS{bConfigurationValue}=="1"
    ATTRS{bmAttributes}=="80"
    ATTRS{bMaxPower}=="100mA"
    ATTRS{urbnum}=="10835"
    ATTRS{idVendor}=="10c4"
    ATTRS{idProduct}=="ea60"
    ATTRS{bcdDevice}=="0100"
    ATTRS{bDeviceClass}=="00"
    ATTRS{bDeviceSubClass}=="00"
    ATTRS{bDeviceProtocol}=="00"
    ATTRS{bNumConfigurations}=="1"
    ATTRS{bMaxPacketSize0}=="64"
    ATTRS{speed}=="12"
    ATTRS{busnum}=="4"
    ATTRS{devnum}=="2"
    ATTRS{devpath}=="3"
    ATTRS{version}==" 1.10"
    ATTRS{maxchild}=="0"
    ATTRS{quirks}=="0x0"
    ATTRS{avoid_reset_quirk}=="0"
    ATTRS{authorized}=="1"
    ATTRS{manufacturer}=="Silicon Labs"
    ATTRS{product}=="CP2102 USB to UART Bridge Controller"
    ATTRS{serial}=="0001"

  looking at parent device '/devices/pci0000:00/0000:00:12.0/usb4':
    KERNELS=="usb4"
    SUBSYSTEMS=="usb"
    DRIVERS=="usb"
    ATTRS{configuration}==""
    ATTRS{bNumInterfaces}==" 1"
    ATTRS{bConfigurationValue}=="1"
    ATTRS{bmAttributes}=="e0"
    ATTRS{bMaxPower}=="  0mA"
    ATTRS{urbnum}=="134"
    ATTRS{idVendor}=="1d6b"
    ATTRS{idProduct}=="0001"
    ATTRS{bcdDevice}=="0300"
    ATTRS{bDeviceClass}=="09"
    ATTRS{bDeviceSubClass}=="00"
    ATTRS{bDeviceProtocol}=="00"
    ATTRS{bNumConfigurations}=="1"
    ATTRS{bMaxPacketSize0}=="64"
    ATTRS{speed}=="12"
    ATTRS{busnum}=="4"
    ATTRS{devnum}=="1"
    ATTRS{devpath}=="0"
    ATTRS{version}==" 1.10"
    ATTRS{maxchild}=="5"
    ATTRS{quirks}=="0x0"
    ATTRS{avoid_reset_quirk}=="0"
    ATTRS{authorized}=="1"
    ATTRS{manufacturer}=="Linux 3.0.0-24-generic ohci_hcd"
    ATTRS{product}=="OHCI Host Controller"
    ATTRS{serial}=="0000:00:12.0"
    ATTRS{authorized_default}=="1"

  looking at parent device '/devices/pci0000:00/0000:00:12.0':
    KERNELS=="0000:00:12.0"
    SUBSYSTEMS=="pci"
    DRIVERS=="ohci_hcd"
    ATTRS{vendor}=="0x1002"
    ATTRS{device}=="0x4397"
    ATTRS{subsystem_vendor}=="0x1043"
    ATTRS{subsystem_device}=="0x8496"
    ATTRS{class}=="0x0c0310"
    ATTRS{irq}=="18"
    ATTRS{local_cpus}=="00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000003"
    ATTRS{local_cpulist}=="0-1"
    ATTRS{numa_node}=="-1"
    ATTRS{dma_mask_bits}=="32"
    ATTRS{consistent_dma_mask_bits}=="32"
    ATTRS{broken_parity_status}=="0"
    ATTRS{msi_bus}==""

  looking at parent device '/devices/pci0000:00':
    KERNELS=="pci0000:00"
    SUBSYSTEMS==""
    DRIVERS==""

Those information will be useful to determinate for sure that this device is your Zwave controller. We will use several information, flagged above as DRIVERS ATTRS{manufacturer} and ATTRS{product} With that, we will be sure that we’ll be talking to our controller. You can chose others attributs.

Create the rule¶

• Create a new file, in folder etc/udev/rules.d Let’s call it 98-usbcp210x.rules
• Enter those information in the file :

# for z-Stick serie 2 to domogik /dev/zwave
DRIVERS=="usb", ATTRS{manufacturer}=="Silicon Labs", ATTRS{product}=="CP2102 USB to UART Bridge Controller", SYMLINK+="zwave", MODE="0666"

The DRIVERS ATTRS{manufacturer} ATTRS{product} values must be coherent with what you have found above. * Ask udev to rediscover your device :

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

• Your device should now be re-discovered, let’s confirm it :

$ ls -l /dev/zwave
lrwxrwxrwx 1 root root 7 2012-08-27 00:46 /dev/zwave -> ttyUSB0