Official website

Tuesday, May 19, 2015

Inexpensive Z-Wave gateway using a Banana Pro and a RaZberry daughter card

Lately Jubito grows its family by contributions of individuals and vendors and I thank them in public each time I make a reference. More details in social networks e.g.: facebook.

Every piece of hardware I received has an interesting aspect that opens a new challenge to the Jubito ecosystem. For example, Z-Wave integration. An interesting technology, but still, a little bit expensive.

While I'm studying the Z-Way JSON API that allows to execute commands on server side using HTTP GET/POST requests, I'd like to share some early developments for those who want to learn the basics and for the adventurous. In this post I will deal with the RaZberry module by Z-Wave.me on a Banana Pro.

Since I currently owned only one device (Fibaro wall plug) I will focus on SwitchBinary Command Class (0x25/37). The Switch Binary Command Class is used to control all actuators with simple binary (on/off) switching functions, primarily electrical switches.

Those who have experience with the module will probably have a complete understanding of what I'm talking about.

But let's take a look at some methods. The command to execute is taken from the URL. All functions are executed in form:
http://YOURIP:8083/<URL>

  • http://localhost:8083/ZWaveAPI/Run/controller.AddNodeToNetwork(1) - Start inclusion [1].
  • http://localhost:8083/ZWaveAPI/Run/controller.AddNodeToNetwork(0) - Stop inclusion.
  • http://localhost:8083/ZWaveAPI/Run/controller.RemoveNodeFromNetwork(1) - Start exclusion [1].
  • http://localhost:8083/ZWaveAPI/Run/controller.RemoveNodeFromNetwork(0) - Stop exclusion.
  • http://localhost:8083/ZWaveAPI/Run/devices[n].SendNoOperation - Refresh device list.
  • http://localhost:8083/ZWaveAPI/Run/devices[n].instances[0].SwitchBinary.Set(value) - Binary values accept 0-99 for switching off and 255 for switch on.
  • http://localhost:8083/ZWaveAPI/Run/devices[n].instances[0].SwitchBinary.data.level.value - Get the state of the device (true->on, false->off).
  • http://localhost:8083/ZWaveAPI/Run/devices[n].instances[0].Meter.data[s].val.value - Measures the amount of electrical energy in kWh that was consumed.
  • http://localhost:8083/ZWaveAPI/Run/devices[n].data.givenName.value='<A new name>' - Rename a device [2].

[1] You can include devices by pressing the 'Inclusion' button. This turns the controller into an inclusion mode that allows including a device. A led on the controller indicates this status. The inclusion of a device is typically confirmed with a triple press of a button of this particular device. However, please refer to the manual of this particular device for details how to include them into a Z-Wave network. The inclusion mode will time out after about 20 seconds or is aborted by pressing the 'Inclusion' button again.
The same applies for the 'Exclusion'.



[2] Rename a device:


Use <lock></lock> tags when you want to bypass parser and pass a URI with blank spaces as one argument.

To create an HTTP GET method as an Instruction Set for alternative use, you can move to Instructions->Add New Launcher and put your getter there. This will allow you to invoke a Z-Wave function into another Instruction Set. You can search in this blog for common actions, but I will come back later with analytical article (*).


You can review the whole object in real time to reveal all the available functions but I won't deepen on the data model -yet [ http://localhost:8083/ZWaveAPI/Data ]:


To have a human readable tree view, copy and paste the JSON object to an editor, such www.jsoneditoronline.org.


List of available devices [ http://localhost:8083/ZWaveAPI/Run/devices ]:


Let's stand here and see some examples on Jubito's side.
Jubito has a native API for HTTP GET method i.e.: judo http get <Request-URI>.

Try any of the above operations from the terminal.
Examples:
  • judo http get http://localhost:8083/ZWaveAPI/Run/devices[n].data.givenName.value - Gets device name.
  • judo http get http://localhost:8083/ZWaveAPI/Run/devices[n].instances[0].commandClass[37].Set(255) - This will switch on the plug. It is equivalent to http://localhost:8083/ZWaveAPI/Run/devices[n].instances[0].SwitchBinary.Set(255) or .Set(0) to switch off.


That was a quick introduction to the Z-Way API. Before you get confused, Jubito comes with a simple interface that implements the basics like, inclusion, exclusion and list of available devices with their actions (on/off), including some additional information.
While is still beta, I won't add a link on the menu button yet, but you can navigate to z-index.html:
http://<host>:<port>/www/z-index.html


Please make sure you have the latest version [0.2.8.299]:


(*) Let's consider this post as the first part of a Z-Wave session. In future articles I will present ways, on how to use a specific function, on a custom Instruction Set, and how these can interact and expand functionality and logic by other mechanisms, including evaluations and schedules.