Using files instead of database storage: what's the usual flow for adding a new thing/item?

  • Platform information:
    Hardware: Raspberry Pi 1 Model B
    openHAB version: openHAB 2.3.0-1

Hi,
I’m pretty new to OpenHAB. I was able to play a little with it and now I would like to add all my devices (mainly Ikea light bulbs) in OpenHAB. However, since adding the devices is a tedious process (sometimes my devices are not discovered immediately) I want to make sure that I don’t loose the configurations in case something goes wrong with the card.

So, my understanding is that, in order to easily backup the configuration, I should define the things/items in files instead of the Paper UI database.

Could anybody tell me if there is a “standard” approach on defining the items in the files with/without using Paper UI ? I read the documentation but I couldn’t find such a work flow, so I’m counting on your experience / best practices suggestions on it.

Thank you !

I dont use things files, (only for those bindings which require it)…
I use PaperUI for things, and files for items. PaperUI handles things just fine. Most often you dont need to do some extra with things. But with items files you could have a need of setting tags etc. Then it´s much easier using items files.
I did start of using PaperUI for everything, but I simply had to switch all items to files because it gave me a much better overview and I was able to set taggings etc.

There is no “standard” or right/wrong approach on this matter. You do what suits you the best.

How do you backup your configuration ? Is backing up the items/scripts/rules folders enough ? I’m thinking that, in the unlucky event of a card failure, you’d have to rescan again to find all the things.
And, when all things are found, would the mappings between things and items still be valid ?

Thats a question nobody wants to answer :grin:

If you use items files, they´re easy backup´d up just by copy those… You simply could just copy all folders in the /etc/openhab2. But if the system crash, then you´ll need a full backup strategy. In my opinion this is a huge lack in openhab running the “easy to use” apt-get hasslefree installation. I know, quite a few people do not agree with me on this matter, but the truth is. Having a decent backup strategy in openhab simply isn´t an easy task, even though openhab comes with partly “build-in” Amanda. It still requires lots of knowledge for a matter which isn´t quite obvious for openhab in general. In short - you need to know linux in ways which is not required for openhab itself…
This is not unusual for applications, OS´s etc. So it´s not something openhab do different than others. My concern is mostly, that a backup strategy should be atleast as easy and as important as getting the system up running. It´s not!

I do not have a automatic backup strategy, yet - I run openhab from an Rpi 3B, not using SDcard but insted using an external SSD. When I do backup, I shut down the Rpi, unplug the SSD, connect it to my windows workstation, create a full image of the drive, plug it back into my Rpi, and start again. My main reasons for using this way are:
I have not yet been able to understand how Amanda works. (mainly due to lack of time and Linux knowledge). I know this is a poor excuse, when I just stated above, that a backup strategy should be as important as getting the system running. But sometimes I know whats right to do, but have to do it wrong. Otherweise I´ll get nowhere.
My original plan was to set up openhab in an test enviroment, add all kinds of stuff which slipped to my mind. When things has been tested and approved, I would start all over using the latest release including a backup strategy, (maybe even different hardware).
Unfortunatly I struggle and find myself spending much more time than expected on testing and getting the approval done, due to not all is working as it´s suppose to, as well as trying to learn all kinds of stuff in openhab, which making me spend lot of time on trying to get things working insted of just dump those things and try something else. But due to personal reasons I feel I´m bound trying to help the developers with my experiences, just as well as I´m still learning openhab…
It´s a lot bigger learning curve than original expected. And I´m too ´stupid´ to set limitations for my interest in this system. I guess I need something like 48 hours a day to fufill me needs and interests in this, and backups are the most borring part everywhere :slightly_smiling_face:

yes if you use only text based configs (for both items and things)
everything else (addons like bindings, transformations, persistence, etc) can be re-installed on a clean system.
For more advanced setups using a persistence DB, you will need to backup that DB storage also (but this is outside OH2).

1 Like

Ok, and how would I add things in the .things file ? Is there a discovery process for the command line or do we have to use Paper UI for that ?

Assuming that you use Paper UI to do the discovery, how do you proceed after a new thing appears in the Inbox ? This is something that I found to be missing from the docs (or at least, if it exists, is pretty well hidden :slight_smile: )

Purely: manual :slight_smile: (by editing flat text files)
Read the corresponding docs entry for the 2.x binding and search in this forum for other examples.
The structure of a .things file is almost the same across bindings.

I record all the data/parameters from the discovered Thing in the Inbox and use it to manually define my stuff. I don’t accept the Inbox entry so nothing is added in my system.
If you use the same Thing name in the file, the Inbox will not show anymore the Thing as newly discovered.

This is a mistaken understanding. The built in commands (openhab-cli backup, openhab-cli restore) back up everything no matter how you define them.

Some old timers like using an all text file approach for Things and Items because that is what they are used to and/or it fits better with an already established workflow.

Some power users who have hundreds+ Things find it easier to manage Things and Items defined in text files.

But there is no difference in terms of backup and restore between the two.

And, importantly, the “database” that the Things and Items created in PaperUI get’s saved to are plain text files, not some opaque binary format.

Well, https://www.openhab.org/docs/configuration/items.html documents the syntax for creating Items.

Each binding will have its own format and set of fields so you will need to look at the binding’s README for how to manually create Things in .things files.

Most users I think follow Kim’s approach. Let PaperUI manage the Things so you can take advantage of automatic discovery and use .items files for Items so we can take advantage of features like tags and OH 1.x version bindings which are not supported in PaperUI.

If you are using openHABian you should set up Amanda. If not, run sudo openhab-cli backup and copy the resultant file off of your SD card and you are good. To restore copy that backup back to the SD card in the same location (assuming a catastrophic SD card failure) and run sudo openhab-cli restore. That will grab everything you need including installed bindings, anything done in PaperUI, and anything configured through /etc/openhab2.

Personally, I’m one of the old timers previously mentioned so I use git.

No. You also need a bunch of stuff from /var/lib/openhab2, most importantly /var/lib/openhab2/jsondb and /var/lib/openhab2/persistence. But there might be other important folders in there depending on what bindings you have installed. And note that if you are not using one of the embedded databases for persistence, you will need to back that data up separately.

It depends on the binding. For example, when you use the Zwave binding and add the controller Thing, by default it generates a random string as part of the ID. When all the nodes that are on that controller get added, part of their ID will come from the controller’s ID, including that random string. You can avoid this by replacing that random string with one of your choosing (I use “dongle”) when you first add the zwave controller.

I would expect the zigbee controller to work the same.

But there will be many bindings though where that won’t be the case and the Things will all come back with the same IDs.

Of course, if you include jsondb in your backup and restore then none of this matters since everything will be backed up.

Finally, some devices like zwave controller and zigbee coordinators may need to be backed up separately as well.

1 Like

Just to add a clarification: This is assuming that he is using PaperUI for any Thing/Channel/Item configs
If he goes full manual (text files in $OPENHAB_CONF) there is no need to back that up.
My jsondb is completely empty for example.

Of course, as already mentioned, this is not the “mainstream” approach, so it is wise to backup parts of $OPENHAB_USERDATA as well. I don’t use openhab-cli backup so I don’t know exactly what parts are included.

There are some bindings that may require jsondb stuff (I think Homekit is one of them)… in this case, you need to backup jsondb as well.

HABot is also coming which will make use of jsondb :slight_smile:

For the persistence data store: I consider it an external subsystem so I have a dedicated backup for that (even if it’s mapdb or rrd4j).

If he is using MapDB he also needs /var/lib/openhab2/persistence/mapdb.

If he is using RRD4J he also needs /var/lib/openhab2/persistence/rrd4j

If he is using zigbee or zwave he might need those folders too (I’m not positive about that).

If he isn’t using services/addons.cfg he will need /var/lib/openhab2/config and perhaps kar as well?

There is a ton of stuff in userdata that isn’t related to jasondb that should also be included in a proper backup.

openhab-cli includes them all which is why I always recommend it. If you use openhab-cli, all your bindings, binding configs, persistence data from embedded databases, and binding specific files get backed up.

Personally I use paperui for things and flat files for items. The key is when you are defining your “controller” thing (zwave/zigbee stick, nest account, echo control account in my case) is to change from the randomly(?) generated Thing ID to something else. I use something descriptive like “zwave_stick”. Then, when you define your items you do it like this:

Switch     BedroomLight_Switch    "Bedroom Light"   (GBedroom) [ "Lighting" ]  {channel="zwave:device:zwave_stick:node15:switch_binary"}

That way, if you ever need to delete or rediscover your things (like was the case when moving to the new zwave binding) all you need to do is make sure you use the same name if you need to create the new controller and the things link up automatically to your items once you add the things from your inbox. I don’t bother with changing the names and rarely need to change parameters so i’m able to stand up a new OH copy in less than an hour from fresh install by going that way and backing up my /etc/openhab2 folder and copying it back in after reinstalling bindings, creating all my controller things, and doing a scan/add all discovered things.

I would like to thank everybody for their tremendously useful answers!

I consider this topic answered.