Z-Wave RaZberry

Introduction

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.

The RaZberry is the new girl on the block when it comes to Z-Wave interfaces.
It's designed to be plugged onto the GPIO header of a Raspberry Pi board. After downloading and installing the z-way software via a script (described later) it turns the Raspberry Pi into a Z-Wave gateway.

It comes with it's own web-server, where you can browse to and control/monitor the interface, view command queue and include/exclude devices etc.
The firmware of the RaZberry daughter-board is highly optimized. It's works very smoothly. The great part is that the software comes with an API so other products can hook into that.



RaZberry on Raspberry Pi

Since the RaZberry was designed to run on a Raspberry Pi installation is easy.

Hardware installation

Plug the RaZberry board on the GPIO pins of the Pi, as displayed below and power up the device.

Operating system

Follow the guidelines on the Raspberry blog how to install the operating system of your choice. For this instruction the standard Debian Wheezy image is used. Look here for more information RaspberryPi

Tested Z-Way version

The following list of Z-Way version have been successfully tested with DomotiGa:

Z-Way Version
v1.4.0
v1.4.1
v1.5.0
v1.7.0
v1.7.1
v1.7.2
v2.0.0

Install the Z-Way software

1. Download and start install script

Open an SSH or local login session on Razberry and type in the following command line:

$ wget -q -O - http://razberry.z-wave.me/install | sudo bash

Follow the steps on screen.

2. Reboot your Raspberry

# reboot

3. Check installation

Open a browser session to "http://ip of your raspberry:8083"
Choose Expert UI.
Start adding Z-Wave devices.


The standard installation will install the latest official version, previous version can be found on the following site:
http://razberry.z-wave.me/z-way-server/


RaZberry as USB dongle

You can also transform the module into a universal USB dongle.
I did this because I didn't want to push the module inside the Cubietruck case.

Make sure the USB<>serial converter has a 3.3V logic mode, most of hem only have 5v which is too much for the module and will damage it!!
I use an USB-BUB from modern-device.com, but JeeLabs also sells them I think.
Here my experimental setup.

usbserial.png

RaZberry on Cubieboard2 or Cubietruck/Cubieboard3

Since the RaZberry add-on board only needs GND, 3.3V and Serial TX/RX you can also connect it to other (better suited) mini computers, like the Cubieboard2.

Please note that this configuration is not yet supported by Z-Wave.me Read Response on forum here.
But it does works fine for a week now. Be careful upgrading or switching to other Linux distro's though, it may break.

Also note that the hardware installation is not simply plug and play, you need solder skills, or have the correct wires and pins.
And installation of the Z-Way software is a multi-step process and depends on the distro you run on your Cubieboard2.

PLEASE NOTE THAT ALTHOUGH IT WORKED FINE FOR ME THIS MAY DAMAGE YOUR BOARD AND/OR RAZBERRY MODULE
I'M NOT RESPONSIBLE FOR ANY DAMAGE CAUSED, USE AT YOUR OWN RISK

Hardware installation for Cubieboard2

Connect the RaZberry to the Cubieboard2's UART like in the picture below.
Make note of the orientation of the RaZberry, it's viewed from the top.

The UART connection on top of the board is used as a serial console port, so we need to disable the getty process which is enabled by default later on.

It's technically possible to use one of the other UARTs the Cubieboard2 exposes on it's 96pin headers.
But I didn't have the correct header connector, and it may involve enabling the extra ports via the script.bin file. (needs more investigation)

Cubieboard2-RaZberry connection

Hardware installation for Cubietruck/Cubieboard3

For Cubietruck you can make the same mapping to the 4 pins plug.
But there is one difficulty, the Cubietruck doesn't have 3v3 on pin 2.
So you have to solder a patch on the board.

Only do this if you have a good/small soldering iron and a loupe.

Alternative 3v3 Pin:
You can also use pin 1 or pin 2 of CN9 and make the connection at the back.
Thanks Patric Hansen for sharing this tip.

PLEASE NOTE THAT THIS MAY DAMAGE YOUR BOARD AND/OR RAZBERRY MODULE
I'M NOT RESPONSIBLE FOR ANY DAMAGE CAUSED, USE AT YOUR OWN RISK

cubietruck-patch.jpg


cubietruck-overview.jpg

Operation system

First make sure that your Cubieboard2 runs Cubian or Ubuntu 14.04.x, and is up-to-date.
For instructions how to do this please refer to this wiki page Cubieboard2
Other Linux distro's may or may not work, but I choose one which looks like the one Raspberry Pi runs.

Install the Z-Way software

We just run the default install script which fails at some points as you can see in the transcript below.
But we fix those errors manually afterwards, of course we can edit the script before we run it to prevent them.
Lets say I leave that as a task for the viewers.

1. Download and start install script

$ wget http://razberry.z-wave.me/install
$ sudo sh ./install
Removing MathKernel
Reading package lists... Done
Building dependency tree       
Reading state information... Done
E: Unable to locate package wolfram-engine
Installing additional libraries
Reading package lists...
Building dependency tree...
Reading state information...
libyajl2 is already the newest version.
sharutils is already the newest version.
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Installing additional libraries for HomeKit
Reading package lists...
Building dependency tree...
Reading state information...
libavahi-compat-libdnssd-dev is already the newest version.
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Getting Z-Way for Raspberry Pi
--2014-11-04 08:40:33--  http://razberry.z-wave.me/z-way-server/z-way-server-RaspberryPiXTools-v1.7.2.tgz
Resolving razberry.z-wave.me (razberry.z-wave.me)... 46.20.244.36
Connecting to razberry.z-wave.me (razberry.z-wave.me)|46.20.244.36|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 17045614 (16M) [application/x-gzip]
Saving to: ‘STDOUT’

100%[=================================================================>] 17,045,614  3.73MB/s   in 5.5s   

2014-11-04 08:40:39 (2.97 MB/s) - written to stdout [17045614/17045614]

Previous z-way-server installation found
Stopping z-way-server: done.
Stopping mongoose http server
Making backup of previous version of Z-Way in /opt/z-way-server_2014-11-04-08-40-49
Copying settings
config.xml replaced by the new one - make sure to restore your changes
diff /opt/z-way-server/config.xml /opt/z-way-server_2014-11-04-08-40-49/config.xml:
2c2
<     <device>/dev/ttyAMA0</device>
---
>     <device>/dev/ttyUSB1</device>

!!! Defaults.xml and config.xml updated with new versions !!!
Creating Z-Way startup script
Adding z-way-server to autostart
 System start/stop links for /etc/init.d/z-way-server already exist.
--2014-11-04 08:40:51--  http://razberry.z-wave.me/webif_raspberry.tar.gz
Resolving razberry.z-wave.me (razberry.z-wave.me)... 46.20.244.36
Connecting to razberry.z-wave.me (razberry.z-wave.me)|46.20.244.36|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 408241 (399K) [application/x-gzip]
Saving to: ‘STDOUT’

100%[=================================================================>] 408,241     1.10MB/s   in 0.4s   

2014-11-04 08:40:51 (1.10 MB/s) - written to stdout [408241/408241]

./install: 228: ./install: [[: not found
 * Stoping zbw_connect                                                                                      * ok
zbw_connect patched
 * Starting zbw_connect                                                                                     * ok
--2014-11-04 08:40:52--  http://razberry.z-wave.me/mongoose.pkg.rPi.tgz
Resolving razberry.z-wave.me (razberry.z-wave.me)... 46.20.244.36
Connecting to razberry.z-wave.me (razberry.z-wave.me)|46.20.244.36|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 44749 (44K) [application/x-gzip]
Saving to: ‘STDOUT’

100%[=================================================================>] 44,749      --.-K/s   in 0.06s   

2014-11-04 08:40:52 (733 KB/s) - written to stdout [44749/44749]

Adding mongoose to autostart
 System start/stop links for /etc/init.d/mongoose already exist.
Start mongoose http server
sed: can't read /boot/cmdline.txt: No such file or directory
Opened config/zddx/c916626d-DevicesData.xml
diff: /boot/cmdline.txt: No such file or directory
Starting z-way-server
Starting z-way-server: done.
Thank you for using RaZberry!

If you install it over an already installed one, you have to change the config file again, and copy the json wrappers over.
They are backupped in directory /opt/z-way-server_<date and time>

At this point the software is installed but unable to run because a few libraries are missing.
Let's install them.

2. Install needed libraries

# apt-get install libxml2 libarchive-dev curl

Now try to see if you can start the Z-Way server.

2b. libarchive on Ubuntu 14.04

If you run Ubuntu 14.04 the libarchive.so has version 13 instead of needed 12.
You can fix this by creating a symbolic link, Z-Way will work fine with it.
This is the command for Cubietruck (ARM), on x86 it will be different.
Simply run this command to find the libarchive.so.12 location.

$ ldconfig -pv|grep archive
$ sudo ln -s /usr/lib/arm-linux-gnueabihf/libarchive.so.13 /usr/lib/arm-linux-gnueabihf/libarchive.so.12

3. Try to run

# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/z-way-server/libs
# cd /opt/z-way-server
# ./z-way-server

Z-Way version v1.7.2 from 2014-07-26 15:20:00 +0400 (build 428d48e765a32b39615c073af93e8666497724c9)
Using default configuration file config.xml
Failed to open log file: 13
Failed to open http log file: 13
Starting Z-Way for device /dev/ttyAMA0...
...
[2014-11-04 08:43:48.851] Failed to open device: No such file or directory
failed to start ZWay: Can not open port (-20)

4. Fix serial port in config

Find out on which port the RaZberry module is placed, then enter this in the config.xml

# vi config.xml
<device>/dev/ttyS0</device>

5. Disable getty process on /dev/ttyS0

$ sudo vi /etc/inittab

Put hash before these two lines
#1:2345:respawn:/sbin/getty 38400 tty1
...
#T0:2345:respawn:/sbin/getty -L ttyS0 115200 vt100

$ sudo reboot

6. Check installation

Open a browser session to "http://<ip of your server>:8083"
Choose Expert UI.
Start adding Z-Wave devices.

The Green LED on the RaZberry board means data communication.
The Red LED means the Z-Wave chip is into include/exclude mode.

Configure RaZberry support inside DomotiGa

Module Enabled
Enable RaZberry module.

TCP Host and Port
Specify the IP address of the RaZberry interface here, port is default 8083.

Username and Password
Support for authentication is not implemented in the RaZberry software itself.
They recommend to put a third party proxy server in between on the support forum, not tested yet.
If you leave the username and password empty the RaZberry code should connect using http, if you are specifying them https.

Poll Interval
If set to 0 polling is disabled, otherwise it will poll at each interval for updates on the z-wave network.
It's preferable to leave this on 0 and install the update trigger described below.

Debug
Enable debugging if something is not working, it generates a lot of log contents so use carefully.

About Z-Way's back-end

The Z-Way software has a part called 'automation',
it's where you can program your own code in JavaScript to do your own thing, polling for battery levels,
trigger certain Z-Wave node with value of others etc.

This part can come handy later when we want to poll some 'not so smart' devices
to update their values at regular intervals.

But we first use it to report to DomotiGa if there are any updates received.
I have not figured out if it can also report the node and instance number with it.
If so, we can just fetch updates from that device only.

But DomotiGa knows the timestamp of the last fetched update already so we only get the new ones.

These are the steps needed to configure the update trigger mechanism.

1. Install curl command

$ sudo apt-get install curl

2. Now we can configure Z-Way's back-end scripting.

Note: DomotiGa v1.0.18 will have the following 2 scripts included in the wrappers/razberry directory, so you can just copy them.

Copy scripts:

$ cd ~/domotiga/wrappers
$ mkdir razberry
$ cd razberry
$ vi domotiga-trigger.sh

If not available create them:

$ cd /opt/z-way-server/
$ vi domotiga-trigger.sh

And paste the following code into it:

#!/bin/sh
curl -sS -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "razberry.updatesready", "id": 1}' localhost:9090

Make it executable:

# chmod +x domotiga-trigger.sh

Create automation script:

$ cd automation
$ vi domotiga.js

And paste the following code into it:

/*** DomotiGa ZAutomation module *********************************************

DomotiGa - an open source home automation program
Copyright (C) Ron Klinkien, The Netherlands.

******************************************************************************/

var cbk = function(type, arg) {
try {
    //console.log("JSON trigger script executed!");
    system("/opt/z-way-server/domotiga-trigger.sh");
  } catch(err) {
    debugPrint("Failed to execute script system call: " + err);
  }
};

function attachToDataHolder(element) {
  element.bind(cbk);
  for (var key in element) {
    if (element[key] && element[key].name !== undefined) {
      // this is a child element - descend inside
      attachToDataHolder(element[key]);
    }
  }
}

//console.log("DomotiGa custom.js script executed!");

for (var devId in zway.devices) {
  var dev = zway.devices[devId];
  attachToDataHolder(dev.data);
  for (var instId in dev.instances) {
    var inst = dev.instances[instId];
    attachToDataHolder(inst.data);
    for (var ccId in inst.commandClasses) {
      var cc = inst.commandClasses[ccId];
      attachToDataHolder(cc.data);
    }
  }
}

3. Add script to RaZberry startup

$ cd /opt/z-way-server/automation
$ vi main.js

Insert line just before last }, adjust path of script to your location.

...

    //--- load Z-Way utilities
    (fs.list("z-way-utils/") || []).forEach(function (file) {
        try {
            executeFile("z-way-utils/" + file);
        } catch (e) {
            controller.addNotification("error", "Can not load z-way-utils file (" + file + "): " + e.toString(), "core");
            console.log(e.stack);
        }
    });
executeFile('domotiga.js');
}

3. Authorize the framework to run system command

$ vi /opt/z-way-server/automation/.syscommands
/opt/z-way-server/domotiga-trigger.sh


Add return/blank line to prevent errors.

If we don't do this or have a typo in above entry the system calls will not run.
You can check the logfile (/var/log/z-way-server.log) for these lines after restart of Z-Way.

[2014-11-03 10:27:30.102] Failed to execute script system call: This command is denied by policy

4. Restart Z-Way Server with

 
$ sudo service z-way-server restart

Now DomotiGa's RaZberry module should receive the JSON-RPC calls and fetch the updates, like below.

2014/11/03 22:12:48 [JSONRPC] Got a RemoteCall for Method 'razberry.updatesready'
2014/11/03 22:12:48 [RaZberry] Get update by fetching 'http://192.168.178.105:8083/ZWaveAPI/Data/1415049150'
2014/11/03 22:12:48 [RaZberry] Send HTTPGet request 'http://192.168.178.105:8083/ZWaveAPI/Data/1415049150'
2014/11/03 22:12:48 [JSONRPC] Response for Method 'razberry.updatesready' Data 'true'
2014/11/03 22:12:48 [RaZberry] Received data '{
    "devices.22.data.lastReceived": {
      "name": "lastReceived",
      "value": 0,
      "type": "int",
      "invalidateTime": 1400933824,
      "updateTime": 1415049168
    },
  "updateTime": 1415049168
}'
2014/11/03 22:12:48 [RaZberry] Update Timestamp: 2014/11/03 21:12:48 (1415049168)
2014/11/03 22:12:48 [RaZberry] Found 2 updates.


Using Open Z-Wave instead of the RaZberry plugin

@mories tried using the Open Z-Wave plugin instead of the RaZberry plugin and that seems to work fine, see New Razpberry software v2.0.0 not working with DomotiGa.

OpenZWave and RaZberry are largely equal, only the RaZberry can do this in parallel (requests) and handles timeouts better. OpenZWave will sometimes show a delay for 1-2 minutes and sometimes goes into a "bad" state.


Troubleshooting

After a short while Z-Way doesn't run anymore

Check Z-Way log for errors.

$ tail /var/log/z-way-server.log
[2013-12-17 14:00:16.713] Serial port has gone

If you see this in one of the last few lines, check if there is another process running using the port.

# fuser /dev/ttyS0
/dev/ttyS0:          29824

# ps aux|grep 29824
root     29824  0.0  0.0   1660   644 ttyS0    Ss+  17:26   0:00 /sbin/getty -L ttyS0 115200 vt100
root     29966  0.0  0.0   3132   716 pts/1    S+   17:30   0:00 grep 29824


My device is not visible in DomotiGa, I see it in the RazBerry GUI though

Maybe you have a device which is not known yet by DomotiGa's RaZberry plugin.

Every time DomotiGa starts a dump of the RaZberry data received by DomotiGa is saved to 'logs/razberry.log', you can mail it to the address in the README file, and specify which node id's have issues and which values you would expect.

You can also create this output by surfing to your RaZberry with a normal web-browser visiting this address:

http://&lt;ip of server>:8083/ZWaveAPI/Data/0


The application can't use /dev/ttyAMA0

With the default Rasberry Pi image the ttyAMA0 serial device is used as tty terminal and need to be disabled. This can be done as follows:

sed -i 's/console=ttyAMA0,115200//; s/kgdboc=ttyAMA0,115200//' /boot/cmdline.txt
sed -i 's|[^:]*:[^:]*:respawn:/sbin/getty[^:]*ttyAMA0[^:]*||' /etc/inittab
reboot


Resources


Comments

  • Added by kasteleman over 3 years ago

    Added a picture (select image.jpg below). Unfortunately only had 3 colors for the wires, so used some green tape..... :-(

  • Added by kasteleman almost 3 years ago

    Also implemented NGINX so i can redirect de RaZberry webinterface. Therefore i closed the port 8083 on the external interface in my firewall and compiled nginx from source on my cubietruck with ssl and proxysupport. Part of my nginx.conf looks now as following:

    This is what i put in nginx.conf:

        ssl_certificate /<path to certificate files>/server.crt;
        ssl_certificate_key /<path to certificate files>/server.key;
    
        server {
            listen       443;
            server_name  localhost;
            ssl                  on;
            ssl_session_timeout  5m;
            ssl_protocols  SSLv2 SSLv3 TLSv1;
            ssl_ciphers  HIGH:!aNULL:!MD5;
            ssl_prefer_server_ciphers   on;
        satisfy any;
         deny all;
        auth_basic    "closed site";
            auth_basic_user_file    /<path to .htaccess file>/.htaccess;
    
            #For logging, want to see the client-ip in the logging
         set_real_ip_from "put you're routerip here";
         real_ip_header X-Forwarded-For;
        real_ip_recursive on;        
    
        location / {
                root   html;
                index  index.html index.htm;
            }
    
        location /zway {
            proxy_pass        http://127.0.0.1:8083/;
         }
    
        location /expert {
            proxy_pass        http://127.0.0.1:8083/expert;
        }
    
        location /config {
            proxy_pass        http://127.0.0.1:8083/config;
        }
    
        location /pics {
            proxy_pass        http://127.0.0.1:8083/pics;
        }
    
        location /ZWaveAPI {
            proxy_pass        http://127.0.0.1:8083/ZWaveAPI;
        }
    
        location /ZDDX {
            proxy_pass        http://127.0.0.1:8083/ZDDX;
        }
        }
    

  • Added by thechad over 3 years ago

    Just wanted to say thanks so much for this guide!
    I just set this up on my Pi and it's working perfectly. The updates are so much more reliable than OpenZwave. Very happy.:) :) :)

    • Added by Piranha over 3 years ago

      Hi kasteleman,

      I'm trying to get a CT running with Razberry. I have some trouble with the shared libs, even if I follow the steps above. Which distribution are you using? Cubian? Which version? I tried it with Cubian and Lubuntu but no chance!

      Would be happy if you could shortly describe the steps to install razberry on a CT.

      Thanks in advance.

Updated by: Alexie, Updated over 2 years ago
Access count: 111247

Attached Files

razberry.png (91.8 KB) rdnzl, 09/27/2013 06:37 PM

cubieboard2-razberry.png - Cubieboard2-RaZberry connection (567 KB) rdnzl, 10/01/2013 04:01 PM

razberry.jpg (23.2 KB) rdnzl, 10/01/2013 06:21 PM

config-razberry.png (30.1 KB) rdnzl, 10/02/2013 06:32 PM

image.jpg (1.37 MB) kasteleman, 12/17/2013 10:12 PM

cubietruck-overview.jpg (833 KB) rdnzl, 04/08/2014 06:55 PM

cubietruck-patch.jpg (1.06 MB) rdnzl, 04/08/2014 06:55 PM

usbserial.png (1.56 MB) rdnzl, 05/24/2014 02:56 PM

board-details.png (56 KB) rdnzl, 11/04/2014 09:54 AM

zwayDev v1.7.pdf (2.05 MB) Alexie, 01/08/2015 03:31 PM

zwayDev v2.0.pdf (2.33 MB) Alexie, 01/08/2015 03:31 PM

Also available in: PDF HTML TXT