openHAB is a Java-based platform (developed in parallel with Eclipse Smarthome, on which it is based) that provides interface, control, and automation functionality for your home. It supports many devices and networks through “bindings”, including Z-Wave. A rules engine provides for automation, and several user interfaces are available.

Since HomeAssistant doesn’t support the scene control features of the HS-WD100+, I decided to give openHAB 2 a shot.

It works reliably once configured.

Until you get to that point, it’s a hot mess…

Installation

There are a number of ways to install openHAB – including a Docker Image and a pre-built Raspberry Pi image – but in the end, it’s just a Java application. Since I generally use Scientific Linux, and there aren’t RPMs available, I decided to install it by hand.

The installation is simple enough: make sure you have Oracle’s 1.8.0 JDK installed, extract the openHAB zip to an appropriate location, and add a systemd service file. Then simply tell systemd to start the thing. Once it’s started, you can visit your installation with your favorite web browser on port 8080 and start setting up your system.

In theory…

Bits and Pieces

openHAB is, in essence, an asynchronous message bus with a bunch of independent microservices hanging off it (not that they use that term, but hey, I’m a modern developer!). Everything is a service on that bus. Fortunately, unless you’re going to develop plugins for it, you won’t need to know much about that.

Some of the objects you will need to know about:

• Bindings, which interface between openHAB and your hardware. The Z-Wave binding is a good example; it supports the Z-Wave Serial API for devices such as the Aeotec Z-Stick.
• User Interfaces, which provide you with methods of interaction. The Paper UI is a good example of this, though I recommend that you also install HABmin, since Paper is an absolute mess.
• Persistence Plugins, which persist item states to the database of your choice. This is more important than you think.
• Things, which are individual devices in your system.
• Channels, which are information and points of control for those devices.
• Items, which link Things and their Channels to named objects that you can use in rules and such.
• Rules, which are pretty much what you’d expect; they allow you to define actions in response to various events.

Note that this is not an exhaustive list; openHAB is a complex beast, and there’s more than just this available. These are just the ones you should know about if you’re going to get a usable system going.

One of the stranger things about openHAB 2 is that there are two ways to configure it: through the UI, or from the command line via configuration files. Unfortunately, it appears that there is also a separate storage mechanism for stuff configured in the UI, and it can conflict with the config files.

I recommend avoiding the UI for configuration until they get that sorted out…

Getting Connected

In my case, I’m starting with a simple Z-Wave network, via my Aeotec Gen 5 Z-Stick; there are roughly twenty devices currently on that network. Luckily, adding them to openHAB isn’t all that difficult. Before you start, however…

The system comes up with something called “Simple Linking Mode” enabled. In this mode, when you add a new device, the system will automatically create Items that coincide with each of the Thing’s channels. This sounds great, right? Automatic configuration FTW!

Except that it names these items atrociously, and you can’t change those names. You’re left with obnoxiously long things that you have to remember and type to use them in rules.

I recommend disabling the Simple Linking function. You can do that from the Configuration/System menu in the Paper UI.

With that done, you can get your Z-Wave stuff working:

1. Install and configure the Z-Wave binding.
2. Go to the Inbox, and click the big white plus in the blue circle. This will put your Z-Stick into inclusion mode.
3. Tell your device to include itself in your network. For most switches, this just means tapping the switch, for example.
4. Click the icon at the left of each device to add it to the system.
5. Once your devices are added, you’ll need to add Items for each of the device’s channels. I recommend using item files; more on this below.

Once you complete these steps, you should be able to go to the Control section of the Paper UI to see and control your devices. So far, it looks like this is only really useful for testing; you can at least see that your devices work.

Defining Items In Files

This is an area where I strongly recommend reading the documentation. There are a lot of permutations. For reference, this is one of my typical items:

Switch light_lr_table_lamp_1 "Table Lamp 1"
  <light>
  (gLivingRoom)
  ["Lighting"]
  { channel="zwave:device:########:node#:switch_binary" }

This translates to:

• A Switch item with the identifier light_lr_table_lamp_1
• The icon should be a lightbulb.
• The text name is “Table Lamp 1”. This is used in a number of places, and is what Alexa will recognize if you use the openHAB Alexa Skill.
• It’s in the group named gLivingRoom.
• Tag it with the “Lighting” tag. In this case, that’s so the Alexa skill will see and operate on it.
• It represents the specified channel. You can find the channel strings in the Paper UI by going to Configuration/Things and clicking on the Thing you want to define items for. The correct channel string is listed below the name of each Channel.

Note that there are more than just Switch items; you can also define Dimmers, Numbers, Colors, and more. Each type of item has a defined set of commands you can use with it (On and Off for switches, a percentage for dimmers, etc.). You need to choose correctly, or your item won’t work properly – or at least not with all available functionality.

Needless to say, adding items for each of your devices and their channels can be quite tedious. If I could rename items created by Simple Linking (and Tag them, and group them, and…) then I wouldn’t bother, but the config files seem to be the only way to get full functionality with reasonable item names.

Not that the example I gave is reasonably named, but that’s beside the point.

Persisting Your Stuff

Without persistence, openHAB starts fresh on every restart; this means that items which update infrequently will be in an undefined state until they report in. Persistence can help avoid this by restoring the last state the item was in. I highly recommend this if you’re using any battery-powered devices.

Unfortunately, it can’t all be configured in the UI.

After setting up your chosen database, you’ll need to use the Add-Ons section in the Paper UI to install the persistence add-on, and then you’ll have to set up a configuration file to get it set up. It’s a bit overcomplicated, so I recommend starting out simply. My basic configuration looks like this:

Strategies {
  everyHour : "0 0 * * * ?"

  default = everyChange
}

Items {
  * : strategy = everyChange, everyHour, restoreOnStartup
}

Basically, I restore everything on startup, and also record every change, plus hourly checkpoints. You can define per-item persistence events and schedules here if you want, but I haven’t seen the need so far. Keeping the data is useful, but the restore on startup functionality is the reason I configured it.

Note that you’ll also need to specify your database configuration at services/jdbc.cfg.

If you want to do this, you’ll need to read the documentation. If you can find it…

Writing Rules

With your Things, Items and so forth configured, you can finally start writing automation rules. These are stored in the conf/rules directory of your openHAB installation, and are in a nameless language based on Xbase and Xtend (which I’d never heard of before). The language is tailored for automation functionality, though the documentation leaves something to be desired.

As with much of openHAB’s documentation.

A picture is worth a thousand words, so here’s a simple rule from my test installation:

rule "Outdoor Schedule - ON"
when
  Channel 'astro:sun:local:set#event' triggered START
then
  logInfo("front-lights", "SCHEDULE: Sunset, turning on outdoor lights")
  sendCommand(light_porch_front, ON)
  sendCommand(light_coach_front, ON);
end

Most of this is fairly straightforward and obvious: the rule is executed at sunset and turns on my outdoor lights at the front of the house. The event comes from the Astro binding, which provides all sorts of events for different astronomical phenomena.

It took some googling to figure out how to use the Astro events in rules; the documentation really does kinda suck in a lot of areas.

Alexa And The Cloud

If you have an Amazon Echo, openHAB has a skill for you. In order to use this skill, however, you will also need to sign up for myopenhab.org, which is their online connector. Among other things, it allows you to talk to your openHAB installation’s web UI from anywhere in the world.

Once you have that set up, just add the Alexa skill, give it your account information, and tell Alexa to discover your devices. If you’ve tagged your items correctly (again, see the documentation) it’ll just work.

When I initially started using the skill a couple of weeks ago, I had some trouble with performance late at night; sometimes it would take forever to respond, and sometimes it wouldn’t work at all. Whatever it was, it was something with their skill, and it’s not been happening lately. Your mileage may vary.

It has a significant advantage over the Wink in that it recognizes anything that you tag – including groups. It’s nice not to have to define my groups in the Alexa app.

Overall Impression

I can’t speak to the original openHAB, but openHAB 2 is not for the faint of heart. If you’re looking for something easy to use, this is most definitely not for you. Setting up openHAB will give your google-fu a serious workout.

Don’t say I didn’t warn you…

Once you get over that hurdle, though, and once you’ve got everything configured and running the way you want it, it pretty much just works. It’s fast. It’s reliable. Pretty much all you could want in a system.

The only issues I’ve had come from Alexa misunderstanding me when I talk to her, and that’s not openHAB’s fault.

This is one of those projects that would be amazing if it were easier to use and more complete in the ways that matter, but it’s unfortunately lacking in some key areas. I’m getting to the point of writing my own system because I can’t find one that truly works the way I’d like while still being powerful. openHAB is the closest I’ve found so far, but it’s not quite there yet.

So what’s wrong with it?

Oh wow, where do I start?

The Documentation Sucks.

That really bears repeating, and worse, it’s a classic case of bait-and-switch. There’s some really beautiful documentation available on their website for openHAB 2, but when you get a little ways into configuring your system, you’ll realize just how incomplete it really is. Take the persistence documentation, for example.

There isn’t any. Not for OH2, at any rate.

Much of the time, as with this example, you end up having to go back to the 1.x documentation to find what you need, and that’s a crapshoot. Ultimately, it looks like 2.x wasn’t really ready for release (for this and other reasons), and got prematurely shoved out the door to make someone’s deadline.

The UI Needs To Call An Exterminator

The Paper UI has a lot of potential, but it’s absolutely riddled with bugs. I can’t even edit Z-Wave devices half the time; little red boxes pop up telling me “404” or “500” or similar. They don’t tell me what actually went wrong, either – and nor do the logs.

It’s also kinda half finished, in this weird state where they’re trying to make everything doable through the UI, but it’s not quite there yet. This results in a bizarre hybrid management approach where you can do some things in the UI, but most you’ll need to use config files for.

Paper is a great idea with a lot of potential, but it wasn’t even close to ready.

Startup Disorder

Asynchronous operation is a good thing, but openHAB has seriously overdone it. There does not appear to be a defined startup order for openHAB, or at least, not one that’s enforced. To give a simple example, your rules will likely be active and ready by the time the Z-Wave binding gets itself together on startup.

This is a problem, and the primary reason I so strongly recommend configuring the poorly documented persistence subsystem – and I’m not yet convinced that even that will fix it completely.

Why, you ask?

Your rules may fire spuriously during startup as the Z-Wave binding learns and sets the current state of various things. There does not appear to be a way to distinguish between “I’m just just initializing the value” and “Yes, something really happened”. If your rules and/or persistence aren’t set up correctly, your house might end up looking like a disco during startup.

A saner way would have been to initialize the bindings, gather all the data, and only then start the rules engine…

But that’s just me.

And Speaking of the Rules Engine…

The openHAB language could do with a little work.

The core structure of it is really nice and very powerful, but that’s about where my love for it ends. There’s too much crossover from Java. Using a Java-esque syntax is one thing, but I take issue with the fact that, as an example, the import statement even exists.

And yes, I’ve had to use it a couple of times.

To be fair, they’ve eliminated a lot of the need for it in OH2 by automatically importing the most common things, but that’s hardly the point. I don’t know much about Xbase/Xtend, but it looks and acts a lot like one of those compile-to-C-source-code sorts of languages, but with Java as the target. It ends up losing some serious style points for that.

It’s been my experience that some of the most vocal proponents of home automation know exactly squat about software development – and IMO, that’s as it should be. One should not have to be a software developer to write automation rules. With OH2, it’s almost a prerequisite.

In addition to the general structure of the language, there a number of odd gotchas with it. These range from the glaringly obvious to the annoyingly subtle. It’ll take time to find them all, methinks.

Obvious Missing Features

There are no global functions. Nada, nil, nothing. If you want a handy function that you can reuse in various places, the closest you can come is to define a global variable and stuff a lambda function in it. If you want to pass arguments in, that’s the only way.

Remember what I said about it helping to be a developer?

I suppose I’m kinda contradicting myself here. OH2 does appear to have a scripts mechanism that you can use for at least minimal code reuse, but it has a serious limitation in that you can’t pass anything into your scripts. If you want to do something like this, you’re back to the lambda.

It has no global functions, but it has frickin’ lambdas. How wrong is that?

Oh, and that variable you defined that has your lambda assigned to it? You can only use it from the file it was defined in. What, you have your rules organized nicely into multiple files?

Too bad.

Missing Objects That Should Be Standard

There are some really basic things that come up frequently in automation, and Timers are probably the best example of this. A common desire is to have a lamp automatically turn off after a set period of time elapses. Perhaps you might also want to reset that timer if a motion detector triggers, indicating that someone is still in the room.

There is no first-class representation of Timers in openHAB.

If you want to do this, you have to delve into pseudo-Java land and create a timer in code. You have to store it somewhere. You have to deal with the timer’s whole lifecycle. And, of course, you have to figure out how to do all this, which is not easy due to the lacking documentation.

It’s just plain harder than it should be.

Downright Obnoxious “Features”

There are thread synchronization primitives in openHAB’s rules language.

Seriously.

Now, I will grant that it’s very difficult to get automatic synchronization right in a DSL that will execute in a highly asynchronous, multi-threaded environment. That said, this is something that many actual professional software developers don’t understand correctly, if at all! If you expect users of a home automation system to understand the concept of threads and synchronization, then you’re living in a fantasy.

This is really just another effect of the Java bleedthrough I’ve already mentioned. The rules engine is tied too closely to Java to escape this sort of thing.

It’s unfortunate, because the general concept of this language has potential.

General Instabilities

OpenHAB 2 works very well once it’s set up and configured, but getting there can be a challenge. While you’re working on it, though, there are some glaring issues that just won’t quit. The one that bites me most often is issues with renaming items in the configuration files. This can happen frequently in the early stages of configuration, while you’re figuring out your naming strategy.

Oftentimes, openHAB will get confused if you rename an item. Or remove it and re-add it. Or just look at it funny.

This is a clear bug in the part of openHAB that automatically reloads the rules files when they change, and the only solution is to restart openHAB. I’ve yet to find another way to resolve it. It continues to annoy me every so often.

Conclusion

openHAB 2, while conceptually excellent, was released prematurely as near as I can tell. The documentation has major (and very important) gaps in it, and the UI is teeming with bugs. In my opinion, it needed another couple of months to bake.

You also need to have a pretty good understanding of programming to truly make use of this thing. For me, this isn’t a problem; I code for fun, and sometimes even professionally (though I do try to avoid that these days). Unless you’re a programmer, you’re in for a world of confusion with openHAB.

If you can get over those hurdles – and deal with the teething problems – it’s a surprisingly reliable system. It tends to get confused when you’re actually editing configuration files, but once you have them set, just restart it and let it be. It’ll work reliably, every time.

So far.

That said, there are enough issues that I’m already looking for alternatives. Home Assistant is unfortunately out of the running (for now) due to the lack of support for the Central Scene command class. And I don’t want to be tied to the cloud. So far, I’ve not found anything else that meets my requirements.

I might just have to code something up, assuming I can find the time…