Setup & Maintenance: A Paper UI replacement proposal

Hello community,

in this post I’m going to introduce a functional* design study for a next generation Paper UI.

*functional: Some data is provided by a fake backend as the corresponding services are not yet in openhab core.

Important: This is a design study and not set in stone. Your feedback and contribution is key for a better OH maintenance app.

I’d like to say a few words on some key aspects.

Design / Usability

  • You can switch between a bright and dark theme on the maintenance page
  • Change from 3-column to wide mode via the header-bar icon on the right.
  • All (code) text editors have syntax highlighting and validation.

A UI for Rules and for Timers. Timers are unfortunately not yet done, I need your help with a proper design to express even the most complex recurring cron timer expression.

Newby friendly

  • A tutorial in Paper UI NG is key to make a new user become familiar with core OH concepts and were to find those within the app.

  • Context help on every single page. Inline explanation texts were necessary.

  • Self-contained. I don’t want to take any files away from you, but OH should also be configurable completely without ever seeing a single configuration or log file.

  • Templates/Snippets for Scripts: A blank editor is not helpful at all. Templates/Starters will help make the user familiar with the syntax. Templates/Snippets can be fetched from anywhere, we could setup a github repository for example. At the moment I provide one basic template.


A big concern at the moment is that we have a dual system of configuration. You either use the UI or files. And you cannot change to the other option without a massive time investment.

Please have a look at how I see this solved.

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.

Find known binding/service problems more easily

  • Binding / Service configuration pages show all open github Issues and Pull requests. This way a user can easily see if a problem he/she is experiencing is already known.
  • A troubleshoot section is shown in the context help, as long as the binding provides a “” file in the source code repository (yeah I know: not a single binding is doing this yet).
  • A changelog page and links to it in some places make users aware of breaking changes.

Where do I find it

Without further ado, please have a look:

You start with demo data. Click on the login link in the bottom right corner and
enter the address of your openHAB installation for example “”.

If you want to use this interface from the website directly, you must enable CORS ( Cross-Origin Resource Sharing ) feature in your {openhab-dir}/etc/smarthome.cfg file.



The demo looks really great! Thank you.
Not sure if I am getting it correctly, but I cannot login with my local OH2 installation “” (connection refused) and when I then try to login back into the demo version by entering “demo”, the systems complains with an error that my input does not have the required format. Restarting my browser helps re-establishing the connection to the demo version.

I forgot to add that you need to enable the CORS feature in your {openhab-dir}/etc/smarthome.cfg file, true.

Sorry for my ignorance, but shouldn’t it be /runtime/services.cfg?
At least an entry
gives me this in the logs:
2019-04-16 22:00:57.926 [INFO ] [] - enabled CORS for REST API.

Actually the file doesn’t matter, because the options namespace is fully qualified ^^

EDIT: this was a user error erroneously reported. The PaperUI replacement runs w/ 2.5M1 once the service.cfg with the additional entry is actually saved :crazy_face:

Thanks David, still not sure what I am doing wrong.
added org.eclipse.smarthome.cors:enable=true to my services.cfg and restarted OH2
Now the error changed to “failed to fetch”
I am running OH2 2.5 Milestone 1 edition on a VM (Virtualbox) w/ Ubuntu 18.04
My log is showing jetty errors:

2019-04-17 20:18:50.434 [ERROR] [ersey.server.ServerRuntime$Responder] - An I/O error has occurred while writing a response message entity to the container output stream.
Caused by:
Caused by: Connection reset by peer
Caused by: Broken pipe

The caused by statements appear in various combinations seemingly. Can post full error log if that were to be helpful.

Looks like the current CORS part is not well maintained :confused:

Personally I do not run into this problem, because I’m using nginx as reverse proxy,
configured by openHabian (with a little patch that is not yet merged into the openHabian repo), which handles CORS for me.

I also have replaced the entire subsystem and updated jetty from a 2014 version to a 2019 version in core in a recent pull request, as the old (or should I say current) way is quite fragile:

So I guess openHAB core is not yet ready for my Paper UI replacement (at least if you use it from the website directly) :confused:

1 Like

Thanks, appreciate the explanation. I do not have the knowledge necessary to apply all the patches and updates that you are using. Here is to hoping that your PRs will make it through the system soon.

You have been enticingly forward thinking and I would love the opportunity to further learn about your visions. I am saying this even so my current comfort level are text files for configuration :wink:, but, hey, I may be convinced otherwise; I am sure there are many ways that are better than what we currently have, albeit by necessity they will be different and require users to change and learn new things. But then again, we are not using rotary phones anymore either…

1 Like

@David_Graeff just an update, it connects w/o problems once CORS is activated (2.5M1 no other mods are seemingly needed); forgot to save the modified service.cfg …very embarrassing…:flushed:

Thanks much again…played around a little…this is really great work and may just be the thing that weans me off text file configs…

I have implemented all required services for openHAB core this week to make the logging page and maintenance page operate on real data.

Let’s see how quickly I can pass the maintainer reviews.