Skip to content

Home

Jump to bottom
Julien Wajsberg edited this page Apr 27, 2016 · 15 revisions

Basics

This project is an openzwave adapter for Mozilla's Project Link project, and is used within foxbox.

The adapter uses the following projects under the hood:

  • open-zwave is an open-source and cross-platform library to control ZWave networks. We currently forked it essentially for building issues on MacOS X but we proposed our changes upstream and plan to move back to upstream.
  • openzwave-rust is a quite straight adaptation of the open-zwave library in Rust. We tried to keep a very close API.
  • openzwave-stateful-rust aims to be more rusty and give more features. It especially keeps a list of all nodes and values, and notifications are sent using Rust channels.

A companion project is openzwave-rust-example: that project uses the same underlying libraries and it is even sometimes necessary to do some actions that foxbox and the adapter itself can't do yet.

Configuration paths and deployment

First, some terminology. When we initialize the openzwave library we pass 2 directory paths: one is the system configuration paths, the other is the user configuration paths. Basically the system config path contains things that can not change but the user config path contains things than will change.

Usually the system config path contains the devices information XML files, while the user config path contains the saved network files.

Very good, but how are they configured in the adapter ?

Very simple.

For the system path, we use whatever path the openzwave library is while compiling. This is good because as a developer this makes it very easy to use them without even thinking of it. But of course when you'll need to deploy the program this path will likely not exist. Then the best location is /etc/openzwave that is checked by openzwave as a last resort. So you should copy there all the files that are in the config subdirectory in open-zwave. Another possibility is to copy it to a config subdirectory of wherever you launch your application.

For the user path we use a subdirectory in the profile directory. On Linux this is in ~/.local/share/foxbox/openzwave. You'll find there the Open-Zwave log and the current zwave network.

Access a controller

Depending on your controller, and depending on your system, there are different cases. Some controllers will need a driver before the system gives access to it.

On Linux and MacOS X, the controller will show up in /dev. On Linux it will usually be prefixed by tty (eg: ttyUSB0 or ttyACM0) while on MacOS X it will usually be prefixed by cu. (eg: cu.SLAB_USBtoUART or cu.usbmodemXXXX). We autorecognize some of them but we know this is not exhaustive so you can either provide as a command line option:

cargo run -- --disable-tls --config 'openzwave;device;/dev/ttyACM0'

or as an entry to foxbox.conf:

{
  "foxbox": {
    ...
  },
  "philips_hue": {
    ...
  },
  "openzwave": {
    "device": "/dev/ttyACM0"
  }
}

So far we tested the code with the following controllers:

  • Aeotec Z-Stick S2
  • Aeotech Z-Stick Gen5
  • UZB Static Controller.

What to do if nothing seems to work

The best tool we have to diagnostic if there is an issue is openzwave-rust-example. So please clone and cargo run the project. If you get anything (especially logs about nodes and values) then you're likely good. Otherwise, please follow along.

Check the log

While running, the underlying library will write a log in config/OZW_Log.txt. You'll find valuable information there.

Is it the right device file ?

Check the device as said earlier. If the device you have does not seem to be in the auto-detected list, you can pass the device path to the openzwave-rust-example binary, for example: cargo run -- /dev/ttyUSB1.

Do I have the rights to open this device file ?

Usually a device belongs to a particular group. Your UNIX user needs to have the rights to read from this device and the easiest is to add the user to this group, and then logout and login again.

Foxbox will display an error in the log if the autodetected or provided device file is not readable.

Pairing devices with controllers

Some controllers have physical buttons to pair devices. This is good as long as you don't need a secure pairing. Read the documentation for your controller to know how to use it.

If you need a secure pairing or your controller doesn't have a physical button, you'll need to use the programmatic API through openzwave-rust-example. There we provide a add-node that will be useful:

add-node <home-id> [secure]

home-id is the hexadecimal ID for this network, you can display it if you type the controllers command. secure is an optional flag.

Once you typed this command you'll see notifications coming, saying that the controller is in waiting mode. You can now do the pairing from the device. When you do it you'll see new notifications coming in the console.

Then you can quit the example program (if you use CTRL-D or the q command you'll save the network in a local file -- this won't be used by foxbox but will be used next time you run openzwave-rust-example).

So far we tested the code with the following devices:

  • Fibaro Motion Sensor Manual - Note: If you're not seeing any node information from the sensor, then you can wake it up by pushing the button (by the battery) 3 times. The LED will turn Blue for about a minute and the node information should be transferred to the host.
  • Fibaro Door/Window Sensor
  • Vision Deadbolt Lock Door ZM1702
  • Kwikset 910 SmartCode Deadbolt
  • Schlage Connect Touchscreen Deadbolt
  • Leviton Vizia RF+ Zwave Plug-in Appliance Module
  • Everspring Zwave Miniature Door/Window Sensor

Troubleshooting getting values

To know if foxbox discovered values you can access the URL http://localhost:3000/api/v1/services. Note: I suggest to use the tool jq to prettify the output, eg: curl http://localhost:3000/api/v1/services | jq ..

But sometimes all values are not discovered yet. So if you see Services but not Getters or Setters, please look below. If you don't see some Openzwave Services at all, then you should look again at the explanations above.

One problem is that we don't yet pair devices directly in foxbox. That means that you pair it differently (from another program for example), and when foxbox starts it will need to discover the network. The problem is that some devices may sleep at that moment and so we don't get their values.

There are 2 solutions to this:

  1. Wake up the device. On some Motion Sensor devices you can try to quickly press 3 times their button (this wakes up the device), then pressing it once some seconds later (this sends it back to sleep, so allow some time before this -- possibly don't do it at all ;) ), and possibly do these steps twice. You'll need to do this each time the foxbox starts up.
  2. Copy the config files from openzwave-rust-example/config/* to the openzwave subdirectory in the profile directory. You'll need to update them from openzwave-rust-example everytime the network changes, and then copy them over. Note that openzwave would still know if the network changes, but it would take longer than having a uptodate saved network.

secure, really ?

We use a default security key for now. This is not secure but good enough for demo purposes. Of course this needs to be changed.

I want to contribute !

Perfect, have a look at the issue lists on the various projects I mentioned above :)

Clone this wiki locally