Adding z-wave to OpenHAB

After setting up OpenHAB, we are ready to run it. It's exciting to see that it works. I imagine to control outlets, light switches and light bulbs from my phone.

OpenHAB isn't tied to any specific devices or protocols. It talks to various devices by binding which is extensible. There's a z-wave binding to communicate z-wave devices. So first thing to do is to add z-wave binding. After you add z-wave binding to your OpenHAB, you can use it to find your z-wave devices. There are two steps. First is to add a z-wave controller. Then include various z-wave devices.

First, install a z-wave controller. A z-wave controller acts like a bridge between your other z-wave devices and OpenHAB. The controller understands z-wave network and protocol. OpenHAB sends commands to and receives states from z-wave devices via the controller. Thing of it like a Bluetooth module. Without it, your computer won't find any Bluetooth devices or use them. A z-wave controller is usually a stick or a module attached to your computer. I bought Aeotec Z-Stick Gen5. It's straightforward to add it to OpenHAB. You can do it from Paper UI or HABmin. Go to "Extensions" and add "Z-Wave Binding". The controller will then appear in Inbox and you can add it. You need to at least configure the serial port for your controller. This is to tell what device on your computer is the z-wave controller. You can list all /dev/tty* and find the one that's added when you plug in your stick. Or you can find it from "dmesg". Its name is /dev/ttyACM0 on my machine. Then you configure your controller and set the serial port.

Then you can include your other z-wave devices. I found that each device I bought came with the instruction about how to include it in a z-wave network. But there're some tricky steps. I'll only point out the tricky steps since otherwise it's straightforward from the instruction.
1. Turn your z-wave controller into inclusion mode. The instruction usually says to press a button on the z-wave controller. You don't need to do that. You turn it into inclusion mode from OpenHAB UI. Add a new thing and select "Z-Wave Binding". OpenHAB will make your z-wave controller into inclusion mode for 30 seconds.You should have time to proceed to next steps.
2. OpenHAB may not actually initialize your devices even though it shows up in your thing list on UI, especially for battery devices. I still try to understand how it works. My guess is that OpenHAB needs to wake up the devices a couple times and get the information from the device. This is done at OpenHAB side. Even if you press wake up button on your devices, it may not help. Before it's fully initialized, you may see "Unknown Device" for your device. Sometimes it's showing the right type and name, but channels' values are not available. One way to check whether it's fully initialized is to check /openhab/userdata/zwave/. There's should be an nodeXXX.xml file for your device. XXX is a number assigned to your device. If you turn on debug log when you add your z-wave device, you'll find the node number.
3. Even if the nodeXXX.xml file is created, OpenHAB may still not be able to get device states or send commands to it yet. You may need to wait one day or two. I guess OpenHAB needs to wake up the devices a few times to be able to communicate with it.
4. Paper UI is created for Eclipse SmartHome. It's not tailored for OpenHAB 2. You may find sometimes it's not working as you expect. I suggest to use HABmin.
5. Turn on debug logging for z-wave binding. You can run /openhab/runtime/karaf/bin/client to get to karaf console. And run the command log:set debug org.openhab.binding.zwave.

I spent a couple days trying to figure out why I couldn't add my device. It's always showing "Unknown Device" or its state wasn't updated. Then I first discovered that I didn't need to press the button on the z-wave controller to be in inclusion mode. Then I learned that I may need to try to include/exclude the devices a few time to have the device added correctly. Last, the state may not update immediately, but it will in a day or two. The OpenHAB community is a great resource. There are friendly users and developers help to troubleshoot. It's frustrating at first when things don't work. Then it's exciting when you see you can control from your phone. I encourage you not to be afraid of trying out and obstacles. It's worth the efforts to learn and to improve.


Leave a comment

Your email address will not be published. Required fields are marked *