How to setup things files?

I’m using openhabian on Pi3

This whole concept of file vs. UI-based approach is extremley missleading for beginners (and I’m a full time developer).
If you are looking for tutorials it is a total catastrophe. Some uses GUI, some uses files, some use both. I spend days until I understood that stuff that I add via GUI is NOT appearing in the file system…

Since the GUI thing is not working very properly and still is not very user-friendly I no am trying to set up my OH2 from scratch (now the sixth time now) - but I want to avoid the GUI as far as possible…

I Found several tutorials about rules and sitemaps… But how do I configure things? I added the bindings via the GUI… But what do I do next? How do I configure the things and items??? How can I get the IDs and stuff like that from the Item?

I found this:

Can I automatically add the things files?
Imo that’s they way it should work: You add the things via GUI and the files will be generated at the same time. Not with two different approaches (db/files). That’s totally confusing…

Can I add as many things/items/rules files as I like? If yes? Is there a difference between one big file and several smaller files? I’d like to seperate lighting, heating, sensors and security…

Although I really like OH, I’m still confused…

thanks a lot


Agreed it can be confusing, I went through the same process. Started with GUI as seemed quick to get started (and generally recommended) but I’ve subsequently refactored and I think 99% is now file based. As you’re a developer I’d highly recommend the file route, you can always play with the GUI to see stuff but do final build in files. There are some recommendations about not doing this for Zwave bindings and maybe others but I don’t have those so can’t confirm/deny and worst case you can mix and match files/with GUI.

It was a daunting prospect to refactor but actually once you’ve started and done a few it’ll make sense. So for something like a network bound thing:

Thing network:device:192_168_0_20 "TV Samsung" @ "Lounge" [ hostname="", retry=1, timeout=5000, refreshInterval=30000, use_system_ping="true" ]

I only connect for the online status so the channel deals with that on my Item:

Switch tv_Samsung_Lounge_Online "Samsung Lounge Online [%s]" <switch> (gAnyGroupsYouWant) { channel="network:device:192_168_0_20:online" }

My astro things (sanitised so you can’t stalk me!):

// The main 'local sun' thing
Thing astro:sun:local "Local Sun" [ geolocation="45.123456,-0.432111", interval=300 ]

// Full moon is the bound item so reducing the interval
Thing astro:moon:local "Local Moon" [ geolocation="45.123456,-0.432111", interval=3600 ]

The items:

DateTime LocalSun_Rise_StartTime "Sunrise [%1$tH:%1$tM]" (grp_House) { channel="astro:sun:local:rise#start" }
DateTime LocalSun_Rise_EndTime "Sunrise [%1$tH:%1$tM]" (grp_House) { channel="astro:sun:local:rise#end" }

There are masses of available channels for things like Astro which are great but I suspect most will end up only using a limited few so the file setup isn’t hard.

What I also found really handy was you can read the PaperUI JSON database because it’s basically a text file, just look in the openhab2/jsondb folder and you’ll find the appropriately named files for things, items and channel links etc. If you’re stuck on something you can usually read what PaperUI is doing from it’s database and reverse it back in to the required native file format. Personally when I was done I also shutdown OH and did some text editor editting of the channel link database as it seemed to have not cleaned up after itself in some instances.

The structuring of your files is flexible and your preference. I don’t have many Thing files as most of my devices are not bound so I’ve lots of Items.

I tend to group as you mentioned like network, sensors, heating, security etc although as with everything there are always some bits that live in a grey area!

One to watch for: This maybe only related to the live stable release 2.1 but editting groups via files and specifically the groups an item belongs to isn’t reflected unless you restart OH. Personally if I don’t a lot of editting of things and items I tend to just restarted OH so I know it is in a good state, also tail openhab.log and ensure no errors!

1 Like

This is a side effect that OH is in a major architectural transition from the old OH 1.x way and the 2.x way. As development continues the differences will become less pronounced. In the end I think the goal is that everything will be in the JSONDB (or whatever that storage becomes in the future).

No, but you can write your own .things files. Most users however, use the karaf console or one of the admin UIs to manage Things so they can take advantage of automatic discovery of Things. There are some bindings that do not support .things files very well, though that too is also improving.

Yes, you can have as many files as you want. No, there is no real difference from OH’s perspective. I too separate my files by function.

I can confirm this for Zwave. There are so many devices and each device has its own parameters and settings in its Thing definition that it is challenging to write the .things files yourself. And it is so easy to just click in the inbox and accept the automatically discovered Thing (or accept it through the karaf console). However, if you do want to manually define the Things, I think you need the development branch of the binding as the mainline branch doesn’t yet support manually created Things.

Well… That really sucks… With the GUI I could add all stuff I wanted really wuick, but wasn’t able to add any “smart” stuff… The only thing I was able to do is switch a light on or off…
With the files I eventuelly can add rules and can control everything, but have to add every bloody part of my smarthome by hand…
Just my Harmony has over 100 singel commands - and thats ONE item… How can I find out all the functions and channels that are included in my things? What about Items without an IP address (Ikea Lightbulns, Hue lamps, sockets etc)? How can I find out the data…

I tried the code you posted @RayMYP and wasn’t able to activate a single light bulb…

How is a non-expierenced user supposed to handle that? Every step is 3-hour fight, nothing works intuitively and
the documentation here is almost of no help…

With this system I’m (by far) quicker if I add everything in the GUI, use OpenHAB as an interface that I access via REST and code everything myself with Javascript and/or PHP…

sorry for the rant… I’m kind of frustrated…


Each device is represented by its own unique Thing. If it is a Thing from a Binding that supports manual creation of Things (all bindings will be there at some point soon) all the Things and Channels will be documented in that Binding’s readme. If you have automatically created Things you can look at the Thing in PaperUI and it will list all of its Channels and the Type of Item it needs to be linked to. If not, all the Channels supported by a Thing will be documented in the Binding’s readme. Or you can look in the Things JSONDB file which will show all the Channels for each Thing which includes the Item type that Channel can be linked to and the Channel ID: It will be of the form:

"uid": {

which would translate to the Item

Switch MyZwaveItem { channel="zwave:device:dongle:node25:switch_binary" }

This question is a non sequetor and belies a misunderstanding of how OH works. You would probably benefit from a review of the Beginner’s tutorial and a review of the Concepts section of the User’s Guide.

Bindings care about IP addresses, RF signals, GPIO pins and whatnot. Thing represent a single device that a given Binding can talk to. Channels represent a single piece of information or single actuator on a given Thing. Items are linked to Channels. So the Item is far insulated from any of that stuff.

However, if you are dealing with a 1.x binding, there are no Things, no Channels, no automatic discovery, and no ability to configure or manage the binding or Items bound to them in PaperUI (hence the mix of UI and text based configs). In this case you have an Item which gets bound to one or more binding and each Item has a binding config string that tells it what device or end point that Item represents. For example, the MQTT binding is a 1.x binding so here is one of my Items for a Sonoff Switch.

Switch aOutside "Outside"
    <christmas> (ChristmasLights)
    { mqtt=">[mosquitto:cmnd/sonoff-0587/POWER:command:*:default],
            <[mosquitto:stat/sonoff-0587/POWER:state:default]" }

The specific binding config string is fully documented in each Binding’s readme.

tl;dr Read the binding’s readme

I think as @rlkoshak suggests this shows that you haven’t really grasped the concepts of things, bindings, items and channels. You have to understand that a binding only encapsulates certain functionality related to the problem scenario it’s trying to resolve/simplify. So for the first example I posted of a ‘Network’ binding it’s mainly useful for maintaining Items that indicate live/dead (ON/OFF) for network devices. Armed with that sort of binding I can create a handful of items and include those in a Group:NAND(ON:OFF) so if any of those items go OFF the group changes to OFF and I can send an alert, infrastructure down!

Now one of those devices might be a lamp but the Network binding has no idea about that, it’s not the problem world it’s set out to solve. If you have an IKEA lamp you need a binding service that can deal with talking to IKEA lamps about ON/OFF, dimmer or RGB etc if the lamp happened to be WiFi enabled you might actually choose to also add it as a Network binding so you could see if the lamp has fallen off the network but the network binding won’t turn the lamp on or off.

What is the “smart” stuff? From day one I wrote all my rules via files and was using PaperUI to create things and items, you can mix and match a reasonable amount to suit your preference. I moved away from the GUI because I can actually create 50+ things and another 50+ items faster in text files than I can clicking around a GUI. As I said before I still find the GUI useful for browsing and exploring what a binding might offer but not much more.

With flexibility comes complexity and you’ll find using the standard rules engine and DSL has it’s own quirks as much as anything else new and different but there’s nothing stopping you using REST and PHP etc if you want to do your business logic there. But you should evaluate the DSL offering and alternatives like JSR223 first and make an informed decision.

No one solution is ever perfect for everyone so ultimately you have to decide what works for you.

1 Like

Yes I know… but this is what I definitley not wanna have. I tried that and run into massive problems… That’s why I want to add the things via files…

a) how?
b) as far as I ujnderstand: there are no things there at the moment…

I know… I understand the concept of bindings/things/items/channels, but how do I translate that stuff into a file…

I think as @rlkoshak suggests this shows that you haven’t really grasped the concepts of things, bindings
I think I do understand the concept… I’ve already programmed my own API based on that - and it’s working just fine.
But so far I only added all the stuff via GUI - which I want to avoid…

May be I take an example from my system:

I added the Hue Binding at the UI. OH correctly recognized the HueBridge, and is listing it in the inbox:

HueBridge (
Hue Bridge

But what’s next? How can I now fill my things file? Where do I get the data? All the stuff, that was automatically added via GUI before where I just clicked “add as a thing”? How do I add a Hue remote control or a simple Lightbulb for example? All the stuff that’s already connected to the bridge?

Via PaperUI, going to the Add-ons link, you can find the binding documentation by clicking o the binding. Right from where you installed it from. Just click on the name of the binding.

You will not get there via Configuration/bindings/“binding”.

Almost every documentation contains a chapter “thing configuration”. I checked for the hue.

1 Like

Yeah… That’s what I was looking for… thanks…

But it’s still not working…

After I added the Hue Bridge as thing, alle the lights appeared in my inbox:


Color Light


Bridge hue:bridge:1 [ ipAddress="192.168.X.X", userName="XXX" ] {
    0200 bulb1  [ lightId="5" ]


Switch Light1_Toggle { channel=“hue:0200:5:bulb1:color” }


sitemap home label="SmartHome" {
    Frame label="Wohnzimmer" {
            Switch item=Light1_Toggle            

What did I do wrong here?

thx & regards,

Your Thing definition is wrong, or at least differs from mine. Mine is working. :wink:

I wrote the light id twice. Although it’s the same entity, the parameter “lightId” is not the same as the address number between bulb type and bulb name.
Make it look like that

Bridge hue:bridge:1 [ ipAddress="192.168.X.X", userName="XXX" ] {
    0200 5 bulb1  [ lightId="5" ]
1 Like

thanks… but still not working…

is there way to check if the hue authentification is working?

Sure, you may check the logs.

If you are using openHABian, you could point your browser to http://openhabianpi:9001 to review them.

1 Like

Here is the log entry:

[WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model 'home.things' is either empty or cannot be parsed correctly!
[ThingUpdatedEvent         ] - Thing 'hue:bridge:1' has been updated.
[ThingUpdatedEvent         ] - Thing 'hue:0200:1:bulb1' has been updated.
[WARN ] [ome.core.thing.internal.ThingManager] - Cannot delegate command 'ON' for item 'Light1_Toggle' to handler for channel 'hue:0200:5:bulb1:color', because no thing with the UID 'hue:0200:5:bulb1' could be found.`

This is confusing… there seems to be a problem parsing the things file, but he updates the things anyway…

This message says “either empty”, wich happens for a short moment, while the file is being written. The file-changed event is a bit too early

My suggestion is to discover the things via PaperUI. You can copy the channel information to your items definition file. Later on, when you are familiar with the items, you can add the things per file, restart, and it’s done. PaperUI is a great help for starting.

And, by the way, it’s best to use the id-notation which is used by PaperUI instead of an own id scheme. (Did it, switch back due to some annoyances, but nothing too serious.)


This message says “either empty”, wich happens for a short moment, while the file is being written

ok. can i assume that this is the case here? and there is no problem with my things file? When I intentionally add a syntax error, it will be shown in the log file with a line number as well. So I guess there is no problem.

[quote=“job, post:14, topic:36812”]
My suggestion is to discover the things via PaperUI[/quote]

That’s exactly what I want to avoid… Last time it wasn’t possible to delete things, it stopped with an error message and then everything was screwed up…

This is the major problem I see at OpenHab… that makes it sooooo damn difficult to get started: there are always two ways to do something… Two UIs, three ways to add things/items two ways to address items etc…

I see this as a feature! You may choose whatever you prefer :grinning:
I’m using a mix of everything (PaperUI things, channels via text files linked to those things, manually created items without any binding config linked to auto discovered things and channels, …) and it all works fine.

1 Like

In PaperUI under Add-ons, when you click on an add-on’s name it opens that add-on’s README in another browser tab.

Or you can go to and browse to the User Manual, Add-ons and the add-on you are interested in.

Or you can go to and search for the addon you are interested in.

Another misunderstanding. Bindings are add-ons. The Inbox is where you will find the Things that your Bindings have automatically discovered.

First, you install a binding. Then you configure a binding according to its README. Then, if the binding supports it, you accept automatically discovered Things out of the Inbox.

That is a Thing ID. You can find the Channels for a given Thing in all the ways I already described. Or you can look at the README in one of the ways I describe above.

You say you have read the documentation but you have some major confusions about key concepts with OH which is probably the main source of your frustraitions and difficulty.

And like I said, not all bindings will currently support that. And given your confusion about very basic concepts like the difference between a binding and a Thing I have to recommend against this. I think your issues is misunderstanding, not the UIs. Until you have a bit more experience with OH I would:

  • Install bindings through PaperUI
  • Use PaperUI to accept automatically discovered Things out of the Inbox.
  • Use PaperUI to discover available Channels on a given Thing
  • Do everything else in text configs.

This is the easiest path.

If this is an apt-get installation the JSONDB is located in /var/lib/openhab2/jsondb.

They are plain text JSON formatted files. Do not edit these files while OH is running.

That may be the case, but your harmonyhub:hub:HarmonyHubWohnzimmer is most definitely a Thing and if it was an automatically discovered Thing (i.e showed up in the Inbox) you will find it in the JSONDB.

Your questions and misuse of termonology indicate you do not, in fact, understand these concepts.

OK so far

That is an automatically discovererd Thing. You need to accept it out of the Inbox. It will then appear under Things in PaperUI. Click on that and it will list all of the Channels available on that Thing at the bottom of the page. Some have only one Channel, some have dozens of Channels.

Since the HueBridge is a contorller, you may need to do something else to have the rest of your Hue devices discovered or manually create them through PaperUI or .things files. Looking at the Hue Binding README


The Hue bridge is discovered through UPnP in the local network. Once it is added as a Thing, its authentication button (in the middle) needs to be pressed in order to authorize the binding to access it. Once the binding is authorized, it automatically reads all devices that are set up on the Hue bridge and puts them in the Inbox

Excellent, progress!

And this is why there is the recommendation to use PaperUI or the Karaf Console to aut9omatically discover Things where possible.

Thousands of Hue Users, many of which are not technical, have been very successful in setting up Hue through PaperUI. But if you don’t want to use PaperUI, you can do the same operations from the Karaf console.

It is an opensource project currently undergoing a major re-architecture while maintaining backwards compatibility that supports the integration of 200+ technologies and APIs and tens of thousands of devices from hundreds of different vendors. Its going to be complex.

But, like sihui, I see the fact that we have options for how we want to set it up which will meet our individual needs is a feature.

1 Like

Yes I know those “features”… I’m a softwar developer… Said this a thousand times “It’s not a problem - it’s a feature

You may choose whatever you prefer

Maybe… half a dozen different solutions and none is really working properly.
That’s the reason why everone is talking about Apple Homekit, Philipps Hue and Amazon Alexa - and nobody talks about OpenHab.

but you have some major confusions about key concepts with OH

I don’t think so. I’m well aware of the differnce between bindings and things… (as I said: I’m using OpenHab vor a couple of months now and build my own RestAPI, accessing, things and items). It’s just hard to describe something, if you can’t use neutral expressions like “item” and “thing”,

Use PaperUI to accept automatically discovered Things out of the Inbox

If that had worked I would still use it. But automated adding of things caused a lot of problems at my previous Installations (e.g. I was not able to delete things via GUI)

They are plain text JSON formatted files

Ah that’s good… than I can import the DB from my old installation

armonyhub:hub:HarmonyHubWohnzimmer is most definitely a Thing

Yes, but It hasn’t been added yet… It’s neither in the JSON DB nore in the GUI and not in my things file. It just has been deteceted by OpenHAB, after I added the binding…

You need to accept it out of the Inbox

Yes but as I said before: I want to handle things via file and NOT via GUI. Thats the whole idea why i started from scratch

And this is why there is the recommendation to use PaperUI or the Karaf Console to aut9omatically discover

If the GUI would be working, I would use it. But it doesn’t! The GUI just sucks… Looks like an early Beta…

you can do the same operations from the Karaf console

It seems that you misunderstood me, maybe because English is not my mother tongue…
But again: I want to use files to setup things!

It is an opensource project currently undergoing a major re-architecture

Then you should have done the re-architecture BEFORE you published a new release that is not working - or publish the new release AFTER you write proper tutorials and documentation…

And it doesn’t help me that OH is able to support hundrets of different APIs when the three APIs that >I< need aren’t working properly…

Which is why I use Item when referring to an OH Item and item when using it for the general meaning. Same with Thing.

“Working properly” is a subjective measurement, but the thousands of successful and happy OH users seems to point to OH doing something right. Noone here has claimed it is all roses and puppy dogs and lots of work id being done to make it better.

I see OH talked about everywhere, but everyone is in their own individual media bubble. What I see may not be what you see.

But I do find it interesting how many users migrate to OH FROM those systems because of their limitations.

So, you have said this many times. You have provided no details except “it didn’t work”. So we haven’t addressed it. I’ve not seen other reports of this particular problem. Maybe the fix to your rare and otherwise not yet reported problem is as simple as Clear the Cache

All we are getting is “PaperUI didn’t work so it and all people who use it are evil.” What do you expect from us?

So are you just ignoring all the times I’ve said “or you can do it from the Karaf console?”

And you may not understand me.

This cannot be done yet for ALL bindings. Look at the README for the three bindings you need to see whether or how to define Things in text files. If it doesn’t tell you how to create Things, you can only use automatically created things.

Even when it can be done it will be harder for you.

They did. OH 2.2 works great for thousands of users and 2.1 works perfectly for thousands more.

You’ve provided no details about the PaperUI problem except to say you couldn’t delete Things. You’re a programmer. Logs? Errors? Exceptions? Ask for help on the forum?

No, lets burn the whole thing down and then get mad when OH doesn’t let me do it exactly the way I want to.


I reinstalled OpenHAB about five times (new SD card, new Raspberry) and always ran into the same problems with the GUI.
So for me the fix is: Don’t use files!! Every OH user I know personally recommended this… So now this is what I do. So please stop trying to convince me to use the GUI again.

What do you expect from us?

That you accept that I DONT WANT TO USE THE FILES - as said in the headline of this thread.
You may find that Paper UI is the coolest piece of software this earth has ever seen, but I still don’t want to use it.

Is this so hard to understand? I’d like to have help setting up OpenHAB using >>>FILES<<<… is that so hard to understand?

lg, Dave