Configuration GUI vs Files questions

Setup, Configuration and Use Beginners
1

Hi All,

probably a stupid question - I tried to find guidance in den docs and the community but didn’t got my head arount those :frowning:

I understand that there is a JSON configuration “database” which is used through the UI based configuration. So all Things I create on the UI will be stored within that JSON db.

I also understand there is a file based configuration in the config folder which is supposed to overwrite (fully - partially - I don’t know) the configuration stored in the JSON db.

My problem is that I don’t understand how these two stores really work togeter.

Because if I add a thing in my configuration file folder, I don’t see it in the GUI :frowning:

And if I would like to extend / change the code of a thing (e.g. for the TR064) the code in the GUI looks totally different from the code in the docs.

Is there probably something broken with my configuration (as the files are not picked up by OH)?

Or am I just missing some understanding how things fit togehter?

How can I change the thing configuration in the UI to reflect the options available in the config file?

Cheers
Stefan

2

Look upon them as two different ways to load configuration data into the behind-the-scenes JSONDB

Then something is wrong; tell us more about what you did, and where you looked for the results.

Can you be specific, what option do you think have in file that is not in GUI edit?

1 Like
3

Thing is, they’re not designed to be used together.
Read https://www.openhab.org/docs/configuration/#textual-vs-graphical-configuration

Likely yes.

Clarify what “GUI” you are talking about first
Your last sentence makes me believe you’re talking about pages.
You will never get to see any Things or Items in pages. Only widgets that you define yourself, just like in sitemaps. That’s the user UI, it’s the OH3 equivalent of sitemaps. What you see at the “Code” tab is dynamically generated YAML, it’s what gets stored (JSON-encoded) in jsondb.
There are NO input files for this.
But that’s NOT what the configuration section of the docs I quoted refers to anyway.

To create Things and Items use the proper menus below Settings (“Einstellungen” if set to German) or direct link http://192.168.x.y:8080/settings/items/
If you create Things and Items through files, they will appear there, too.

4

Actually I am not talking about pages - this difference is totally clear :slight_smile:

I am Talking about the Code behind a thing:

OH_things_code
OH_things_code2270×844 75 KB

My assumption was that the code behind a thing would be the same, regardles of the location (GUI or file).

5

Understood - but it gets really complicated if you try to just use the UI to configure everything and the whole documentation is refering to the file based configuration :confused:

1 Like
6

From your screenshot you have when creating a thing you have three tabs

Thing & Channels are a user friendly GUI to create a correctly formatted thing in the code tab.

Your assumption based on that screen shot is correct though if you go to the code tab and make changes. They will be visible in the thing & Channels tabs.

The files they mention are text based files I think for new users they are best described as legacy files so ignore the .things files. @mstormi provided a good link explaining this.

Best reading further down to see the new user recommendations

The docs are written for people who are completely new and people migrating from OH1 or OH2.

7

And this was plain wrong and the root of your confusion.
Like pages YAML, it’s dynamically generated and has no file equivalent.

Not at all. Not sure what you refer to but the documentation refers to Things and Items, not files.
Code tab is not a file and isn’t referenced anywhere as an input medium, is it.
It doesn’t make sense to use it for that purpose when you have the UI right next door because unlike file syntax, UI is self-explanatory, isn’t it.

8

Actually it is really confusing.
The documentation explains how things work in file-syntax. Which just can’t be copy/pasted into the OH3-UI. You must have an understanding, how and where you do things. That’s, what TE means, I think.

example:
If you like to configure a KNX actuator, you’ll see in documentation something like this:

Bridge knx:ip:bridge [
    type="TUNNEL",
    ipAddress="192.168.0.10",
    portNumber=3671,
    localIp="192.168.0.11",
    readingPause=50,
    responseTimeout=10,
    readRetriesLimit=3,
    autoReconnectPeriod=60,
    localSourceAddr="0.0.0"
] {
    Thing device generic [
        address="1.2.3",
        fetch=true,
        pingInterval=300,
        readInterval=3600
    ] {
        Type switch        : demoSwitch        "Light"       [ ga="3/0/4+<3/0/5" ]
        Type rollershutter : demoRollershutter "Shade"       [ upDown="4/3/50+4/3/51", stopMove="4/3/52+4/3/53", position="4/3/54+<4/3/55" ]
        Type contact       : demoContact       "Door"        [ ga="1.019:<5/1/2" ]
        Type number        : demoTemperature   "Temperature" [ ga="9.001:<5/0/0" ]
        Type dimmer        : demoDimmer        "Dimmer"      [ switch="5/0/0", position="5/0/2+<5/0/3", increaseDecrease="5/0/4" ]
        Type string        : demoString        "Message"     [ ga="5/3/1" ]
        Type datetime      : demoDatetime      "Alarm"       [ ga="5/5/42" ]
    }
}

You’ll have to go one attribute at a time from either the textual example or the “Bridges”-table on the same page, to type the information into the UI - and be sure to distribute it in at least two or more things in UI, where in many cases the names for the attributes are not corresponding with the textual description in the docs.

So, e.g. “Network Address” in UI is named ipAddress in the example and the table - and in the YAML.
…but at least the UI does much more wrt help-text at the time you type the attributes in.

I have honestly no idea how to fix this in the docs at all from a documentation point of view - as it has to both address the users working with textfiles and the UI.
Same goes with rules examples - most (if not all) are DSL, but OH3.3+ slowly but steadily moves to JS Scripting from my personal feeling…

9

hmmm… Thinking about it: one way to solve this would be some kind of “import” into OH3-UI based config with *.things files - as it is already possible with *.items… sort of at least.

10

Unfortunately a lot of bindings, and therefore the Things associated with them, changed from OH2 to OH3 in sometimes subtle ways e.g. a number channel might now be a number:temperature channel.
Means a lot of straight ‘imports’ of old stuff would be error-prone.

Back to

Your openhab.log will contain boot time announcements about config files found and processed, just as it did in OH2

1 Like
11

No. You should clarify what you mean by the documentation you talk about, but the (official) doc doesn’t and actually I believe never did.
To the best of my knowledge, there’s no generic explanation of things and items syntax as it has not been recommended to use that ever since OH2 came out.
If someone like the KNX maintainer for his addon (!) chooses to include examples as things/items that’s not the documentation either or just a minor part at best.
It’s just sometimes done because it’s easier to use text to illustrate configuration than to extensively describe UI moves but strictly speaking, examples don’t belong into a reference documentation.
cc: @Confectrician

12

No, binding contributors are asked to provide examples for textual configuration in the readme. In some cases it is missing as it is not recommended for a particular binding to use textual config cause of complexity.

13

Comment; might be worth everyone reviewing official generic docs

and

which have not changed much from OH2

1 Like
14

I stand corrected. Kudos to whoever added it late.

Well I remember the days it didn’t exist so yes it HAS changed much :slight_smile:

15

The documentation would be the one listed above under “Documentation”: https://openhab.org/docs

btw: no need to tag a binding maintainer as this just was an example on how you are left with in general, if you’re kinda new to openHAB and tried to understand the documentation.

16

and that’s what I pointed out in my 2cents: the documentation refers to files configuration only. OH2’s PaperUI was and OH3’s GUI configuration is completely omitted from the docs, which makes it harder for newcomers to understand in my opinion.
and as I said, I have no clue on how to solve this - because without any file-documentation those, who configure OH3 with files won’t have a chance to continue doing so - and without UI-based explanations, especially entry-level users will have a hard time figuring out, what the heck is going on… at least, that’s what I think.

17

They don’t.

For some bindings, a restart of the binding and/or OH itself is required to pick up changes to .things files.

Yep, and if you want to change it you have to change it in the .things file if that’s where it’s defined. It’s either or, not both. You can’t modify a Thing in the UI that’s defined in a .things file and you cannot modify a Thing in a .things file that’s defined in the UI.

In part that’s because the UI is able to be more self documenting. You don’t need to know each and every possible property on an MQTT Channel, they are all just presented to you with a brief description of each field in the UI.

KNX and modbus are to exceptions. Because of their complexity, I believe the general recommendation is to avoid the UI for these bindings.

But ultimately, the focus, detail, and approach each binding author takes to document their individual binding is up to them. Some choose to only show .things syntax while others choose only to show UI and still others show both.

I think the best that can be done is to file issues and submit improvements to the add-on docs where a deficiency is found.

That is to some extent legacy. But there is a rewrite of the way the rules are presented which will not favor any rules language over others.

To the best of my knowledge, there’s no generic explanation of things and items syntax as it has not been recommended to use that ever since OH2 came out.

It’s there. But for Things in particular, knowing the generic syntax is only part of the problem. The user also needs to know all the properties and valid values supported by the binding and not all binding authors provide everything needed in their docs.

The Items reference is pretty complete though, really only lacking a good section on metadata.

But defining them in the UI is not even addressed in the reference docs yet and I think that can lead to confusion.

I think it’s important to understand what the different sections of the documentation are for.

  • Concepts: intended to provide definitions and explanations for core openHAB concepts
  • Getting Started: to show how to implement a config, demonstrate the core openHAB concepts and show how they all work together
  • Configuration Guide: these are reference docs; these need to be used like you’d use a dictionary or an encyclopedia. You look stuff up in them, not read them from beginning to end.
  • Add-on docs: should provide everything you need to know to install, configure and use the add-on.

So yes, of course the Configuration Guide is always going to be text config heavy. You don’t need as much reference material in the UI since it’s mostly self apparent. But much of that reference material is going to be the same. Rules DSL syntax is mostly the same whether it’s in the UI or in .rules files. Things and Items syntax is mostly irrelevant in the UI. MainUI Widgets syntax is not well supported in text files at all.

But that doesn’t mean improvements are not welcome and needed. A complete overhaul of the rules is in work. This will include a rewrite of the Actions. All examples include Rules DSL, Jython, JS Scripting, and JRuby. I’m still thinking about how to do Blockly. See Rework Rules Documentation · Issue #1855 · openhab/openhab-docs · GitHub if you want to pitch in and help.

18

honestly, I think it’s a personal decission, which fit’s best for you and which one you prefer.
As mentioned multiple times, mixing it is propably not the best idea, except some rare cases.
And as also mentioned, some Addons do not provide textual examples, so you are on your own to create it and that will take a while to figure out or find anything on the net…

Personally, I totally like the textual definition, as it’s pretty easy to share some of your stuff with anybody…
Even for finding any kind of errors is more easy to reproduce / test…
Just copy’n’paste the things, items, rules and your sitemap, that’s it.
Same like the components for the ‘new’ UI…

19

Thank you so much for all your comments and explanations.

I am starting to get my head arround things and believe that my missing part is not necessarily within OH but more related to the binding documentation and the discovery side of things.

Let me explain where my confusion actually started:

I have a homematic bridge connected to a Raspimatic → That works absoutely fine.

To my CCU I connected a HM-WS550STH-I which provides temperatur and humidity informations.

Autodiscovery pickt that sensor up and successfully created a thing in OH, but only with a channel for the temperature and humidity is missing.

My assumption was that there must be a way to manually configure that missing channel.

I tried to understand how I might add channels to that thing using the code tab within the Things-Administration and got more and more confused.

So my learning out of all your great comments. My understanding of how “things” work together in OH is right and if I want to stick to the GUI configuration an need to talk to the binding maintainer and let him know that there is a defincy which might be addressed in the future.