Skip to content

Semantic Tags: set EQUIPMENT tags on Things #4617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 23 commits into from
Apr 3, 2025

Conversation

andrewfg
Copy link
Contributor

@andrewfg andrewfg commented Feb 23, 2025

Addon developers may (or may not) set POINT/PROPERTY semantic tags in their addons. These tags are set either a) in the channel-type.xml of the addon, or b) dynamically at run-time via the addon Java code. The purpose of POINT/PROPERTY tags is for Main UI to offer appropriate tags on Items so that they will properly fit in the the user's hierarchical semantic model. Thus eliminating complexity for users.

Main UI also allows the user to apply EQUIPMENT tags when creating the user's hierarchical semantic model. However currently the user has to decide on, and apply, the EQUIPMENT tags manually themselves when setting up their system.

The purpose of this PR is to add a semantic EQUIPMENT tag to Things. This allows developers to set the EQUIPMENT tag on a Thing either a) in the thing-type.xml of the addon, or b) dynamically at run-time via the addon Java code. So that addons can offer the most appropriate EQUIPMENT tag via the Main UI. Thus further eliminating complexity for users.

This PR does the following:

  1. It extends the XSD schema validation scheme to allow a semantic EQUIPMENT tag on Thing types; analogous to Semantic Tags: validate POINT/PROPERTY tags on Channel Types #4615
  2. Adds code to permeate EQUIPMENT tags on Things throughout OH core wherever it may be needed. Specifically in the classes, DTOs and (de)serializers for thing types and things.

See also #4615
Resolves #4614
Used by openhab/openhab-webui#3124

Signed-off-by: Andrew Fiddian-Green [email protected]

Signed-off-by: Andrew Fiddian-Green <[email protected]>
@andrewfg andrewfg requested a review from a team as a code owner February 23, 2025 11:39
@andrewfg andrewfg marked this pull request as draft February 23, 2025 11:39
@andrewfg andrewfg changed the title XSD Add new definition for semantic tags on things XSD Add new definition for semantic tags on thing type definitions Feb 23, 2025
@openhab-bot
Copy link
Collaborator

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-5-semantic-model-proposal/162526/96

@andrewfg andrewfg changed the title XSD Add new definition for semantic tags on thing type definitions XSD Add semantic tag on things Feb 23, 2025
Signed-off-by: Andrew Fiddian-Green <[email protected]>
@andrewfg andrewfg marked this pull request as ready for review February 23, 2025 16:24
@andrewfg andrewfg marked this pull request as draft February 24, 2025 07:56
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
@andrewfg
Copy link
Contributor Author

@mherwege can I kindly ask you to be a sparring partner for this PR? My goal is to allow developers to set a (proposed) semantic (equipment) tag in their thing type xml, and have this permeated through the thing type instances to the actual thing instances so that the UI can use that semantic (equipment) tag (as a hint) in creating a semantic model.

@mherwege
Copy link
Contributor

@mherwege can I kindly ask you to be a sparring partner for this PR? My goal is to allow developers to set a (proposed) semantic (equipment) tag in their thing type xml, and have this permeated through the thing type instances to the actual thing instances so that the UI can use that semantic (equipment) tag (as a hint) in creating a semantic model.

@andrewfg Sure. I like the idea as long as it does not then enforce anything on the item semantics. So I would think that it should be carried to the point of a having a tag on the thing, but then it should be up to the UI to pick this up as a suggested equipment semantic when creating the group item with its points (create model from thing).
As it should not be used on the thing directly, except when creating items, I am wondering what it should be called. Some day someone may think it carries meaning beyond a suggestion for an equipment group item, and may want to also show that in the UI...

@andrewfg
Copy link
Contributor Author

andrewfg commented Feb 24, 2025

Indeed. The tags in the ChannelType xml are hints for semantic “point” and semantic “property” tags which are intended for functional Item creation. And the single tag in the ThingType xml would be a hint for the semantic “equipment” tag intended for semantic GroupItem creation. The remaining “location” semantic tag is entirely user dependent and would not come from the xml.

PS we could even explicitly name it equipmentTag ..

Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
@mherwege
Copy link
Contributor

mherwege commented Mar 4, 2025

Obviously it needs work now on the OH WebUI side in order to utilise this semanticEquipmentTag when creating the semantic model. => @mherwege :)

I don't think this is a very complex change in the UI. I can take care of it, but would prefer to finish the core code first. There are a lot of moving parts and dependencies here, and creating a core that has it all for testing a UI change against is a bit of a challenge. It will be easier to do when we get the core changes over the line first.

@andrewfg andrewfg changed the title Add semantic equipment tag on things Semantic Tags: allow EQUIPMENT tags on things Mar 16, 2025
@andrewfg andrewfg changed the title Semantic Tags: allow EQUIPMENT tags on things Semantic Tags: set EQUIPMENT tags on things Mar 16, 2025
@andrewfg andrewfg changed the title Semantic Tags: set EQUIPMENT tags on things Semantic Tags: set EQUIPMENT tags on Things Mar 16, 2025
@andrewfg
Copy link
Contributor Author

It will be easier to do when we get the core changes over the line first.

@mherwege understood. IMHO all the changes in OH Core are ready to merge (via this PR). So it would be helpful if you can review this and give LGTM so that we can indeed proceed to merge it.

Copy link
Contributor

@mherwege mherwege left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@andrewfg
Copy link
Contributor Author

Ping @ccutrer apropos our discussion on Equipment tags

@kaikreuzer
Copy link
Member

@andrewfg May I ask you to rebase this PR?

andrewfg added 2 commits April 3, 2025 18:03
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
@andrewfg
Copy link
Contributor Author

andrewfg commented Apr 3, 2025

May I ask you to rebase this PR?

@kaikreuzer done! Apparently the CI / JavaDoc test failed but I don't know why.

@holgerfriedrich
Copy link
Member

@andrewfg the log of the javadoc job needs improvement. Running it locally, I see the message causing it to fail:

[WARNING] Javadoc Warnings
[WARNING] openhab-core\bundles\org.openhab.core.thing\src\main\java\org\openhab\core\thing\Thing.java:246: warning: @param argument "tag" is not a parameter name.
[WARNING] * @param tag the semantic (equipment) tag or {@code null} if no tag has been configured.

…thing/Thing.java

Co-authored-by: Holger Friedrich <[email protected]>
Signed-off-by: Andrew Fiddian-Green <[email protected]>
Copy link
Member

@kaikreuzer kaikreuzer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@kaikreuzer kaikreuzer merged commit 85d539c into openhab:main Apr 3, 2025
4 checks passed
@kaikreuzer kaikreuzer added the enhancement An enhancement or new feature of the Core label Apr 3, 2025
@kaikreuzer kaikreuzer added this to the 5.0 milestone Apr 3, 2025
florian-h05 pushed a commit to openhab/openhab-webui that referenced this pull request Apr 15, 2025
Refs openhab/openhab-core#4617.

If the thing provides a default `semanticEquipmentTag`, this will be
used when creating an equipment from thing instead of the default
`Equipment`.

Signed-off-by: Mark Herwege <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement An enhancement or new feature of the Core
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add semantic equipment tag on things
8 participants