OpenHAB Configuration

Pre-requisite: Please go through demo setup page



  • One of the most popular home automation software platforms
  • Vendor and technology agnostic Java Software running over JVM
  • Controls almost any smart device connected on WiFI/BT/GPIO/Zigbee/Zawe/… through bindings which can be installed as add-ons
  • Bindings for most of commercial smart switches / lights / sensors available in the library, saving time and effort for the user.
  • Rich and easy to understand documentation.


The following devices were used to test provided image (though you can use any other peripheral device supported by OpenHAB:

  • Vision Z-Wave USB Adapter
  • Aeotec SmartSwitch 6 (Z-Wave compatible)
  • Aeotec Multi-sensor (Z-Wave compatible)
  • Philipa Hue Bridge
  • Phillips Hue light

It’s not mandatory for the user to use same hardware, though it may make it easier for you if you consider the following :

If you are choosing devices from different vendors which are using competing standards (e.g. Zigbee / Zway), then try to stick on one standard.  The primary rationale is that on Raspberry Pi3, you will need USB adapter for each, and making both adapters run in parallel will be a challenge.

If devices are using other protocols, make sure you have a corresponding binding avaialble in OpenHAB2 (

If you are an advanced user and have experience on how to implement custom Java bindings, then you should be all good.


The following tutorial is not supposed to replace OpenHAB official documentation, users are advised to go through:-

Detailed Steps




OpenHAB is pre-installed in the image, and all standard interfaces can be used as per user preferences.

For a new user though, our recommendation is to use Paper UI as we found it intuitive and ability to provide all 4 steps from a single interface (install / hardware discovery / mapping / control)


Note : OpenHAB 2 demo is based on standard openhabian image (without GUI)

Default user name : openhabian

Passwd : openhabian

Step 1 : Install Add-ons

The first part of completing add-ons installation is to install bindings for all the hardware you are planning to control from OpenHAB.

From paper UI, you can go to Add-ons / Bindings and search for bindings you need.

For Z-Wave or Zigbee compatible devices, it’s sufficient to download generic Z-Wave or Zigbee binding.

This step is optional, by default we have installed some UI within the image, but if you want to uninstall or install some other interface, check Add-ons / User interfaces section.

Step 2 : Hardware Discovery


Hardware discovery is a simple procedure on paper, but still could require a bit of time for a user to master it. If you are a new user to OpenHAB, first step we will suggest is to enable Configuration -> System -> Simple Mode . Selecting this option will create a simple mapping for each channel and you could survive without creating an item map.

To detect hardware, go to inbox and then search for devices. If device is discoverable, it will be shown in inbox.

In current example we are using Phillips Hue controller and if it’s connected to network, it will be appear in inbox

After hardware is discovered, it might be OFFLINE

Most important step of hardware discovery is to ensure that device is properly configured and is ONLINE

To change device status to ONLINE, press sync button on device (On Phillips Hue control, it’s big button on the top)

Configuration for each hardware is generally different and there are lot of resources on the web where you can look for configuration support. See the next section for generic configuration examples.


Once the main controller is discovered and configured, more devices will be discovered via the inbox (if there are compatible devices)

Step 3 : Configuration

Configuring Z-Wave adapter : main parameter to configure is Serial Port where USB adapter is connected, rest of settings can be left to default values.

Name of device will be something /dev/ttyACM0 or /dev/ttyACM1, to figure out, you can plug-out and then plug-in adapter from USB to see which new device appears (ls /dev/ttyACM*)

Other configurations you would like to change is Location, location listed for device will control how devices are shown in the final interface. You are free to change location as per your wish as it doesn’t impact functionality at all (only interface)


Click on Channels which you want to enable, and corresponding controls will be automatically created (If you haven’t enabled Simple Linking, then you will have to create a control yourself)

Step 4 : Run / Control

Go to Control and you will be able to see all devices you have configured.

If you want to try other interfaces, you can also try to use Classic UI

Note that advanced users might want to create their own item / site map. If you wish to do that, we recommend going through the official documentation page for detailed steps.