Getting Started with OH3: rewriting the tutorial - 6. Model your home with Items & link Channels

Development Documentation
, ,
41
  • Locations are Groups with one of the Location tags applied.
  • Equipment is usually a Group with one of the Equipment tags. You put an Equipment into a location by making it a member of that Location Group. In rare cases an Equipment might be represented by a single Item.
  • Points are Items with a Point tag and optional Property tag applied. You make a Point part of Equipment by making it a member of the appropriate Equipment Group. In rare cases a Point might be applied to a Location directly instead of an Equipment.

You can see a mostly complete list of all the tags in the picture in the tutorial (some new tags have been added since that drawing was made).

See the Item docs for how to set a tag on an Item. I assume you already know how to create a Group and set Group membership on an Item.

Without the tags the Items are not part of the model (not all Item need to be part of the semantic model). Thus, without the tags there is no way for the UI to know what Items represent and where they are located.

1 Like
42

I think the documentation here should also explain how to configure the widget of a group.
As shown in the images their state is “NULL”.

How do I derive a Group State from Member Items?
In OH2 it was: Group:Switch:OR(ON,OFF)

In OH3: Select Group from Items, go to edit and then Select Member base type: Switch
Then select Aggregation Function and select One ON then ON else OFF.

Next, Add Metadata and select Default Standalone Widget. Change the default widget
to Toggle Card and save. Now you can turn on/off all your switches in the group.

43

The default widgets are covered (will be covered) in the Pages sections of the Getting Started tutorials. The problem is if you try to cover everything all at once it becomes too much. So the deliberate flow of the tutorial is Things → Items and Model → Persistence → Pages → Rules → Cloud → Comprehensive example. I actually moved Persistence to before Pages because I needed Persistence concepts there.

I’ll have to think about Group state. The getting started tutorial isn’t intended to be comprehensive. It can’t cover everything. So we have to pick and choose what and where we put certain things. In this case, adding Groups, setting their type and their aggregation function is a wholly separate topic unto itself.

44

Thanks for all the work on the documentation. But I still don’t get two aspects:

Can you maybe comment on the practical difference between locations and groups?

Second, how can I group elements of same type?

I opened a discussion here: OH3: Meaning of Locations and Groups

Thanks a lot!

1 Like
45

Can someone add short information to the tutorial how to enable (and disable!) points in Google Home and Alexa? I described my issue here: OH3 MainUI: How to register (and exclude) items for Google Assistant and Amazon Alexa?

46

A Group is an Item that has other Items as members.

A Location is a Group with a Location tag.

Add the Items that represent the “elements” as members of the Group.

That belongs in the readme for GA and Alexa integration, not in the Getting Started Tutorial.

47

An item can be of location type, separate from a group.

Screenshot_20201228-171609998 (1)
Screenshot_20201228-171609998 (1)1080×1712 97.9 KB

48

Okay, many thanks. Buy what is the purpose of a location item? What can it “do”?

49

But it wouldn’t make sense to do that because the way you put Equipment and Points into a location is by adding them as members of the Location Group. And since Locations don’t do anything themselves, an Item as a Location dues nothing for you. Better to leave it out of the model entirely.

It’s could be a place holder in the model I guess. But you’d have to change it to a Group before you could do anything with it.

50

Yes. If an item is a location, it will be picked up by model.
Bindings such as openweathermap have channels which I think will default to a location item, which will then appear as an outliers in model.

51

Yes that’s maybe an unfortunate naming decision. An item can be a location in terms of semantics (it represents a certain place) or it could have a location type meaning the type of value it accepts is a longitude/latitude pair. Those are completely different and unrelated concepts despite having the same name…

2 Likes
52

First things first: great work!
My honest respect to the developers and their effort.

EDIT: sorry for slow typing. Some of my thoughts already seem to have come up during the last hour.

Approaching new ideas I always try to understand what’s been the intention and rely on consistency thereafter. It really helps me, if I find the model and the usage - here the UI - consistent and understandable.

Please let me elaborate on the Semantic Model under these circumstances. Words starting with capitals are identifiers from the UI.

Category
Is it mostly icon or only icon? Wouldn’t it make sense to display a textual and/or graphical icon picker, like it is displayed for Type, Semantic Class and Semantic Property?
What about your own pictures select box?

Changing a Group Item’s type
In the UI it seems one can not change the Group Item Type after creation, opposite to Semantic Class and Semantic property. You have to delete the affected object an re-create it.
If you like to and the object sits at a higher hierarchical level in the model, all sub-object will be moved to the container of the affected object and have to be manually restructured. A loss against textual configuration files, as long as you can’t select, drag and drop multiple objects.

Add Location
If you choose Add Location in the modelling part of the UI, you can choose a Type during creation. There you can choose e.g. Dimmer, which, as other Types as well, seems not to make sense at this point, for they seem to represent Point Items. Or is it, that you mean Group with Dimmers - a construct not yet seen in the textual configuration files?
You can even select Location or Group as the type, which I find irritating. For a Location is naturally of type Location and not of type Dimmer or Player. “Model your home with Items…” states: A Location is a group item…
Also "HABot Walkthrough (2/n): Semantic Tagging & Item Resolving says, that “The ontology defines 4 main types: Location, Property, Point and Equipment, with associated tags for each of them.”
It is (like) a Java class hierarchy and defines sub-classes e.g. for Location, like Indoor, Room, etc.
So it doesn’t makes sense to me, that I can choose a Type which is not a sub-class of Location at all for a Location, especially not select between Location and Group type.

Maybe it’s only in the words. Maybe it’s meant to say “Add (tagged) Group (Location, etc.)”. But then again Dimmer, etc. makes no sense.

Please let me say, that I can follow the possibility to set a Semantic Class and Property on Locations.

Add Equipment / Add Point
For me the same problem. The said is true for Equipment, for Point it is the other way round, for you can choose a Type of Group: “A Point is not a Group but any other type of Item and is usually linked to a Channel”

Point and Property
Now to the hardest part: imagination :wink:
It’s almost impossible to fit everyone, so I agree that Point and Property should be used in a creative manner, that adds to the outcome. For me a simple ON/OFF (for Switch or State) is missing. Yes, you could imagine a Level of 0 or 1. And what about Power and Energy - same physical quantity.

What do you think of my thoughts?

BTW: as mentioned in some posts already adding Equipment directly to Locations doesn’t seem to work, for there will nothing be displayed under Locations, Equipment or Properties.

1 Like
53

Maybe I’m missing the nuance here, but I certainly have Dimmer Type Groups.

Group:Dimmer:MAX gdHallwayLights

From

54

OMG - I am so sorry. Looking at my old configuration files and the documentation again…I don’t know how I could have overlooked it.

1 Like
55

Only the icon. It’s only used in Sitemaps and in administration areas of MainUI. It’s mostly a legacy carry over from OH 2. I think PaperUI first introduced category as the name for the icon. I think there were plans for doing something with that at one point but those plans were abandoned when the maintainers for PaperUI abandoned openHAB.

Category is not involved in the model.

I don’t know if custom icons are supported or not. I think they are though and they would follow the same rules and approach as documented at https://openhab.org/docs/configuration/items.html#icons

Certain aspects of an Item is fixed. These include the name and the type I think, there may be others. It appears that it works differently with text based items but it really isn’t. You can’t change these on a text base Item either. But it appears that you are doing so because what is actually happening is that when your .items file is unloaded, all of the Items defined in that file are completely destroyed. Then when the .items file is reloaded all of those Items are recreated. The Items are not edited in place. So in the UI, to make those sorts of changes you have to do the same thing. Delete the Item and recreate it.

The model is there for your benefit and has to be flexible enough to support a number of ways to represent your home automation. There could be a use case where someone may want to give a type to a Location Group but I doubt that would be a common use case. Ultimately a Location is just a regular old Group like any other Group and the same generic Group form is presented when creating a Location Group.

You have always had the ability to give a Group a type in .items files since Groups were introduced
way back probably before OH 1.0. Group:Dimmer:MAX defines a Group of type Dimmer presumably containing Dimmers. The state of the Group would be the state of the Item with the maximum value. Furthermore, sending a command to a Group and the command is forwarded to all of it’s members.

That’s an unfortunate case where the same name is used for two different things. First realize that the model was adopted from somewhere else so it’s not so easy to just go and change it because of the conflict. Anyway, the type you see in the Group menu is for a Latitude/Longitude coordinate. There is a Location type Item in OH that has existed long before the model. This has nothing to do with the model’s Location tags. Put another way, the Location type has no semantic meaning for the model.

In general I would expect a Location Group and an Equipment Group to not have any type what-so-ever. Again, the Location type has nothing to do with the semantic model. It’s a type of Item and it’s state is a lat/long coordinate. Everything about the model is built up using Group membership and tags. Nothing else is used in the model beyond that. Setting a Type on a Group may be useful in other parts of openHAB (e.g. rules) but it does not do anything for the model.

An Equipment represents a device. A device may have one or more things it reports and things it can do. Each of those is represented by a separate Item. These Items are the Points. The Equipment is a Group. The Equipment contains all the Point Items as members of the Group.

In rare cases you may have an Equipment with just one Point. In that case you can skip the Equipment Group and just create the single Item and give it the Equipment Tag.

When you create equipment from Thing, the Group Item that represents the Equipment is created along with Items linked to all the Channels you select.

When you create points from Thing, the Group that represents the Equipment is not created. Instead you can select an existing Equipment Group to put the Items into. This is because there are many cases where Points on an equipment come from different Things (e.g. a Network binding online Channel to track the Equipment’s online status).

There are cases where you do want to use a Group as a Point. For example, I might have a Group:Number:Temperature:AVG AverageTemp that aggregates all the temp sensors in the house into an average. I might make AverageTemp a Point type Measurement with a Property type of temperature and make it a member of the House Group.

I use Switch/Power for that. Remember that the tags go in pairs. Switch/Energy might make sense too, but for me I tend to reserve Energy for power usage sensors and will Measurement/Energy for that case. For battery statuses I use Status/Energy. Also, you don’t have to add the property so you could just use Switch and skip the property if that makes more sense to you. But it’s the Switch that tells you that it’s an ON/OFF and its the property that tells you what the Switch is controlling or reporting.

The key is to pick something that makes sense to you and be consistent.

56

Thanx for your effort to answer my lengthy question in an similar way. From first reading I already got some impression and ideas and will try to experiment.

57

So maybe the “location” item should be renamed “installation” to be separated from the tag.

Wouldn’t it also be reasonable to call the icon property “icon” instead of “category”?

Just from an outside perspective…

58

I think even the type can be changed. Just the name (aka ID) is fixed. You just can’t edit some options from the Model page in MainUI but have to go to Items > Edit to do so.

1 Like
59

hello,

how is it possible to set in my location over equipment from thing a temperature to my radiator?

when i use ["Setpoint", "Temperature"] i only can read the targetsetpoint

thx

60

A Location is a Group with one of the supported Location tags. An Equipment is a Group or an Item with one of the supported Equipment tags. A Point/Property is an Item with a supported Point tag and optionally a supported Property tag.

To put anything in a Location, you make it a member of that Location.

When creating an Equipment from Thing, you must first click on to select the Location you want the Equipment to be in. That will add the generated Equipment Group into that Location’s Group and all the Point Items will be members of the Equipment Group.