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. |
OH (thing) bridges would never need to be in the semantic model though, I think? This is different to the equipment group you mentioned earlier right? |
Why do you say that? Many Bridges have channels that are linked to items, so it is perfectly sensible to see them in a semantic context.
Yes. |
I didn't know about this. Could you give me an example? |
Sure. Following are just a couple..
|
Indeed, this was the idea from the start! By looking at actual examples, we could then derive some sort of generalisation / rules. Without this exercise, it'll be a bit more abstract. But this can also serve as a source for the eventual expansion / revision of the semantic model. So multi-purpose. @andrewfg has identified a few other points towards this as well. All in all a great idea.
We also don't want to go too generic, like you could say a Bathroom is just another type of Room, for example. Of course in this case we all agree that it's a good idea to subcategorise them (Bathroom, LivingRoom, Kitchen, etc). On this topic:
Having a unique semantic tag for them, would simplify the code so you only need to filter on the semantic tag and not have to further filter again (on label, or custom tag, or group membership etc). Of course if this is irrelevant to "you" (as in general "you"), you could just not utilise the MasterBathroom tag and apply the more generic Bathroom tag for everything in "your" house. The nebulous thing is that you can create a custom tag MasterBathroom in this case, but then you could argue that for everything else. I think MasterBathroom / MasterBedroom has a place in the default tag, but of course this is only my opinion.
I would argue that
Also with FrontYard vs backyard, the two "yards" usually serve different purposes and receive different treatments when it comes to automation, that I believe they should have their own tags. Grouping them under Outdoor_Yard is good, so it gives you option for when you don't care, you'd just use their parent. So perhaps this rule could be further refined? A location tag should identify a category which makes them unique for the purposes of automation as well as organisation
I agree as long as it satisfies the "automation + organisation" aspect above.
How about
Agreed
Locations should be limited to Locations. A Kitchen Pantry is a specific location in which some equipment (sensor, lights, heater, fridge, etc) can reside. The question about whether there's a difference between A and B goes back to the question whether having a more unique one would aid in organisation and whether they need to be differentiated in their automation.
This would depend on whether there's an actual need to add more things into that category. If so, then naturally a hierarchy would make sense.
For me each of these have separate meaning and receives separate treatment in automation. For example, I want to turn off Backyard lights, but not back porch lights. But this is where I'm still confused about semantic tags vs actual locations.
Then so should
Somebody must've added this in the past for a reason. What if you had multiple summerhouses :D But maybe it should be called
I thought a Cellar is a special storage space for your liquor? Whilst traditionally it's located in some sort of basement, it could also be in a special cupboard/pantry/room in the kitchen or some other parts of the house.
This goes with the idea of organising your automation without having to add extra criteria. In a "typical" house, you have:
IMO these should be synonyms of one thing
I kind of agree that these should exist, but not yet sure whether the others should not. FrontDoor is a special one in almost every house and I think that should exist.
|
Roger that. |
|
So here are some suggestions. The easy ones..
Or perhaps (more better) we should try to follow the BIM codification of ISO 19650 which is "an international standard that uses building information modeling (BIM) to manage information throughout the life of a built asset". I don't know much about the details, but I know it is definitely a big thing. |
|
I have a couple of suggestions..
|
There's also linear slider ;) |
|
We also probably need the following
|
=> So perhaps Equipment.WALL_DEVICE ?? |
|
To inform this thread, I learned a huge amount about semantic equipment tags on things by playing around with a real actual binding example -- namely the Hue system here => it makes me think that we would perhaps learn a huge amount more by doing similar exercises on other real actual bindings. |
Actually @rkoshak I think |
|
I do want to emphasize something. I'm not really arguing for or against any specific tags. I'm mainly using these as examples to try to come to some rules we can use to assess these and future tags and then I want to use the rules to justify or eliminate the existing tags and apply them to future tags. I also want to emphasize that tags identify the type of something. It will be common to have multiple Items with the same tag in as model. To uniquely identify a specific instance we need additional information (e.g. position in the model. name, label, metadata). Location is a little weird because the tags are actually the least important in the semantic model (they add the least amount of information and they cause the least amount of impact on how everything is shown and how reasoning is performed). At the same time, these tags are the most likely to be used only once in the model. So I don't want to get too hung up on Location tags. If I tagged everything as "Location" but built my semantic model the same way I do now, the only different is the automatic color chosen for the cards that appear in the Locations tab of MainUI. The label on the card, the information HABot uses to reason on the model, and everything else would work the same. Locations should follow any rules we come up with, but we should probably not base our rules on Location tags. AFter this post I will switch to Equipment and Point/Property examples I think because I think the nature of Locations is leading us astray.
The tag isn't the only piece of information we have here though. We also have:
All of these should be used in addition to the semantic tag to provide information about the specific Item. A tag's entire reason for being should not be to uniquely identify a specific Location, Equipment, or Point/Property. The purpose of the tag is to identify the type of that Item. So do we need a separate tag for "MainBathroom" or is the semantic tag "Bathroom" coupled with the Item name "Main_Bathroom" enough. I'm not arguing against a "MainBathroom" tag here. I'm just making sure that this is taken into consideration when assessing any new tag. It will be common to have many instances of Items tagged with the same semantic tag. Tags cannot be used to uniquely identify something. If I get a list of all the Bathrooms, I still need to use additional information to identify the hall bathroom on the main floor and the hall bathroom on the top floor (for example). Where we ran into trouble before is everyone wanted to have their own terms represented as a separate tag. "Yes, we already have a Patio tag but in Florida we call that a 'lenai' so I want a 'lenai' tag." I want to create some rules we can use to say "Yes, that's a great idea!" or "No, we already have that case covered with the existing tags, you should use the existing Patio tag but call your Item 'Lenai' or create a custom tag." Without some rules, it's just going to be arbitrary based on what the reviewer thinks and we won't have consistency. But our rule needs to be consistent too. If we think MainBathroom makes sense but Lenai does not, our rules need to clearly lead to that result.
I do too but I think it's a useful case to consider when comming up with a rule. And if we accept that these make sense, what does that open us up to in other categories where applying the same rule could lead to scores of new tags rendering the list too hard to work with or forcing us to be inconsistent.
HalfBath and WaterCloset can both meet that rule and we already both intuitively feel they these shouldn't be included. But I do take issue with the word "unique". We do not and should not have a unique tag for every light in the house forr example. The semantic tag identifies the type of something and does not uniquely identify it. If we are not in agreement on this point I don't think we can ever come up with a consistent approach. Location tags need to be the type of the location, not a unique identifier for a specific Location.
As long as it's clear I'm happy with any approach. That approach makes sense.
But how are we to judge that? That's really what I'm after. I can make a good argument that having a tag for HalfBath would aid in my organization and differentiated in my automation. My half bath doesn't have a humidity sensor in it and it would be convenient to not have it included when I want to turn on the vents since there's no info to turn on that vent.
If I have a wardrobe with motion sensors and lights? I'm inclined to say no, that wardrobe shouldn't be included but I'm struggling with comming up with rules that would clearly exclude that tag while including tags that do seem to make sense like MainBedroom.
So how do we make a rule or rules that decides that those are good but HalfBath and Wardrobe are bad? That's what I'm really after. As I said above, getting hung up on Locations may be hindering us. It might be better to focus on Equipment.
That's where it gets complicated. But I think that ColorTemperature is only something that, in a home automation context, is used with lighting. So I would include both and put ColorTemperature under Light and Color would stand on it's own. But that's just my own arbitrary thoughts. What would that look like as a rule we can use to make sure we are consistent?
That's a major point I'm trying to get across. If you have multiple summerhouses, all of them should have the same tag. They are all summerhouses. The tag isn't the only piece of information. You distinguish between multiples using the name, label, and synonyms. It's the Item name that distinguises between the two. Given that you can and should have more than one instance of most of these tags, our heuristic can't be based around something that implies each Item has a unique tag. I personally don't think "SummerHoure" or "VacationHouse" either really add anything. I wouldn't include either. But I'm open if there's a consistent rule we can apply to justify them. The fact that it's a house is captured. Which house it is doesn't need to be and I'd argue shouldn't be encoded in the tags. That's what all the other information is there for. I think about it like bedrooms. Ignoring the the whole MainBedroom discusssion, do we need Child1Bedroom, Child2Bedroom, Child3Bedroom, or just Bedroom and have the Item name and other info used to distinguish between the three? If the same arguments for including FrontYard (for excample) justifies adding a bunch of ChildBedroom tags, I think we are off the mark. If the same argument can be used to add a proliferation of LightBulb tags because if there's one type of thing that there is likely to be more than one of in a Location, it's lights, we are off the mark. The tags need to be used to tag something based on what kind of thing it is, not uniquely identify it.
I agree, so we need a rule that allows that without needing to create a separate tag for each child's bedroom. The automation for the teenager might be very different from the automation for the eight-year-old.
I like that idea. We just need to be careful because not all Properties are Numbers. We can't exclude them because UoM is meaningless in that context. I can have a String, Switch, Contact, Player, Rollershutter, Dimmer, et al Item which all represent a Property. For example, a Dimmer Item to represent a volume control, or a Contact Item to represent Openness. But in cases where there is a clear mapping between the unit and a Property tag that should be probmoted somehow.
I'm not sure about this one. We need the Point tag in the first place because there isn't enough information only in the Item type. And Item types can be used in unusual ways. For eaxample, OH Switch Items are binary, only ON or OFF. But the concept of a switch with multiple states is reasonable (e.g. ON, OFF, AUTO) and one would use a String Item for that. It still makes sense to use a Switch semantic tag on that String Item. But there are other cases where they can be more tightly coupled. A DateTime Type would probably only be tagged with a "timestamp" tag an a Number:Time would only be tagged with a "time" tag (I don't think "time" exists as a tag yet). A Setpoint tag would only be used with a Number or a Dimmer Item.
End users are not going to know about or be able to use an ISO spec to choose their Equipment tags. We also don't want to eliminate the flexibility to "build your own equipment". For example I have a dumb humidifier powered by a smart outlet with a wireless humidity sensor near by. The outlet and humidity sensor are modeled as a single equipment in my model because they work together (through a rule) to make my humidifier smart. We can't be so proscriptive here to eliminate these sorts of possibilities. And the ISIC is huge! Same for ISO 19650. I like the idea of reviewing those but a whole sale adoption of them I think would be unweildy.
Indeed, I think there's more than one tag that need to be fixed. I think most of the tags use camel case so using that as the standard would probably be the least disruptive overall. |
@rkoshak I fully agree with, and support, your aim. Forgive me for being blunt, but a thousand word essay about the things you don't like, will not advance your aim. I would like to propose a way forward. We need four rules. Each rule being one paragraph. No longer. So let us try together to write those paragraphs. My proposal is that I write four DRAFT paragraphs. Based on what everyone has said so far in this thread. Then our operational working procedure is that if one does not like the paragraph, then they are obligated to provide an edited and improved version of that draft. In other words, we try to follow a positive criticism and editing cycle. No more essays on the negative. Hopefully if we can repeat this cycle of positive criticism and editing, after a few iterations we will generate a usable final set of texts. Is that OK with you? |
|
I don't think I'm being negative. Your proposal is fine. I thought I already did that with the rules I posted above. Maybe we'll have better luck if they didn't come from me. Here are the rules again, with the examples removed. A Location tag should identify a category, a type A proposed new tag should not be just another name for an already existing tag. It is OK to add some sub-tags to a category if it serves to help inform the end user what the category tag represents and it's a commonly used name for a location/equipment/point/property. But we need to resist the urge to try to be comprehensive. When the name of a tag is ambiguous in whether it can be an Equipment or a Point or Property, add what it is to the tag. A Point tag should be what you do to or how you get the state of the Item. Use the hierarchy. Properties should always be a noun and represent something commonly controlled or sensed in a home automation context. |
|
I don't quite understand this rule:
Why is Property not allowed here? |
|
I wrote that because it encapsulated something that was in the original documentation. But I agree that it doesn’t really make sense. PS it is not in the word document, which I think should become our definitive text. EDIT: there may be cases of Status points where a property is not necessary (e.g. Status : Ready) but it's hard to extend that into an argument that a status property is forbidden EDIT2: I will modify the word doc to reflect that. |
|
Attached is a revised version of the proposed rules DEVELOPER INFORMATION ON SEMANTIC TAGS.docx -- this describes a) the rules for using tags, and b) the rules for adding new tags. => @rkoshak / @jimtng please enter your revisions to the document and post the revised version here. @rkoshak the rules for adding new tags can equally be used for your purpose of retroactively removing existing but non appropriate tags; however since this will be a one time effort I will not explicitly mention that purpose in the document. |
|
I don't have Word and don't want Word so I have no idea if track changes and comments survived the conversion back and forth. I don't really have a good palce to host it. I'll try to share it through my NextCloud instance. Let me know if that doesn't work. One general comment I have is I think there might be confusion over how locations are used in realtion to points and equipment. Almost all of the time the location applies to the equipment, not the points. The points become placed in a location by being a member of an equipment that is a member of a location. It's a transitive relationship. Rarely does one put a point in a location individually without an equipment. Putting a point in a location and an equipment is basically a hack to solve a specific UI problem and it is not something that contributes to the logical structure of the model. |
It is a good point. In #4615 I am introducing XSD validation to allow up to one point tag and up to one property tag on channel types resp. instances, and in #4617 I am introducing support for, and XSD validation of, one single equipment tag on things types resp. instances. So in other words I am preventing the use of location tags by developers. And the location tags would ONLY be added by the user when setting up their specific system for the purposes of grouping items in the semantic model. But nevertheless this obviously doesn’t not remove the need for scrubbing the location tags. |
Agreed. I was just confused by the rule for providing a loaction tag to the Channel. That would be pushed down to the point Items linked to those Channels, presumably. While not an impossible use case to have points from one Thing end up in different locations, it's a less common use case to have a model configured in that way so the rule surprised me. However, if we were to support location tagging at the time of creation of an Equipment, I think that would be wholly outside anything the binding developer can influence. So nothing more would need to be done in the Thing XSDs and such beyond what you describe even were MainUI changed to allow us to create a new Location when adding equipment or points to the model instead of requiring the location to be created first. |
I don't want to enter into a big discussion here. But just to take minor issue with your "wholly outside" statement. There are many bindings (e.g. Hue, NeoHub, HDPowerView, Tado, ..) where you first configure your system using the respective manufacturer's App. And that process involves assigning your equipment to rooms. Then when you add those devices as things into OH the respective API gives you this equipment room information. But as I say it is quite an exotic potential use case, with many potential pitfalls, so I don't really want to open up that can.. |
:) .. and yes the comments did make it; many thanks. Attached below is a revised version of the document where I think I have taken over all your suggestions. |
|
@rkoshak are you happy with the revised version of the word document? If so then the next steps would be:
Is that OK? EDIT: I already did part 1. of the above here so perhaps instead of reviewing the word document you can review the respective PR instead? |
Signed-off-by: Andrew Fiddian-Green <[email protected]>
|
Sorry for the delay. I'm rarely at a computer where I can easily review a Word document over the weekends. I'll go over and review the PR. |
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: