Z-Wave - Open Z-Wave Support¶
- Table of contents
- Z-Wave - Open Z-Wave Support
Z-Wave is a wireless communications protocol designed for home automation, specifically to remotely control applications in residential and light commercial environments. The technology uses a low-power RF radio embedded or retrofitted into home electronics devices and systems, such as lighting, home access control, entertainment systems and household appliances.
OpenZWave is a free software library that interfaces with selected Z-Wave PC controllers, that you can use without requiring in-depth knowledge of the Z-Wave protocol to interface to devices on a Z-Wave network,
DomotiGa uses a wrapper to interface to the OpenZWave library. This OpenZWave wrapper transforms the open-zwave library C++ calls to C calls so DomotiGa can use them, together with JSON-RPC methods to report status changes of the Z-Wave network back to DomotiGa.
A very big thank you to Jaren, thanks for building and sharing the wrapper code!
Getting DomotiGa's open-zwave support to work is a 2 step process:
1. Build the open-zwave project.
2. Build the DomoZWave wrapper.
1. Building open-zwave
Install needed development headers:
Ubuntu / Debian
$ sudo apt-get install git-core libudev-dev libcurl4-gnutls-dev
# yum install systemd-devel
On CentOS 7 also create a file (as "root") with the following commands (otherwise the library can't be found during start-up):
# echo "/usr/local/bin" >/etc/ld.so.conf.d/usrlocal.conf # ldconfig -v
Download latest open-zwave code like this:
$ mkdir ~/install $ cd ~/install $ git clone https://github.com/OpenZWave/open-zwave open-zwave-read-only $ cd open-zwave-read-only
Compile open-zwave code:
2. Building DomoZWave wrapper
$ cd ~/domotiga/wrappers/domozwave $ ln -s ~/install/open-zwave-read-only ./open-zwave $ make clean $ make $ sudo make install
Enable open-zwave option under Open Z-Wave settings.
During first run there is a logfile name 'OZW_Log.txt' and a open-zwave status file named 'zwcfg<homeid>.xml'_ created in the directory '~/domotiga/wrappers/domozwave'. If debug is enabled, the wrapper will also write a logfile named '~/domotiga/logs/domozwave-<year>-<month>.log'.
If you run into issues, please add all 3 files into the support ticket.
update/recompile open-zwave and/or wrapper¶
The open-zwave and/or wrapper are updated regularly. The following steps will guide you with updating your DomotiGa to the latest one. If the open-zwave is updated, then the wrapper also needs to be updated.
Execute all 4 steps to complete the update
1. Update the open-zwave:
$ cd ~/install/open-zwave-read-only $ git pull
Compile open-zwave code:
$ make clean $ make
2. Building DomoZWave wrapper:
$ cd ~/domotiga/wrappers/domozwave $ make clean $ make $ sudo make install
3. Remove the zwcfg*xml, because sometimes the format is changed:
$ rm zwcfg*xml
4. Restart DomotiGa
Open the configuration window under Interfaces -> Z-Wave -> Open Z-Wave
- Serial Port selects the port of the Z-Wave Controller
- Poll Listening Devices enables a poll of non-sleeping devices
- Poll Sleeping Devices enables a poll of sleeping devices
- Update Neighbor enables a neighbor update
- With every of these three options you find an "at" field that specifies when the poll or update is done using a "cron string"
- For a detailed description of the cron string see Time-Now triggers.
- "*/30 * * * *" means every half hour
- "30 3 * * *" means every night 03:30
- Debug enables debug output
Open Z-Wave Commander¶
The Open Z-Wave Commander works only in a Client-Server configuration if JSON-RPC is enabled.
Under the Controller tab you can find:
The left set of buttons are for the Controller, the right set of buttons for the (selected) node.Node
The following is the list of Z-Wave known to work with DomotiGa and the openzwave library. In principle all normal Z-Wave devices should work, with the exception of security devices (e.g. door locks) and with some limitations thermostat devices.
|Aeon Labs||Z-Wave Stick S2||Install/Config|
|Vision||Z-Wave USB Stick||Install/Config|
|Aeon Labs||Home Energy Meter (HEM), 2 or 3 clamps||Install/Config|
|Aeon Labs||Micro Smart Energy Switch||Install/Config|
|Aeon Labs||Multi Sensor||Install/Config|
|Aeon Labs||Multi Sensor 6||Install/Config|
|Digital Home System||DHS-ZW-SNMT-01 Multi Sensor||Install/Config|
|Everspring||AN158 Plug-in Meter Appliance Module||Install/Config|
|Everspring||SP103 Motion Sensor||Install/Config|
|Fibaro||FGBS001/321 Universal Module||Install/Config|
|Fibaro||FGD211 - Dimmer||Install/Config|
|Fibaro||FGR221 Roller Shutter Controller||Install/Config|
|Fibaro||FGS221 Double Relay Switch 2x1,5kW||Install/Config|
|Fibaro||FGK101 - 107 Door/Window Sensor||Install/Config|
|Fibaro||FGWPF/E 101 - Wall Plug Switch||Install/Config|
|Fibaro||FGSS001 - Smoke Sensor||Install/Config|
|Fibaro||FGMS001 - Motion Sensor||Install/Config|
|GreenWave||PowerNode 1 port||Install/Config|
|GreenWave||PowerNode 6 port||Install/Config|
|HomeSeer||HSM100 Wireless Multi-Sensor||Install/Config|
|Philio||PST02-ABC Wireless Multi-Sensor (zwave plus)||Install/Config|
|Popp/Duewi||ZDAN 300 Dimmer||Install/Config|
|Popp/Duewi||ZS 3500 Switch||Install/Config|
|Vision||ZP3102 - Motion Sensor (zwave plus)||Install/Config|
|Z-Wave.Me||ZME_06435 Motor Control||Install/Config|
Questions and answers¶
Unknown device in Open Z-Wave Commander
If you notice that your just added device is shown as unknown device e.g. "Unknown: type=xxxx, id=xxxx" in Z-Wave Commander, means that the device isn't known yet in the open-zwave library. Please report this to the open-zwave project (https://github.com/OpenZWave/open-zwave/issues) with all relevant information. They will include it in the next revision of the open-zwave and this will extend the known device database
The procedure to report it properly is as follows:
1) Check ~/domotiga/wrappers/domozwave/zwcfg*xml file and find your unknown device, and notice the following lines (this is an example):
<Manufacturer id="0115" name="Z-Wave.Me"> <Product type="1000" id="0004" name="Unknown: type=1000, id=0004" /> </Manufacturer>
2) Check ~/domotiga/wrappers/domozwave/open-zwave/config/manufacturer_specific.xml file, and locate the manufacturer section:
<Manufacturer id="0115" name="Z-Wave.Me"> <Product type="1000" id="0002" name="ZME_06433 Wall Flush-Mountable Dimmer" config="zwave.me/ZME_06433.xml"/> <Product type="1000" id="0003" name="ZME_06435 Motor Control"/> </Manufacturer>
3) As you can notice, the Product type="1000" id="0004" is missing here.
4) The file needs to be modified, and the result will be:
<Manufacturer id="0115" name="Z-Wave.Me"> <Product type="1000" id="0002" name="ZME_06433 Wall Flush-Mountable Dimmer" config="zwave.me/ZME_06433.xml"/> <Product type="1000" id="0003" name="ZME_06435 Motor Control"/> <Product type="1000" id="0004" name="ZME_064435 Wall Controller"/> </Manufacturer>
5) Report the information from step 2 and 4 with the open-zwave library, that they know what to add to the manufacturer file.
Remove a failed Z-Wave device
It is possible that a device is faulty (or incorrectly removed from the Z-Wave network), from r1054 it is possible to remove it with the following steps:
- Go to Z-Wave Commander
- Click on the node to be removed
- Go to tab "Controller"
- Click on "Remove Failed Node"
- Restart DomotiGa
Replace a failed Z-Wave device
It is possible that a device is faulty, from r1054 it is possible to replace it (same device type !) with the following steps:
- Go to Z-Wave Commander
- Click on the node to be replaced
- Go to tab "Controller"
- Click on "Replace Failed Node"
- Go to tab "Node"
- Click on "Refresh NodeInfo"
Build a debug version of openzwave
For debugging is can be handy to build a debug version of the openzwave library:
- See the INSTALL file in ~/install/open-zwave-read-only:
Some Options you can set: "BUILD=(release|debug)" - Build a Release or Debug Version of the Library (Release is default)
Known issues with the open-zwave library¶
If you use many Z-Wave devices it can take a few minutes before the open-zwave library is fully initialized. During initialization the open-zwave library queries all devices for all known parameters. Only after the full initialization you can start controlling your devices.
Querying all listening devices takes long
If you unplug one of your listening devices, DomotiGa still will try to query (request state, Watt, kWh, etc). This will timeout in the open-zwave library resulting in a "delay" of 10-20 seconds per device.
Some On/Off/Dim commands aren't directly executed
If you have many Z-Wave devices and you query them regularly (e.g. every 5 minutes) then during the start of the query and until the LAST response comes back from the open-zwave library no On/Off/Dim command will be directly processed. Those On/Off/Dim commands will be executed AFTER the LAST response is received. Thus if you do an On/Off/On, then our light will turn visible on, off and then on again. See also the "Querying all listening devices take long". We are looking into this "issue", but the timing is trivial if devices are unplugged or none-existing values are retrieved.
DomotiGa uses 100% CPU after unplugging the Z-Wave USB stick
This is an issue in the open-zwave library and not a bug in DomotiGa of the DomoZWave wrapper. The workaround is to restart the ZWave interface or restart DomotiGa. The issue is logged with the open-zwave project (https://github.com/OpenZWave/open-zwave/issues/111).
DomotiGa isn't getting any Z-Wave status updates anymore
There is a known bug in the Aeon Z-Wave USB stick that it will stop responding after 6-9 months. Restart of DomotiGa of your system will not work either. Unplug and replug to the Aeon USB stick to resolve this issue.
- Wikipedia about Z-Wave
- Z-Wave device library - pepper1
- Z-Wave manuals by Z-Wave Europe
- open-zwave library
Added by Martin almost 3 years ago
Fedora 24 install guide
echo "usr/local/lib" > /etc/ld.so.conf.d/local.conf"
dnf install systemd-devel json-c-devel curl-devel