Foreword
If you are unsure of what the Semantic Model is, or what it can do for you in openHAB 3, then check the documentation here.
This post is my notes on creating a Semantic Model via the configuration files (*.items files), rather than the UI.
Background
I read this post, and used this list in order to work this all out.
General
The Semantic Model is made up of Items with extra bits of information tagged on to them. These extra bits of information tell openHAB a little bit more about what the Item is, such as whether it is a Location, an Equipment, a Property or a Point.
You can tag existing Items, or create new ones.
Locations
Locations within the Semantic Model are Group Items tagged with a specific location tag from the list.
A quick note: Locations within the Semantic Model are not the same as a Location Item.
- Location Item: a proper Item that holds latitude and longitude values.
- Location in the Semantic Model: a Group Item tagged with a defined Location from the list.
It is unfortunate that they are both called Location!
Top level Locations
Let’s create a couple of top-level Locations, as follows:
//HOUSE MODEL
//INDOOR
Group gIndoor "Indoor" ["Indoor"]
//OUTDOOR
Group gOutdoor "Outdoor" ["Outdoor"]
Here we have defined two Locations for the Semantic Model: Indoor and Outdoor.
The tag is the ["Indoor"] or ["Outdoor"] part of the Item configuration. The text Indoor or Outdoor must be a valid location tag from the list.
The name of the Group Item itself (gIndoor and gOutdoor above) can be whatever you want. Same with the label.
If the above is saved in a Item configuration file, you will see the following within the Model section of the openHAB 3 UI:
Second level Locations
We can add more Locations within the Indoor and Outdoor Locations as follows:
//HOUSE MODEL
//INDOOR
Group gIndoor "Indoor" ["Indoor"]
//GROUND FLOOR
Group gGroundFloor "Ground Floor" <groundfloor> (gIndoor) ["GroundFloor"]
//FIRST FLOOR
Group gFirstFloor "First Floor" <firstfloor> (gIndoor) ["FirstFloor"]
//OUTDOOR
Group gOutdoor "Outdoor" ["Outdoor"]
Group gGarden "Garden" <garden> (gOutdoor) ["Garden"]
We have now added a Ground Floor Location within the Indoor location by:
- Adding
(gIndoor)to the configuration of theGround FloorItem - Adding
["GroundFloor"]tag to the configuration of theGround FloorItem
Note that there is also a <groundfloor> in the configuration: this defines the icon for this Location, and must be a valid icon name.
Note that all that we’ve been doing is creating Group Items, and defining other Group Items (such as gGroundFloor) as members of higher-level Group Items (such as gIndoor).
The Model in the openHAB 3 UI will now look like below:
Third level Locations
Now lets add a Living Room and Kitchen into the Ground Floor Location. The below is only the addition to the existing configuration from above:
Group gLivingRoom "Living Room" (gGroundFloor) ["LivingRoom"]
Group gKitchen "Kitchen" <kitchen> (gGroundFloor) ["Kitchen"]
See full configuration
//HOUSE MODEL
//INDOOR
Group gIndoor "Indoor" ["Indoor"]
//GROUND FLOOR
Group gGroundFloor "Ground Floor" <groundfloor> (gIndoor) ["GroundFloor"]
Group gLivingRoom "Living Room" (gGroundFloor) ["LivingRoom"]
Group gKitchen "Kitchen" <kitchen> (gGroundFloor) ["Kitchen"]
//FIRST FLOOR
Group gFirstFloor "First Floor" <firstfloor> (gIndoor) ["FirstFloor"]
//LOFT
//OUTDOOR
Group gOutdoor "Outdoor" ["Outdoor"]
Group gGarden "Garden" <garden> (gOutdoor) ["Garden"]
We have placed the Living Room on the ground floor (gGroundFloor), and tagged it with the appropriate Location tag ["LivingRoom"]. We have also defined a Kitchen location in the same way.
You can continue to create Locations by defining (or modifying if they already exist) further Group Items, into as many levels as you like - just add the relevant ["Location"] tag!
Equipment
Now lets create a piece of Equipment that lives in the Living Room. I see Equipment the same way as I see Things - a reference to a single real physical device, such as a relay. And as with Locations, a piece of Equipment is an Item with some extra information to tell openHAB what type of Equipment it is. Normally Equipment will be a Group Item.
In this example I will create two pieces of Equipment: a relay which turns a light switch ON and OFF, and a sensor with temperature and humidity data.
Group gLivingRoomSensor "Living Room Sensor" (gLivingRoom) ["Sensor"]
Group gLivingRoomLight "Living Room Light" <light> (gLivingRoom) ["Lightbulb"]
As with the Locations, pieces of Equipment must be tagged with names from the list - in this case ["Sensor"] and ["Lightbulb"]. Both pieces of Equipment are located in the living room (gLivingRoom).
Note that tagging is done in the same way - adding defined strings in-between square brackets. Because the list of defined names for Locations and Equipment is different, openHAB 3 knows whether your Group Item is a Location or a piece of Equipment.
Points and Properties
Now lets add some points to the Equipment, so that we can do or read something!
Switch
For the light we will add the Switch Item which is linked to our relay (in my case via the MQTT Binding). Below is the original Item configuration, pre-OH3.
Switch sLivingRoomLight "Living Room Light" <light> { channel="mqtt:topic:sLivingRoomLight:switch" }
And now with Semantic Model tags:
Switch sLivingRoomLight "Living Room Light" <light> (gLivingRoomLight) ["Switch"] { channel="mqtt:topic:sLivingRoomLight:switch" }
We have added this Item into the (gLivingRoomLight) Group, so it is now part of the Living Room Light Equipment.
We have tagged the Item ["Switch"]. openHAB 3 now knows this is a Point with a type Switch. Again, we must use the defined Point names from the list.
Sensor
For the sensor we will add the two Items which hold our sensor information. In my case again this information is coming from the MQTT Binding.
Number nLivingRoomTemperature "Temperature [%.1f°C]" <temperature> (gLivingRoomSensor) ["Measurement", "Temperature"] { channel="mqtt:topic:swLivingRoomShortLight:temperature" }
Number nLivingRoomHumidity "Humidity [%.1f%%]" <humidity> (gLivingRoomSensor) ["Measurement", "Humidity"] { channel="mqtt:topic:swLivingRoomShortLight:humidity" }
Adding to the Sensor Equipment is as before - add (gLivingRoomSensor) to the configuration.
The temperature Item has tags ["Measurement", "Temperature"]:
- Point type
Measurement(from the list!) - Property type
Temperature(from the list!)
Logically, we are measuring a temperature at this Point. Similarly, ["Measurement", "Humidity"] for the humidity Item means openHAB 3 knows that we are measuring a humidity at that Point.
Note that it doesn’t matter which way round the Point and Property sit inside the square brackets: ["Measurement", "Humidity"] is the same as [ "Humidity", "Measurement"] as Points and Properties do not share any tag names.
Summary
- Locations = Group Item
- Equipment = Group Item*
- Point = Item (single)**
- Tag = name from the list inside square brackets, at the end of a Group Item configuration, or just before the Channel definition for a single Item.
[*] normally, though theoretically you could tag a single Item with an Equipment tag.
[**] normally, though a Group Item could have a Point tag as long as it also isn’t a piece of Equipment.
Other notes
- Points do not necessarily have to live in Equipment. A Point can live in a Location just by itself.
- If part of the Semantic Model was defined and created using the UI you may find that your stuff has lost its position in the model after a restart of openHAB. Recommend that it’s either all UI, or all configuration files, but not a mixture, to reduce unpredictability!
)
which has multiple items (e.g. on/off switch and color wheel) I fully get the idea to represent the physical lightbulb (in addition to the openHAB Thing) also as a Group Item (aka Equipment) - with multiple items (e.g. Switch item, Color item) linked corresponding to semantic Points (e.g. switch type Point and setpoint type Point). But in case the physical lighbulb has only an on/off switch (nothing else) it would mean that by introducing the semantic model, I would not only need to add a tag (in my item file) but also an additional Group Item…
