RazBerry

Pierre Kil edited this page Jan 13, 2017 · 6 revisions
Clone this wiki locally

This manual applies to ZWay v2.0.0 and higher. See Changelog for details. Other references:

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

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 Get Started Pages 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.

  • Go to http://IP_OF_YOUR_RASPBERRY:8083 to get access to the UI selector screen with your browser (Chrome is best, FF, IE sometimes problematic).

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

RazBerry - inclusion

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

RazBerry - interview

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.

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!

RazBerry - Switch7On

RazBerry - 7Status

RazBerry - 7Sensor

RazBerry - thermostat

RazBerry - console

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

RazBerry - table1

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

RazBerry - HA_live

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

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

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

RazBerry - logicalRule

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.

##See Also

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

*cross-links last updated 20170113