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

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.


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)


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:


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.


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.


#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.


Only a few channels have tags, and none of them are one the semantic ones: see

@ghys : Can you explain what tags should be added to a channel representing a temperature for example?
I could then update few bindings to add what is required.

For example:
If the channel measures a temperature, ["Measurement", "Temperature"]
If it’s a setpoint of a thermostat, ["Setpoint", "Temperature"]
If it’s a CO Alarm, ["Alarm", "CO"]
The first tag is the Point class and the second, the related Property.

For Points:
In general alarms should have ["Alarm"], read-only items ["Status"] unless there’s a more appropriate Point class, and items that control something ["Control"].
The difference between ["Measurement"] and ["Status"] is subtle, generally ["Measurement"] is for quantifiable values and ["Status"] for discrete values.

For Properties:
If it’s a volume channel, for instance of a media player or speaker, add ["SoundVolume"].
["CO"], ["CO2"], ["Gas"], ["Smoke"], ["Water"] can often make sense as related properties of Alarm points.
["Light"] is tough, I have used it both with ["Measurement"] (for luminance sensors) and ["Control"] or ["Switch"] for channels of lightbulbs (dimmers or switches).
Similarly, ["Presence"] can be a related property of a ["Status"] point or an ["Alarm"] point - you can have the actual presence status in the status item and set the alarm item only when you’re away. Maybe at some point the UI will present you in the home page all your Alarm switch items that are ON, and offer the ability to acknowledge by setting them back to OFF.


@ysc : I started adding a lot of tags on my items. I am now just amazed by the result when I then go in the tabs Locations, Equipments and Properties.
I see that in the locations tab, properties are not displayed in case you have no equipment attached to your location. This is something already corrected or shall I create an issue ?

Thanks, confirmed. Fixed in - I believe it can make the release.

@ysc I’m trying to wrap my head around the semantic model and how to adapt my setup to it and I have some questions that I hope you can answer.

Scenario 1

Say I want to have a single dimmer control all lights in a room. This dimmer item has no knowledge of any channels etc, that varies by room and may trigger rules as well.

Can a point have a location but not be related to an Equipment?

Scenario 2

I have written a scene based set of rules that control my lights most of the time. The only user control for this system is selecting the scene.

Is there a Property that lines up with the concept of Selection widgets in the UI?

1 Like

Yes. If you select a location in the model page you’ll have a button to add a Point directly under it, which means you can do it.

For Scenes, you can simply have a Point (no special class) at the root level, or even an item outside the model, remember it’s not mandatory to tag all your items.

Yeah I could have answered that one myself :expressionless: sorry

Right, I was more looking for a means for the UI to have introspection on the possible states for a String item. In digging around I wonder if I’ve stumbled on it: stateDescription?

But of course. I’ve been looking too closely to understand and apply the ontology to my entire system.

Thank you