Converting PaperUI config to text-based

  • Platform information:
    • Hardware: Raspberry Pi 3
    • OS: Rasbian
    • openHAB version: 2.4.0, installed via packages

I have a relatively small OpenHAB setup, with about 25 Things - mostly Philips Hue sensors and bulbs, but a couple of Sonos speakers and other individual things, plus a Z-Stick with a motion sensor. I’ve configured all of this through PaperUI.

Lately I’ve been increasingly concerned about the lack of version control afforded to me by that approach - I’ve had a few occasions where I’ve changed something and wished I could easily ‘undo’ to a previous state. Similarly, I worry about the lack of backup should something catastrophic happen.

Less significant, but still motivation for making the change is that I’d like to be able to organise the files ‘my way’ (probably mostly naming conventions, but perhaps folder structures or similar if that’s possible) rather than relying on how the UI presents them. I’ve also wasted time on a few occasions trying to change some parameter only to find that it’s failing because of some bug in the UI, or that I can’t change it in Paper UI and have to switch to Habmin instead (or vice-versa).

I’m aware that everything (?) can be configured through text files, and as a software developer I think that would make me feel a lot more comfortable.

Does anyone have any advice on the best approach to make that change? Specific questions:

  • Will I have all the same functionality through text files? I’ve seen a few posts here regarding text-based config for Z-Wave devices, suggesting that it’s non-trivial. As I currently only have the one Z-Wave device, I would be happy to leave its config through the UI if that’s the better choice.
  • I’m assuming that I can do it gradually, moving things and items from the UI config to text files one at a time. Is that right? Any recommended approaches to making the transition smooth?
  • Any recommendations on file structure / naming conventions / etc? I’d like to use Git to version everything - should I have a separate git repository on the file system of my RPi and symlink to there from the OpenHAB directories?
  • What haven’t I thought of?

I personally did move all my items from PaperUI to text based config.

The best way IMHO is to leave the things configuration within PaperUI and just transform one item after another to text based files.

Naming convention: I’m really bad at that, but here’s what I do.
I have for each “technology” an items file. e.g ZWave.items, MQTT.items and so on.
And i’d like to keep the items like:

Switch Illumination_GroundFloor_LivingRoom {channel="zwave:......"}
Number Illumination_GroundFloor_LivingRoom_W {channel="zwave:......"}
Number Illumination_GroundFloor_LivingRoom_kWh {channel="zwave:......"}

So in the end, i’m naming like:

Itemtype <Type>_<floor>_<room>_<extension>

The really good thing is:
just start adding items from text based files.
You can have both in parallel and once you’re happing, just go to PaperUI and delete the PaperUI-ish items

And yes, you will have the same functionallity and even more since you

1 Like

Actually paperui is storing it’s data as formatted JSON files, perfect for backups. Restoring need to be done while openHAB is not running.

Advantages of text files are:

  • Copy and paste
  • The expire binding.

Tagging is possible via habmin or soon also in paperui.

Transformations should be performed with profiles nowadays, not on the item level.

Copy and paste is actually the selling point.

My 2ct.

Cheers, David

1 Like

First things first, I like a very granular approach to configuration files, so my setup might have too many for your taste… That being said, here we go:

  • if a binding has bridges, one “thing” file per bridge (hue.things, mqtt-bridge-internal.things, netatmo.things, unifi.things, …)
  • next, a thing file per “thing” if it has extendable channels (here, mqtt2 comes to mind, I love that feature :smile:): mqtt-miflora-zuzuplant.things, mqtt-sonoff-tv.things, …
  • for items, a similiar granularity, mqtt-miflora-zuzuplant.items, mqtt-sonoff-tv.items, hue-lamp-office.items, …

Also, the core of my openhab installation is dockerized.

What this granularity buys me is that my “main” installation can run with the full set of configuration, seperated from my development and testing environments. If I want to test, say, some new Hue features, or further experiment with the MQTT binding, I can start a second docker image, with a reduced configuration, and play with just that. In the mean time, the family can continue enjoying the fully featured main installation.

As to the versioning, of course I keep all those little files in git. Goes without asking :smile:

1 Like

What are the reasons for you saying that the best way is to leave things configuration within PaperUI? (I’m facing the item migration myself now)


Each thing has different configuration parameters depending on the type of the binding the thing is using, that’s why i’d like to manage my things within PaperUI.
Since i do have a lot of similar items (smoke detectors, door contacts and so on) i am way faster to configure them in text files. Just copy/paste, change the label and the channel (which I can easily copy from the thing in PaperUI) and that’s it.

And especially with ZWave devices the thing has more to offer than just channels (e.g. association groups). And for me it is easier to configure those in PaperUI than in text files.

1 Like

Thanks, I see! I’ll give it a try!