OH3 semantic best practice

I try to better understand the semantics of OH3. When configuring semantics for a lightbulb switch what do you choose for Semantic Class?

  • control
  • point
  • switch

Edit: what about the thing itself:

Equipment or ``Lightbulb`?

Thanks for your comment

Hi, what helped me was this chart:

From the screenshot i believe you want to create an Equipment on Item level. You should consider to create an Equipemnt first in the semantic model and then add the item Aussenlicht as a point within the equipment.

This would look like this:


“Lichter Esszimmer” is the Equipment, Wandlampe Esszimmer the item. You can still tag the equipment to what it looks like. In this case a Lightbulb.

1 Like

One thing that helps me is to look at how the Item gets rendered in the Locations, Equipment, and Properties tabs. That is all controlled by the semantic tagging. If it isn’t looking like you want in terms of organization take a different approach in your tagging.

For example, you can add Point/Property tagged Items to a Location without it being a part of an equipment. But when you do it will cause there to be an Equipment and Properties tab added to the Location Card. That may be desirable or you may hate that. If you hate that, then always make sure your Point/Property tagged Items are members of an Equipment Group.

You can construct Equipment with Equipment. But when you do you will have to click down twice to see the subequipment’s Points/Properties. Maybe that’s desirable, maybe you want to see it all at one level. If you want it at one level then don’t make subequipment.

Only Items with a Point and Property tag will appear in the Properties tab.

As an example, I have a bunch of diverse stuff that all appear as Chromecasts. I tagged the ones attached to TVs as Receivers, those that are Home Hubs as Virtual Assistants, and the home minis and Chromecast Audios as Speakers. But they really all have the exact same controls and it made no sense for them to appear in different cards on Equipment and the Properties tabs. So I went back to use the same Equipment tags for each one (receiver I think is what I used).

Those are the sorts of things that will drive your semantic tagging approach. Determine how you want them to appear in the auto generated tabs. How do you want to use them in HABot? From there, use tagging that supports what you want.

In some cases the semantic tag you use will be a little awkward. For example, most of my battery powered devices report their remaining charge as a percentage. But visually and how I’m using them it made the most sense to use LowBattery/Power as the Point/Property tags. In the above, it’s kind of awkward to tag a Google Home Mini as a receiver but it works out best that way for how I want them to appear on the UI. And then they appear along side the Rokus too which makes the most sense.

The model is there to serve you. Experiment and find what works best for you. Also, don’t put too much emphasis on the model. It is very important but it is also optional. It doesn’t drive a whole lot of stuff outside of MainUI and HABot right now. So do what makes sense.

Finally, do not put everything into the model. I personally only have about 60% of all my Items in the model. You’ll have a lot of Items that are only used in Rules. Other Items might get wrapped up into the widget used to display another Item so there is no need to include it in the model. As an example, for those Chromecasts I have, I display the Playback Mode, Media Artist, and Media Title all on one default list widget on the Playback Mode Item. So I’ve excluded the Media Artist and Media Title Items from the model entirely.

An alternative to that if you have some other reason to include these in the model, you can set the visibility of the widget to false.

1 Like

This is very good advice!

In the last few days I played a bit with the model, I too changed the tagging after I saw how it was rendered in the UI.

I want to add some aspects, that I had to find out:

  • first I struggled because I thought, that the tagging in the model would have some kind of influence on who an item would behave. But, at least in moste cases, that is not the case. It is e.g. perfectly fine to tag some switch as a blind. I use this for items that activate some scenes, which I tagged as lights or blinds or whatever, so that they are shown in the appropriate category

  • in same cases I tagged several physical devices as one equipment. For example in nearly every room I have more than one roller shutter. For each room I have items to control the shutters individually and to move the, together. First I tagged every shutter as an individual equipment, but creating one equipment for every room and adding all items to it looks (in my opinion) much better in the ui.

  • I have some items, that control the „over all“ behavior of openHAB, e.g. if blinds should be moved automatically in the morning or evening or for sun protection. For these items I created a „virtual location“, as it made no sense to attach them to a room of the house.

  • first a tagged simple switches for lights and other devices as equipment directly in the room. But in the ui these devices where sorted at the beginning and I could not change this by defining the widget order. After creating an equipment and adding the devices as points this is not an issue any longer (and it looks better)

The semantic model is a very powerful feature. Luckily I had so e time to try it out, all in all it took several days. But now I have a perfectly usable UI without having to create a single page nanually.

My advice would be, to try it out with only a few items and locations and adding the rest after you have figured out how you want it to look. I went „all in“ (how hard can it be :smirk: ) and that was probably not the best idea I ever had, as I changed the tagging several times.

Another approach is to add the house itself as a location. This occurred naturally for me because I actually have two separate houses represented in my model, my own house and my dad’s house. So my Locations model looks like

Dad's House (Building tag)
  |_ Dad's Office
  |_ Dad's Living Room

My House (Building tag)
  |_ Outside
  | |_ Entryway
  |_First Floor
  | |_Family Room

And so on. So stuff that’s global to the house, like the weather readings and forecast are located in My House (I used Outside for awhile and may go back to that at some point).

Two other tips I can give for customizing the UI is:

  • define custom list Item widgets and reuse those to customize how the Items look in the cards, see Example Custom List Widgets for some examples by using them to define the “default list widget” on the Items

  • use the visibility field to hide those Items that you don’t have to see all the time. For example, I have a bunch of Items representing the online/offline status of various services. I only ever need to see these in my UI if it happens to be offline. So I set the visibility field to only show the widget when it’s offline. I only care about the Chromecasts when it’s actually actively streaming something. So I hide all it’s widgets except when it’s actively streaming something. The gray bar for the Equipment still shows up in the Location and Equipment cards but that’s OK for me.

1 Like

Adding these items to the house is a nice idea, I will try this out!

For weather forecast and some other values, e.g. from the astro binding, I have an other virtual location. But I will probably remove most of them from the model. For my needs the weather widget I found here in the forum and a few other values I placed on the overview page are enough. And if need be I still have a sitemap with all of my items and the Basic UI or the iOS App.

For me „finishing“ the model will probably end like building the cologne cathedral, building started in 1248, after a few hundred years it paused for 300 years and was finally finished in 1880, after 632 years. But this is part of the fun :grinning:

define custom list Item widgets and reuse those to customize how the Items look in the cards, see Example Custom List Widgets for some examples by using them to define the “default list widget” on the Items

Yes, this thread helped me lot, thanks for sharing this! I can only agree, this helps a lot and it makes the UI more consistent.

And for all the old-fashioned guys like myself the widgets can be assigned in the item file, without having to use a mouse :smirk: