FAQ - Frequently Asked Questions about openHAB 2
The main reference for openHAB 2 is the documentation at http://docs.openhab.org. Below you can find frequently asked questions surrounding openHAB 2 and the migration from openHAB 1.x.
This thread is a Wiki Thread - Everyone can add content to it!
Please add questions and appropriate short answers as they arise.
¶ What’s openHAB 2?
Have a look at: http://docs.openhab.org
¶ What are the differences compared to openHAB 1.x
¶ Can I simply upgrade and switch over my configuration?
No. A clean restart is the best option. For further details, please see the migration guide: http://docs.openhab.org/tutorials/migration
¶ Should I start with openHAB 1.8.3 or 2.x?
openHAB 2 is officially released and most activity on this forum centers around it, so without knowing more about your objectives, I would recommend it as a starting point. There are no more changes to the core of openHAB 1, so some issues won’t be fixed there, while development is active and ongoing against openHAB 2. There are many new features in openHAB 2 and is mostly easier to use for the novice.
¶ Installation & Setup (Linux)
¶ Configuration (File-based)
¶ Where are my files?
See the table here
¶ Where can I find
The global configuration file
openhab.cfg known from openHAB 1.x does not exist anymore. Individual files per system component and ad-on located under
<openhab-conf>/services have taken it’s place. This step makes configuration more flexible and easier to maintain. The
<key>: prepended to each configuration property (as known from
openhab.cfg) is removed in the new
<key>.cfg file. Please pay attention to the fact, that most/all details available through configuration files are also available through PaperUI, which should be preferred. Please check the migration tutorial for more details.
¶ Configuration (UI-based)
¶ Why are Things and Items created inside Paper UI not written back to config files?
Short answer: That’s by design. The openHAB internal database is filled with entries from both the config files and settings done through Paper UI. openHAB will never change your config files (i.e.
/etc/openhab2/* or similar)
Long answer: TODO
¶ I would rather stay with config files only. Do I need to use Paper UI?
PaperUI is not mandatory for openHAB 2 users! It offers functionality like basic system and add-on settings, device discovery and items definition. All these things are also possible through file-based configuration. PaperUI is one way of interacting with the openHAB 2 core system. You might just as well configure your bindings in
addons.cfg, services in the corresponding
*.cfg files, things in the
things folder, items in the
items folder, rules in the
rules folder, …
¶ Addons and Bindings
¶ How can I install a newer add-on version in openHAB 2?
Bindings are automatically updated when a new version of openHAB is installed or the existing openHAB setup is updated.
Caution: The following information is only needed if an experimental or cutting-edge version of a binding should be installed, e.g. a binding under new development or a bug-fixed version of a binding provided by the developer for testing.
Bindings are provided in the
*.jar file format and can be downloaded in various places, most imporrtantly:
If you want to install the latest snapshot version of an add-on, you can download the archive file
openhab-addons-2.3.0-SNAPSHOT.karfrom https://ci.openhab.org/job/openHAB-Distribution/. This file contains all add-ons that were built in the last successful snapshot build.
.karfile is a zip archive. You can extract the add-on’s jar file this archive file. The add-ons are stored in the folder
repository/org/openhab/(e.g. the Homematic add-on jar file is stored in
Pull Request build
If you want to install the latest version of an add-on (that probably has not been merged), you can install it from a “Pull Request” build. You can find the results of successful builds at this URL: https://openhab.jfrog.io/openhab/libs-pullrequest-local/org/openhab/ (e.g. the full URL to the Homematic add-on would be https://openhab.jfrog.io/openhab/libs-pullrequest-local/org/openhab/binding/org.openhab.binding.homematic/2.3.0-SNAPSHOT/)).
After you have downloaded (and extracted) the add-on
*.jar file, proceed as follows:
Uninstall an existing version of add-on in Paper UI (if available) or if you have installed it by adding it to services/addons.cfg, just remove the add-on from the binding= line.
Because the uninstall in Paper UI does not remove the installed add-ons completely, you might also have to use the openHAB Console to remove it:
Log-in to the console
Execute the command
bundle:list -sto get the symbolic name of the add-on.
bundle:list -s | grep homematic- the command grep is used to filter the list)
If no search result comes up, continue with the next step.
Execute the command
bundle:uninstall <symbolic name>to remove the add-on.
Restart openHAB (this step is optional and not strictly needed)
Copy the downloaded
*.jarfile to the
addonsfolder of your openHAB installation. The folder is dedicated to sideloaded add-ons and can be found in the main openHAB folder structure, see e.g. for Linux systems.
To check whether the new add-on version has been successfully started, you can open the openHAB Console and query the active bundle version with
bundle:list -s | grep <symbolic name>.
openhab> bundle:list -s | grep org.openhab.binding.homematic
gives output similar to:
222 | Active | 80 | 220.127.116.11804101734 | Homematic Binding | org.openhab.binding.homematic
Hint: if you go to the “Add-ons” page in Paper UI the add-on will not be shown installed. This is correct for all add-ons that are loaded from the
If the add-on is shown as “Installed” instead of “Active”, have a look at your openhab logfile. There you may find a line like
Unresolved requirement: Import-Package: org.eclipse.smarthome.binding.mqtt
This means, that you have to copy a file like org.eclipse.smarthome.io.transport.mqtt-.jar into the addons folder. For the above example, you will find the correct jar in the matching openhab-.zip and not in openhab-addons-.kar.
Before you can reinstall the release version, you must uninstall the active add-on version:
Open the openHAB console and get the symbolic name of the add-on you want to remove
bundle:list -s | grep Homematic)
Uninstall the add-on
Delete the jar file from the
addonfolder of your installation
Restart openHAB (this step is optional and not strictly needed)
Reinstall the release version of the add-on, e.g. through Paper UI’s “Add-ons” page
¶ How do I tell if my devices/technology are compatible with openHAB?
Browse the list of Available Add-Ons to see if there is an add-on for the technology of the device (e.g. if the device supports Z-Wave, look for the Z-Wave binding). If it is listed read the readme for that add-on which will include any hardware limitations for the device (e.g. some add-ons will only work with certain controllers or certain versions of devices).
If your technology is not listed all is not lost. If the technology has an open and documented API or a library or program that can be called from the command line then integration with openHAB can be accomplished using one of the lower level bindings such as the HTTP Binding, TCP/UDP Socket Binding, Serial Binding or the Exec Binding.
¶ Where do I find a list of compatible hardware?
Unfortunately no such list exists. As of this writing openHAB supports almost 150 different home automation technologies and APIs through independently developed add-ons. For many of these add-ons, there may be support for a handful of controllers but once the controller is supported ALL devices in that technology are supported. For others, there is no controller or only one device is supported. For still other add-ons, they interact with another hub which gives openHAB the ability to interact with everything that that hub supports. Couple this with the fact that the dozens of new devices are released every month creating and maintaining such a list would be a mammoth undertaking, quickly fall out of date, and be of limited utility to the users.
Therefore, the best approach to choose hardware, particularly when first starting out, is to choose a candidate technology and read the binding’s readme for that technology for any caveats, limitations, or specifics that apply to that technology. Search the forum for and read the types of problems people have had with the technology and other potential limitations.
Do not be afraid to ask the forum for advice, recommendations, or a review on specific devices or candidate technologies.
Please add questions you would like to see answered as FAQs in the comments below.