Next generation design: A Paper UI replacement proposal

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.

1 Like

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.

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.


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:

1 Like

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…


: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.

1 Like

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.

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.

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”.


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!

Yes… perfect template for openHAB3 new user documentation!

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.




It sounds like you want to stop people from contributing good ideas and waiting for the AC, although I think that all texts, images, tutorials made for this design study are re-usable for every other future prototype. I mean that’s the entire purpose of this design study, I guess.


1 Like

Not at all, but lots of users are responding with the apparent assumption that what is presented here is what will happen. I just want to inject a little context. It’s a proposal of what could be. Not a fait accompli. Some or all of these ideas will likely become incorporated into the next version of PaperUI. But there are other ideas out there too and the process for how the ideas will be adopted is not yet defined.

What is presented here is great and I did say I don’t want to stop the work, but there are certain aspects like config file formats, Rules builder approach, etc that have a huge impact on the future direction of OH and needs to be adjudicated by the AC. There are other developers who have done some work in this area that are not part of the discussion as well (e.g. Yannick has already built a prototype Rule’s editor for the NGRE).

Perhaps unless someone comes up with something radically different that the AC agrees to. I’m aware that there is another prototype that exists that is not being discussed right now. As a for instance, I’m already looking to have to rewrite about 30% of my existing NGRE docs to meet this GUI. I’m looking at about the same amount of work to meed Yannick’s Rule builder too.

And starting to build the docs at this point generates the impression that what is presented is what will happen. And we don’t know that yet.

Finally, Kai did ask us to hold off on some of these discussions until the AC is a little more defined so we don’t rile up the users like happened on the config file threads. My comment above is in part to respect that request as well.


At long last… This was really necessary.

Wrong thread ^^

True ^-^

I tried the design study, but it failed on firefox (65.0, 64bit) Finally got a glimpse of the future (very promising!) when changing to Chrome :slight_smile:

Oha, thanks. I usually check Firefox as well, but I missed a recent change.

I’m currently thinking about the rule editing. It’s not an easy task.

Editing is already possible, as seen in the picture, but how to present the three categories best?

Maybe having a three column design, or a tinted background behind triggers/conditions/actions respectively.
Or something like a frame, like here:

1 Like

There is a lot I don’t like about IFTTT, but their recipe builder is kind of nice. Break it up into a sort of wizard flow maybe for the initial creation.

Yannick’s prototype uses a top to bottom arrangement with color coding and a more “yahoo pipes/Node Red” arrangement of elements. So all the triggers go at the top. Then all the conditions, then all the actions at the bottom. Each section is denoted by a different color and sometimes shape.

Speaking of NodeRed, they have a little more free form (I don’t know if Yannick’s is presented top to bottom of constrained to top to bottom).

In both cases I don’t know if I like the need to double click to drill down into each node for the properties. I like the way the parameters are presented right at the top level here, though users will quickly run out of space if they have more than two of any one type.

I don’t know if it needs a frame if you have some other way to show like types. Rules pretty much flow on one direction so position on the graph could do it. Color can do it. Shape can do it. Any combination of the three could do it.

One thing that would be nice though is to have a special shape or color for the “run another rule” action. In that case clicking/double clicking could take you to that other rule. Double clicking a Script Action or Script Condition should open the code editor.

The lines are visually instructive but I’m not sure they are strictly needed. The triggers are going to pass to the conditions and finally the actions. Unless there are constructs in the NGRE JSON Rules I don’t know about that’s all that is allowed.

I’ve spent some time with the current PaperUI UI for this so I don’t really know the full of what’s possible with these Rules.

1 Like