OH 4.1: Tutorial to manage custom semantic tags

In openHAB 4.0, some technical refactoring in the core framework were done to define a registry for semantics tags and define a REST API to manage semantic tags (add/remove/update). The default semantic tags cannot be changed but you can add new equipment, new location, new property and new point as you wish.

In OH 4.1, you can now provide your own semantic tags using a file. It was decided to rely on a YAML format for the configuration file. So, for example, create a file named myTags.yaml (the yaml extension is important) and place it in the “config)tags” folder to trigger the loading of its content.

If you have basic knowledge of YAML, the specific syntax for defining a semantic tag is very simple. Here is an example file:

#
# Configuration file containing a list of custom semantic tags
#

version: 1

# For each semantic tag:
#  - uid and label are required
#  - description and synonyms are optional

tags:

  # Example of a new equipment
  - uid: Equipment_Curtain
    label: Curtain

  # Example of a new location
  - uid: Location_Indoor_Room_HomeCinemaRoom
    label: Home Cinema Room
    description: The room containing my home cinema system.
    synonyms:
      - Home theater room
      - TV room
      - Movie room

The “uid” is very important and define the location of your semantic tag in the tree. In the example, “Location_Indoor_Room_HomeCinemaRoom” defines semantic tag “HomeCinemaRoom” as child of “Room” which is itself child of “Indoor” which is itself child of “Location”. There are constraints on the name of a semantic tag (like HomeCinemaRoom); it must start with a capital letter letter and contain only letters and numbers.

You can have multiple YAML files with different semantic tags but keep semantic tags dependent on each other in the same file.

Now reopen Main UI (semantic tags are loaded by Main UI when you open Main UI).
Create a new group and select HomeCinemaRoom as semantic tag:

Create a new group and select Curtain as semantic tag and “My Home Cinema Room” as parent group:

Now, go to the Equipment tab in Main UI and you will see:


Now, go to the Location tab in Main UI and you will see:


Enjoy!

10 Likes

Please, note that custom defined tags (myTags.yaml file) seems to be loaded after .items definition files.
New tags are taken in account only after .items files loading (thus seem unknown in the model view until the item file is reloaded). I observed the same behaviour when items are GUI defined (but then you can not force reload them).

@Lolodomo : is the addition of org.openhab.core.model.yaml-4.0.0.jar still needed in 4.1 snapshot ?

Yes because my PR is still not yet merged, unfortunately.
I need to investigate the problem you reported.

I thought it had been solved (at least it was past week) in UI side via Ensure semantic model pages are built after tags are loaded by florian-h05 · Pull Request #2066 · openhab/openhab-webui · GitHub.
But now I’m unsure. My personal tags are present, available on item definition but missing in the model view.

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.