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


This Wiki topic’s goal is to serve as a working document, in order to provide an up-to-date tutorial for OH3 aimed at new users and novices. Everyone is welcome and encouraged to edit it, when we’re satisfied it will make its way to the official docs. You may reply for the specific purpose of improving the article are allowed, but please, this is NOT a support thread: if you’re stuck while reading this and are simply seeking support please open another thread. Thanks!
This page has been transitioned to the official docs. See Semantic Model | openHAB.


Things represent devices and the sensors and actuators of those devices. But one of the purposes of openHAB is to abstract from the specifics of each of the hundreds of supported technologies and APIs so that a light switch is a light switch whether it’s controlling a Hue light bulb, a KNX wall switch, or a custom DIY relay that speaks MQTT. To provide that abstraction openHAB uses Items.

There are a fixed set of Item types representing all the different ways that a sensor reading can be represented or ways a device can be interacted. The configuration of your Items is where meaning is applied to your devices. For example, instead of dealing with zwave:1231242:node12:switch we can deal with “Livingroom_Lamp”.

Items are the main entity that the rest of openHAB works with including Pages, sitemaps, rules, and persistence.

There are many ways to organize your items, one of which is to make use of the semantic model (descriptions for location, type of equipment and more). openHAB 3 makes extensive use of the semantic model to automatically create Pages (see next section) and to provide natural language interaction. Therefore we recommend creating the semantic model right from the start and sticking to it. This will make your life easier in the long run. Taking the time to understand and choose a logical structure for your home will save you from needing to re-do the work a second time in the future.

This section gives a good example of one way to model your home with locations and equipment descriptions. The semantic model, when setup correctly, will allow openHAB to turn all lights off in a kitchen when asked, as the framework can understand the kitchen location and what items are lights in that location.

Introduction to the Ontology and Relationships:

The above drawing shows the relationship between the four main concepts in the model.

  • A Location is a Group Item that can contain sub-Locations, Equipment and Points and represents a location (building, room, etc.).
  • An Equipment is normally a Group Item that can contain sub-Equipment, and Points.
  • A Point is not a Group but any other type of Item and is usually linked to a Channel.
  • A Property is an additional tag on a Point Item that indicates what sort of point it is. For example, a thermometer might be a Point of type Measurement with a Property of type Temperature.

Example of an advanced model:


(made with https://www.diagrameditor.com - file here: Semantic Model.txt (3.3 KB) change extension to .drawio)

We have an Indoor location which has a House. the House has a Ground Floor and the Ground Floor has rooms including a Living Room. The Living Room has a Rollershutter equipment which in turn has a Control and Power point Item. The locations and equipment are Group Items and Control and Power are other types of Items.

One key feature of the this ecample model is that you are not required to only use the semantic model. It is possible and encouraged to create Groups and Items that are outside of the model where necessary. In this example, the Rollershutter in the Living Room is a member of the AllRollershutters Group which could be used to determine if any are OPEN and send commands to all the rollershutters in the house at once.

You can use as few or as many layers of Locations as you wish to model your home. For instance if you live in a flat (apartment) your root Locations might just be the rooms. If you only have one building, you can omit the indoor/outdoor layer and the building layer to only have a hierarchy of floors and rooms, etc.

Equipment’s are often mapped to Things but not always. You can represent a single Equipment with several Things - for instance a computer might have points to switch it on (send a wake-on-lan packet), off (shell command), determining if it’s online (network polling), how much power it consumes (Z-Wave wall plug). All these multiple Things from different bindings can be combined to model a single piece of Equipment.

The Computer is the equipment and it could be located in a room called the study location. The computer is made up of multiple Things, some of which are not physical devices.

A front door can have points to determine if it’s open or closed (with a sensor) or locked (with a smart lock), and a camera/motion detector.

Building the Locations Model

From the Settings screen, click on Model.

Let’s start with a hierarchy of Locations. Click on Add Location.

Add your first item, a Group representing the ground floor: Give it a name (choose carefully, you cannot change it afterwards, a popular convention is to prefix groups with “g” but it’s not mandatory). Choose a label, category (it mostly defines the default icon), and specialize the item by choosing a more accurate semantic class than “Location”, here “GroundFloor”.

Once it’s created, make sure it’s still selected on the left, and click on “Add Location” again - this will add another location within the first floor. Typically rooms are directly under floor locations.
Add an item representing the living room, call it gGF_Living, set the sofa category and the LivingRoom semantic class.

Now let’s add the kitchen: Make sure to select Ground Floor again and choose Add Location to add the third item (name: gGF_Kitchen, category: kitchen, semantic class: Kitchen).

To add the first floor to the root level, we need to clear the selection first, click on the white space in the tree, or Clear in the bottom toolbar. Add the ground floor, and its rooms (master bedroom, bathroom, etc…) to your model.

You should end up with something resembling this:

(side note: there might be Home Builder-like functionality in a wizard in the future to prepare the locations).

Modeling Equipment

Now let’s add some Equipment and Points.
You could proceed like for the Locations and create them by hand, but there’s an easier way.
If the Equipment you’re adding is one of the Things that you already added, you have two options.

1. From the Model page

Select where in the model you want to add the Equipment, for instance, the kitchen, and click on Create Equipment from Thing.

Select the Thing you want to create the Equipment from, and alter the details of the Equipment item that will be created. If you don’t find an appropriate Equipment class, choose Equipment.

Below are all the Channels defined by the Thing, sometimes Things will have hundreds of channels so here you have the opportunity of choosing which ones will be linked to new Points items. Check the channels you’re interested in and only those.

For the plant sensor Thing added earlier, we have an opportunity to change the default basic Number types and make them quantifiable. Quantity types (Number with a dimension) provide conversion facilities between Units of Measurement, and the default persistence is more granular. For percentages like humidity or battery levels, use Number:Dimensionless, which a quantity type without a dimension.

Also set the semantic class to Measurement and choose an appropriate related property.

When you’re finished, click Add in the title bar: the Equipment and Points should be added to the model where you wanted:

The “Plant Sensor” Equipment has been created under the Kitchen location and all the selected Points represent the selected Channels of the Thing.

2. from a Thing’s page

From the Settings, click on Things and click on the Thing you wish to add to the model. Switch to the Channels tab.

Click on Add Equipment to Model below the list: you’ll encounter a similar screen to the one above. The difference is, rather than selecting the Thing, you have to select where in the model you want to add the Equipment.

Select Pick From Model in the Parent Group section, the treeview of the Locations and Equipments will appear; select the parent group, for instance Living Room, then choose Pick in the top-right corner of the dialog box.

Then do the same as above, configure the Equipment item and the Points, then click Add.

Go back to the Model by choosing Model in the sidebar and verify that the Equipment added to the model from the thing page is effectively there as well as its Points.

Note how the Channel Links section lists the link to the Thing/Channel, and you also have a control widget to control the item - since it’s linked to the Color channel of the Hue bulb, the light will reflect the state of the item.

Finish adding Equipment and Points from your Things.

Retrofitting Existing Items to the Model

There may be times where a user needs to add existing Items to their model. Perhaps they are migrating from an older version of OH, they did not follow the advice above to start with the model to begin with, or they are following a tutorial or example that doesn’t include the model. In this case all is not lost. Existing Items can be added to the model. Browse to the Item in the Items settings, click on Edit and choose an appropriate Semantic Class and Semantic Property. Then add the Point as a member of the appropriate Equipment or Location Group. If the Equipment Group doesn’t exist yet, create a Group and use the appropriate Equipment semantic tag first and add the Equipment to the appropriate Location Group.

Next up, Pages.

Next -> Pages
Previous -> Advanced Thing Creation

Next -> Persistence
Previous <- Adding Things - Advanced

6 Likes

8 posts were split to a new topic: Evolution of the functional/semantic model

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.

A simpler option might be to add a default hierarchy if there is no existing data. Indoors Outdoors House Garage Ground Floor come to mind. You might also include Frint Yard and Back Yard under Outdoors.

I was thinking about a very user-friendly wizard to get started, not everyone has a need for a full model, for instance those living in flats don’t need unnecessary levels with floors and so on. So there would be a series of questions like:

  • do you live in a house, or a flat, or a duplex?
  • how many floors do you have?
  • describe for each floor which rooms apply to them
  • do you have outside areas, like a garden or a garage/carport?
  • check the outside areas that apply to you
  • any additional buildings like a shed or guest house?
    etc.
4 Likes

Perhaps different cultures but here in North America a Carport is a covered outdoor area. a Garage is either attached to the house or a separate Building.

One thing that jumps out to me as a native English speaker. Your English is better than my (non-existent) German. In English the word “Equipment” is both singular and plural “Equipments” is incorrect English.

I realize English is a very vague, backwards language but it is all many of us have to communicate. I do have a bit of very rusty French from high school in Canada though.

Yes I was taught/reminded of that with varying levels of friendliness lately :laughing: (I found an entire article about it). But now I have to check and correct every occurrence, I counted over 80 of them in the code.

4 Likes

Maybe some suggestion of how to handle Things that control multiple Equipment would be nice. Eg in my case I have a Shelly 2.5 2-port relay that is installed in Room1 and controls the light of a mirror in Room1 and a ventilator in Room2. It also has a temperature sensor. Would you model the Shelly as an Equipment with just a temperature point and have the relay points the respective mirror/vent equipment?

1 Like

I think you can have equipment inside of equipment. The model is there to help you. So it’s not so much about being “right” as it is what’s most useful for you. So what are you using the model for?

Is there anything else about the Shelly that you care about that would cause you to put it into your model at all? If all you care about is the relay, model the light as one piece of equipment and the ventilator as another piece of equipment. The relays belong to those. The fact that it’s a Shelly that actually “owns” the relays is irrelevant in this model.

Room 1 (equipment)
    light (equipment)
        Shelly 2.5 Relay 1 (point)
Room 2 (equipment)
    ventilator (equipment)
        Shelly 2.5 Relay 2 (point)

If you do want to model the Shelly, than perhaps it makes sense to make the light and ventilation be equipment under the Shelly equipment. But then you have to pick which Room the Shelly is in. I think I saw Yannick mention that you can’t have the same equipment in more than one Room. But perhaps you can have a zone that has the Shelly 2.5 equipment and the sub equipment can be in Room 1 and Room 2.

Bathroom Suite (room or zone)
    Shelly 2.5 (equipment)
        online status (point)
    Room 1
        light (equipment)
            shelly relay 1 (point)
    Room 2
        ventilation (equipment)
            shelly relay 2 (point)

Or

Bathroom Suite (room)
    Shelly 2.5 (equipment)
        relay 1 (point)
        relay 2 (point)

Which of the above makes the most sense? Which most closely matches how you think about these devices? Which is closes to how you use these devices?

1 Like

According to the existing OH2 docs, very few bindings use the model. What is the larger benefit to implementing this instead of just using Group Items ?

1 Like

I just checked since it’s an interesting scenario.
In fact the model allows you to have an Equipment be part of another Equipment, but also in a Location.
So if you define your 2 Locations, and Shelly relay as an Equipment, and the HVAC/Light as separate equipment, and then add them to both the Shelly equipement group and the Location groups they’re in, they will appear twice in the model - you see it’s the same item because it highlights in both places:

image

You cannot do that from the model page but you can change the group membership from the items pages. In the case of the light you’ll end up with this:

So it has both a isPartOf relation with the Shelly relay, and a hasLocation relation to the room1 location.

See openHAB 3.0 my getting started notes: Model and Pages for an example. tl;dr it gives HABot the context it needs to interact with it using natural language and it gives the Main UI the information necessary to construct Pages automatically for you so there really isn’t any need to create a sitemap unless you want to. When you have a model, the UI all but constructs itself.

I wasn’t aware that any bindings use the model. I thought bindings couldn’t see Items and therefore it shouldn’t even be aware of the model since it’s all done through Group membership and Item tags.

You don’t have to use the model. But I’ve been playing with it and IMHO it’s totally worth the effort. The way it builds Pages really makes it powerful.

2 Likes

As the two rooms are not really connected I don’t really like putting them into some common group. OTOH, I would like to have the temperature sensor of the shelly report to me. So what I currently did was more or less the first part, but also have an Equipment “Shelly R1R2” in Room 1 with a point of “Temperature”:

Room 1 (equipment)
    light (equipment)
        Shelly 2.5 Relay 1 (point)
    shelly (equipment)
        Shelly 2.5 Temp (point)
Room 2 (equipment)
    ventilator (equipment)
        Shelly 2.5 Relay 2 (point)

What I will probably do now is to try what is mentioned here, so that I can have both links (location and group-equipment) shown:

Thanks! That sounds interesting, I will try. What would be lost is probably the actual location of the Shelly in this case. Or could I place the Shelly Equipment in Room 1 instead of on the top level?

Yes I suppose, or in any other location. Normally the “hasLocation” relations are only to the direct parent group, so there shouldn’t be any conflicts, like HABot not able to figure out where your lightbulb is because it’s in a room and its parent equipment is in another. The more it’s tested in the field, the better!

I wasn’t aware that any bindings use the model. I thought bindings couldn’t see Items and therefore it shouldn’t even be aware of the model since it’s all done through Group membership and Item tags.

When you add a new link to a channel which has a channel type, the channel type can tell you which tags should be applied to the item. So if we’re creating a new item along with the link, and the “suggested” tags from the channel type are semantic tags, we could create the model a lot easier with that “Add Thing as Equipment” feature, because for example, items linked to channels measuring temperatures would be tagged “Measurement” & “Temperature” automatically.
This needs bindings to provide those tags in the channel types descriptions though, that’s largely not the case currently, but we should aim for that IMO.

1 Like

Are you aware of any bindings that have it, so I can learn how it is done in development?

I was thinking of Tags

Tagging is a new feature and only a few I/O add-ons have implemented it. The easiest way to determine if tags have been implemented in a specific add-on is to see if the add-on documentation explicitly discusses their usage. Tags will be ignored if no Items in the openHAB installation support it.

from https://www.openhab.org/docs/configuration/items.html#tags

#Item Tag v2 Support
Version 2 (v2) of the Alexa skill used openHAB HomeKit style tags to expose items to Alexa. Version 3 (v3) of the skill supports this by translating v2 style tags to v3 metadata labels internally. These tags are still required if the items are being exposed to the HomeKit or Google Assistant integrations. Below is the translation of v2 tags to v3 labels.

from https://www.openhab.org/docs/ecosystem/alexa/