15 minute primer: OpenHAB2 with z-wave

Here's a very rapid guide on how to install openhab2 on Ubuntu 16.04.3 with z-wave support. It may help somebody out there!

I'm using a z-wave AEOTEC z-stick GEN5 which supports the FLiRS feature, mainly because this allows the user to wake a remote device, rather than wait for the device to arbitrarily wake to receive commands.


From a fresh installation of Ubuntu 16.04.3 I suggest deciding whether you wish to use the Stable Release or the Testing Release. I'm using the testing release as I encountered some GUI problems with stable 2.1.0, plus it lets me keep on the crest of the curve in terms of updates.

Have Java?

First up, install the recommended version of java on the host - Zulu. You may already have a version of java installed and it may be fine, but be aware of some of the issues or limitations mentioned in the page linked above.

The downloads for Zulu are here, you need version zulu-8.x with java jdk 1.8 and the command to download it if as follows:

wget http://cdn.azul.com/zulu/bin/zulu8.25.0.1-jdk8.0.152-linux_amd64.deb

Install the java-common package and then zulu:

apt install java-common
dpkg -i zulu8.25.0.1-jdk8.0.152-linux_amd64.deb

To test the installation, run "java -version" to see the installed version:

root@LittleBrick:/# java -version
openjdk version "1.8.0_152"
OpenJDK Runtime Environment (Zulu 8.25.0.1-linux64) (build 1.8.0_152-b16)
OpenJDK 64-Bit Server VM (Zulu 8.25.0.1-linux64) (build 25.152-b16, mixed mode)

Installing openHAB2

To install the Testing Release base-package, follow the instructions listed in the openhab2 documents:

wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -

apt-get install apt-transport-https

echo 'deb https://dl.bintray.com/openhab/apt-repo2 testing main' | sudo tee /etc/apt/sources.list.d/openhab2.list

apt-get update

apt-get install openhab2 openhab2-addons

You will then be prompted to setup systemd to start the service automatically with the following message:

### NOT starting on installation, please execute the following statements to configure openHAB to start automatically using systemd
 sudo /bin/systemctl daemon-reload
 sudo /bin/systemctl enable openhab2.service
### You can start openhab2 by executing
 sudo /bin/systemctl start openhab2.service

So, go ahead and setup the automatic startup if desired:

  /bin/systemctl daemon-reload
  /bin/systemctl enable openhab2.service

Next, start the service:

/bin/systemctl start openhab2.service

While the service starts, it's a good idea to monitor the logfiles as this happens, so that you can become familiar with the messages and chatter which occurs, especially at a later stage with z-wave.
The following method allows you to see all of the updates to the critical logs: events.log, openhab.log and audit.log, as they occur:

tail -f /var/log/openhab2/*

Note: If the log files remain blank at this point and the  issue the command "/bin/systemctl status openhab2.service" and review the output from the process. An example of a failed start is below, this was due to the java jdk not being present and karaf could not run:

root@LittleBrick:/# /bin/systemctl status openhab2.service
openhab2.service - openHAB 2 - empowering the smart home
   Loaded: loaded (/usr/lib/systemd/system/openhab2.service; enabled; vendor preset: enabled)
   Active: activating (auto-restart) (Result: exit-code) since Wed 2018-01-10 19:49:40 GMT; 4s ago
     Docs: http://docs.openhab.org
           https://community.openhab.org
  Process: 12695 ExecStop=/usr/share/openhab2/runtime/bin/karaf stop (code=exited, status=1/FAILURE)
  Process: 12676 ExecStart=/usr/share/openhab2/runtime/bin/karaf $OPENHAB_STARTMODE (code=exited, status=1/FAILURE)
 Main PID: 12676 (code=exited, status=1/FAILURE)

Jan 10 19:49:40 LittleBrick systemd[1]: openhab2.service: Unit entered failed state.
Jan 10 19:49:40 LittleBrick systemd[1]: openhab2.service: Failed with result 'exit-code'.

All going well, if you now connect to openhab2 (http://(server-ip):8080) you should be presented with the panels for each of the UI's. Next, let's jump to getting z-wave working...

Configuring the z-wave USB device

First, let's discover the z-wave USB and add a udev claim-rule for it. In my case I have an AEOTEC z-stick GEN5, so I'll need to find the vendor ID and the product ID to add it into the udev claim-rule.

Insert the USB device and run "lsusb":

root@openhab2:/home/root# lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 002 Device 002: ID 0658:0200 Sigma Designs, Inc.
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

My device is the "Sigma Designs" entry and all of the information which we need for udev is supplied in the output.

0658 = idVendor
0200 = idProduct

Next, create a file called "/etc/udev/rules.d/50-usb-serial.rules" and insert the following udev statement into it with the idVendor and idProduct substituted as needed:

SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ATTRS{idVendor}=="0658", ATTRS{idProduct}=="0200", SYMLINK+="USBzwave", GROUP="dialout", MODE="0666"

In the above case, I'm creating a new dev called USBzwave as part of the dialout group. Then, reload udev:

udevadm trigger --reload

Then setup the openhab account with the required permissions:

adduser openhab dialout
adduser openhab tty

The AEOTEC z-stick GEN5 should now be available at /dev/USBzwave!

Configuring openHAB2

I found this a little tricky to work out as a lot of the documentation for z-wave applies to openHAB (version 1) and not openHAB2.
Very simply, to add the USB device you need to edit the file /etc/default/openhab2 with the following parameters:

EXTRA_JAVA_OPTS="-Dgnu.io.rxtx.SerialPorts=/dev/USBzwave"

Now, restart the openHAB service and then install the z-wave binding. Then, from PaperUI, enter the Inbox and click the blue plus (+) icon, click through to the "Configure Z-Wave Serial Controller" page and select the /dev/USBzwave device as the serial port, the z-wave thing (AEOTEC) should then appear, but still needs to be configured.
Go to Configuration and Things, select the newly discovered USB device, edit it and select the serial port "/dev/USBzwave" from the drop-down menu.

You should now have the AEOTEC thing listed under Configuration -> Things,, and that should be it!

I'll try cover off setting up persistence with the easy to use Influx database next.