Table of content¶

Last change¶

New instructions to apply changes from immediatly previous version.

• 0.4.0b1 : (12-10-2015) Compatibily library : OpenZwave >= 1.3.401, python_openzwave >= 0.3.0 (b4)

  • Target : python-openzwave, domogik (0.4.1)

  • Update, compile and install python_openzwave.

  • Change log :

    • New version for domogik 0.4.1

• Previous change

Purpose¶

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 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

Dependencies¶

• Python-openzwave (>=0.3.5)
• tailer 0.3 library for Python (>=0.2.1)

Controller/devices Compatibility List¶

Following interfaces are supported and verify with domogik:

• Aeon Labs Z-Stick Series 2
• RaZberry (using rule with /dev/ttyAMA0 instead of /dev/ttyUSBx)

Others controllers are supported by openzwave, you can check here

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,

• Express Controls

  • HSM100 - EZMotion luminosity and temperature sensor

• Danfoss

  • Living connect (thermost heating)

Create the udev rule for 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 then create a new udev rule that will create a link called /dev/zwave that will point to /dev/ttyUSBx.

$ 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.

$ ls /dev/ttyUSB*
/dev/ttyUSB2

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

$ 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==""

# 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"

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

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

Plugin configuration¶

Install the tailer library for Python¶

• tailer 0.3 library for Python

Install tailer :

$ sudo pip install tailer

Install python-openzwave¶

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

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

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

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

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

State and version of libraries¶

The two flag Openzwave and Manager give the state of respective library

• Red : Stopped

* Green : Alive * orange : Starting * Grey : Unknown * Black : Failed

Openzwave: is the openzwave librarie installed. Manager: is the ozwave plugin manager connected to openzwave.

On right python-openzwave and openzwave libraries version are display, only if the plugin is started.

This row can be collaspe to display openzwave configuration options.

Openzwave configuration options¶

Here you can check all options. All details are commented in table.

Soon in a future release, it may be possible to edit them..

Controller and Network tab¶

Under state libraries row, a tab list and display all controller knowns.

Get Zwave controller informations¶

• you can check to verify the information on zwave network state and controller in the first part of the page.

The status information can be refreshed using button.

Get Zwave devices (Nodes) informations¶

• Devices initialisation field give state of global initialize process.

The process can take a long time (up to 5 min). Be patient..... All nodes discovered and / or stored are scanned one by one to be initialized.

The status information can be refreshed using button.

Representation	Message	Description
	Pointing the mouse over icon in column “NodeId” give status of initializing.
	Uninitialized	No starting init operation.
	Initialized - not known	Node has completed init, but openzwave don’t know is model (shows xml openzwave files).
	Completed	Node has full completed init.
	In progress - Can receive messages (Not linked)	Node can now receive messages, but his initialization not finish. Probably node sleeping. Controller have finish init, when node awake it state should be Completed.
	In progress - Linked to controller	Node is recognize by controller, initialization is in progress.
	In progress - Can receive messages	Node can now receive messages, but initialization not finish.
	Out of operation	Node is mark as failed, controller don’t find him.
	Pointing the mouse over battery icon in column “NodeId” give status of battery level.
	Value in %	Fill icon picture level of battery.
	Pointing the mouse over icon in column “Awake” give status of listening mode.
	Awake	Node is awake, message can send immediately.
	Sleeping	Node probably sleeping, message are put on send queue.
	Pointing the mouse over icon in column “Type” give capacities of node.
	Primary Controller	Node is primary controller, is the main device used to configure and control a Z-Wave network. The only difference between a primary and secondary controller is that the primary is the only one that can be used to add or remove other devices. For this reason, it is usually better for the primary controller to be portable, since most devices must be added when installed in their final location.
	Secondary Controller	There can only be one primary controller - all other controllers are secondary controllers.
	Static Update Controller	A Static Update Controller (SUC) is a controller that must never be moved in normal operation and which can be used by other nodes to receive information about network changes.
	Bridge Controller	A bridge controller is able to create virtual nodes that can be associated with other controllers to enable events to be passed on.
	Routing	Node is a routing device that passes messages to other nodes.
	Listening	Node is a setening device that does not go to sleep.
	Beaming	Node is a beam capable device..
	Security	Node supports security features.
	FLiRS	Node is a frequent setening device that goes to sleep but can be woken up by a beam. Useful to determine node and controller consistency..
	Buttons on column “Action” get access of others commands on nodes.
	Detail Node	Show/hide command class capacities table.
	Update Node	Send to node Name and Location field to update it. Saving modification in config file with “Save config” button
	Edit association	Manage groups association.
	Force Refresh Node	Causes the nodes data to be obtained from the Z-Wave network in the same way as if it had just been added. This method would normally be called automatically by OpenZWave, but if you know that a node has been changed, calling this method will force a refresh of the data held by the library. This can be especially useful for devices that were asleep when the application was first run. Four options possible : Node informations : Fetch the data for a node from the Z-Wave network State Node : Fetch the command class data for a node from the Z-Wave network Dynamics data : Fetch only the dynamic command class data for a node from the Z-Wave network. Heal node with reroute : Try to heal node and reroute it after.
	Monitor Node and log it	This commmand store all event send an receive by a node. To stop monitoring click again button. Log file saved in user path defined in config section. (defaut: share/domogik/data/ozwave/lognodeXXX.log) Log contains also openzwave log if unable.

Manage association devices (groups)¶

• Some devices have the ability to be combined with other devices and can send their information.
• These associations are using groups, access to the dialog management groups is done with the button

how to use management associations¶

Note

• Due to the possibility of sleeping devices, the system considers the command to have been transmitted.
• In the case of a device sleeping command will be transmitted when the device wakes up.
• So the association will be effective as this momment there.

Warning

Careful if the plugin is stopped between time command is lost.

• 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.

Manage devices Commands Class¶

Drivers and controller commands¶

In this section, orders can be sent directly to the driver

Graphic neighborhood network¶

• You can refresh graphic by button

• You can move nodes and arrange it for better links view, but not function to save position for the moment.

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)

Network statistic and tests¶

Tree actions possible :

• Get information about network statistic.
• Start a healing process with reroute all node (node byn node).
• Send test message for all node awake (not sleeping node) - Enter number of send test message per node.

Node statistic and tests¶

two actions possible :

• Get information about a node statistic - Enter node number and click button refresh.
• Send test message for all node awake (not sleeping node) - Enter number of send test message per node.

Device test messages¶

You can send test message to all active nodes, or just one. Enter node number, number of message and click button “Send test messages”. Results are display in “Node statistic” section for both case.

Memory usage¶

• A click on button “refresh” show you how memory is use by plugin. It is an estimation.

Show log file informations¶

• You can display n lines from beginning or until end of ozwave plugin log file or openzwave lib C++ log when is activate in plugin parameter.
• Select type log, number of line(s) and click button.
• Negative value on number of lines shows full log.

List of manufacturers and product compatibilities¶

• You can check all manufacturers and products reognized by openzwave library.

Detailed architecture¶

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.

$ src/tools/packages/insert_data.py src/share/domogik/plugins/ozwave.json