OpenHAB 5 Semantic Model Proposal

1

I’ve been using openHAB for over seven years, and during that time, I’ve seen the platform evolve into an incredibly powerful system for home automation. Yet, my recent experience trying to implement the Semantic UI project by hmerk brought to light how the current semantic model can become a stumbling block. Inconsistent tagging, scattered workarounds, and limited clarity all point to deeper structural issues. As openHAB is a community-driven project, I’d like to share a new structured semantic approach for openHAB 5, in the hope that it sparks discussion, collaboration, and an even more user-friendly future for everyone. This proposal was made after hours of debate with Chat and Claude about different ideas and approaches. So blame AI if you don’t like it :slight_smile:

A Structured Semantic Model for openHAB 5: A Proposal

1. Introduction

Semantic modeling in openHAB is about providing meaningful structure to your smart home Items, so you can easily:

  • Navigate the UI (e.g., grouping devices by location or function).
  • Automate tasks based on consistent categories (like “turn off all lights”).
  • Integrate with voice assistants, which can discover devices more intuitively.

However, the current model (Locations → Equipment → Points) can become confusing or inconsistent even for simple devices, never mind more complex devices or multi-function sensors. Community members often resort to workarounds, injecting extra metadata or naming conventions to force a better UI experience. This suggests a streamlined, structured approach that helps every user—whether setting up a simple lamp or managing complex gear like EV chargers and solar inverters—achieve predictable, effortless control.

2. Current Model Challenges

  1. Tagging Confusion

    • Many users struggle with which tag combination to use: “Measurement,” “Property,” “Equipment,” “Point,” etc. The documentation doesn’t fully address advanced devices, leading to guesswork.

  2. Limited Handling of Complex Devices

    • EV chargers, multi-sensors, solar inverters, and other modern gear don’t fit neatly into existing categories. Attempts to tag them often result in ad-hoc or custom tags that aren’t fully recognized by the auto-generated UI.

  3. Inconsistent Workarounds

    • Projects like semanticHomeMenu or “Enriched Semantic” rely on extra metadata and naming conventions to produce better UIs. While clever, these approaches diverge from the official model, causing fragmentation.

  4. Documentation Gaps

    • The official Model Tutorial covers basic usage but not more advanced expansions. Forum threads are full of partial solutions and repeated questions on best practices.

3. A New Structured Approach

3.1 Vision & Rationale

The proposal for a future openHAB 5 centers on a three-tier hierarchy:

  1. Location – A physical or logical area (e.g., “Living Room,” “Garage,” “2nd Floor,” “Front Yard”).
  2. Device – A recognized category (e.g., “Light,” “Thermostat,” “EVCharger,” “DoorLock”) from an official dictionary maintained by openHAB.
  3. Endpoint – An individual control or measurement (e.g., On/Off, Dimmer, Temperature, LockState).

Each Location remains flexible in naming (e.g., “Main Floor,” “FirstFloor,” “EG” (Erdgeschoss))—the crucial point is that you identify it as a Location rather than guess at tags. The system recognizes this item as a location group in the hierarchy. Devices within that location choose from a curated dictionary, and Endpoints define specific control or measurement functions. This ensures clarity for both the UI and any automation or integration features.

3.2 Official Device Dictionary

  • A maintainer-approved list of categories (Lights, Locks, Cameras, EV Chargers, Multi-Sensors, etc.) to cover most household needs.
  • The community can propose new categories via a process—ensuring consistent coverage without custom “one-off” tags.
  • Aligns with voice or automation “device types” (e.g., “all Lights,” “all Thermostats,” “all EV Chargers”).

3.3 Benefits at a Glance

  • Clarity: Define “KitchenLight” with category Light rather than guess at multiple tags.
  • Consistency: Everyone’s “Light” device is recognized the same way, so the UI reliably groups or controls them.
  • Scalability: Multi-sensors, solar, specialized devices integrate systematically if added to the dictionary or matched to existing categories.
  • Better User Experience: Freed from ambiguous tag combos, the UI can automatically display “all lights,” “all thermostats,” etc., with minimal user input.

4. Use Case Examples

Here’s a snippet of how your semantic model might look:

House (Location)
 └── Kitchen (Location)
      └── KitchenLight (Device category=Light)
           ├── OnOff (Endpoint type=Switch)
           └── Brightness (Endpoint type=Dimmer)

4.1 User Interface

  • Action: “Show me all lights in the House.”
  • Result: The UI gathers every Device tagged with Light, including KitchenLight. The user can easily toggle or adjust brightness.

4.2 Automation Script

getDevicesByCategory("Light").forEach(light -> {
    light.endpoints["OnOff"].sendCommand("OFF");
});
  • Explanation: This rule targets all Light devices and sends “OFF” to their OnOff endpoint. Add more lights later, and they’re automatically included.

4.3 Voice Control

  • Command: “Alexa, turn off all lights in the kitchen.”
  • Outcome: Because KitchenLight is defined as a Light under the Kitchen location, voice assistants recognize it with no extra manual mapping.

4.4 Additional Examples

  • Battery Monitoring: A motion sensor device with a BatteryLevel endpoint can appear in “all battery statuses,” making checks or alerts easy.
  • EV Charger: Mark GarageCharger as EVCharger, with endpoints for ChargerOnOff and ChargingPower, simplifying both UI displays and voice commands.
  • Security Check: A DoorLock device in each room can be toggled or monitored as one category across the entire house.

5. Expanding the Vision

5.1 A Unified Experience

  • Consistent UI Generation: Each Device category is known, so the UI logically arranges or groups devices without random tags.
  • Simpler Rules: Queries like “get all motion sensors in the house” or “list every temperature endpoint above 25°C” become straightforward.
  • Reduced Documentation Confusion: Clear guidelines: “Add Location → Pick Device category from dictionary → Define endpoints.”

5.2 Community Inclusion

  • The official device dictionary is collaborative: if a new device type (like “PoolPump” or “AirPurifier”) gains traction, maintainers can add it.
  • Everyone benefits from a shared standard, minimizing fragmentation and guesswork.

5.3 Seamless Maintenance

  • Clean Hierarchy: You see a structured “House → Room → Device → Endpoints” tree, making it easy to visualize and maintain.
  • Designed for Growth: Large or small installations stay organized and query-friendly.

5.4 Potential Future Enhancements

  • Localization: Map “Light” to “Lampe” or “Licht” in different languages without breaking the structure.
  • Standardized Scenes & Modes: Possibly define “Scene” or “Mode” categories in future expansions.

6. Challenges & Clarifications

This proposal is not without potential pushback or complexities. Below are some common questions and how the new approach might address them:

  1. Do I Need Rigid Location Names?

    • No. The system only needs to recognize that an Item is a Location; you’re free to name it “GroundFloor,” “1st Floor,” “Main Level,” etc. The key is that it’s tagged or declared as a Location in the hierarchy, not that it follows a preset naming scheme.

  2. What if a Device Spans Multiple Rooms?

    • Typically, devices belong to one primary location. If you have truly shared devices (like a multi-room speaker), you might designate a “Common Area” location or choose whichever room is most relevant. The structured approach still applies.

  3. How Do We Handle Virtual or Outdoor Spaces?

    • Locations can be conceptual (e.g., “Backyard,” “Garden Shed,” “Roof”). The proposal doesn’t force a single naming strategy; it only requires that you classify the group as a Location in the model.

  4. Why Not Keep Using Custom Tags for Exotic Devices?

    • Custom tags lead to inconsistent UIs and confusion. By adding new devices to a maintained dictionary, everyone benefits from uniform behavior, standard icons, and streamlined queries. That said, the dictionary can grow to accommodate real-world scenarios.

  5. What About Migration from openHAB 3/4?

    • A future openHAB 5 could offer a migration assistant, or users can manually reclassify Items into the new “Location → Device → Endpoint” structure. The community’s experience suggests that partial or automated migrations might not be perfect, but the end result is a more coherent model.

  6. Are We Overcomplicating Simple Use Cases?

    • Not really. If you just want to set up a few lights and sensors, you pick a location, pick “Light” or “Sensor,” and assign the endpoints. The extra clarity is beneficial even for small setups.

  7. How Strict Is This?

    • “Structured” doesn’t mean you lose freedom; it means the system is consistent in how it recognizes Items. Names remain yours to choose, but the classification is what drives a more reliable UI and automation experience.

7. Conclusion

This proposal outlines a structured semantic model designed to simplify openHAB setup for both novices and power users. By using a clear hierarchy—Location → Device (category) → Endpoint (type)—with an official device dictionary, openHAB can eliminate inconsistent tagging, streamline UI generation, and strengthen integration with voice assistants and automation rules.

  • Locations remain flexible in naming but consistently identified as hierarchical areas.
  • Devices align with recognized categories rather than arbitrary tags.
  • Endpoints capture specific controls or measurements, avoiding the confusion of vague or overlapping tag combos.

Thank you for reading and considering this approach. I look forward to hearing your perspectives and working together to make openHAB more intuitive and user-friendly.

8 Likes
2

Would it be possible that a device can be assigned to multiple locations?

3

As I understand it from the comments he’s made about the topic, the semantic model originally was a fairly experimental and rough feature that Yannick added as he was building the the new OH3 interface. In the intervening years, there’s been a lot of great work from many of the UI contributors to grow the model’s features and usability. In the end however, it will always remain fundamentally just one thing: a human friendly system of organization of OH items.

That said, I don’t see how this proposal is different than what already exists. Can you show more concrete examples of the functional difference between what exists and what you are proposing? The vocabulary has changed from Equipment → Device and Point → Endpoint, but the relationship between these things in a

is exactly the same. And, as far as I can see, all the other things listed as “new” under section three already exist as well. There is an official semantic document what defines the options available in the base model and their relationships; the UI groups all these things by each of the possible categories in the overview page tabs, my many different multisensors are not the things in my home that I have had any trouble fitting into my model categories (the sensor equipment works quite well for that, for me).

This is (new vocabulary aside) precisely what my semantic model already looks like. Again, what is it about this that is new in this proposal?

I think this is the theme that I fundamentally don’t understand. You make several similar references to this idea that the current semantic tags are somehow confusing. It is true that I have a few devices and items that don’t 100% correspond to pre-configured list. But that is precisely why there is now the ability for the user to expand that list to cover these special circumstances.

Before I can really grasp what it is that you are proposing here, I think I need to see an example or two of what you see in your current model that is confusing with “multiple” or “ambiguous” tags, and what about this proposal actually reduces those tags.

5 Likes
4

No, it can only be included in one semantic group.

5

Interesting, but are you implying to remove the ability to add custom tags? Or only in the semantic tree?

I use them a lot in combination with rules to implement behaviour. For example adding a tag ‘dusk’ to a light or switch will turn it on when it’s dark and off when I got to bed.

6

Remember, these are some ideas that came from having to try and solve issues and frustrations. We really need to make OH easier to use.

Below is a concise explanation of why this change is being proposed, how it solves the current model’s pain points, what it does to simplify UI generation (especially compared to hacky or forced renaming in Semantic UI projects), and concrete examples of multi-sensor and AV receiver setups. The goal is to demonstrate how a structured device/endpoint approach in openHAB 5 can resolve confusion and enable easier automation, voice control, and UI creation.

1. Why Change the Current Setup?

1.1 Existing Pain Points

  • Multiple Tags for One Item
    In the existing system, an “Equipment” might need multiple tags (e.g., “Equipment,” “Sensor,” “Measurement,” “Temperature”) to show up in the right spots. Users often guess which combos work, leading to inconsistent or non-intuitive results in the auto-generated pages.
  • Ambiguity Around Points and Properties
    Should a temperature Item be tagged “Point_Temperature” or “Temperature + Measurement,” or both? Which is correct for the UI to recognize it? Documentation covers only the basics.
  • Complexity for Advanced Gear
    EV chargers, multi-sensors, or stereo receivers can be tricky to represent. People end up using custom tags or complicated group structures—leading to partial or broken auto-generation in the UI.
  • Renaming Headaches
    Projects like “Semantic UI” require very specific naming or metadata injection to achieve a consistent UI experience. That means renaming items or adding custom fields, which is tedious, prone to error, and still not guaranteed to be recognized by default openHAB pages.

1.2 What’s Different with the Proposed Approach?

  • Single Dictionary-Driven Classification: Each device is chosen from a fixed set (like “Light,” “Thermostat,” “AVReceiver,” “MultiSensor”), and each endpoint (like “OnOff,” “Temperature,” “Volume”) has a single recognized type. No more guesswork with multiple tags or property combos.
  • Automatic, Consistent UI: Because there’s one recognized category for a device, the system knows how to display or group it. Voice assistants and automation rules can uniformly query “all Lights” or “all Thermostats” without missing half your items.
  • No Forced Renaming: You aren’t forced to rename all your items to match some unique pattern. You simply set the device category and endpoint types. The system handles the rest in the auto-generated pages.

2. How This Implementation Solves the Problems

  1. Reduces Tag Confusion
    • Instead of “Is it Point_Temperature or Measurement_Temperature? Do I need Sensor too?” you just pick a single Device category (e.g., “TemperatureSensor”) with an endpoint for “Temperature.”
  2. Easier UI Generation
    • The UI sees you have a “Light” in the “Kitchen” with an “OnOff” endpoint—bam, it appears under “All Lights” and “Kitchen.” No extra hacks or metadata.
  3. Simplified Automation & Voice
    • Searching or controlling items by category (e.g., “Turn off all Lights,” “Check all EVChargers”) is straightforward.
  4. Handles Specialized Devices
    • Complex gear like AV receivers or multi-sensors can be modeled in a consistent way, without needing to guess multiple overlapping tags or naming rules.

3. Examples

3.1 Offer A & B for Multi-Sensor

Scenario: A device that measures motion, temperature, and battery level.

Option A: One “MultiSensor” Device (Multiple Endpoints)

Kitchen (Location)
 └── KitchenMultiSensor (Device category: "MultiSensor")
      ├── Motion (Endpoint: "Contact" or "Motion")
      ├── Temperature (Endpoint: "Number:Temperature")
      └── BatteryLevel (Endpoint: "Number:Dimensionless")
  • Pro: One device in the UI, clearly representing the physical box.
  • Con: If you query “all MotionSensors,” it might not appear unless also marked as “MotionSensor.”

Option B: Multiple Device Entries (One Function Each)

Kitchen (Location)
 ├── KitchenMotion (Device: "MotionSensor")
 │    └── Motion (Endpoint: "Contact")
 ├── KitchenTemperature (Device: "TemperatureSensor")
 │    └── Temperature (Endpoint: "Number:Temperature")
 └── KitchenBattery (Device: "BatterySensor")
      └── BatteryLevel (Endpoint: "Number:Dimensionless")
  • Pro: Granular control and easy queries (e.g., “all TemperatureSensors”).
  • Con: More “devices” in your model than physical boxes, which some find cluttered.

Either approach is better than juggling multiple property tags for each item. You pick from a recognized dictionary (e.g., “MotionSensor,” “TemperatureSensor,” or “MultiSensor”) so everything aligns with the auto-generated UI.

3.2 AV Receiver / Stereo System

LivingRoom (Location)
 └── AVReceiver (Device: "AudioSystem")
      ├── Power (Endpoint: "OnOff")
      ├── Volume (Endpoint: "Dimmer" or "Number:Volume")
      └── InputSource (Endpoint: "String" or "Selection")

Why This Is Easier:

  • You don’t need to guess if you tag it ["Equipment","Audio","Control"] or ["Equipment_Audio"] or ["Media"]. Instead, you pick the known dictionary entry “AudioSystem” or “AVReceiver.”
  • Endpoints get typed once, and the UI knows how to group or label them (e.g., “Power,” “Volume,” “Input”).

4. Conclusion: What This Proposal Aims to Solve

Core Goals:

  1. Eliminate Tag/Property Ambiguity: No more “Which tags do I use for temperature or motion?”—you pick the recognized device category and endpoints.
  2. Streamline UI Creation: The system automatically knows how to display or group your gear (lights, thermostats, sensors, AV receivers) without special naming or metadata hacks.
  3. Enhance Voice & Automation: Queries like “all Lights” or “all MotionSensors,” or “turn off all AVReceivers” become trivial, because everything is consistently categorized.
  4. Reduce Renaming Hassles: No forced item renaming to match a specific pattern; you simply classify them under the new dictionary-driven approach.
  5. Offer Flexible Multi-Sensor Handling: Either define one multi-sensor device or multiple specialized sensors—both are valid, so long as you stay consistent with the dictionary.
  6. It doesn’t stop anyone from doing custom tagging - it just means that a UI or Rule won’t use that tag.

Ultimately, this structured approach ensures openHAB automatically creates cohesive interfaces, voice integrations, and rule logic—without the confusion, guesswork, or advanced “Semantic UI” hacks the current model often demands.

4 Likes
7

If you followed the project, this has been introduced due to massive performance issues, which cannot be solved with your proposal.
It is the fact that strictly using the semantic information would require the use of a lot more oh-repeater components, which will slow down the UI until it is no more usable.
We have been at this point already.

8

I have over 120+ equipment group items in my model. Not a single one of them requires multiple semantic tags. In fact, what you have here is not a correctly configured model. Sensor is an equipment tag and is the only tag you need in this example on an equipment group. Measurement and Temperature are point tags and don’t belong on the group item at all. You can’t even add those point tags to an equipment item from the UI unless you manually type them into the 'Non-semantic Tags" section of the item editor. The same is true for multiple equipement tags; the UI properly enforces only a single semantic equipment tag.

Again, you mention guessing here. What guessing?

image
image630×630 25.3 KB

You can select one and only one from this list. If none of them are precise enough for the equipment you are creating, then you can either create your own equipment tag or just use the generic equipment.

Are you using text files to create and configure your semantic model? That has been discouraged from the very beginning for exactly the kind of confusion you appear to be experiencing.

Again, Point_Temperature isn’t even an option for a point tag. It seems to me that you are mixing up several different concepts here. When the user creates an item with a semantic tag, the UI processes that item and based on the tags creates a semantic metadata namespace that can be used in several more advanced areas. The Point_Temperature is one of those metadata values. These are shown on the item details page in the UI because they are occasionally helpful for the users who need those more advanced functions, but they are not semantic tags and they are not something that a user should ever set. And, if you are using the UI as recommended, you cannot make this mistake as Point_Temperature is never found in the list of point property options.

I have never encountered this issue that you are referring to here myself. Nor can I remember seeing on the forums a question about having “complicated group structures” inside an equipment group that wasn’t an example of an improperly configured model. Can you show a real-world example of this?

You are never going to “solve” this “problem”. In addition to @hmerk’s point about the naming structure being required because of the limitations of the widget system and not the model, this is simply always going to be the case. If you want the semantic model to be approachable to new users and useful for general users you must keep the amount of information included in the model to some reasonable limit. More advanced projects are going to require layering additional information on top of that and it is impossible for the OH devs to predict in advance all the different types additional information that will be needed by custom projects in the future. Whether that extra information is in the form of item naming conventions or tags or metadata is up to the creators of that project and the design parameters.

The model was originally just a fixed set of options and users repeated asked for the ability to customize and extend that. Going back to a fixed list would likely strike many users as a significant step backwards. It would certainly break my model where I have incorporated several additional custom semantic tags.

I think this already breaks down for 2 reasons.

  1. that there just isn’t enough consistency in home IoT outside of OH to be sure that every example of a particular type of device is going to use the same data type for the same function. As a very basic example, most devices report battery as a percentage estimated remaining, I have some that actually just report a boolean battery is low True/False and one that reports raw voltage. Automatically assigning an item type based on semantic point type is too rigid. The semantic model is about being able to tell OH what the structure of your system is; not OH telling you what the structure of your system has to be.
  2. You have already lost critical information. I am starting to get the impression from some of your comments that you are concerned about the difference between the Semantic Class and the Semantic Property of a point. It is this combination that determines what the default representation of the point will be in the autogenerated pages and lists. But this combination of information is absolutely critical in many cases. For example, you bring up thermostats many times as a typical “complex” device. Well my thermostat has 6 different points with of the property Temperature. I don’t want all of these rendered in the same way because some of them are measured values of the ambient and out door temperatures and some of these are value that I can set for the function of the thermostat. These two different types are then rendered as Measurement and SetPoint classes respectively and now the UI knows based on the combination of class and property which component to use to render this item. Sure, you can create two different “endoints” such as TempMeasure and TempSet, but then once again you’ve just recreated what already exists.

OH already “knows” how to display Semantic Points based on the information. I really don’t see where you are getting that it doesn’t. As with all things OH, sure the docs could be a little more comprehensive, and there are surely some combinations that users would like to see or are a little unusal. But the automatic overview pages are at present the main benefit to setting up the model in the first place for most users, so it just doesn’t make sense to me that adding a semantic UI is different in this proposal.

Once again, however, no out of the box solution is going to cover all the possibilities unless it is too limited to be useful to new and advanced user alike. Going back to a temperature example, If I have a thermostat, smart water-heater, and a smart oven, all of those are going to have a point to set a temperature, but I might not want the same widget to display in all those cases not just because of the various ranges (which could be handled with proper state description metadata), but because I might want different visual warnings within those ranges, such as a very bold red value if I accidentally turn my water heater up to 200 °F. So instead, you as an advanced user have the ability to modify how the model renders any single one of its parts.

I don’t use voice assistants, but I use several jsscripting rules that take advantage of semantic data. I have never experienced it missing my items. This sounds, again, like an improperly configured model.

You are not forced to rename anything with the basic OH semantic model. Again, this is no different than what currently exists. If you wish to utilize some other system that also includes a need for renaming items then that is a feature of that other system and it may include semantic data or not, but there is no correlation at all between the current OH semantic model and item names. If you don’t want to rename you items, then don’t use whatever that other system is.

Ultimately, from my perspective, I continue to see nothing that is truly new here. It seems you are trying to address two classes of problems: 1) complexity of model configuration and 2) utility of the model. But these are not actually independent. Currently, if your model is properly configured then all the utility problems you have identified disappear. As for the configuration problems, those appear to come down to two fundamental points: 1) the docs could be more comprehensive, and 2) the model is easier to configure if there are predetermined options. Well, the model is one of a hundred places where the docs could be expanded and the predetermined options are already there if you use the UI which is the recommended approach for exactly this reason.

Note that this does not mean that I believe the model as it currently stands is perfect. There are definitely some ways it could be made easier for users to get to a properly configured model (I have contributed some PRs towards this goal myself). But, I do not agree with the idea that that need is a problem with the way the model is structured, that need is just a lack of UI devs with the time to prioritize this.

6 Likes
9

This is now no longer possible (in 5.0). The non semantic tags input will not accept valid semantic tags now.

3 Likes
10

I believe the location should be recursive, as it currently is. That way you can have e.g. some locations in the First Floor, others in the Basement, and tell the system to turn the lights on the First Floor off. That would include lights in the Kitchen, Living Room, etc., but nothing from the other floors.

1 Like
11

This has already failed. What will be done to make sure this time will be different? This is why the ability to create custom semantic tags was implemented in the first place.

Also, this list will grow very long. Is a list of 100 tags really an improvement over defining your own custom tags?

The rest seems to describe pretty much what the semantic model already offers with some nuances and improvements which I think would be kind of nice.

Today you could use

items.getItemsByTag("Light").forEach(light => {
  light.members.filter(endpoint => endpoint.tags.includes("OnOff"))
               .forEach(endpoint.sendCommand("OFF"))
})

A built-in action would be nice though.

:point_up_2:

I wonder if the main problem is documentation here, but I don’t really see anything above that is significantly different from what we already have.

Maybe we are missing the fact that a custom tag inherits from an existing tag. So if for some reason you did want to create a separate Equipment for your multisensors, you could and have it inherit from sensor and the UI would treat it the same as a sensor.

I’m not going to argue that there is no room to add some more tags to the Equipment and Point/Properties tags (and maybe remove a couple too) but from reading the above it sounds like the assumption is that custom tags are just hanging out there unconnected to anything.

I’m not sure that’s a great use of a semantic tag. You could use dusk as a tag without adding it as a semantic tag and not even need to change your rule. That’s an example of trying to shoehorn a functional model into a physical model.

The Point property controls what UI element is used to display it. The Property tag controls which card the Item is shown on the third tab of the Overview page.

The Point tag is the “what does it do” and the property tag is “what does it do it to”. For example, a smoke alarm could be tagged with Alarm and Smoke. A leak alarm with Alarm and Water.

I don’t want the voice assistants to have access to all my semantically tagged Items, ever.
But each voice assistant has its own model which does not fully correspond to OH nor the other systems (GA is different from Alexa for example). So there will always be some required translation.

But Motion is the motion sensor. Query for all motion sensors and it’s Motion that you should get. And then if you need to you can get to the Equipment KitchenMultiSensor from the Motion since that’s the parent Equipment Item. KitchenMultiSensor doesn’t need to be tagged with MotionSensor.

You can do that with what we have now without breaking it up like that.

Using the currently semantic model it would look like this:

Kitchen (Location)
  |__KitchenMultiSensor (Sensor)
    |__Motion (Measurement/Motion) // Note there is no Motion property but there should be
    |__Temperature (Measurement/Temperature)
    |__BatteryLevel (Measurement/Power)

In a rule if you want all the Sensor Items that have a motion sensor as part of them:

items.getItemsByTag("Sensor").filter(s => s.tags.includes("Measurement" ) && s.tags.includes("Motion"))
                             .map(s => s.getEquipment());

Replace getEquipment() with getLocation() to get all the locations which have a motion sensor.

Maybe this is the root of your problem. But what you are proposing is how it works now.

LivingRoom (Location)
  |__AVReeiver (Receiver)
    |__ Power (Control/Power)
    |__ Volume (Control/SoundVolume)
    |__InputSource(Control/Media) // I'd probably create a custom tag Input here that inherits from Media

You don’t have to guess on the tags.

That’s how it already works. And the default widget shown is based on the Item type and the Point tag. If the Point tag indicates it’s something that can be commanded (e.g. Setpoint) it chooses a slider widget. If it is a tag that indicates a sensor (e.g. Measurement) it uses a label widget.

Already exists but needs better documentation clearly.

At least with Google this is already handled. With HABot this is also already handled. And I showed above how it can be done in rules.

Already possible. The only difference is if the dictionary doesn’t have something you need, you can create the tag you need.

Why not? That would be a step backwards.

I agree with @JustinG, I think this is a documentation problem coupled with using .items files for the most part. Because there is very little in the proposal that is significantly different from what we have now and in some ways is significantly more limited than we have now. And it seems like your biggest problem is with limitations in a third party widget and MainUI which is outside the semantic model in the first place.

  • Which tags to choose? For managed Items you are presented a list with only those tags that are appropriate.
  • Renaming Items? Not a semantic model issue.
  • How many tags to use? Exactly one for Locations and Equipment. Up to two for Point Items, exactly one Point tag and 0 or 1 Property tag.
  • Complex equipment? The Equipment tag identifies the type of the Equipment (e.g. Receiver) and then for the members of that Group Item each Item has a Point tag indicating what sort of action or data the Item represents and a Property tag to indicate what type of property the Item represents (e.g. Setpoint/Temperature for a thermostat target temperature verses Measurement/Temperature for a thermometer reading).
  • Don’t have a tag for something you need? You can define a custom tag and have it inherit from an existing tag. OH will treat this new tag the same as the one it inherits from. For example, I’ve created a Location called “Den” which inherits from “LivingRoom”. If ask HABot for all living room equipment it will return the equipment for the Den.

@mjcumming I would really like to know what documentation you looked at, what you understood and didn’t and maybe we can figure out how to make them better.

5 Likes
12

I appreciate everyone’s feedback. After reading through the thread, though, it seems we’re bumping into the same core challenge: openHAB’s current semantic model, while powerful, was never tightly structured around a “device-centric” view—unlike Home Assistant’s clearer “devices and entities” approach. That flexibility is a hallmark of openHAB, but it also makes the platform harder to learn and maintain, which arguably does impact user growth compared to Home Assistant’s more intuitive defaults.

It’d be great to elevate the conversation around how we can unify and simplify openHAB’s model without losing the advanced capabilities. Instead, these discussions often get stuck in the stance that “if it works for me, it’s fine,” which can dismiss the frustration new and even experienced users face with more complex or custom setups. There’s room for fresh ideas that could make openHAB’s semantic model more approachable and robust—without forcing anyone to abandon existing configurations or workflows.

Hopefully we can find ways to improve the overall usability, rather than just tearing down proposals. The success of other platforms highlights the growing preference for a more structured and user-friendly approach—one that still supports power users. My hope is that we can keep an open mind about new solutions that could make openHAB more appealing and accessible to a broader community.

7 Likes
13

Your suggestion makes sense for me. (The current model does not. Which is why I have not implemented it…)

14

You are conflating two different topics here.

In the last few months, I’ve actually spun up an HA container because I have a device where the communication with OH was just not up to the level I wanted. HA claimed to be able to deliver, and it did and now I use HA as a bridge to MQTT for a small handful of my devices.

You are mistaking the OH’s semantic model for the actual functional structure. OH’s bindings → things → items structure is parallel in nearly all functional ways to HA integration → device → entities structure. The difference is that HA automatically populates much more of that tree for (whether you want it to or not) and OH makes you build it yourself. In HA the “semantic model” is still separate from the actual integrations (it appears to be the Locations and Areas settings), and there HA follows the same structure as OH model (and your proposal) of location → device → entity.

HA does make it fewer clicks (slightly) to build a model around the devices you have configured, but whether this is a good thing is a matter of opinion. I have not made any attempt to configure locations in my bare-bones HA and, yet, it has numerous rooms listed (some accurate, some inaccurate). Where did it get this information? Clearly, at the very least, it scrapped much of this info from my Sonos system, an integration I never told it I wanted, and, in fact, disabled at the first available opportunity. This was, for me, nearly enough reason to turn off HA completely and try a different route for my extra devices. This is not intended to turn into another OH vs HA digression just one example of how whether HA does it or not should be 0 factor in how OH progresses.*

*- disclaimer: I find HA to be a PITA. If OH’s communication with these other devices reaches parity with HA, I will drop this HA → MQTT bridge like a hot potato.

I don’t think anyone here is opposed to this. However, to start that conversation in a meaningful fashion there must be a consensus on the starting point or “unifying” and “simplifying” become just jargon.

No one has said that here. I have said explicitly that “There are definitely some ways it could be made easier for users to get to a properly configured model”. Rich has said (apologies, if I mis-interpret), you’re right, there’s confusion here, let’s tackle the docs and see if that fixes it before we try and “fix” something that isn’t actually broken.

Couldn’t agree more.

I apologize if you feel that the goal has been to “tear down”, your proposal. You have my assurance (for whatever value you put on that) that the goal is to get the facts straight so that any subsequent discussion is starting on the correct foundation.

However, the truth of the matter is that the proposal, at least as initially articulated, does not actually include many “fresh ideas” but does, in fact, push some significant inaccuracies and contributes to more confusion. I don’t know how many of these inaccuracies are your own experience or just come from the AI chat you say was the foundation of your proposal, but any discussion based on these misconceptions will be meaningless at best, if not actively detrimental to less experienced users.

If your argument is that OH’s semantic model lags behind HA’s in usability, but you (as it appears, though you have not verified this) are basing your opinion of OH’s model on text-based attempts to configure it, then you are not even comparing apples to oranges, you are comparing souffle to oranges.

Please, by all means, work with the information Rich and I have provided to correct and refine your proposal. If you feel that in light what new information you have been given, there’s still something critically new in your proposal then show me where I’ve gone wrong (I never mind being shown I’m wrong, that’s one good way to learn). That’s how this system works best. But, please, do not interpret counterpoints to your proposal as “close-minded”, gate-keeping, or malice because they are a part of the process too.

5 Likes
15

tl;dr: The proposed solution is not significantly different from what the current semantic model does but is much more limited in many ways (e.g. how do you distinguish between a temperature setpoint and sensor reading?), depends on a process that has already failed to maintain a fixed list, and attempts to solve problems that originate not from the semantic model but custom UI widgets inability to effeciently access the model in the first place combined with misunderstanding how the current model works.

All of the capabilities listed are already supported by the existing model.

Most of the pain points would not be addressed by this proposal and instead need new MainUI base widgets that are semantic model aware.

The rest of the pain points would be addressed by documentation and updates to the tooling (e.g. VSCode extension.) since they come from not understanding how the current model uses tags.

Below I lay out what parts of OH are touched by the semantic model (to scope what it means to replace it), the high level requirements the semantic model needs to implement, a point by point comparison of the proposal to the current semantic model and finally examples of how the current semantic model currently supports all the “benefits” listed.

Summary of my recomendations:

  • Improve documentation
    • How to create custom tags
    • Tag hierarchy
    • How different tags are interpreted tby MainUI to select default widgets
  • Make semantic data more available in an effecient way to UI widgets and/or new UI widgets that can efficiently use this data
  • Improve tooling for file based users (e.g. add semantic tagging to the VSCode extension)
  • Improve the default set of tags to include more commonly used devices, and properties.
  • Add some error checking to .items file parsing and report when the semantic tags are not valid (e.g. mixing an Equipment and Properties tag, more than one tag of a given type, etc).

If we want to go there then I can say these threads usually get stuck in “I don’t understand it therefore let’s burn it down and build something new” and the “new” ends up just repackaging the old.

But I’m not trying to tear down anything. There is a lot of room for improvement in the semantic model. I’m all for improvement here. But the semantic model is tied into a whole lot of OH. If we are going to burn it down and start over there has to be a high bar to pass to make the work worth while.

Maybe if we lay out the scope and requirements we can move this discussion forward.

Scope

So where is the semantic model used today?

MainUI:

  • Overview tabs
  • Model
  • Item creation
    • From Model
    • From Items
    • From Things (create equipment from Thing, create points from Thing)

Rules:

  • semantic actions to navigate the semantic hierarchy

Core:

  • custom tags
  • REST API endpoints

HABot:

  • the semantic model was originally developed for this

These are all the parts of OH that will be touched by singificant changes (completely rewritten in some cases) to the semantic model. It’s a big job.

Requirements

So what do we need the semantic model to do for us?

  • build a hierarchical representation of the home automation
  • add information in that representation so that reasoning can be performed against the model
    • how to indicate this Number Item is a setpoint but that one is a sensor reading?
    • how to identify all the devices (maybe of a given type) in a location?
    • how to determine certain Items belong together as part of a single device?
    • how to indicate all the Items dealing with a certian type (e.g. all temperature Items, all humidity Items, all lights items, etc)

Problems with the current model identified in this thread

Very fair statement. It can be confusing. It’s doubly so if one is trying to apply the model using .items files because you have no UI to guide you and prevent you from making mistakes. But it’s only as consistent as you use it. If you use tags inconsistently there’s nothing any model can do to help with that.

All the workarounds pointed out here and the UI experience identified are not caused by the semantic model as it exists today but are caused by limitations in the openHAB API. The root problem is the semantic widgets @hmerk et al created can’t actually use the semantic model. The workarounds stem from that, not limitations in the semantic model itself.

I think fixing this problem is a great idea and I bet @JustinG would agree. But the problem here isn’t the existing model, it’s that the model isn’t available to custom UI widgets in an effecient enough manner to make use of them.

This is something that should be addressable in the current system. I think that a number of tags are poorly named, there are a number of important tags that are missing, and a number of tags that don’t make a lot of sense and IMO should be eliminated.

But this shows a confusion because you don’t really use a combination of tags on a single Item except for Point Items and there you select one tag from one list and another tag from a separate list.

When using the UI, there is no confusion about which list is appropriate because you are only presented with the list of viable options.

Documentation definitely needs imrpovement. But what do you mean by “advanced devices”? Do you mean devices made up of multiple Items?

I think you are referring to the custom UI widget you are trying to use from the marketplace.

The overview tabs of MainUI and even HABot fully recognize and present custom tags appropriately.

Making the semantic model easier to use effeciently here would be the solution to this problem. Again, the problem is lack of the semantic model, not the model itself.

image
image819×277 15.3 KB

Both Media Player and Remote Control are custom tags I’ve created.

image
image1931×390 12.3 KB

image
image754×766 33.1 KB

All of these properties are custom tags I’ve created.

I can ask HABot about any of them.

image
image802×498 25.3 KB

image
image805×816 42 KB

Custom tags are fully integrated with the model and fully recongnized by OH itself. It’s the inability of custom widgets to effeciently get at this information that makes those third party components unable to use them.

But it is true that the existing sets of tags are not complete and in some cases they can be confusing (why is there a smokealarm but not a waterleakalarm for example?). Improving the existing sets of tags would be a great improvement overall. We should not have to wholly rely on custom tags.

But the complex devices part is confusing because the existing model is the way it is in order to handle complex devices. That’s why there’s an Equipment category in the first place and why you can build nested Equipment.

Again, this is a limitation of UI widgets, not the semantic model. The problem is these third party custom widgets don’t have effecient access to the model so they need work arounds to do without the model. Changing the semantic model won’t fix this.

There is already an issue open for adding docs to add custom tags. And we definitely need better documentation for the semantic model. But lack of good documentation does not justify throwing out the capability and rebuilding it in my book.

Volunteers desperately needed here. The existing issue for custom tags would be great first PR for someone since everything you need is already in the issue. A PR just needs to be generated and submitted.

A more complete and thorough documentation would be great too. Maybe added to the Items configuration page as a new section.

I do think there is room for improvement here. I think that MainUI can do a better job at guessing at the default widgets given the information it has in the already existing model. But that doesn’t require throwing out the existing model but actually making more use of it.

This is how semantic tags were originally managed. It didn’t work.

This is incorrect. An Equipment has exactly one tag chosen from the list of Equipment tags. There are no combination of tags required and in the UI it prevents you from adding more than one tag from the list in the first place.

This pain point is a fundamental misunderstanding of the existing semantic model.

Indeed the documentation needs to be vastly improved. But first of all let’s eliminate “both” because it can only be tagged with one or the other, never both.

To answer the question though, what does this temperature Item represent? If it’s a setpoint for a thermostat you’d want to use Setpoint for the Point tag and Temperature for the Properties tag. MainUI will render this as a setpoint widget.

image
image737×59 5.66 KB

If it’s a therometer you would use Measurement for the Point and Temperature for the Property and MainUI will render it as a label widget (i.e. read only) with the added bonus that clicking on it will open a chart of that’s Item historical values.

image
image737×59 3.33 KB

Switch for the Point will render a toggle.

These mappings definitely need to be documented.

But the UI will recognize it no matter what it’s tagged so long as it’s tagged with a known semantic tag. The third party UI widgets may have different restrictions but again, that’s because they can’t access the semantic model in the same way, not a limitation of the model in the first place.

In the Overview tabs there is no such limitation. One can make their Equipment hierarch as complicated or flat as needed and they will be rendered as configured. 3rd party custom UI widgets will have different restrictions.

This is because they can’t actually access the semantic model fully, not a limitation of the semantic model itself.

Comparison of the new approach with the existing approach

The existing model is three tiered.

The current model is flexible. You can name your Items anything you want. You don’t guess at tags.

image
image704×703 25 KB

But if you want a flat hierarchy you can just use Location or Room as your tag and rely on the Item name to distinguish between types of rooms. However that could cause confusion for HABot and the like but if you don’t use HABot no problem.

So this part of the proposal is less capable than what we have now. There is also no mention of whether a hierarchy is maintained. Can I have a house with floors with rooms?

image
image515×585 33.7 KB

Note, stay tuned, drag-and-drop is comming to that Model view.

This is currently called an “Equipment”. There is an official dictionary of tags for Equipment. When using the UI you get to choose from a list.

image
image705×704 29.2 KB

There is your official set. But now we can also add our own if that list doesn’t have what we need. When you create your own the tags are situated into the tag hierarchy. So if for some reason you want to distinguish between “sensor” and “multisensor” but still have multisenor be treated as a sensor, you can put it under sensor in the hierarchy.

Equipment
|__Sensor
    |__MultiSensor

Then reasoning systems that use the semantic model can say “give me all the sensors” and your multisensors will be returned too.

This proposal offers less capability than we have now which is concerning.

This is currently called Points and this is the one place where there are two tags because there are two important pieces of information needed at this level. What does the Item do and what does it do it to (called the Property)?

There are two separate official lists of tags for each. The Point list is a set of terms related to actions.

image
image705×704 23.2 KB

The current list is IMO woefully incomplete. I think a concerted effort to come up with a better default set would be a good thing.

The Property list is a set of nouns.

image
image705×704 25.9 KB

This list too is probably missing a good number of tags.

The current solution is better than the proposed solution because an Endpoint of “Temperature” (for example) isn’t sufficient. There isn’t enough information there. You couldn’t tell the difference between a thermostat setpoint and a thermometer, both of which would be a part of a Thermostat “Device”. That’s why there are two tags here.

Putting it all together, here’s how a thermostat could be represented in the current model (this is how I model it in fact). Starting with L means it’s a location. Starting with E means it’s an Equipment. Starting with P means it’s a Point.

L-My Home (Home)
|__L-Indoors (Indoors)
    |__L-MainFloor (GroundFloor)
        |__L-FrontRoom (FamilyRoom)
            |__E-Thermostat (HVAC)
                |__P-CoolSetpoint (Setpoint/Temperature)
                |__P-FanMode (Control)
                |__P-HeatSetpoint (Setpoint/Temperature)
                |__P-IndoorTemperature (Measurement/Temperature)
                |__P-ThermostatMode (Control/Temperature)

There are a few more Items but those are the ones I actually use and will remove the rest once I’m done testing. It looks like this in the UI.

image
image442×839 49 KB

Again, this is how the tags were originally managed. It didn’t work. What will be done to make sure it works this time? Who is going to be responsible for this?

The current semantic model can handle this.

There are no multiple tags to guess from. There is a single tag to choose from a list.

This happens now for those parts of the UI that can actually access the semantic model. You’re main problems are with custom UI widgets that cannot access the full semantic model.

I’m not sure exactly what is meant by this but binding authors do provide suggestions for semantic tags when you create the Items using “add equipment to model from thing” or “add points to model from thing”. They can only really suggest from among the existing set of official tags which is why I do think it’s important that we have a better set than we have now.

image
image829×749 54.6 KB

The binding correctly suggests Measurement/Temperature for the Item that will be created here that represents the outside temperature.

Is that what you mean?

This too already happens. That’s what the Locations, Equipment, and Properties tabs are all about. If I want to see every Item related to humidity I go to the Properties tab and click the Humidity card.

image
image750×753 123 KB

Or I ask HABot.

image
image790×1193 88 KB

Or in a rule:

items.getItemsByTag("Humidity")

though, as I discussed above, a semantic action that can do this would be useful.

House (House)
|__Kitchen (Kitchen)
    |__KitchenLight (LightBulb)
        |__OnOff (Switch/Light)
        |__Brightness (Setpoint/Light)

On the Locations tab there will be a card for Kitchen. In that card there will be a heading for Kitchen Light. Under that will be an entry for the Switch and another for the Brightness. The Switch will show a toggle and the brightness will show a slider.

This works like this today. (I don’t have a dimmer anywhere so can’t show this as an example.

On the Equipment tab there will be a card for LightBulb (you can change the name) with all the Equipment tagged with that. Each Equipment will have a heading and under that heading will be the controls for that light.

image
image769×758 94.9 KB

Or you can ask HABot.

image
image790×1193 88.4 KB

Already showed the code for this above.

The problem here is each voice assistent has their own semantic model and controlling scheme. Some mapping will need to be made which should be possible. In fact there is nothing stopping someone from implementing this now. If a mapping were implemented there’s nothing preventing that from working with the existing semantic model.

image
image769×758 46.8 KB

I set the visibility to false for Items that are not below a threshold or alerting so right now this card is mostly empty. But rows will appear when a battery gets below 25%.

An example of the current model of a sensor with a battery:

image
image426×502 39.5 KB

I don’t have a charger but this is possible now.

image
image759×761 82.1 KB

This is how the Overview tabs are populated today.

It’s no simpler really than what we have today. But we could add some new actions to make this even better and it would work with the existing model.

That’s how it is now.

We even have a way to do it all at once through “add equipment to model”

image
image600×1498 72.8 KB

This didn’t work before.

There should be no guesswork and we already have a standard set of default tags. That set needs some work.

Like this?

image
image665×574 36.8 KB

I think the current default set of tags are localized. Someone who uses a language other than English needs to verify.

That’s a great idea which is possible with the current model.

No, the current model doesn’t require regid location names and you can even define synonyms so the same location has multiple names. We rarely call something the same thing the same way all the time.

This is exacly how the current model works.

This is exactly how the current model works only if you do want to differentiate so you can say soemthing like “turn on all the lights on the ground floor” that it gathers all the lights in all the locations on the ground floor. If you don’t want that, just use “Location” for your tags and depend solely on the Item name and label. That’s works too.

Because maintaining the dicutionary with community involvement has already failed as an approach. And eliminating custom tags doesn’t fix anything but does prevent a whole lot.

With what is presented here so far, it’s the same model only less capable.

Agreed. Or you can not use the model if that’s your choice.

We already have all of this.

This is already too long so I’ll stop here.

4 Likes
16

While this might not bring much to the table, I can only say that I have tried a couple of times to ‘Go Semantic’. Every time I have given up, because it is not self explanatory enough and my patience is very low when it comes to spending time with things that does not make sense, and I am unsure what it would bring me in the end.

I have therefore accepted that semantic is not for me, and perhaps as a result of this(?), I don’t use much of the rest of the web user interface, but prefer files, and the old clunky rules.
Maybe, if I was installing OH as a new user today, it would be different - maybe I would be prepared to spend the extra time, and maybe it would be easier to start step by step, and not with house already full of items. But the result is that I actually don’t like to mess with OH anymore, apart from a restart every now and then, when it slows down - “it just works”. And update at least once a year, to not fall too much behind.

While writing this, I thought I should get some experience again, since it was years since I last tried. And it looks to be better, but same thing again - lots of fields to fill in, that does not make any sense to me, and referencing to ‘Items’ is that the items that I know about in my item files? Also, like the question about some Prefix (which defaults to ‘I’??). Why do I need this?
It feels like survival of the fittest - if you know what to do, and what fields that are important, then it might be simple.
Maybe you can say ‘go away and read the manual’, which is fair enough. :slight_smile:

And - I don’t mean to complain, just voicing that there are some users, that thinks this is overly complicated - and therefore simply don’t use it. Which is a shame.

I therefore hope that this could be a direction going forward. But I realize that it might also be that OH has simply outgrown me.

3 Likes
17

Hear! Hear!

4 Likes
18

If you would like to help, perhaps you could elaborate your experience, provide us with screenshots / details of what you have read / seen / tried to setup so we know where the stumbling blocks are towards understanding / using the Semantic Model.

It is often difficult for those who already “get it”, so a fresh perspective might help in making it easier for others to gain understanding.

2 Likes
19

Honestly…it’s not really a shame. It’s no worse than you not putting in the time to learn the MQTT binding if you don’t have any devices that communicate over that protocol. The model is just another ancillary part of OH that adds some features some users might find helpful. If it’s a feature you really needed to get your system working the way you want then it would be worth your time. If you do the cost/benefit analysis and decide against it, that’s OK too. You clearly get what you need from your current build which is great.

I don’t want to sound like I’m completely heartless and that “if you can’t figure out the model then you don’t deserve to use it…” I continue to agree that more effort needs to be made to make entry in to the model easier so that users can determine for themselves whether the benefits of the model are useful to them.

In fact…

this sounds like you are referring to one of my contributions to the model UI intended to help new users get it configured. I did not expect anyone to get hung up on this particular part of the interface though, so this is useful feedback.

To answer the question, you don’t need it, but it’s an important aspect of flexibility. All the components of the semantic model are just items (here’s where a “go away and read the manual” might help a little :slight_smile: ), and those items are going to get names just like every other OH item. So there are two important reasons a user should be able to configure a prefix for the auto generated model components: 1) many users prefer a prefix- suffix- based naming convention (see Rich’s post above where he demonstrates L- and P- as part of his naming conventions) and should be able to customize this to fit their needs, and 2) some users use OH to track more than one living unit and may need two parallel semantic models using prefixes to distinguish, for example, house- and cabin-.

1 Like
20

Well, the semantic discussion is above my pay grade but this is for me the interesting part. If I create a widget the only option for parameter selection is an item. If we want to make it easier to create standard GUI’s this should be expanded to whatever is decided for the model.

So making it possible to select locations, groups, type of items, maybe even tags in the parameters would improve usability. You know the input for the parameter will be a certain kind, and you can build the widget on top of that. And if you could iterate over the items in the location, group, whatever the possibilities would grow.

Probably a bit off topic, but my 2 cents.