Tuesday, October 28, 2014

ZWay access with Shell Script

I bough this GPIO daughter board called RaZberry from Amazon a few month ago.
There were a few other options out there but I liked the fact that this works with RaspberryPi.

Don't be confused by the naming. RaZberry-Pi is the name of the small daughter board that has Z-Wave chip on it. The board communicates with other Z-Wave devices. There are two types of Z-Wave devices: stationary and mobile. Stationary device is always awake and mobile one is under sleep most of time.

Another confusing naming sense is on the software part. "ZWay" is the software that works with RaZberry-Pi. Don't be confused with "Z-Wave". I don't like this confusing naming sense but that's what it is for now.

I have been studying about ZWay for a month by now and I finally found the easiest way to access ZWay system. For detailed background knowledge, you can read this PDF document; be warned that the English in the document gets harder to understand due to the broken grammar.

Their webpage explains how to install ZWay: http://razberry.z-wave.me/index.php?id=24

Once you installed ZWay, it runs as a service at boot up time.
You can check the service script from /etc/init.d/z-way-server

It provides web user interface from http://IP-address-of-ur-raspberry-pi:8083
You can "include" your Z-Wave devices from the web user interface; details will be depending on what device you are including. Once those devices are "included", you can access the information with web URL; for example, http://IP:8083/ZWaveAPI/Run

One thing that you need to understand is that there are three numbers to do any work:
  1. device id or also often called node id,
  2. instance id, which is zero most of time.
  3. command class id
Device id starts from the number, 1, not from zero. RaZberry takes the number, 1. If you have two Z-Wave devices, the first device probably got the device id, 2, and the second device got the device id, 3.

I am not clear about what instance id does but as far as I can tell, it is zero in most of devices. Probably one device can have more than one features or something.

The command class id is little hard to follow. It is a kind of function name but not in alphabet. For example, command class id number 37 is "power switch binary". I guess it is a kind of Enum number for different functions. Those numbers can be found from the PDF document above.

What's so frustrating with the web user interface of ZWay is that I cannot wire two devices. For example, I wanted to turn on a light if a sensor device detect motion. Or I want to turn on a light if a door sensor detected door opening.

The latest ZWay finally implemented those abilities but it is still very hard to understand what I am supposed to do. The web user interface is very cryptic and there is no manual about how to use it. Also it is still not possible for me to involve other custom event; for example, turn on the light *if* hard disk has less than 30MB empty space.

ZWay is implemented top of web user interface, which I think waste of CPU resource. I just need a command line tool that can allow me to access each device information. A big portion of ZWay is written in JavaScript, which I think the less stable programming language; because it is often browser dependent, it is type-insensitive and it has less performance due to the interpreter style execution.

Interestingly, when I installed ZWay, it came with C library. I started writing bunch of code that will do what I wanted to do. It took three weeks for me to get the C++ program running and I was very excited. But it turned out that this C++ program must be running as a daemon so that it can receive data from non-stationary devices. I realized that this was going to be a bigger program than I expected.

Fortunately I figured a much much easier way to access the device information. I can access device information with wget via URL. When I was struggling with the web user interface and the poorly written PDF dev document, I didn't understand how to use it. After writing the C++ program, I learned many aspects of ZWay so it wasn't just waste of time, I believe. lol

if [ ! -f $WGET ]; then
    echo $WGET not found
    exit 1

if [ "$#" -lt 4 ]; then
    echo "Usage: $0 deviceId instanceId commandId get"
    echo "Usage: $0 deviceId instanceId commandId set (1|0)"
    echo commandId:
    echo "  37: power switch binary"
    echo "  48: sensor binary"
    exit 2

if [ "x$4" = "xget" ]; then
    if [ "x$commandId" = "x48" ]; then
elif [ "x$4" = "xset" ]; then

$WGET -q -O- $URL/devices\[$deviceId\].instances\[$instanceId\].commandClasses\[$commandId\].$path
The script above is just a simple example; not close to any generic script. I only have two devices so far so I implemented only two commands: "power switch binary" and "sensor binary".

Now with the script, I can find out if the door is open or not and I can turn on the light with any additional condition I like to add.

No comments:

Post a Comment

About Me

My photo
Tomorrow may not come, so I want to do my best now.