Frequently Asked Questions (FAQs)

Setup, Configuration and Use Runtime
1

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.

General

What’s openHAB 2?

Have a look at: http://docs.openhab.org

What are the differences compared to openHAB 1.x

There are quite a few. They are discussed here, here, and here.

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 openhab.cfg?

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:

After you have downloaded (and extracted) the add-on *.jar file, proceed as follows:

  1. 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.

  2. 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:

    1. Log-in to the console

    2. Execute the command bundle:list -s to get the symbolic name of the add-on.
      (e.g. bundle:list -s | grep homematic - the command grep is used to filter the list)

    3. If no search result comes up, continue with the next step.

    4. Execute the command bundle:uninstall <symbolic name> to remove the add-on.
      (e.g. bundle:uninstall org.openhab.binding.homematic)

  3. Restart openHAB (this step is optional and not strictly needed)

  4. Copy the downloaded *.jar file to the addons folder 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>.

Example:

openhab> bundle:list -s | grep org.openhab.binding.homematic

gives output similar to:

222 | Active   |  80 | 2.3.0.201804101734    | 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 addons folder.

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.

How can I reactivate the release version of an add-on?

Before you can reinstall the release version, you must uninstall the active add-on version:

  1. Open the openHAB console and get the symbolic name of the add-on you want to remove
    (e.g. bundle:list -s | grep Homematic)

  2. Uninstall the add-on
    (e.g. bundle:uninstall org.openhab.binding.homematic)

  3. Delete the jar file from the addon folder of your installation

  4. Restart openHAB (this step is optional and not strictly needed)

  5. Reinstall the release version of the add-on, e.g. through Paper UI’s “Add-ons” page

Hardware

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.

12 Likes
3

Second real trial of oh2 b5 after having used oh1 for years
Did manual installation in expert mode though

Started with paper UI - really impressing, but… as an experienced user it would be much faster for me to do a copy&paste in the config files as in oh1; however instead of doing a clone of my current (running) oh1.8 system I want to do a setup oh2 from scratch. Therefore have started with hue as the easiest one, installed binding, identified bridge and after bridge got my 86 things (lamps). Have started creating items for first 2 lamps under paper ui I wanted to move now into config files and continue with changes.

However surprise: I do not find any things and items under ./conf/things ./conf/items which I had created under paper ui. Actually my perception was that all the configuration I do via paper ui on oh2 would be written into the config files and vice versa.

Can someone throw more light into this whether my understanding is wrong and if so, where do I find the config of all the staff created with paper ui and whether both paper ui conf and manual conf at same time would work.

Many thanks, best Jens

1 Like
4

This perception is wrong, at least a little bit. :wink: If you do your configuration using PaperUI, all the data is stored in files, but not the mentioned ./conf/* files. PaperUI writes the data in a JSONDB, which can be found under userdata/jsondb. And yes, this file is editable.

And also yes that you can use the PaperUI based json-files and manually created conf-files at the same time.

1 Like
5

Many thanks for fast reply. Now I got a better understand. Just had a look at those config files under jsondb. You are right it is editable but nomenklatur is completely different from previous config files :frowning2: and not very manual editor friendly.

So one more question: What is the configuration for at .conf/*files ?
Is is only interim for those who want to upgrade from oh1.x to oh2 or will this remain longer and is another way how to configure oh2 with old oh1.x configuration nomenklatur?

Sorry for those questions but I want to find out of what is the (for me as coming from oh1) easiest way to configure oh2 without loosing all the advantages oh2 brings.

Best Jens

6

Yes, I think the json-files are not intended to be edited on a more frequent basis. At least not as we did it with the OH1 files.

The conf-files I think are still there because of the OH1 -> OH2 migrations. A lot of the (a little more experienced) users who come from OH1 do it this way: Let the things be discovered automatically using PaperUI (and therefore stored in json db) and do everything else manually with conf-files (items, sitemaps, rules etc.). Especially if they are migrating an existing and possibly very complex OH1 configuration and therfore don’t want to start from scratch.

PaperUI for sure will remain. Wether the conf-files do remain or not, I don’t know. On the short run I’m sure they also will remain.

2 Likes
7

@jaydee73 I would be thrilled if you added your answer to the FAQs on top. This question neeeeeeds to be covered by the FAQs :wink: Please also have a look at Recommended way to backup/restore OH2 configurations and things?

8

I will try to add more content to the first post of this topic (see also: Cannot locate thing, item, etc files on a pi)

1 Like
9

Would it be possible to make a main thread/page for custom rules of people. I have some rules for rollershutters and echo usage which i would like to share with you.

1 Like
10

Hey Phill,
sure thing. That’s what the whole Tutorials and Examples category is for. Just create a new thread named “Rollershutter Automation” and throw your rules in there :wink: See other examples in the category to get an idea.

1 Like
11

Guys, please update this FAQ.
When a new file is put to OpenHAB /addons folder, one must change the file permissions. Otherwise it will be invisible or maybe just inaccessible to OpenHAB.

Something like that:
chown openhab:openhab org.openhab.binding.enigma2_2.1.0.SNAPSHOT.jar

12

It’s a wiki. You should be able to correct it and add to it yourself. Since you have the experience you would be better able to write the updates.

13

Sorry, but not true if you have configured a samba share according to the docs and are copying the files through this share …

1 Like
14

@rlkoshak Good point, thanks!

@sihui I will recheck the samba config on my PI3 openhabian, but on my system, downloaded and installed less than month ago, the behavior is different. And I’m sure I didn’t changed the samba config just because I’m not a Linux expert.

A moment ago I tried to copy some OpenHAB 2.3.0 JAR file using a samba share and checked after that the file permissions on the PI3 system. The owner of the file is openhabian user, not openhab. Also the file doesn’t have an executable flag, but I’m not sure it’s required for OpenHAB2 JAR files.

So, as I can see, Raspberry PI users must change permissions for files copied to /addons folder, otherwise they will be invisible or inaccessible for the OpenHAB software. Also files may be put not only via samba share. I copied a file via SSE using MC. Unfortunately I just followed the FAQ and didn’t imagined to take care about permissions.

IT’s not the big deal to update the FAQ topic. But I mentioned above that I’m not a Linux expert. So it’s better to discuss firstly, than write incorrect changes. My opinion that it’s enough to add something like “Please check the file permissions, the file owner should be “openhab”. Use chown openhab:openhab to change permissions”.

15

Also the steps 4) and 5) are incorrect, at least for OpenHAB 2.2. When some binding is uninstalled in Paper UI, it doesn’t appears in the Karaf bundle:list -s output and cannot be uninstalled using bundle:uninstall.

1 Like
16

Please be aware that there are other methods of installing openHAB than openHABian!

I can assure you that on a linux manual installed system following the steps in the docs there are no permission issues.
I never tried openHABian, so if there are permission problems with that installation method, it is not recommended to change the FAQ (because that one is general), but to open an issue for openHABian.

What’s wrong with it on your system?

openhab> bundle:list -s
START LEVEL 100 , List Threshold: 50
 ID │ State    │ Lvl │ Version                │ Symbolic name
────┼──────────┼─────┼────────────────────────┼─────────────────────────────────
 ...
228 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.action.mail
229 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.action.pushover
234 │ Active   │  80 │ 0.10.0.201801152239    │ org.eclipse.smarthome.binding.a
237 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.binding.caldav-comm
239 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.io.caldav
240 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.binding.expire
242 │ Active   │  80 │ 2.3.0.201801141430     │ org.openhab.binding.harmonyhub
244 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.binding.http
245 │ Active   │  80 │ 0.10.0.201801152239    │ org.eclipse.smarthome.binding.h
246 │ Active   │  80 │ 0.10.0.201801152239    │ org.eclipse.smarthome.config.di
247 │ Active   │  80 │ 0.10.0.201801152239    │ org.eclipse.smarthome.io.transp
248 │ Active   │  80 │ 2.3.0.201801141430     │ org.openhab.binding.amazondashb
249 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.binding.mqtt
250 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.io.transport.mqtt
251 │ Active   │  80 │ 2.3.0.201801141430     │ org.openhab.binding.network
252 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.binding.tinkerforge
253 │ Active   │  80 │ 2.3.0.201801141430     │ org.openhab.binding.mihome
254 │ Active   │  80 │ 0.10.0.201801152239    │ org.eclipse.smarthome.extension
255 │ Active   │  80 │ 2.3.0.201801141430     │ org.openhab.io.openhabcloud
256 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.persistence.influxdb
257 │ Active   │  80 │ 1.12.0.201801160209    │ org.openhab.persistence.mapdb
264 │ Active   │  80 │ 2.3.0.201801201844     │ org.openhab.binding.zwave

…

1 Like
17

I haven’t tested this, but in theory, as long as the (*.jar) file can be read by any user (chmod xx4), it should work (the manually deployed binding will be loaded)
…maybe execute is also needed?.. not sure

18

@sihui What’s wrong with it on my system? Don’t know, is it wrong or just different - again, I’m not a Linux or OpenHAB expert to say is it wrong or not.
What says FAQ on this page? 1) Uninstall the addon in Paper UI. <steps 2-4 are skipped to not waste the time> 5) Execute bundle:uninstall …
On my system, official openhabian on Raspberry PI3, OpenHAB 2.2 stable, when step 1) is performed, the bundle disappears from the Karaf console. At least it became invisible by bundle:list -s output and indeed it cannot be uninstalled using bundle:uninstall command.
It’s not the big deal, because newest bundle JAR with right permissions, placed to the /addons folder, became automatically visible in Karaf console and OpenHAB automatically uses it like it was installed in Paper UI. I only want to notice that FAQ on this page sometimes is different, maybe incorrect, than real working system. It may be confusing for newbies.

OK, I believe someone who will read this FAQ page, will also read our discussion and keep in mind that it’s better also to recheck the file permissions.

2 Likes
19

Hello @westward, Hello @sihui and @Dim,

As @rlkoshak said before, the FAQ is a wiki page and should allow everyone to add improved answers easily. I was a bit sad to see a longer discussion but not a single edit in the wiki itself. I have just done a few improvements of the FAQ and believe it is now much clearer and makes clear that some steps might be optional or depend on other things. Hope it helps.

2 Likes
20

In my experience that is pretty typical for a wiki. :frowning: