Scrub the semantic tags and add missing tags #4619
Comments
|
My thinking was that we go through the current needs from all the existing bindings, and see what tags are missing/needed, then perhaps we'll have a list of tags to consider. It would then be much easier to see / organise them. I've started this from the linked PR, and that's just from two bindings so far. Then additionally we get input from users about what other tags they need / would suggest. Add them all to the pile and work from there. Posting this request on the forum would probably get us the most feedback. |
|
Looking at the bindings is a good approach. I can open a forum thread, but I'm not super optimistic how useful that will be in the long run. I think what I am hoping for is some sort of rules that we can establish and document which describes what makes a good tag compared to a bad tag. For example, is it meaningful to have "Patio", "Porch" and "Terrace" or does it make more sense to have just one of those and use synonyms and the Item label to distinguish between these outdoor areas. Or does it make sense to add "Lenai"? Do we need "Front Door", "Back Door" and "Side Door" or does it make more sense to have "Exterior Door" and use synonyms and Item label to distinguish between the three? That's the sort of thing I'm hoping will come out of this issue. Of course, I have my opinions but even if my wishes are not met, I'll be overjoyed if we can have some rules in place to help maintainers decide what makes a good tag and what does not. I'm worried that if we don't come up with those rules first, a post to the forum will just gather a ton of tags with lots of overlap. Maybe seeing what's missing based on the bindings will help inform that discussion. Maybe no one else thinks this is a big deal like I do. |
This is a good point. How about, in addition to looking at what the existing bindings may need, we could also look at what Google/Alexa/Homekit currently have and draw inspiration from them? Perhaps once we're staring at a list of possible tags, a rule / guideline may emerge? @lolodomo wrote some sort of a rule here: openhab/openhab-addons#12262 |
|
That's a good idea. Though we have to be a little cautious there since their models do not exactly match ours, so the mapping may not be completely straight forward. But it certainly should show us if we have some gaps. I'll see if I can put them into a table for comparison and post that here to make the comparison easier. I like the rules that @lolodomo posted but those are more about how the tags are used. I'm hop[ing to come up with some rules to apply when deciding whether or not to add a new tag to the default list which is coming at it from a different angle. |
|
I was looking that the Hue binding. It has two types of things. These can be "devices" (e.g. push buttons, lamps, dials, motion sensors, temperature sensors, illuminance sensors, security contacts, etc.) and "groups" (whole house, rooms, and zones). I think the current point / property tags would cover "devices" (maybe with some minor additions e.g. for the dial control). But the "groups" things are a bit different -- they do associate to "locations" (e.g. Kitchen) that would not be in the remit of the developers, but at a higher level they also associate to "group meta-type" i.e. is it a group of all lights in a room (aka "room"), or a sub group of lights either within a room or across several rooms (aka "zone"). I think such "group meta-type" would be candidates to add to the list of "equipment" semantic tags. PS in #4617 I am working to add "equipment" semantic tags to things. And I am using the Hue binding as my test case. Since while the "point" and "property" semantic tags can be hard coded in the ChannelType xml, the "equipment" semantic tags on things will have to be set at run time in the discovery process depending on which things are found "devices" or "groups" and what device type, resp. "group meta-type" is actually found. |
|
For viewing you can see my attempt at mapping at https://docs.google.com/spreadsheets/d/1hKb-sLqHuM_FAUtHCWCjVCjjb1mhVUT5jKfUFggERm4/edit?usp=sharing CSV versions are below. I don't know of a tool to convert it to an MD table but you should be able to copy and import into your spreadsheet of choice. I tried to show the tag hierarchy using spacing. I ordered the tags alphabetically for OH but then I tried to make the GA, Alexa, and Homekit tags appear on the same lines as the OH equivalent, or inserted them alphabetically. Hopefully it makes sense but if not let me know. LocationsNote that I took the GA locations from the Home app. If Homekit or Alexa use Locations I don't know how to find them out. EquipmentI did my best to map but I'm not perfect. Points and PropertiesOnly GA appears to have something that seems to correspond with Points and Properties. |
|
Sorry to be slightly off topic. I am doing some more work on the topic of addons providing semantic tags dynamically for ThingTypes, ChannelTypes and discovery results. And it seems to me that it would be useful if addons could access the predefined tags in the form of To give an example, below is my hypothetical discovery code for the Hue thing discovery to define semantic equipment tags dynamically based on the discovered equipment. See the big |
|
Great work, @rkoshak! First, we need to decide the upper casing. Is it |
@andrewfg Is it not possible to define the tag in the thing-type.xml? |
|
See #4622, maybe that can come in handy? |
The existing OH tags are pretty consistent with starting with a capital letter and using camel case thereafter. I think it would be best to stick with the convention that's already there.
Wouldn't it make sense to pull the tags from the API that already exists backing the REST API tags endpoint? I worry if we have these tags defined in at least three different places it will become unmaintainable. I found a converter to make the table above easier to read here. Unfortunately the hierarchy doesn't get rendered. but hopefully you can look at the csv above and figure it out. It's pretty straight forward and as one would expect.
|
In some cases yes it can be hard coded in the xml. But for example in the Hue binding the discovery process finds generic "device" things. Then the binding queries the "device" via API calls to establish its exact device type .. so in such cases I would return the semantic equipment tags dynamically during the discovery process rather than hard coded in the thing type xml. |
|
Thanks for the awesome work, @rkoshak Proposed Semantic Tag AdditionsAny you'd like to remove from here? Locations
Equipment
For Television/Receiver/Radio
For Air conditioners, alarm system
For Lights
|
|
I am wondering about Equipment_Group for things that "wrap" a group of several other equipment things. For example in Hue a group of lights, or in a security system a group of motion detectors. These are kind of virtual equipment things. Where one may typically arm or command a channel on the group thing rather than individually on the things therein. There is also perhaps a Scene thing which is also a kind of virtual "wrapper" thing. =>WDYT? |
This is supported by the current Semantic Model. An Equipment can contain other equipments. Or do you mean that an equipment with no other purpose but only to contain other equipments? Does this "Group" need to be in the semantic model too? |
|
Umm. I am not sure. I guess a group of lights is also Equipment_Light and a group of motion detectors is an Equipment_MotionDetector. If nested equipment is allowed that would also work. |
|
Are the last part of the names supposed to be unique? In other words, is it allowed to have |
Nested Equipment is definitely allowed. I'm not sure there will be a way to handle something like that from the binding though. At least not with out more significant changes that have been proposed thus far. The binding would need to recommend not just a tag to apply to the Equipment Group but a whole hierarchy of Groups and tags to apply.
This kind of helps illustrate why I think we need some rules for what makes an acceptable tag. Do we really need both Coming up with a heuristic to evaluate what makes a good tag is what I hoped to come out of this issue. We can come up with a list here, but that isn't necessarily my main focus. Looking at this list of potential new tags I have some questions the answer to which might lead us to some rules. Locations
Equipment
Points
Properties
Proposed RulesGiven how I would answer these questions I'd recommend the following rules:
These are just my ideas and I don't want to get too long of a list of rules. But I do think we need to constrain tags some. Given these rules, the following do not make good tags:
For the existing tags:
New Tags I would propose (in addition to what's been already proposed):
These are just off the top of my head.
Yes, they must be unique because the last part becomes the tag that's actually applied to the Item. |
Agreed. |
|
Probably you need to add |
Would these be a child of Equipment_NetworkDevice or are you thinking something else? |
|
I am thinking of actual OH bridges declaring themselves as such. |
The default list of semantic tags are incomplete and inconsistent. Having a way to add custom tags helps some but the default list is the end user's first exposure to the model and it should help them get up to speed on how it works and support the most common use cases with the default list.
At a minimum we should have many more properties, a few more points, and more equipment.
But there are also a bunch of tags that don't make much sense. For example, we probably only need two or three Door tags instead of seven.
I think it makes a lot of sense to come up with some sort of rules for what makes a good tag or not, remove those that don't meet those rules and add any missing ones all in one go rather than fielding a bunch of separate issues to add two tags here and three tags there without any guiding principles.
To deal with removed tags and backwards compatibility, the upgradeTool can search the tags and add any removed ones a user happens to have used as a custom tag.
Your Environment
The text was updated successfully, but these errors were encountered: