Next generation design: A Paper UI replacement proposal

(David Graeff) #101


Clearly not. See MQTT 2.4 documentation as example why the current syntax is confusing and crap.

And there is really a long heated discussion on textual files that resulted in this design study and I feel personally a little offended by you, that you do no take the time to read this thread (click on “summarize” and you get the picture already) and suggest to use the old syntax instead.

I thought about adding a tab to the item in grid mode. But I don’t really know how to present meta-data and what it is used for. Semantic tagging is done per meta-data isn’t it?


(Scott Rushworth) #102

There is a way to use global variables. Jython 2.7.0 definitely works with global variables. In finding a fix for Jython 2.7.1, I learned more about scriptExtensions, which can be used by any language and can be used for global variables. They basically put objects into a shared context accessible by all script engines (all scripts have their own).

As I’ve mentioned elsewhere, I also have Jython and Groovy working for scripted Actions. I will submit a PR once ESH is remigrated, and workup an example for using scriptExtensions.

Metadata is the next best thing! For example, I have metadata in most of my light Items with values for a lux level and brightness setting for each Mode (what I use for TimeOfDay, since I have Party, Vacation, etc.). When the outside lux changes, I have a rule that adjusts the lights according to the metadata for each Item in an active area of the house. I have another rule to detect activity in an area, which turns on/off the lights to values based on the metadata. Previously, this data needed to be stored in Items or in some other object in a rule script. I could add listener’s too, to watch for changes in metadata, but haven’t had the need.

For UI layout, it would be a tree for each Item, with Keys at the root, and branches of name value pairs. The data should be editable, but not sure the best way to design the UI for it.

    |_ Low_Lux_Trigger: 5
    |_ Level: 100
    |_ Low_Lux_Trigger: 90
    |_ Level: 50        
    |_ Low_Lux_Trigger: 30
    |_ Level: 50
    |_ Low_Lux_Trigger: 30
    |_ Level: 10 
    |_ Low_Lux_Trigger: 30
    |_ Level: 1
    |_ Low_Lux_Trigger: 5
    |_ Level: 100

Metadata essentially provides additional data points, beyond e.g. an Item’s state. Here is a writeup that I did…

Eventually, I will get a post about how to setup Area Triggers and Actions, and the rules I use. Once I get the PR out, I’ll distribute them as rule templates! Although, I have DSL versions too.

Semantic tagging uses tags, and also uses metadata for synonyms.

(David Graeff) #103

I had a look at the REST API and I’m not happy with the design. I cannot request a list of metadata namespaces. I can only query metadata if I know the namespace beforehand.

So I can’t really integrate that into the UI yet. The core must change first and allow querying for namespaces.

(Normann P Nielsen) #104

Please have a look at how I see this solved. Every thing/item/rule/timer has a “storage association” (aka filename). The backup service will consider those for exporting to several storage units (aka files).

Every thing/item/rule/timer has a list, grid and textual view mode. The latter one allows find/replace, batch editing. For the format I have settled on YAML for now. Please have a look and tell me if you like that syntax. Maybe there is a better suited format that I have not yet considered.

I love the “storage association” concept, I know it from other products, and its very flexible for automation, backup and the choice between UI editing and good old “vi” :slight_smile:

But I do hate YAML so much, but I can see that it is gaining a lot of land being implemented in many, many products. Personally I do swear much more to JSON, even though I dont admit its harder to read in an editor, but its ensy to handle, simple and well known and supported in all programming languages and tools and REST interfaces.

(David Graeff) #105

It is one single line of code (maybe two) to be changed in Paper UI NG to see the original json instead of YAML. I can imagine that being an option in the future.

(David Graeff) #106

Friday weekly progress update

I’m writing this now, as I don’t have much time tomorrow.

  • Can connect to a real openHAB instance now. If you use the hosted version in the link, your openHAB must be served via https though. (Use nginx as proxy for example on openhabian).
  • Login page, including “demo” data-set for experimenting.
  • Proper about page with open-source attributions (legally required, I think).

Things/Items page:

  • Added/Changed sorting options for items/things. They are also propagated to the local database already, but I haven’t decided yet what to do next.
  • Add item -> Although I wanted to avoid dialogs, I think it fits here
  • You can send item commands to your openHAB instance, yeah. But that’s it already for OH interactivity.
  • Shortcut for list/grid/textual mode (Alt+l, Alt+g, Alt+t in Chrome). The modifier key depends on the browser and platform. MacOS uses the command key instead for example.


  • Nice animation while performing a manual discovery


  • Persistence page added


  • Configuration pages are completely rendered from dynamic data now


  • I have started to document the project

Help required

Please help with …

  • proof reading all context help texts,
  • and writing the tutorial pages. We need some nice diagrams, videos, pictures and of course text to introduce newbies to the interface and openHAB in general. The text should be concise still, no complete novels :slight_smile:

If you know html+css: Please help designing the timer-task page. See Next generation design: Paper UI design study


  • Item meta-tags are missing in this design study, that need to be tackled.
  • Need to think about embedded scripts in rules.

This weeks release is uploaded and live on Friday 6pm GMT+1 as usual.

Cheers, David

(Rich Koshak) #107

Well, I’m out. :wink:

I’ll have a look and play and see what we can do. Probably won’t be until this weekend or next week. Should this be captured in the README.MD file? Or should we start a separate thread and put it into the docs directly? I’m not sure what makes the most sense. @Confectrician, do you have an opinion? Where does existing (and very thin) PaperUI docs come from?

I take this to mean if I check it out and run it from the html/static directory it will connect to my running OH? Awesome!

But OH is already served on HTTPS on port 8443. Do I need to set up nginx to support a LetsEncrypt cert or something else? Or will it work on port 8443?

Well, I got it to run on my OH install following the instructions on github but it doesn’t appear to be connected to my instance of OH. Is there a setting somewhere or am I jumping the gun?

(David Graeff) #108


Locally it just works. I’m talking about the “hosted” instance of paper UI NG. It is served via Https from github and mixed content protection of modern browsers prevent to connect to oh, running somewhere locally on http only.

(Jerome Luckenbach) #109

The other ui duics are managed in the openhab-docs repo currently so with the current structure Thread + direct contribution would be a valid approach.

Anyway i am not sure if this is the best approach for the future.
We are maintaining all addons docs within the addons folders to get them updated parallel to pull requests.
For me there is no valid reason to handle this different after reintegrating esh.
We now have the situation that all ui bundles are maintianed in the openhab2-addons repo.

(David Graeff) #110

Which I think is wrong because of the different technology stacks and different product cycles and different teams working on the repos, but Kai likes it this way.

(Rich Koshak) #111

That is why I asked. It makes a lot of sense to me to treat these docs the same as other add-ons. I also like to have the docs and the code together so that updates to the docs can be part of the same PR and merge as the code changes.

I’ll start a new thread and make them wikis to get something on paper. Where they go will just be a matter of where it all get’s copied to. It may be a bit. This hopefully will be a one pager. I want to play with it a bit more deliberately though before I start something though.

(Jerome Luckenbach) #112

That’s a valid point, but doesn’t affect my statement.
Even if it would be maintained in a different ui repo, i would prefer keeping the docs beneath the code for a better maintainability.

I think this will be the best for now. :slight_smile:

(B K) #113

I created some diagrams and slides for the openHAB Basics videos I’ve been making on my YT channel. I was planning to share the slides one way or another after I got through the last topic in the series (Rules), likely by creating separate topics for each section here on the forums. Here is an example slide, showing the overall “model” of OH2 components in SVG format.


If this could be useful to the next gen GUI documentation, I can put that task of sharing higher on my priority list…

(Rich Koshak) #114

:smiley: I once drew something very much like this only it was a bit more comprehensive (and incorrect in a couple of places). It was also way back during OH 1.x. But it is interesting to see how different people draw the same concepts. I wish I could find it again. Lets talk about OH 2 Drawings . Scroll down and you will see a version that looks very similar to yours.

I did make this different layered view at some point too, I can’t remember why:

It is obviously missing the concept of a Bridge. I think I made it before that was commonly used.

One thing to note, if you want to make drawings for use in the docs, it was decided way back when that is the tool to use which will provide the raw editable files so others can edit it later.

I think a drawing like that could be helpful in the Concepts section of the docs. I don’t think it belongs in the PaperUI NG docs. Those should strictly “how to use” the UI and not cover the whole OH architecture. At least that’s my opinion.

PaperUI-NG / Beginner's Tutorial
(David Graeff) #115

Yes that looks like a good overview.
I have found a graphic once that I included as a placeholder on

That is what I’m aiming for. The texts should end up in the Paper UI NG repository. Either as markdown, processed during the build, or straight as html, like I’m doing that at the moment.

(Rich Koshak) #116

Do you envision the docs for this becoming a generic OH tutorial (using PaperUI-NG of course)? That opens the scope quite a bit but I like the idea of the docs and the embedded tutorial in the UI being the same.

(David Graeff) #117

I expect a person who installs OH for the first time not to read our website documentations first, except the “Install” part maybe.

That persons first contact will be the website interface (I have named it Setup & Maintenance) instead. I see the responsibility on that interface to teach the user the core concepts of OH and where to find those concepts within the interface.

After he/she has finished the tutorial, the person needs to know that he/she wants to install “bindings” to configure “things” and, if necessary, create “channels” which need to be “linked”.

(Rich Koshak) #118

OK, so the docs we are really after is the Beginners Tutorial (improved and completed) using PaperUI-NG as the interface.

I’m going to open a new thread now and explain the scope. PaperUI-NG / Beginner's Tutorial

Everyone who is willing and able, please join in!

(Andrew Rowe) #119

Yes… perfect template for openHAB3 new user documentation!

(Rich Koshak) #120

OK folks. The work that is presented here is awesome and it really helps to show what is possible. However, it is a bit premature. Before this or any other proposed replacement for PaperUI or any other major part of OH is to take place, it will need to be discussed and approved by the yet to be established Architecture Council (hopefully very soon, once the snapshots are working again).

This approach is one potential approach and it is exciting to see where it can go and what is possible. But isn’t the only approach nor the only prototype.

I don’t want to stop the work but I do want to help direct the discussion a little bit from “this is what WILL replace PaperUI-NG” to “something like this COULD replace PaperUI-NG”.

Stay tuned for the Architectural Council process announcement which I think will bring some more context and direction to the discussions.