Access Keys:
Skip to content (Access Key - 0)
This manual applies to ZWay v2.0.0 and higher. See Changelog for details.
Other references:
v2.0.x OpenRemoteHelpers reference
Previous Openremote reference for RaZberry 1.3-1.4.1
Public Z-Way releases: http://razberry.z-wave.me/z-way-server/
Since ZWay 2.0.2 clients like OpenRemote need to authenticate with ZWay on the Raspberry Pi. The description here does not yet take that into acoount. A quick work-around is to allow anonymous (unsecure!) access to Zway. You can achieve this in ZWay Smarthome as follows
  • Create a room named devices, and assign all ZWay devices to that room
  • Create a user named anonymous with role anonymous
  • Edit user anonymous and allow access to room devices
  • (If you already assigned devices to rooms, you have to give user anonymous access to all those rooms)

Your OpenRemote client should have unrestricted access to ZWay now.

Instructions for proper authentication will follow here shortly
Unfortunately, ZWay does not comply with the IETF Authentication standard. So proper authentication with the OpenRemote http-command will not work.

20160605 There is a slightly updated version of OpenRemoteHelpers available in the Zwave>Me App store

Configure Z-Wave for Razberry

Competence level
Some acquaintance with the Raspberry Pi.

OpenRemote offers several ways to interact with Z-Wave devices. One solution is the direct native Z-Wave support, the other approach is to interact with Z-Wave networks controlled by a remote device like is done for MicasaVerde Vera, and in this case the Razberry.

If you are new to OpenRemote, do read the Introduction first. There are a number of instruction videos available.

The Application

This document describes a Community Supported application. Razberry is a Z-Wave controller board that connects to the GPIO interface of the Raspberry Pi. It not only is a piece of hardware, but it also comes with a complete API(Z-Way) that can be accessed with a HTTP protocol. In addition there is a simple user interface, to setup and maintain the network of Z-Wave devices. The primary audience for Razberry is the DIY community and developers. Razberry is a product of Zwave>me.

For novice users the Z-Way API still is rather complex. The Z-Way API not always seamlessly fits the OpenRemote needs. One solution would be to design a dedicated protocol for Razberry as has been done for Micasaverde Vera. It was decided to make the necessary adaptations on the Razberry side.

Design Criteria

In this context Razberry is an autonomous smart device, which should basically function even if not controlled by OpenRemote. Configuration of devices within OpenRemote should be simple and intuitive, while preserving the ability to control devices using the original Z-Way API calls. Due to limited power of the Raspberry Pi, installation of both OpenRemote and Z-Way on one single Raspberry Pi is left out of scope.

Protocol

The standard interface to RazBerry is the HTTP protocol which exposes their Z-WAY API. Though this API significantly reduces the burden of interfacing Z-Wave devices, it is still rather complex for the uninitiated user. Fortunately the Razberry automation engine allows the creation of user defined simple functions, which also are accessible using the HTTP protocol.

Platform

This instruction is tested on OpenRemote Controller Professional v1.10 on Synology DS212+. Raspberry Pi 512 Mb, Razberry software version 2.0.0. This instruction has not yet been tested with the free OpenRemote Designer and Controller, but should be compatible.
note: According to the Zwave-me developers this should also work on Windows PC platforms with the new USB Z-stick. That has not yet been tested however.

Get started with the Raspberry Pi

This section describes the installation of hardware and software on the Raspberry Pi. The inclusion and testing of Z-Wave devices. Finally there are instructions to configure and install the RaZberry-OpenRemote module.

Install Razberry software on Raspberry Pi.

  • Take a blank SD card, and follow the instructions for First installation on a virgin Raspberry At the moment of this writing (20141115) the basic image contains a working version of OpenRemote, RaZberry v1.7.1. including the OpenRemoteHelpers. On Windows you can use Win32DiskImager to write the image.
  • Plug the RaZberry board on the GPIO pins of the Pi and insert the SD card. Power up the device. (Alternatively you can use the more powerful Zwave>Me's UZB1 stick, but you need to purchase a separate licence for that device, which makes its cost about 90 Eur)
  • Open a session on Razberry (address IP_OF_YOUR_RASPBERRY:8083) with Putty or similar to Upgrade to the latest version (see on the same page)

Reboot your Raspberry Pi.

Configure RaZberry to use Z-Wave and OpenRemote API

Therefore it is needed to reconfigure the Razberry automation engine, and to add the OpenRemoteHelpers module to it. The user only has to activate this module in the Smart Home client on the RaZberry As of ZWay release v2.1.1-rc6 you can install/update OpenRemoteHelpers from the Online Appstore.
Z-Wave is also installed and activated as an App. For Z-Wave binding, in case of RaZberry daughter board, do keep the proposed port to dev/ttyAMA0, in case of UZB1 do set it to /dev/ttyACM0

Add Z-wave devices

Open the Old Expert UI . Switch to Expert mode in the lower right corner. Via the top menu Network/Network Management start (Re-)include device to add your first device to the network. If you have Z-Wave switches, start with one of those for the initial exercise. Your interface informs you when the inclusion is complete.

Note: You can use a tablet or Smartphone to open the Razberry console to In/Exclude devices at the spot where they are mounted.

Check Z-Wave devices

Select Device configuration from the top menu, and choose the included device from the left side menu. Check that the Interview Stage: says interview complete, and the row below only shows + signs. Under top menu Device control select Switches. Try if it can be switched on/off.

If a device interview is not complete, as indicated with question marks, at the bottom of this screen there is a button for Advanced Actions. Activate that button, and next select force re-interview. Do check the results of that re-interview.

Test Razberry HTTP interface using basic JSON-API calls via a Web browser

For this test it is assumed that you have included at least one binary switch as device #2 in your Razberry setup. We follow the the example given in chapter 7-Command Classes of the Razberry documentation. The respective commands for switching device on, off and read status are:

http://raspberry_IP:8083/ZWaveAPI/Run/devices[2].instances[0].SwitchBinary.Set(255)
http://raspberry_IP:8083/ZWaveAPI/Run/devices[2].instances[0].SwitchBinary.Set(0)
http://raspberry_IP:8083/ZWaveAPI/Run/devices[2].instances[0].SwitchBinary.data.level.value

For a binary sensor (again device #2 (e.g. door open) try with:

http://raspberry_IP:8083/ZWaveAPI/Run/devices[2].instances[0].SensorBinary.data[1].level.value

The output of binary status commands is false|true

These commands are rather complicated. For a beginner it is hard to distill them from the Z-Way Developers Documentation. Nevertheless, the Web browser is a good instrument to test. Also in case any of the OpenRemoteHelpers don't work as desired you can revert to this API.

For direct use see OpenRemote HTTP call. More about that later.

Loglevel settings

The default log settings are rather verbose, which is good for initial testing. With small SD cards the logfile quickly fills all the free space, which can lead to problems. Once your system works OK you can reduce the amount of logging in the following lines of file /opt/z-way-server/config.xml:

    <log-file>/var/log/Z-Way.log</log-file>
    <log-level>6</log-level>
    <http-log-file>/var/log/Z-Way.log</http-log-file>
    <http-log-level>4</http-log-level>

Settings range from 0 (verbose) to 6 resp. 4 (silent)

This concludes the installation and initial testing on the Raspberry Pi

Install OpenRemote Controller

This installation provides an OpenRemote controller. However that would limit you to rather small installations. If you need more power install the OpenRemote Controller on your PC, Mac, Linux box. The Raspberry can still function as a Z-Wave gateway placed centrally in the building for optimised Z-Wave connectivity. Bear in mind that the configurations you make in Designer are easily synchronised with any controller you have running. So there is no issue of moving your designs from PC to NAS , etc..

Control the Razberry

It is assumed at this point that you have a basic understanding of Designer. In Designer you configure your devices, sensors, switches, sliders, etc. In the second step you design the user interface on the basis of those available devices.

OpenRemoteHelpers Module

This module contains a number of javascript functions as shown in the code block below. In essence it translates a simple call from the OpenRemote side to the complexity of Z-Way. But it can do more as shown for the SwitchBinaryStatus function. There the Z-Way status values are transformed into the values on and off as required by the OpenRemote sensor type:switch.

// This is a collection of functions for easy interface with OpenRemote
            case "SwitchBinaryOn":
                zway.devices[N].instances[I].SwitchBinary.Set(255);
                return "on";
                
            case "SwitchBinaryOff":
                zway.devices[N].instances[I].SwitchBinary.Set(0);
                return "off";
                
            case "SwitchBinaryStatus":
                return zway.devices[N].instances[I].SwitchBinary.data.level.value ? "on" : "off";


            case "BatteryLevel":
                // Battery is never in instances
                zway.devices[N].Battery.Get();
                return zway.devices[N].Battery.data.last.value;
            
            case "MeterLevel":
                var S = params.shift();
                zway.devices[N].instances[I].Meter.Get();
                return zway.devices[N].instances[I].Meter.data[S].val.value;
            
            case "MeterReset":
                zway.devices[N].instances[I].Meter.Reset();
                return 0; // just to return something

The full OpenRemoteHelpers code can be found on your Rapberry Pi in

/opt/z-way-server/automation/modules/OpenRemoteHelpers/index.js

Using the OpenRemoteHelpers module

The OpenRemote calls for the described OpenRemoteHelpers functions are reduced to:

General parameters used in the calls are:
N :        the number that designates a Z-Wave device
I :        the number that refers to an instance (e.g. a channel in a dual binary switch
           Use 0 for single binary switches. For dual switches use 1 and 2 for 
	   channels 1 and 2 respectively)
${param}:  OpenRemote system parameter that is used e.g. for passing values 
           from a slider to a call like this.
Status functions that return the value "on" or "off" are to be used in OpenRemote with 
sensors of the type:switch. Apply Regular expression: on|off in the http call. 

http://raspberry_IP:8083/OpenRemote/SwitchBinaryOn/N/I
http://raspberry_IP:8083/OpenRemote/SwitchBinaryOff/N/I
http://raspberry_IP:8083/OpenRemote/SwitchBinaryStatus/N/I
http://raspberry_IP:8083/OpenRemote/ThermostatLevel/N
http://raspberry_IP:8083/OpenRemote/ThermostatSet/N/${param}

As you can see much simpler than the 'raw' Z-Way commands given under testing the Razberry. Do note that if you installed and configured OpenRemoteHelpers, you can equally well use these compact http calls for testing!

(Note that the parameters are separated by slashes now, and the path is OpenRemote instead of the old JS/Run)

Implementation example

With the cloud-based Designer you can now start to configure your devices and screens.

Click on the images below for full picture. Please note that only the Status command does have a polling interval of 2 seconds. This value can be lowered for better system responsiveness. If there are a great many devices, excessive polling may degrade system behaviour. The status command also has the regular expression on|off to remove the quotes from the returned value as required by the sensor type:switch!


The console screendump is taken from a web view. Screen layout made with Pro-Designer.

In the example, the Fibaro switch 5-2 of this dual model is controlled with the calls:

http://raspberry_IP:8083/OpenRemote/SwitchBinaryOn/5/2
http://raspberry_IP:8083/OpenRemote/SwitchBinaryOff/5/2
http://raspberry_IP:8083/OpenRemote/SwitchBinaryStatus/5/2

Razberry connected devices tested successfully with OpenRemoteHelpers Module

Brand Product Kind Support Functionality
Fibaro FGBS-001 Universal Sensor Community 4 temperature sensors, 2 binary sensors coupled to relays
Fibaro FGS-221 Switch Community dual channel on/off, status
Fibaro FGWPE Plugin Switch Community setpoint, status, Watt, kWh
Fibaro FGD-211 Dimmer Community setpoint, status
Duwi ZW ZS 3500 Plugin Switch Community on/off, status
Zwave>Me ZME_06431 Switch Community on/of, status, name, location
Danfoss Living Connect Thermostatic valve Community setpoint read/set, battery level
Eurotronic Stella Z Thermostatic valve Community setpoint set/read, battery level, temperature sensor, direct valve control/heat/saving/frost protect, name, location
Vision Security Electronic Deadbolt Lock (ZM1702) Entry Control Community lock, unlock

A great many devices could in principle be controlled from OpenRemote with the full Z-Way API. Those devices are outside the scope of this listing however.

OpenRemoteHelpers implemented functions

See this Recipe on Razberry forum. That is the place where the functions description will be maintained

UDP protocol as fast alternative Status update channel.

Continuous polling devices for their status values can put quite a load on a system. Reducing the polling frequency can help, but will often result in a sluggish system behaviour. We therefor devised a method that pushes status updates when they occur from RaZberry to the OpenRemote controller. That method is described in the companion document OpenRemote 2.0 How To - Z-wave with Razberry via UDP

Advanced use of RaZberry (Z-Way API)

Some of the applications need proper setting of the time zone. Do set/check with:

sudo raspi-config

You must reboot the Raspberry Pi to effectuate the new setting!
In the previous sections the low level z-wave interface, and the simplified OpenRemote interface has been dsecribed. This part deals with the home automation interface to the abstract devices layer, where the individual protocols no longer matter. To some extent it resembles the OpenRemote REST API, but less restrictive in not being confined to consoles only. See Z-Way API document

RaZberry Status

The OpenRemoteHelpers, and the Status updates over UDP do rely on the availability of the Home Automation engine of RaZberry. To get the status, make in Designer a http command with a GET URL: http://raspberry_IP:8083/ZAutomation/api/v1/status, Content-Type: application/json, RegEx: 200|503, Polling: 1h. Make a custom sensor with the State settings name:off value:503 and name:on value:200. Finally in the GUI designer add an image element that displays a red or a blue Z-Wave image, as shown here. Note: below the warning image, the latest received status update is shown.

Scenes

RaZberry has a special virtual device type:toggleButton. Such devices do only one thing, activate something. An other toggleButton can reverse the action.
One can for instance create a VirtualDevice of this type, that calls some Javascript. For example to set the mode of a thermostat:

zway.devices[N].ThermostatMode.Set(x)

Where,
N: device number
x: 0=FrostProtect,1=Comfort,11=HeatSave

It is a bit of work to create a togglebutton device for every mode of all your thermostats, but you gain a lot in the further configuration of the system. Besides once you have created all three modes for one device, you can import their code in the creation of the other devices. You only have to change the device number.
The next construct is the Scene, which also is of type:toggleButton. In a scene you can specify commands to switches and dimmers, and include other scenes (which include toggleButtons that are a kind of simple scenes.
From within OpenRemote these Scenes can be activated with an the following http command:

http://raspberry:8083/ZAutomation/api/v1/devices/LightScene_24/command/on

The device id LightScene_24 can be found in the Zwave HA GUI under -Preferences-Widgets.

Schedule

The scheduler is a rather simple function that does only one thing: activate a scene at a specific time on certain days. If multiple complex things have to happen at that moment a combination of several scenes is possible.
Again do click on the images for a larger picture!
The schedule function is a more user friendly alternative for the OpenRemote Drools Engine. It is limited to configuring with a graphical user interface. In the creation of some devices the user is confronted with some javascript, which for a great part can be copy and pasted from RaZberry's OpenRemoteHelpers script in
/opt/z-way-server/automation/modules/OpenRemoteHelpers/index.js

Logical Rules

Logical rules are easily configured within the RaZberry Home Automation UI. Like with the Scheduler, scenes are a key concept within Logical Rules too. For example the activation of a scene can trigger a rule. Conditons to trigger a rule are: binary, multilevel, remote, time, nested; The action are setting switches, dimmers, locks, and scenes
From conditions to trigger a rule, time is special. It just sets the period in which changes on other conditions will trigger. If real time crosses a time condition, nothing will happen. Nested allows you to define and/or constructs around sub-clauses in your rule definition. Binary and multilevel are self-explanatory. Remote allows for example to include virtual devices from a 'cloud' of additional Z-Way servers.

Summing up

RaZberry context driven automation functions are definitely easier for the uninitiated user, than OpenRemote Drools. But not all functionality of Drools can be replaced by RaZ-HA.
In the above description only a few automation modules have been mentioned. There are many more in the standard distribution. Also some users are contributing their modules. See [userModules] recipes section on the forum.

Known Issues with RaZberry HA

The more complex Z-Wave devices like Thermostats are not yet directly available in Scene, Schedule and Logical Rule picklists. Quite a lot of those can be tackled with the toggleButton virtual device as described before. And of course operations can also be done on/with devices known as RaZberry Virtual device.

Useful links

Example implementation: Newsletter June 2013(pages 6-7)
OpenRemote 2.0 How To - Control Sunshades - Somfy with Raspberry Pi
OpenRemote 2.0 How To - Control Radiator - Stella Z with RazBerry
OpenRemote 2.0 How To - Sense rain - Hydreon RG-11 Rain Sensor using Fibaro Universal Sensor
OpenRemote 2.0 How To - Monitor Solar Power - FuturePower4All PVlogger

ZWave>Me - RaZberry related repository
Z-wave device manuals

Discussion on usage please in the ZWave.Me forum space. I do not use Google Groups! (pz1)

*cross-links last updated 20160605

Added by Juha Lindfors , last edit by pz1 on Jun 05, 2016 09:53

  1. Oct 20, 2013

    Kenneth says:

    Hi, I followed the instructions here, but couldn't find the file config.json. ...

    Hi,

    I followed the instructions here, but couldn't find the file config.json. I can only manage to find the file config-sample.json instead, which also did not contain the function stated.

    Can I check if anyone is having the same problem?

    1. Nov 02, 2013

      pz1 says:

      See discussion thread In the future please respond to the forum as I have reque...

      See discussion thread

      In the future please respond to the forum as I have requested. That is the only space I watch

  2. Feb 15, 2016

    winston salcedo says:

    Hello, I try to control a dimmer. I make all the steps indicated. I can control ...

    Hello, I try to control a dimmer. I make all the steps indicated. I can control the dimmer from the web browser:
    -off: http: // raspberry_IP: 8083 / ZWaveAPI / Run / devices [2] .instances [0] .SwitchMultilevel.Set (0)

    • on: http: // raspberry_IP: 8083 /ZWaveAPI/Run/devices[2].instances[0].SwitchMultilevel.Set(99).

    I use http://raspberry_IP:8083/OpenRemote/SwitchMultilevelSet/2/0/99 from openremote designer, but this does not work and if I enter this address from the web navedor, it sends the message "404 Not Found". Why I can not control the dimmer from openremote or form browser with OpenRemoteHelpers functions? Thanks for your attention.

    1. Feb 16, 2016

      pz1 says:

      I will never repond to questions posted here! See my earlier request to only use...

      I will never repond to questions posted here! See my earlier request to only use the forum.

© 2008-2012 OpenRemote Inc. OpenRemote is a trademark of OpenRemote, Inc.
Adaptavist Theme Builder (3.3.6-conf210) Powered by Atlassian Confluence 2.10.3, the Enterprise Wiki.