OpenHAB & Z-Wave

How To Integrate 3rd Party Z-Wave Products Into OpenHAB

On this page

Z-Wave On The Raspberry Pi

If you want OpenHAB to control Z-Wave devices, you need to first add hardware that will enable it to act as a Z-Wave Controller. You can buy a USB stick (like a Z-Stick or UZB), or a raZberry board.

Product links to Amazon.com, with the price at the time of writing:

The raZberry is a little module that fits over the GPIO pins of the Raspberry Pi. Even if you have an nRF24L01+ connected it will still fit right next to those wires:

The raZberry in a Raspberry Pi B+
The raZberry module installed in a Raspberry Pi B+

Install The Z-Wave Binding

If you've been following guides on this site, you already have the z-wave binding in the addons_repo folder. Copy the addon from addons_repo to addons (remember to replace 1.7.0 with the version you have):

sudo cp /opt/openhab/addons_repo/org.openhab.binding.zwave-1.7.0.jar /opt/openhab/addons/org.openhab.binding.zwave-1.7.0.jar

If you don't have the addons_repo folder, you can get the binding by downloading the addons zip from the OpenHAB downloads page.

Then enable Z-Wave in the OpenHAB config file:

sudo nano /opt/openhab/configurations/openhab.cfg

Look for the section titled Z-Wave Binding. There are only 2 properties you need to activate (by removing the # at the front).

  • zwave:port is the port of your Z-Wave Controller. If you have a raZberry, it's /dev/ttyAMA0. A USB stick would be /dev/ttyUSB0.
  • zwave:healtime is the time for the daily network heal. You can probably leave this at 2 (2AM).

Option 1: Install Z-Way

Unless you already have another way to configure your Z-Wave network (like the Openzwave Control Panel), you will need to install this now. If you have a raZberry board in your Pi, one option is to install Z-Way. It's the most full-featured UI, but it can also be a little challenging. And you have to disable it after you're done configuring z-wave devices because OpenHAB and Z-Way can't both use the raZberry at the same time.

So if you have a different Z-Wave controller or don't want to install Z-Way, you can skip to the next section for HABmin.

You install Z-Way using the following command:

wget -q -O - http://razberry.z-wave.me/install | sudo bash

When it's done, reboot your Pi. When it's back up, you can browse to the Z-Way UI using http://192.168.1.80:8083 (where 192.168.1.80 is your Pi's IP).

Once you're done adding all your devices you need to disable Z-Way, prevent it from starting up again automatically, and then restart OpenHAB:

sudo service z-way-server stop
sudo update-rc.d z-way-server disable
sudo /etc/init.d/openhab restart

Option 2: Install HABmin

HABmin is "a web administration console for openHAB". One of its features lets you configure your Z-Wave network, and you can also use it to configure other OpenHAB stuff.

The following commands will download HABmin 0.1.3, unzip it, and clean up files we don't need. We're deleting the 1.5.0 Z-Wave binding HABmin comes with because we already installed a more recent version in the previous section.

cd /opt/openhab
sudo wget https://github.com/cdjackson/HABmin/releases/download/0.1.3-snapshot/habmin.zip
sudo unzip habmin.zip
sudo rm habmin.zip
sudo rm addons/org.openhab.binding.zwave-1.5.0-SNAPSHOT.jar

The last step before you can use Z-Wave and HABmin is to restart OpenHAB:

sudo /etc/init.d/openhab restart

Note: if you prefer to start OpenHAB using start.sh and you have a raZberry, you need to edit this script and add "-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0" right after "-Dosgi.noShutdown=true" on the bottom line.

Wait a few minutes, and then browse to http://192.168.1.80:8080/habmin (replace with your Pi's IP address if it's different). For the Z-Wave configuration you'll want the Configuration tab at the top, then click on Bindings in the bottom left corner, and select the zwave binding. The Devices tab in the right half is where you can include and exclude nodes. You need to include a node before you can use it in OpenHAB. If it's already included in another network, you'll need to exclude it there first.

HABmin
In this screenshot, the Multisensor from the next section is already included

Example Z-Wave Item: Multisensor

The device I tested this with is a Philio PSM02 4-in-1 Multisensor which sends 4 types of information: temperature, luminance, motion, and battery charge. To look up which command classes your device supports you can look in the manual, look it up on the Z-Wave Device Library (you can filter by Manufacturer) or just google "<device name> command classes". The OpenHAB wiki has a list of supported command classes.

Figuring out the command classes is probably the hardest part of configuring the Z-Wave binding, and I can't help you with that as each device is different. Some tips:

  • Google "<device name> openhab". You might find a forum post where someone already figured it out for you.
  • Check the OpenHAB log for Z-Wave messages: cat /opt/openhab/logs/openhab.log | more (Enter to move forward line by line, space bar for page by page, CTRL+C to exit).

Once you have this information you can add the items to the items file:

sudo nano /opt/openhab/configurations/items/default.items

For the Slim Multi-Sensor PSM02-2 you would add these 4 items:

Number  Door_Temperature "Door Temperature [%.1f F]" <temperature> (GF_Living) { zwave="9:command=SENSOR_MULTILEVEL,sensor_type=1" }
Number  Door_Luminance "Door Luminance [%.0f Lux]" <sun> (GF_Living) { zwave="9:command=SENSOR_MULTILEVEL,sensor_type=3" }
Contact	Door_Motion "Sensor [MAP(motion.map):%s]" <frontdoor> (GF_Living) { zwave="9:command=SENSOR_BINARY,respond_to_basic=true" }
Number  Door_Battery "Battery [%s %%]" <socket> (GF_Living) { zwave="9:command=BATTERY" }

In this zwave binding (the part between curly brackets), the first number is the node ID. You can find this in HABmin. After that is the command class, followed by various parameters. More information about the Z-Wave Binding is in the OpenHAB wiki.

And finally add them to the sitemap file:

sudo nano /opt/openhab/configurations/sitemaps/default.sitemap

Just add a single frame wherever you want:

Frame label="Front Door" {
	Text item=Door_Temperature
	Text item=Door_Luminance
	Text item=Door_Motion
	Text item=Door_Battery
}

On the OpenHAB site, it should look like this:

The multisensor in OpenHAB

Go Back

Guides