openHAB 4.0 Milestone discussion

Setup, Configuration and Use News & Important Changes
409

This isn’t specific to 4.0 milestones, but the migration to a new major version makes this a perfect time to ask.

I am an ancient user dating back to v1.x. I got into making my own text-based config files (.things, .items, .rules, .sitemap, and even adding bindings through addons.cfg). I found this an easy way to add and edit things. You don’t have to click through 7 different layers of a web interface to change the name of a item, e.g. And I also love that I can backup a half dozen text files, nuke my entire build, and restart from scratch in case I mess up any settings.

So, my basic question is, are these text files now “disfavored” in v4.x or considered legacy or being phased out? I’m just not sure on the status of them. The tutorials, even pages like “Adding Things - Advanced,” all instruct users to use the web interface to add items and things and bindings. But I’ve always found this in tension with the add-ons documentation, which to this day still seems to include text config examples for each binding. (There are only about two bridge-based bindings I use that I cannot figure out without working through the web interface.)

If I am holding on to an outdated and soon-to-be discontinued relic, I will make the shift to whatever the current state of the art is when I move to v4.x. Likewise, if someone tells me I’m missing some useful functionality by being stodgy, I’ll make that shift. Otherwise, I’m pretty happy with the way text files have treated me. I was even playing around with the milestone build and trying to edit the .json files (e.g., org.openhab.core.items.Item.json). Not only could I see these files getting unwieldy with all the brackets and multi-line items, but OH does not seem to update until I restart OH. With the text files, I get instant updates upon saving the file.

Once I sort this out, I will also need to figure out if I really need to update all my rules from whatever ancient coding language I’m still using in my .rules files.

1 Like
410

Config files will not be discontinued in OH4 and we are a lot to hope they will mever be discontinued at all.
There are pro UI and there are pro files.
One chance is that there are probably more fans of config file than UI in OH maintainers.
That being said, it is not impossible that one day the text file format is changed but not in OH4. When it will happen, you can expect a convert tool.

7 Likes
411

Both JS Scripting and jRuby have excellent documentation in the add-on readmes with full reference docs and lots of examples and explanations. The docs are really quite good for these two.

Everything you need to get started is there or linked to from there.

For JS Scripting, a good learning strategy is also to build something in Blockly and look at the code it generates. In OH 4 Blockly “compiles” to GraalVM JS Scripting.

There is a little bit of JS Scripting on Rules - Advanced | openHAB.

Groovy uses the raw JS223 API and doesn’t have a library so JSR223 Scripting | openHAB is going to be your reference.

No.

But most MainUI stuff will not have a text file config equivalent (pages, custom widgets, rule templates, etc.).

If you are doing that you haven’t reviewed the Getting Started Docs. Any entity in OH (Items, Rules, Things) are searchable and navigable from the developer sidebar (alt-shift-d). Minimal clicking through is required.

Can do the same with managed stuff, it’s just a different set of text files.

That’s because, for most users in most cases, auto discovering the Things and using “create equipment from thing” in the UI is more straight forward and faster than defining them in text files and struggling to get the syntax right. You don’t need to do anything to define the Thing except accept it and you can create all the Items linked to the Channels of that thing and have them situated in the semantic model in one go.

All Things can be defined through .things files. I don’t know which two bindings you are referring to but in all likelihood it’s just that the binding authors didn’t document the text file based parameters.

But, there are some things that cannot be done with text file based things. The big example I’m aware of is setting properties on devices in the Zwave binding.

There is no tension though. Except in rare cases where discovery isn’t possible, almost all Things are discoverable and generated automatically for you. But to continue to support those who remain on text based configs, many binding authors also document how to define Things in .things files too. But when using discovery the steps are:

  1. manually create the Bridge (if required)
  2. scan for new devices in the Inbox
  3. Accept those Things you want to include in OH

First, if your only experience with UI is PaperUI, you know nothing about what MainUI is capable of. It’s so much better they are not even in the same league.

Many of the maintainers and a large number of your fellow old timers (been using OH since 1.5) have moved to UI everything with OH 3 (and as stuff like transformations and hopefully soon persistence is available in the UI in Oh 4 I’ll have everything but ephemeris configured through the UI). At the risk of speaking for others, we would not have the patience to configure our OH if it took clicking through 7 UI pages to change something simple. There are limitations of course, but it’s not that bad of an environment to work in. I certainly wouldn’t have the patience for it if it were.

Some of the things you might be giving up with text based configs:

  • some stuff will be UI only (e.g. custom MainUI Widgets, setting properties on Zwave devices, etc.), no one is volunteering to invent a text file based representation for these or there are technical limitations
  • rule templates (why code a rule when you can just install and configure it?)
  • Blockly
  • ability to see and modify your config from any client (phone apps, browser) from anywhere (through myopenhab.org)
  • much easier to set up and work with the semantic model
  • much easier to define custom default widget Item metadata
  • mostly self documenting
  • almost never have to fight syntax errors (except in rules and transformations of course, though with Blockly not even in then)
  • no third party editor required (and there is intellisense and code completion in the editor for rules code)
  • Marketplace add-ons can only be installed through the UI I think, you’d have to download and drop the jar files into the addons folder instead of installing them like any other add-on.

One does not manually edit the JSONDB files. At least not in the same ways you’d edit .items files (etc.). That’s not their purpose and that’s not the most efficient way to do it anyway. To change things you’ll do it through the Karaf console, REST API, or the UI.

Note, as you’ve found, they are only loaded when OH first starts. And if you edit it and then modify something through the UI your changes will be overwritten.

Note on changing the names of Items. This does not happen. The Item name is the UUID of the Item. When using .items files what happens is all the Items defined in that file are destroyed on unload and created anew on reload. You’ve not changed the Item name, you’ve created a new Item with a new name.

So to rename an Item in the UI you have to do the same thing. You have to delete the old Item and then recreate a new one with the new name.

In both cases, rules, ui widgets, and persistence knows nothing of the new Item and need to be updated.

But, you’d find in the UI that the Item label is what gets shown and used almost everywhere. It’s only in rules and UI widgets where you hard code the name of an Item where the name really matters. So the need to rename Items is no where near as vital as it is in text based files. And even then, it’s not something that needs to happen frequently.

You don’t have to but if you are creating new rules it’s probably worth looking at the new options. They are more complete (I still think that Rules DSL cannot access Item metadata) and support a full programming environment so you can have libraries, functions, etc.

5 Likes
412

So it will be huge problem for probably hundreds of OH users. Most users are not programmers. For me Jython rules are simple to read and adopt to my needs. But with other java languages (or others) there may be a problem.

413

Just out of curiosity, which bindings?

414

Nest (I cannot seem to get the authorization codes to stick after reboot through the text files).
I think I had a problem with the MyQ binding when it was in beta, but I guess that’s been sorted out now. So maybe it’s just the 1 binding I have an issue with.

415

:person_shrugging: It’s not like we want this to happen. It’s out of our control when/if it does happen. There’s nothing I personally can do about it except to warn people not to depend on Jython expecting it’s going to be there forever. Of all the parts of OH, it is the most at danger of just up and quitting on us.

It’s been more than five years. That’s a pretty good run. But nothing lasts forever.

And even if we had a replacement, that replacement is going to be very different. It’ll be Python 3 and it’ll likely be built on a new helper library so all your OH interactions will be different anyway.

But I’ll say again, if you like Python, there is already excellent support for Python based rules in HABApp.

I can say that jRuby and JS Scripting are equally and in some ways even simpler than Jython.

And if you are not a programmer Blockly is excellent because it’s all done with visual building blocks.

And don’t forget almost everything your rules do is interact with openHAB. All of those interactions use the same concepts and approaches. It’s not like trying to translate Mandarin into Swahili. It’s more like trying to translate Spanish into Portuguese. The words and syntax will be different for sure but over all you’ve already figured out the logic and there will be lots of similarities.

416

This works for me:

Bridge nest:wwn_account:account [ productId="xxx", productSecret="yyy", accessToken="zzz" ] {
    wwn_smoke_detector hallway_smoke    "Nest Protect hallway"     [ deviceId="aaa" ]
    wwn_smoke_detector familyroom_smoke "Nest Protect family room" [ deviceId="bbb" ]
}
417

I don’t mind using UI for aspects that are not covered in the text files I already know. So I do use the web interface (I think it’s MainUI) for certain things. Just not for my bindings, things, items, rules, or sitemaps.

You’re right, I wasn’t familiar with the sidebar. It’s a nice option, though still requires a bunch of extra clicking that I don’t have to do in a text file that’s sitting open on my desktop. I’m sure it’s not as bad as I made it sound, but I don’t like to learn new things (<-- a lie).

I guess the problem is it’s not as obvious or documented which those are. I presume they are the .json files in the userdata/jsondb folder?

With the text files, I know which files I edit. So I know which ones I need to back up to save what I’ve edited. If I edit something in the UI, I have to trust that I’ve picked the right file storing that something.

418

Yes I know it is not your fault and nobody wants it to happen :slight_smile:
But as I said hundreds of people learned how to use Jython. Blockly is a joke for me. Not so intuitive as it should be and possibilities it gives are really limited like GUI rules. And rules are esentail for good home automation.
Maybe it would be good idea to start a thread with examples how to “translate” Jython to other java languages?

419

Yes, that’s it. Though if you want your addons.cfg backed up too you’ll want to grab the userdata/config folder. But really, if you want to backup your config, you should be using the backup scripts that come with openHAB or openhab-cli if it’s on Linux.

First, backups are taken of the JSONDB files automatically on every change. You can set how many backups are saved under Settings → JSON Storage and you will find them under userdata/jsondb/backup.

So you don’t have to pick the right file or even worry over much about it if that’s all you are after.

But there are other tools available also including rsync, git, svn, etc. to handle version control automatically or semi-automatically. You shouldn’t be relying on your memory for this in the first place.

You can also just look at the timestamp on the files.

Maybe it depends on when you looked but a lot of work has been on on Blockly in the past couple of releases. There is almost nothing left OH wise that can be done in Jython (for example) that cannot be done in Blockly.

3 Likes
420

I use SDM, and it does not work right through the text config. The working json file created through the UI has blank pubsubAuthorizationCode and sdmAuthorizationCode. When I try to create a thing in a text file with the same blanks, it gives an offline error and demands an authorization code. When I go through the process to get authorization codes and enter them, it works until I reboot and then stops again. There’s some voodoo that the UI does that I don’t know how to overcome. :man_shrugging:

421

The authorization code is usually used to acquire the first auth-token and refresh-token. It should be thrown away after that. Once it’s working, try removing the authorization code from the Thing before restarting.

1 Like
422

Just one example, but they do exist: File: Rule Conversions — openHAB JRuby

423

Well what do you know, this seems to have worked! Thanks!

424

Hello,

I put this into my openhab folder

rule "My Scene"
when
then
 switch_mobilemichael_presence.sendCommand(OFF)
end

But in the log an error is recorded

Configuration model 'scenes.rules' has errors, therefore ignoring it: [3,1]: no viable alternative at input 'then'
425

The rule DSL parser does not expect then right after when: you forgot to add the when clause which triggers rule execution. Otherwise openHAB has no clue on when this rule should run.

426

Nope, I am afraid, DSL rules do not support scenes, which do not require a trigger (when clause).

427

So what does it mean for the scene configuration in a file?

428

AFAIK, it is not possible.