Best practices in creating an UI for beginners?

Setup, Configuration and Use Beginners
1

Being new to Openhab I found the UI part extremely difficult. I created things, channels and semantic model for about a day or two (most time spent on reading docs). But I wasted almost 3 weeks trying to display whatever I’ve created in some reasonable manner… and failed. I’m probably doing something wrong, it shouldn’t be so complicated. My initial understanding was I install appropriate widget from the marketplace, point it to the thing – and voila – the info is displayed. But it did not work this way. Not for me at least. Or it works to some extent but looks ugly and misaligned. Moon age displayed in seconds and all that. My stumbling stones are:

  • OH5 seems to significantly change the way the UI is supposed to be created. However, maybe 90% of found information relates to older versions without any deprecation notes. Lots of howtos on text-based configuration, very few consider MainUI as a base. Yes, the system is developing and a lot of information gets obsolete (By “obsolete” I understand not only “not valid anymore” but also “a better way to do this is developed and ready to use”). But I saw only one deprecation note so far. As a result I spent few days trying to comprehend things before I realized they are not actual anymore. I understand the reason why the devs don’t deprecate the stuff that is left behind when the new and better options arise (not to break the existing installations). People who have been using OH since v.2 (or earlier) and have grown with it understand the structure and where to look, but for the beginner there is no way to reliably sort things out. Please add deprecation notes!
  • Lots of different ways to do something, but not all were created equal. For example, I spent a lot of time creating items from the thing’s channels (lots of clicks wasted)… just to realize that what I’ve created does not fit well into the model. I understood I was doing something wrong, but I didn’t know what. The eventual gotcha was: if I use “Create Equipment from Thing” on the Model page, I need only tick the needed channels and they are created automagically! Ten times faster! Where was this info three days ago? When was it at all, I found this by accident. That’s where some “Best practices” articles will help.
  • I couldn’t find the source from which to gather structured information beyond the low-level manpage-style docs that would unveil the sense and rationale below low-level descriptions. And very little of semantics is explained. The docs is good, but it is rather man page-style (or oppositely, too common) and lacks of howto- or wiki-style (=semantic) part. In other words, details are useless unless you have the whole picture clear enough and get yourself familiar with notions used. Top level docs exist as well as the low level, but nothing in between.
  • OH docs and forum threads are using lots of notions that are not clear to the beginner. Now and then I simply can’t understand an answer or a recipe I found online because I either not familiar with notions used or just don’t understand where to find/put described thing. I get the common idea behind the answer but can’t translate it into something usable. It will come with practice, I know. What I’m trying to say is that the learning curve is steeper than it might be. Home Assistant is gathering its (undeserved?) popularity probably mainly because this part is thought over thoroughly.

What I tried to achieve and did not succeed. Until I have the hardware on hands, I decided to make something like a dashboard displaying the data I currently have, namely cameras, weather, astro. Not that complicated, right? Well, not really.

  • I tried to make some layouts, none of them look even close to being satisfactory, but ugly and misaligned. Widget I found for displaying the cam output (one that opens popup on click) doesn’t scale: too small (empty space around) on desktop, overlapping on a tablet. The Overview page wasn’t responsive for some reason: widgets just overlap, while I did it all straightforward: Add Row → Add Column → “+” → widget(s). Within Android app I got a mess, too, besides that no image/video from the cam is seen.
  • Cameras. Thread about IP cams is more than 3000(!) posts. I don’t feel this heroic to read all them thru. I did managed to get picture and alarms in hit-and-miss manner, but I still have questions. Thus, I’ll be asking things than most probably were answered many times before and buried among that 3000 posts. Not too effective, is it? What bugs me besides misaligned widget: jpegs don’t update when they should (I want them update slowly, maybe 1/10 sec and on motion alarm). I set up appropriate fields on the channel, but it does not seem to work. RTSP stream does not get through, while Chromium is able to show it directly. Okay, fine. Setting ffmpeg. Got about 1fps. Tuned the parameter to 10fps. Frequent fame drops while ffmpeg utilizes only ~5% CPU. What’s happening? No idea. Postponed this until I set up the SoC it will run on, then will try to solve this.
  • Sun and Moon astro. There are two widgets for that. Good. The display is ugly: too small font, some strange point outside the widget to the left. And, there are dozens of channels out there. Will I have to spending days setting them all manually in the widget? Can’t it just inhere the channels set up in the model automatically? I have a strong feeling I’m doing something terribly wrong.
  • I want to have nice looking dashboard eventually. Overview page on a demo and auto-generated pages look… well… not so fancy and useful. Adding background images will help to some extent, but I still want something different. Howtos I found all based on HABpanel, which is old way to do things. I can see Responsive Layout Pages and Fixed Layout Pages common descriptions but no practical examples. When I tried Fixed Layout I found that widgets are jumping from their place if I touch them in edit mode and I again don’t understand the reason.
  • I feel that maybe SemanticHomeMenu is what I need but neither can make informed decision about it nor understand how to make use of it and what I will eventually get. Missing mid layer again. There is no semanticHomeMenu page type. How may I use it? Read through few threads on this… and understood nothing and again felt dumb. While this bindings-things-channels stuff gets clear rapidly, the UI part looks like relativistic theory to me…

Hope this discussion may be helpful to elaborate the missing part of the docs and make initial learning curve not as steep as it feels now. Thanks!

UPD: I’m talking about extending this page Showcase & How-tos | openHAB with more recent solutions.

2

First, did you review and use the Getting Started Tutorial? Getting Started is the user’s guide and the rest of the docs are the reference guide.

If yes, pointing out specific places where something is missing or unclear in that guide would be the most useful way to help improve the situation.

Note, my replies below are not intended to be RTFM. They are pointing out where I think what you are struggling with is covered in the docs to help identify where they need improvement.

First “Thing” and “Item” are terms of art with a specific meaning in OH. Do you really mean “point it to the thing”? If so indeed your understanding is incorrect. Widgets only display Items, never Things.

This should be covered in the concepts section of the docs: Concepts | openHAB (this is the first page but I’m referencing the whole section).

How to add a widget to a Layout Page is spread throughout getting started but it’s not covered as a specific topic. That could be one way to improve this.

At a high level, if you want to control how stuff resizes and flows on different sized screens you’d add some rows and columns. Then you click the black +icon on a row to add a widget, select from the list. Then click the widget’s black config icon to set the widget’s properties. Here is where you’d point the widgets at the Items.

Not really. There have been some additions and new features, but over all MainUI has largely remained the same in structure and overall use since OH 3.0.

But there’s not just “the” UI. Not counting the phone apps there are three UIs. You do need to be careful when reading off the forum that what you are reading is relevant to the UI you are using: sitemaps/BasicUI, HABPanel, or MainUI. These are completely separate and independent UIs.

Are you, for example, finding sitemap stuff and trying to apply that to MainUI? The different UIs are brought up in Getting Started at Pages - Introduction | openHAB. That’s not deprecated stuff. That’s a wholly different UI.

If it’s in the forum :person_shrugging: Who’s going to volunteer to read every post made and add deprecation notes? If someone wants to volunteer to do that we won’t stop them off course. But I’m not going to do it. There are hundreds of thousands of posts.

If it’s in the docs, it’s not deprecated. Anything that truly becomes deprecated will almost always generate warnings in the logs. A new “better” way does not necessarily deprecate the old way. “Better” is in the eye of the beholder.

Specifics here would help.

In Getting Started? Semantic Model | openHAB

This whole section describes this step-by-step. Did you miss it or misunderstand it? If the latter, specifics can help improve it.

We have many but more are always welcome. Take this as a call for more people to post more tutorials.

But there are many in the Tutorials and Solutions section of the forum already.

I know I’ve written many such over the years, but we can always use more. Justin just posted an excellent tutorial on best practices for developing custom widgets.

This is what Getting Started is for. It shows how to use OH. Everything else is the low level reference.

There’s a whole page on it in Getting Started. Semantic Model | openHAB.

If you want a really low level explanation see A Deep Dive into the Semantic Model.

I totally agree, and there are always at least one it two PRs open and being actively worked to address this at any given time. But we are also up front that this stuff is complicated, and it takes a lot of work.

They have the advantage of having a company backing them with paid developers. They can say “Hey! Joe Smith! Go implement X.”

We have to wait for a volunteer.

It depends. If you create a semantic model, everything that is in the semantic model will be visible and controllable from the Locations, Equipment, and Properties tabs of the Overview page. No additional work is necessary. Those just build themselves.

If you want a custom Page, that’s going to be a little more effort.

But if you don’t want to tackle that right away, Sitemaps are much easier to create. You could then use MainUI for admin only and use BasicUI for display. It’s less flexible and configurable but because of that it’s much easier to create.

Without specifics there isn’t a whole lot to recommended for help.

But the scale issue I can address. Click on each widget’s config icon and select “column options”. There you can set what percentage of the row that widget consumes for different screen widths. If there isn’t room, the next widget will start a new row.

This is covered here: Responsive Layout Pages | openHAB.

Did you read the IP Camera add-on docs? Or are you trying to display feeds straight from your cameras without the add-on?

The docs are always going to be the first place to look. If you still have problems or questions, a new post is preferred. As far as I’m concerned, no one should read everything. Make it clear you made at least some effort to find an answer, and if the answer is posted somewhere someone will post a link to that. If not someone will help.

Without specifics :person_shrugging: . Some bindings are harder to get working than others due to the technology involved. I’d put the IP Camera add-on near the top.

A lot of people use something like Frigate to manage the cameras. I think there’s a beta Frigate add-on on the marketplace.

But I’m successfully using RTSP so all I can say is it is possible to make it work. But there are lots of variables that can cause problems.
pay

It all depends on how the developer of the widget wrote it. All the custom widgets are community developed and offered. They are not created by nor maintained by the openHAB project. Consequently, their quality and complexity varies widely.

I don’t know this widget specifically so can’t comment. A lot of the time a user will create a widget so you can just provide items that follow a certain naming scheme, and you just need to provide the first part of the name. But other times you have to identify each Item individually.

Note, widgets know nothing about Things. They can’t see them nor can they interact with them. It’s all Item based. And all the relevant Items may not come from the same Thing. That’s by design and a very powerful feature of the OH architecture.

I haven’t looked at HABPanel in years so can’t address that. I also don’t know anything about the semantic home widgets except to say that, like the astro widget you found, are community developed and maintained.

This part I can help with. You install it from the marketplace. Add an instance of it to a Layout Page. Then configure the properties. Based on the little I do know about it, you’ll point it at an Equipment Item from the semantic model, and it will do the rest.

Once last thing I want to point out is on almost every page from MainUI you can open the developer sidebar. The fourth tab of that will have context sensitive step-by-step tutorials and links to the relevant parts of the docs.

If we have any way to make improvements though we need to know ,did you read Getting Started and misunderstood the relevant sections, or did you not read it? I ask because a lot of the stuff you bring up as not being in the docs are in fact there. I’m never going to claim they are perfect and can’t be improved, but they won’t help you if you don’t read them.

The tutorial is designed to be an end-to-end flow through configuring OH. Its purpose is to provide the middle level of the docs. If you read it and didn’t understand, please let’s get into specifics so we can generate actionable suggestions. If you didn’t read it, please do so and come back with any questions left unanswered.

I think that page is generated dynamically based on the number of reads of the post or some other criteria. I scanned through the first dozen it so and almost all of them are still relevant to OH 5. Even the ones that start with OH 3. I didn’t go into the details so there may be some minor details that might have changed. But over all, these things haven’t really changed. But it could be worth an issue to the openhab-docs repo to curate the list a little more to bring the more recent tutorials to the top of the list.

As for more up to date tutorials, all I can do is reiterate the call for volunteers to write them. Also for those who have written them to update them as necessary.

It’s all a community effort.

5 Likes
3

Sitemaps are really easy to use, work in both browser and mobile (with app).
Give it a go first.

1 Like
4

Be sure I did read the tutorial. With any complex topic I always try to RTFM first. As I understand now I did another mistake: I’ve read not only the tutorial, but also forum and some other sources all over the Internet. That’s where I messed things up, stuffing my brains with sometimes obsolete or inaccurate information. So I think I need to take a little time-out and start over: go through the docs for the second (third?) time. I will also pay attention to what I find unclear and keep you posted. Please suggest how can I do that in the most convenient way. One thing we already spotted: I was not the one who stumbled upon the Home Page notion.

As for specific parts missing. OH moves toward extension of semantics use (via semantic model and wider use of metadata). But this metadata and namespace stuff is not unveiled in details. I know Linux well and I understand what namespace is in the Linux kernel context. But when I tried to familiarize myself with ones in OH I got “Understood how the steam locomotive is set up, didn’t get where the horses are hidden” result. I feel that OH docs is often too common, concepts are more or less clear but how to practically use it are not. Maybe adding some examples will help with that. I realize that growing up with OH for years you cannot look at it from beginner’s point of view. That’s why I started this thread, not to complain.

I’m not a native English speaker so my wording may be inaccurate. I meant “point” not in the OH sense, but rather in a programming sense. Let’s call it a “link” not to interfere. (Heck, it interferes, too. Okay, let it be the “connection” or “reference”. Hope this words are not occupied yet). I also used “semantics” in its initial meaning, too, i.e. unrelated with OH’s semantic model few times. Potential source of further confuse. Side note: I understand that it’s too late to change something, but I want to point out that word “point” is overloaded with meanings which lowers its points as an unambiguous term. That’s my point of view. Is the point taken? :slight_smile: I’m not sure that “Endpoint” would reflect its meaning in OH context any better but at least it’s not so ambiguous. I also shamefully accept I still have difficulties to distinguish between Point and Item.

Sure. And please consider narrowing the options for the beginners. The OH usually states something like “this may be done by this, this and also that ways”. Being obviously true, it may add up to confusion. There is a table in the docs explaining difference between BasicUI, MainUI and HABPanel and when to use what but I feel it’s a little to short. Probably a special page on this would help. (BTW such kind of content may be easily generated with AI saving the dev’s time and efforts. Its output must be validated, of course, but it may speed up creating the docs drastically without to compromise the quality).

That’s what I did. I’m afraid I somehow broke my OH installation while initially playing with it and randomly add and remove stuff just to familiarize myself with the interface. There may be some surplus left not cleared properly. I cleaned the cache, but if it’s in the database, it may stay somehow. Stacking on top of it, the standard Gentoo openhab package sets root:root 755 on /etc/openhab while OH tries to write there. Running under openhab user it fails to write, which may have broken things, too. I fixed the permissions, but it might already happened. I think fresh install is a good idea under the circumstances, esp. given that in few days I get last parts needed to assemble my RockPi server. Maybe part of my issues will go…

Definitely not missed, but probably misunderstood something, because from “Things” page I had to add Channels one by one which is very time consuming esp. with Things like Sun that have dozens of Items generated. While from Model page it gets few times faster, because all Items are there from the start, and I only need to check ones I want to use.

This approach has its disadvantages, too :slight_smile: Look at Red Hat’s products: fluffy, over-bloated and badly designed from the start. The idea “we hire 100 more programmers and do this 100 times faster” never worked. Yet possess the manager’s minds now and then. The same with HA. Yes, they are able to pick up fresh hardware fast, but bigger hammer not always work as expected.

It’s great to have that, especially for control/diagnostic purposes. But I find it impractical for everyday use, because the majority of displayed/available stuff is not needed on a regular basis, and useful knobs are buried among the others. I know that you’ve developed your installation to the point you need to look in there very seldom but within nearest few years it won’t be my case. So I want some dashboard to display and allow to control important stuff (wanted to write “thing” though). Probably in a few years my dashboard will contain only few scene buttons, weather and multiroom widgets and that will be it. But not today, the system will develop step-by-step and on early stages the useful dashboard is important.

Yes I did, and I used the binding. But I bought a simple onvif cameras and they’re not fully supported by the add-on (yet?). But I definitely will need a help with it to make it work. Will open new theme on this.

This is important note! Too much information is not any better then lack of one.

Did not know. I will look, thanks.

If using IP camera binding, it won’t pass credentials to the cam that are needed to stream. So the things got screwed. I would be happy to make RTSP work without a need to fiddle with ffmpeg to have it do what’s done already in the first place.

That’s how I expected it to work, but I will try to find out if I did something wrong or just grabbed the widget with restricted functionality, I had an illusion that I’ll be able to do most stuff from MainUI not having to dig into the code. Probably not yet, so I’ll get my hands dirty and see what’s happening.

BTW, another missing part: how to inject CSS into widget code for fonts/sizes/colors/whatever customizing. I may have missed this part, but did not noticed anything about it in the docs, only questions answered on the forum. If I understand correctly, it’s done via Svelte, so maybe just pointing to Svelte docs would be enough.

Okay, I think it’s enough for today, I have to stay with it for a while before I go on. Thank you very much!

5

Rich didn’t mean your “point to” but he meant the “thing” you pointed to.
In a widget or UI definition you refer from, you never point to (or “link to” or “refer to” whatever you like to call it) a Thing but only ever to an Item. (my uppercase use here is intentional as I mean the openHAB objects, not the generic meaning of a “thing” whatsoever in everyday language use. That’s where I think you misunderstood each other).

1 Like
6

Agreed. I’ve been using sitemaps since v2.5 and have little reason to change.

1 Like
7

I’ve been a openHab user since version 1.6 and my UI still is made with Sitemaps.

I have a single sitemap for my wall tablet and mobile , with Android App, and desktop browser. It is not the most fancy UI but it simple enough, it does the job and it just works.

1 Like
8

@mstormi is correct, it’s the term “Thing” that i was referring to.

Major concepts in OH:

  1. add-on: this is a separately installable extension to OH. One type of add-on is a binding
  2. binding: an add-on that communicates with some API or or technology
  3. Thing: an abstract.representation of a device or the connection to an API or a technology
  4. Channel: a single sensor or actuator on a device
  5. Link: connection between a Channel and an Item
  6. Item: normalized representation of sensors, actuators, and aggregations (collections of Items) used to model your home automation. Everything else in OH (rules, widgets, sitemaps, persistence, etc all work on Items). Items may be linked to a Channel or they may not be.
  7. Semantic Model: hierarchical model repenting the physical layout of your home automation using Items

Getting Started is already pretty narrow. I’m not sure there is too much room to narrow it down further.

The reference docs, being a reference, need to be complete.

That kind of stuff is not saved in the cache. Most of that is saved to $OH_USERDATA/jsonsb. These files are plain text so it’s easy enough to check. You can also pull this from the API explorer.

OH should not be trying to write there. But there are some scripts that run prior to OH starting that tries to set the ownership and permissions of all the files OH runs.

As far as I know the OH project doesn’t support Gentoo so that package may not be ours.

Definitely a misunderstanding or a mistatement because Astro things are discovered. You don’t manually create any Channels. However, you may add Items linked to the Channels or you can use “Add equipment to model” to add a bunch all at the same time.

But you also usually only care about maybe four Channels total from a Sun thing. You’d never link all the Channels to Items from an Astro Thing.

Go to the Thing, click the Channels tab, click add Equipment to Model, fill out the form, select just those Channels you want to use and customize the Items that will be created as desired. When you are done those Items will be created and situated in the semantic model.

The model page has almost nothing to do with Things. You can jump to the same “add equipment to model page” from the Model page as I described above from the Channel’s page.

We are all emphasizing all of this because if you don’t understand the difference between a Things and an Item you’ll have a really hard time understanding anything in OH.

Be cautious, the semantic model should only include those items you want to expose to your users. My rule of thumb is only 60%-80% of items belong in the semantic model.

For RTSP there’s a field for username and password when “show advanced” is checked. The docs indicate those properties are there for onvif too.

That’s how it could work. I can’t say that’s how this specific widget works though.

At this point there’s almost nothing you can’t do using only MainUI. Lots of people prefer to use text file configs but I can’t think of anything that can only be done from text file configs at this point except for creating rule templates.

You can use CSS but most of that is exposed through properties on the oh-widgets. Messing around with CSS directly is considered an advanced feature, definitely not something suitable for Getting Started. The two tutorials I linked to about from Justin go over that though.

1 Like
9

The source of confusion was “Create Equipment from Thing” button. By analogy “pointing to a Thing” shall read “pointing to Thing’s Channels represented with set of Items” which is much longer but accurate. But If we think of Thing as a sum of its Channels, we probably may “refer” to a Thing, yet technically it is still invalid.

I hope I understand all this. I asked about “Point” vs. “Item” difference. The docs says

A Point is not a Group, but represents any other type of Item and is usually linked to a Channel.

So Points are mostly just representation of Thing’s Channels in the Model, but what else, beside “usually”? Item may be also considered as a Channel representation or may be a Group, while Point may not. These notions look quite similar to be mixed, so I asked about clarification.

That’s where I made a mistake. I did not understand what “Add Equipment to Model” really does, but read that I have to make links before using the Items and saw an opportunity to add links to Items on the Channel tab, so I started to link them one by one manually. But that’s not how it’s supposed to be done.

It surprisingly does, at least at first run. Maybe that was some initial setup script, I did not dig deep. IIRC OpenHAB initially did not start, I saw the “Permission denied” messages in the logs, that’s why I had to change permissions. After that it runs okay. But you’re right, applications are not supposed to write to /etc. Gentoo has openhab in the portage, but OH doesn’t seem to be popular, otherwise this bug would be fixed already. TBH I did not pay much attention to this, because I’m not going to run OH on my desktop machine after I set up RockPi for this and Gentoo installation is supposed to serve only as a playground to get familiar with OH.

Okay, I suppose everything is clarified enough for me to be able to re-think the whole stuff and sort it out in my head, as well as re-read the docs. If I find something missed or still unclear in the docs, I’ll ask, because that may indicate that this part needs some improvements. I also can make a list of answers or sentences from this thread that were of most importance to me to get things clarified and put the collection into a file (or post here) as a hints to what may be improved – if you find it reasonable.

And I sincerely thank everybody involved in this discussion, especially @rlkoshak! Your help cannot be overestimated. My confusion was to some extent caused by an unfortunate relying to wrong sources of information, but it was hard to get out of it without help. Thanks again!

10

But not all Items are linked to Channels. Some Items can be linked to multiple Channels. In the semantic model, a single Equipment may be made up of a mixture of Items Linked to Channels from more than one Thing and Items not Linked to any Channels at all.

That’s one of the reasons Items exist in the first place. If we only had Channels we wouldn’t have this necessary flexibility. But that’s also why we are very careful with our use of terms.

Definitely review the Deep Dive into the Semantic Model tutorial I posted above.

At a high level, the semantic model is made up of items. There are three types of Items in the model: Locations, Equipment, and Points.

A Location is always a Group Item with one of the Location tags. Equipment is usually a Group Item with one of the Equipment tags. A Point is an Item, usually not a Group, usually Linked to a Channel, with a Point tag and usually a Property tag also.

Nothing about the model cares whether the Item is Linked to a Channel or not. However, there are exceptions which is why we say “usually”.

I have one Point Item that is part of my whole home energy meter which holds the calculated the projected power bill based on the month to date usage. This Item isn’t Linked to anything. It gets updated from a rule.

I have a whole Equipment to represent some sensors at my dad’s house. These also get populated from a rule (MQTT EventBus) and are not Linked to any Channels.

I have a MinHumidity Point Item that is a Group Item with the MIN aggregation function. I don’t think you are even allowed to Link a Group Item to a Channel.

None of these real world examples are linked to Channels. All of them are Points in my semantic model.

Depending on the specific logs, maybe OH didn’t have permission to read these files. :person_shrugging: All I can say is all these files are supposed to be owned by openhab:openhab and the start scripts will try to change them to that if they are not.

Who ever maintains the Gentoo package should have taken that into account.

:+1:

11

Yup, another sitemap fan here since OpenHab 3.x. I am using both the browser client & Android app. Mostly works pretty well for systems that are mostly automated. There are a few things I would love to have however:

  1. A Select with item names and values bound to OpenHab items.
  2. A TextArea item that can display multiple lines of text.
12

If you know what the items are, this can already be done with the selection element and mappings.

13

I actually need the Select mappings to be dynamic - i.e. the pairs are from an item, or perhaps two items.