Beginner Guide how to handle Things and Items

I started OpenHAb some time ago.In the beginning i configured every Item and Thing in Paper UI. This worked out for me. Now i tried to integrate Google Home. While doing this i mentioned that Paper UI doesn’t support all functions (For Example Tags).

I got the advice to configure it in text files. So i started to do that for the items i’d like to add to google home.
But now i wonder myself if there is a Best Practice what to manage with paper UI and what you better manage using text files.

Sry if this is already asked, but haven’t find anything related.

1 Like

I’m not sure if there is any best practice, but I try to keep as much as possible to Paper UI. The items I have configured in files are because they depend on 1.x bindings (in my case expire, exec and nut bindings). Maybe there will be a future when we can do it all from GUI so there’s no need to fiddle around with two different ways :slight_smile:

hmm… ok.
its just a bit complicated to add tags to paper UI items, because u need to use the rest api…

For me (and likely most of us who started out with openHAB 1.x and moved to OH 2.0), I already had text file configs for items, sitemaps and rules, so adding new items to the text file makes the most sense. The other benefit of having it in a text file is that I can make my backup routine extremely simple (zip up the openhab-config folder and copy it off the Raspberry Pi) and I don’t have to worry about the DB somehow becoming corrupted. The OH 2.0 specific “Things” is what I use PaperUI for (and then only to add them to my config when they show up in the Inbox). I’m a firm believer in text file configuration, and will probably never move to the UI (even if the PaperUI becomes a fully functional environment).


Just to ensure, if i run this:
The DB is backed up too?

Yep, it is. So the backup argument isn’t really valid any more :wink:

1 Like

I use paperUI only to configure Things
All my items are in item files
They are organised by functions (more or less)
example: security.items, media.items, doorswindows.items …

1 Like

Like Vincent, I use PaperUI for configuring things, (have a few Things in config files though).
All items are in items file, seperated in devices and functions as well as room specific. All depending on which function/device. (I have an IHC controller which have a tons of different functions, these I keep in room specific item files).

Untill a coupple of months ago, I used PaperUI for things and items every time I tested a new device. And when done testing I moved it to items files. I found it easyer than creating new items in files.
But no more, because I ran into problems when moving items from PaperUI to items files.
Today I believe it´s just as easy creating the items in files first time, insted of using PaperUI, because I can make use of copy/paste very often.

I was just about to add a recommendation to the official OH docs, preview it here.


Good! I need to object against the “use Paper UI to manage ZWave things” though since Paper UI does strange things when saving Things. I’d recommend always using HABmin for Z-Wave Things.

I’m also not sure, is the distinction between OH1 and OH2 bindings clear to a new user? I know that part was a bit confusing for me when I was a newbie (that was just around the release of OH2 though, maybe things are clearer now).

It shouldn’t, and for me it doesn’t. But even if it does, developers should be able to find and fix that.
That shouldn’t affect the recommendation which is meant to be a long term valid one.

There’s other parts of the docs where this is elaborated on in greater detail.

I tend to use files for bith items and things as much as possible (maybe need to revise that for things reading this) but I do get error messages from Visual Studio Code saying my things are incorrectly configured while they are fine and they work fine.
Anyone having similar experience?

Below is my Xiaomi bridge configuration, for each of the things I get the error message:
Provide a thing type ID and a thing ID in this format:

The config is (where id, ip, serial etc are the real values

Bridge mihome:bridge:bridgenumber “Xiaomi Gateway” [ serialNumber=“serial”, ipAddress=“ip”, port=9898, key=“key”, pollingInterval=6000 ] {
Thing mihome:gateway:id “Xiaomi Mi Smart Home Gateway” [itemId=“id”]
Thing mihome:sensor_cube:id “Xiaomi Cube” [itemId=“id”]
Thing mihome:sensor_motion_aq2:id “Motion sensor 1” [itemId=“id”]
Thing mihome:sensor_motion_aq2:id “Motion sensor 2” [itemId=“id”]
Thing mihome:sensor_motion_aq2:id “Motion sensor 3” [itemId=“id”]
Thing mihome:sensor_motion_aq2:id “Motion sensor 4” [itemId=“id”]

I use PaperUI/Habmin for things and files for items mainly because i’m on the development branch of the zwave binding for security and every time you update the binding you should delete all your zwave things and re-add them to make sure you have the newest, proper thing configuration. With file defined items, as long as the node ID doesn’t change like from an exclude/include the items all re-map themselves without any intervention, where with the UI configured things it was very cumbersome manually re-mapping 70+ items

Love the table. My only quibble is that HABmin’s Rule creator isn’t really functional at the moment. It still generates OH 1.x Rules and there have been enough changes here and there since it was last updated that users are as likely as not to end up with Rules that won’t parse.

Until Chris gets a chance to get back to that part of HABmin I’d say “Not Recommended” instead of “Graphical”, or at least don’t put anything in that square. But putting “Graphical” there new users will be enticed to use it instead because in their mind graphical == easier. I’ve already dealt with this problem a number of times on the forum and I fear putting it on the front page of the docs will make the problem worse.

VSCode will also syntax check .items files and .sitemap files as well so I’d recommend VSCode for all of them.

Great content! Thanks for writing it!


Oh, I thought this was a kinda general problem, I’m quite sure I’ve seen @chris recommending against using Paper UI for changing Z-Wave Thing settings. But if the general recommendation is to use it I’ll take back my objection :slight_smile:

And I would object against the use of Habmin :slight_smile: Sometimes it does not refresh the statements of a thing, which can make it rather confusing.
I tend to use both Habmin and PaperUI, for z-wave stuff.

+1 for VSCode recommendation for text files

Agree. Actually I didn’t rework all of it and had simply left that unchanged.
That now made me think I should cross-check all of it again. Still learning something new, too (e.g. never tried to create groups using PaperUI or habmin before).
Here’s the reworked version, let me know what you think of it

1 Like

Excellent and a good and valid overview. Wish I would have had that table 1,5 years ago…

Love it! I think this will help a lot of new users.