Clarification of how to configure OH2 with txt files?

My head is swimming with questions about OpenHAB 2, after 15 months of using OH1 I would like to think I had a good grasp on what is going on and how to configure it. My setup is reliable and is a core part of my home now.

Yet it feels like I am starting at the very beginning again, even to the point where I am not really sure which repos I should be looking at.

I completely respect that the project is open source and version 2 is very much a work in progress, but it would be good to try not fly ahead without leaving a clear foundation for new users to use for years to come.

I do have many questions but I will start with baby steps.

The first step being how to add items.

I like the Paper UI and the way it scans and finds various bits is great, but…

  1. Am I correct in thinking that the Paper UI is redundant for anyone that wants to configure using text files as you can not export the configuration of “things” found with Paper UI to a text file for manual edits?

  2. If true, how do I add them manually? There isn’t a wiki that lists all the addons and how to configure them anymore, so how would I find out what to put in a things file? Is there some information found in the scanned things that can be used in the manual config? What about available actions for said thing?

  3. Is the idea that the config is now stored in a database, but you are still able to write rules using text files? (because I don’t think I have the patience to use the GUI rule builder)

  4. Am I supposed to use a conf/things/myhome.things file or do I use conf/services/something.cfg as mentioned in the docs:

Sourced from the docs : Instead of the global configurations/openhab.cfg file, there is now an individual file per add-on in conf/services. The : prepended to each configuration property is removed in the new .cfg files.

I added Hue and Harmony to the Paper UI, I also added Telegram. A telegram.cfg file has been created in the conf/services folder, but I see nothing for the Hue and Harmony.

The demo config doesn’t seem to help much as there are many items in the conf/items/demo.items file such as switches and dimmers for lights, which are not in the conf/things.demo.things file

If someone can help me to understand the workflow for OH2 that would be a good first baby step


Hello @sam, I’ll make it short but can answer on follow up questions later in more detail.

  1. That’s correct. If you do want to configure your system with config files only, abandon the PaperUI
  2. A lot of details stayed the same, almost everything that changed can be found in the bindings documentation e.g.
  3. As you realized yourself, there is still some work to do…
  4. Things are only needed if the docs binding readme tells you to. Service configuration files will be automatically created when needed. There are a few not yet updated services (like the xbmc binding I think to remember) where you need to create the file yourself, containing the content previously included in openhab.cfg, without the prefix (“xbmc.”).

Here’s something I wrote a few weeks back for a friend and was planing to post to the forum, never got around finishing it though…

Did you see @rlkoshak 's new migration tutorial?

Can you just check your answer for number 1 please? I do want to configure with config files (retracting as the typo was corrected) :slight_smile:

Thanks, I will have a read. I am in two minds about upgrading at all, it was a long journey to get to where I am happy with my setup. But I like a challenge… though I do keep looking at Home Assistant to see what that is up to.

Oh no that was a typo of course :wink:

Let me tell you from personal experience. Upgrading is totally worth it and if you decide to not use PaperUI, you just have to adopt to a few details in your configuration files. I have gone that path a few months back and am not looking back!
The details have been discussed exhaustively before:

Just for clarification, I’ve not yet really focused on the approach that doesn’t use PaperUI yet. That second link makes heavy use of PaperUI. And I should say I don’t really have a problem with it except for the requirement of jumpping back and forth between it and text files to map Items to channels and creating Things for bindings that do not do autodiscovery. I assume that will get better with time.

I’ve also not played around with Habmin much but I understand Chris has added the ability to do just about anything through it without touching the text files at all.

I’m sorry that I still didn’t take the time to read it in full -.-
Would you like me to continue with the Paperless guide? It would reference your migration guide and only discuss differences when working without PaperUI…

Can I suggest to make it clear that you can’t configure things that are configured using text files at all. This is quite a common question (ie “I get the ‘can’t save unmanaged thing’ error”). All configuration needs to be done with text files which means it’s not possible to configure devices (eg ZWave devices). Users will need to use other software to do this (eg open ZWave or Zensys software for ZWave).

The guide is a great start! I think it would be fine to even concentrate more on the textual configuration as this is where 1.x users are coming from and what they are familiar with. See e.g. the services/addons.cfg file, where they could simply list the bindings that they currently have in their addons folder - no need to click through a UI for that.

I would definitely say yes! Actually, I wonder if we can somehow achieve a documentation structure where we can show how to do the same thing through the different options. Note that also HABmin is now an official part of the project, so we do not only have text files, Paper UI, but also HABmin. Installing a new addon can therefore be done through at least 3 different options (yeah, openHAB is about flexibility and not a one-size-fits-all approach, this clearly makes some things more complicated…). Actually “command line / shell” might be even a fourths option…

Does anybody have a good idea, how the different options could be dealt with in the documentation? I wouldn’t want to declare ONE way the right one, but really leave the users a choice. Only the tutorials could decide for one way to do it (the 1.x migration rather leaning towards textual, the beginner tutorial towards Paper UI, etc.).

This isn’t correct - they can be configured, but that needs to be done in the text files. So things defined in text are configured in text, things defined through UI are configured through the UI.

What you refer to though is “device configuration” as discussed here. The only binding that does this is to my knowledge Z-Wave, so for now I would document this aspect in the Z-Wave binding documentation specifically.

Ok - do you mean there something in the thing handler to send configuration updates to the the configuration update method on startup?

@kai - what do you expect the binding to do in order to support this? I can’t find anything in the docs, and the ZWave binding doesn’t do anything special here which is why I made the original point that it’s not supported in ZWave.

Can you please explain how it’s meant to work in the binding and I’ll take a look.

It does - it uses the Thing (handler) configuration mechanism for device management as we have discussed in the linked thread. There is nothing that I ask you to change in the Z-Wave binding.

Ok, sorry, I thought from the way you described this as though you meant that there was something different for the startup since I’m only using the standard handleConfigurationUpdate method and I assumed other bindings were using this.

Can you explain how this works for the startup with text file configurations - does the parser send these parameters using the handleConfigurationUpdate method - does it send these immediately after the device goes online? I’m just trying to understand the timing as there’s a lot happening on the network at startup and I’m wondering if there’s anything I need to account for here.

It works just the same way as with Things from the database (or any other source): The framework calls the registered ThingHandlerFactory.createHandler(Thing thing) and passes the Thing (which includes its configuration). Most factories then instantiate the handler by passing the Thing as a constructor parameter.
As outlined here, a Thing is nothing else than a structured binding configuration String, so it is normally treated as statically defined.

Sure, I understand how the thing is created - that’s not my question. I mean how (or when) does it call the handleConfigurationUpdate method to set the configuration that is specified in the text files.

Never, because the configuration is there from the start.

Or is your question what happens upon a change in the text file? Afaik, the file will be re-parsed and there will be a “Thing updated” event, which will call thingUpdated(Thing thing) on the handler.

Hmmm - ok, so if handleConfigurationUpdate is never called, then the configuration will never be set which is why I thought that text configuration would not be sent to the device.

Correct, as it was never meant to be sent to the device, but only be used by the handler for accessing the device :slight_smile:

Yep - but my original point was that we can’t configure devices with this method so we’re back to the old discussion about device configuration. Currently this is the only method we have to configure devices - I know your position is that the system isn’t meant to support device configuration, but without this ZWave would be pretty hard to use at all.

Hey guys, you lost me in the middle but I want to agree on this, being able to send configurations to devices would be a big step forward making openHAB a complete system. I’m still forced to do configuration in the homematic configuation wizard, which is quite buggy. Are you telling me this is currently not possible because there is no core functionality a binding can use?

The system provides a configuration mechanism, but in ESH it’s stated that this is only designed for configuring the thing (ie the software) and not the device.

However, I only found this out recently (having written the binding 12 months ago), so it’s fully possible to configure devices in ZWave - I provide the ability to configure the devices so long as you’re not using text files (hence my original point). Kais point is that the configuration mechanism is not meant to be used for this, so I’m breaking the rules (slightly) :wink: and there is some ongoing discussion about implementing something else for device management within the ESH forum.