There continues to be a steady stream of posts for help about the semantic model, how to use it, best practices, etc. One common problem is an assumption that the model does more than it really can right now. Another problem is the assumption that the model has to be used.
This tutorial is going to be a deepish dive into the semantic model, much deeper than is suitable for the Getting Started Tutorial. I’m also going to present my suggested best practices. I’ll try to identify those as my suggestions are not the only way to work with the model and may not be the best approach in all cases.
History
Believe it or not, the semantic model was first introduced way back in OH 2.4.0 M5. It was originally introduced to provide more meaning to Items than the standard Item definitions can provide. The reason for adding this new layer on top of Items was to support a natural language interaction between openHAB and a then new (still maintained and available) user interface, HABot.
In order to support interactions like “Turn on the lights in the master bedroom”, HABot needs to know which Items are in the master bedroom and which of those Items control the lights.
How the Semantic Model is Implemented
As already mentioned, the semantic model is a layer built on top of existing Items structures and features, namely Item tags, Group membership, and Item metadata.
Item Tags
These provide information about what a given Item represents semantically. The tags were initially adopted from the Brick Schema but have had additions and changes made for use in openHAB.
There are four categories of tags. Any given Item can only have one tag from one of the following categories.
Location
A Location tag is applied to an Item that represents a location. A location can be very broad like “Indoors” or very specific like “kitchen”. These Items don’t actually do anything. Their entire purpose is to represent the physical layout of your home automation system.
Equipment
Commonly, one device will have multiple actuators (i.e. controls, things that can be commanded to cause an action to occur) and/or sensors. Despite this, the device is a single unit, often represented in openHAB as a single Thing. Therefore , equipment tags are applied to Items that represent a device, like a multi-sensor, HVAC system, etc.
Often an equipment will have a one-to-one relationship with a Thing. However, it is reasonable and expected that multiple Things even from multiple different bindings might be combined in a single equipment. For example, one might have a Zwave smart switch connected to a dumb humidifier combined with an MQTT humidity sensor and an Unbound Item combined into a single humidifier Item tagged with the “HVAC” equipment tag.
Point
A point tag applies to the Item that represents the actual actuator or sensor such as an individual Switch for an actuator or a Number:Temperature for a sensor. The point tag indicates what the Item does.
What does that even mean, “what the Item does”? Let’s look at some examples. A thermometer might use a “Measurement” point tag because it represents the measurement of something. A light switch might use “Switch” as the point tag since it switches something on or off. A Play Item to control a media player might use a “Control” tag. An Item that switches ON when the smoke alarm detects smoke might use an “Alarm” tag.
One might ask, how do I know that the Number:Temperature Item is a “Measurement” of temperature? That’s where the properties tag comes in.
Properties
A properties tag can not exist without a corresponding point tag. They never apply to the same Item tagged with an equipment or location tag.
Point tags indicate what the Item does. To indicate that our Number:Temperature Item is a “Measurement” of temperature, we’d add the “Temperature” properties tag. That smoke alarm would use the “Smoke” properties tag. A humidity sensor might use “Measurement” as the point tag and “Humidity” as the properties tag. As a short hand I’ll indicate a point properties tag pair using “/”, e.g. “Measurement/Humidity”. That switch that turns on the humidifier might use “Switch/Humidity”. A water leak alarm might use “Alarm/Water”.
Hopefully you can see how rich the opportunities are to build the model using just these two tags.
Group Membership
In addition to just identifying what each Item represents using tags, the semantic model supports the creation of a hierarchy. The hierarchy represents the physical layout of the home automation (i.e. what is in what location) and the groupings of individual Items into equipment.
The actual hierarchy is created through Group membership. An Item with a point tag becomes a part of an equipment by making it a member of the Group Item with the equipment tag. A point or equipment is placed in a given location by making it a member of the Group Item tagged with that location’s tag.
There are some rules about these Group memberships though.
-
Any given Item can only have a tag from a single category of tags above with the exception of properties which can only be tagged on an Item that already has a point tag.
-
Location Items can only be Groups.
-
Locations can have any number of other locations, equipment, or point tagged Items as direct members.
-
Equipment Items can be Groups (the usual case) or single Items (not recommended, see below).
-
Equipment can have any number of points or equipment tagged Items as members.
-
Point Items can be Groups (rare use case) or single Items. If a Group, the members of the Group should not have any semantic tags and the Group should have a type and aggregation function.
-
No semantically tagged Item can be the direct member of more than one semantically tagged Group.
-
Any semantically tagged Item can be the direct member of any number of non-semantically tagged Groups.
Let’s look at an example hierarchy, a humidifier I have in my front room.
At the top of the hierarchy I have a location “Wuthering Heights”. That represents my home. You’ll also notice I have another root location, my “Dad’s House”.
Next I’ve split the location hierarchy into floors. There are three floors in my house including the basement and I’ve three Group Items tagged with the appropriate tag for the floor as a direct member of “Wuthering Heights”.
In the “Ground Floor” I’ve a number of rooms with stuff automated in them and each gets it’s own location Group Item using the appropriate location tag. The humidifier is in the “Front Room”.
Under the “Front Room” there are a number of equipment. Each is represented using a Group Item using an appropriate tag. The closest tag I had to choose from for the humidifier was “HVAC” so that’s what I chose.
Under “Main Floor Humidifier” there are three Items which represent the actuators and sensors that make up the equipment. Each has a different point tag indicating what the Item does but the property is “Humidity” for all of them because all three work with humidity.
Item Metadata
If you don’t use HABot, you can skip this section.
Sometimes one might have more than one name for the same thing. For example, we interchangeably use “front room” and “living room” in our common speech in our house. Given that HABot is supposed to be based on natural language it needs to be able to support that. It does so by offering a synonymns Item metadata. You can add a comma separated list of alternative names for the Item (in addition to the label) that can be used to refer to the Item,
How Do I Build the Model?
The previous section should have given you an idea on the mechanics for how to define your semantic model. But it doesn’t tell you how to actually construct the model. Unfortunately that’s not something that a tutorial will be able to address fully. We can’t create the model for you because each and every person’s home automation is unique and the purpose of the model is to help serve you, not impose upon you.
But there is some general advice I can offer.
-
Don’t over think it. Make the model serve you. If it seems tedious or not helpful, you are probably trying to over define/design the model.
-
Not everything needs to be in the model. In my experience about 60% of Items belong in the model. YMMV. In general, if your end users don’t care about the Item it probably doesn’t belong in the model.
-
Approach the model from your home automation user’s perspective. Let’s say you have a smart switch in the hallway that controls a light in the kitchen. The users of your home automation don’t care that the switch is in the hallway, they just want to turn on the kitchen light. So put the switch in the kitchen. The model should represent your home as the users see it and will use it through openHAB, not how you, the administrator, sees it. Specific technologies used, hidden relays in a closet somewhere, and stuff like that are irrelevant to the end users, so don’t model those.
-
You don’t have to use the model if you don’t want to. If you are coming from OH 2 or older you may have no use for the model. Even if you are just starting with OH 3 you may not have a use for the model. So don’t feel compelled to use it. It’s not required.
-
In my opinion, it’s not worth the effort to make the model work in .items files. I therefore recommend that if you do plan on using the model, consider using managed Items instead. If you do choose to use .items files, do not mix and match. There is a bug when some Items are in .items files and others are managed which breaks the model.
-
In my opinion, it’s not worth the effort to retrofit a bunch of existing Items to work with the model. It’s tedious, error prone, and time consuming. Instead, I recommend recreating your Items using the “Create Equipment from Thing” and “Create Points from Thing” options. This will allow you to define dozens of Items all at once in a matter of minutes and the Items will already be situated into the model. Having done it both ways recreating the Items in this way took almost half the time.
-
Be consistent. You want all your lights to work and look the same so model them all the same way using the same tags. For example, I made the mistake of using the “Smart Assistant” equipment tag for my Google Hubs and the “Speaker” equipment tag for the Google Home Minis. This seems reasonable because that’s what they are. However, that ends up splitting them apart in the Overview Pages for no good reason. As another example, let’s say most of my lights are smart bulbs with one that’s just a Switch. Because I can make that single Switch be an Equipment with the Lightbulb tag but the Color Items all have two Items (one for Color and another for Color Temperature) I used a Group with the Lightbulb tag. As a result this odd lightbulb not only gets shown differently on the Locations tab of the UI, it has its own card which is undesirable.
How the Semantic Model Is Used
There currently are four places where the semantic model is used in OH as of this writing.
Model View
The semantic model is how the Model settings page is rendered. The Group membership hierarchy is rendered as a collapsible tree structure making navigating the model quick and visual. The locations, equipment, and point tagged Items are rendered with a different icon (see screenshot above).
Rules
There are a collection of new Actions that can be called from rules. These let one determine whether the Item is a location, equipment, or point, determine the equipment or location the Item belongs to, and query for the Item’s tags.
HABot
Ans briefly mentioned, the semantic model was originally developed to be used with HABot. HABot is a UI add-on that allows for a dynamic and free flowing interaction with OH using natural language.
See HABot - UIs | openHAB for details.
Overview Page in MainUI
MainUI is the main UI openHAB users will interact with. Among the administration parts, MainUI presents an Overview Page that consists of four tabs.
Overview
This is the first tab and it is what all users will see when first logging into OH. This tab is a Layout Page and should be custom built by you.
Locations
This page is populated based on the semantic model. Every location that has a direct member that is an equipment or a point will have a card generated.
Badges may appear on the card based on the states of the point Items that are direct members of that location Group or members of an equipment that is a direct member of the location. For example:
The above screen shot shows the Master Bedroom location. The card indicates that the Master Bedroom location is itself in the Top Floor location. And there are a number of badges that indicated what’s going in in that room. One light is on (there’s a little number if there is more than one). The HVAC is on (in my case the humidifier). The temperature is around 65 °F and the humidity is 36% and the light level is 47.
Identifying which Items represent the lights, HVAC, temperature, humidity and light level is achieved through the equipment, point, and property tags.
One reason to be consistent is so, for example, all the lights appear on the card the same way. If one were to tag a plain old Switch Item with a Lightbulb equipment tag, but the rest are in equipment Groups because they have more than one Item, the Switch will appear on a completely different tab. So either always use an equipment Group or never use one for all the Items of a certain semantic type.
Opening the card will show the individual point Items. If there are any point Items that are direct members of the location and not members of an equipment will be shown on a separate properties tab of the card. The above shows only equipment. Each equipment gets a gray label and the point Items that are a part of the equipment show up below that label. If an equipment has subequipment, that will appear as a row you can click on to open another card showing the points.
Equipment
This tab works very much like the locations tab with the following differences:
- Each type of equipment (i.e. each unique equipment tag) gets it’s own card. This is one reason to be sparing in your use of equipment tags. For example:
This is the first row of my Equipment tab. It makes no sense that each door ends up in its own card. They are all doors so they should be grouped together. But I tried to use the most specific equipment tag and there is a separate tag for each type of door. As a result I end up with an Equipment tab that doesn’t make sense. Instead my plan is to change the equipment to just be “door” so they all group into the same card. The same happened when I used different equipment tags for my Home Hubs and Home Minis.
-
Clicking on a card will show each instance of that equipment type similar to how they are displayed in the locations cards.
-
Equipment cards do not show badges.
Properties
Notice the name here. It’s “Properties”, not “Points”. Only those point tagged Items that also have a property tag will be represented. Each property tag gets it’s own card and all the Items with that property are displayed, grouped based on the point tag used.
Rules of Thumb and General Advice
- Always use Group Items for equipment, even if there’s only the one Item.
- Only include in the model those Items your end users will interact with.
- Use descriptive labels. Take the screen shot above of the Humidity card. If all the Items are labeled just “Humidity” the card would be completely useless. We couldn’t tell which room the sensor is reporting for.
- Focus on how things appear to your end users. If a switch controls the kitchen lights, put the switch in the kitchen even if it’s located in another room. Your users don’t care where the switch is, they only care about where the lights are.
