Semantics

OpenHAB supports a semantic model to help you define relationships between items.

Item helper methods

Several semantics helper methods are defined on items in order to easily navigate this model in your scripts. This can be extremely useful to find related items in rules that are executed for any member of a group.

Note: In openHAB 3.2, Item#equipment and Item#location will return itself instead of its parent equipment or location if it itself is an equipment or a location. This behavior changed in openHAB 3.3 to return its parent equipment/location or nil if none is found.

Enumerable helper methods

Enumerable helper methods are also provided to complement the semantic model. These methods can be chained together to find specific item(s) based on custom tags or group memberships that are outside the semantic model.

The Enumerable helper methods apply to:

• Group item’s members and all_members. This includes semantic #location and #equipment because they are also group items. An exception is for Equipments that are an item (not a group)
• Array of items, such as the return value of #equipments, #locations, #points, #tagged, #not_tagged, #member_of, #not_member_of, #members methods, etc.
• items[] hash which contains all items in the system.

Semantic Classes

Each Semantic Tag has a corresponding class within the org.openhab.core.semantics.model class hierarchy. These semantic classes are available as constants in the Semantics module with the corresponding name. The following table illustrates the semantic constants:

These constants can be used as arguments to the #points, #locations and #equipments methods to filter their results. They can also be compared against the return value of semantic_type, location_type, equipment_type, point_type, and property_type.

# Return an array of sibling points with a "Switch" tag
Light_Color.points(Semantics::Switch)

# check semantic type
LoungeRoom_Light.equipment_type == Semantics::Lightbulb
Light_Color.property_type == Semantics::Light

Examples

Find the switch item for a scene channel on a zwave dimmer

switches.items

Group   gFullOn

Group   eGarageLights        "Garage Lights"             (lGarage)                 [ "Lightbulb" ]
Dimmer  GarageLights_Dimmer  "Garage Lights"    <light>  (eGarageLights)           [ "Switch" ]
Number  GarageLights_Scene   "Scene"                     (eGarageLights, gFullOn)

Group   eMudLights           "Mud Room Lights"           (lMud)                    [ "Lightbulb" ]
Dimmer  MudLights_Dimmer     "Garage Lights"    <light>  (eMudLights)              [ "Switch" ]
Number  MudLights_Scene      "Scene"                     (eMudLights, gFullOn)

switches.rb

rule "turn dimmer to full on when switch double-tapped up" do
  changed gFullOn.members, to: 1.3
  run do |event|
    dimmer_item = event.item.points(Semantics::Switch).first
    dimmer_item.ensure << 100
  end
end

Turn off all the lights in a room

Group   gRoomOff

Group   eGarageLights        "Garage Lights"             (lGarage)                  [ "Lightbulb" ]
Dimmer  GarageLights_Dimmer  "Garage Lights"    <light>  (eGarageLights)            [ "Switch" ]
Number  GarageLights_Scene   "Scene"                     (eGarageLights, gRoomOff)

Group   eMudLights           "Mud Room Lights"           (lGarage)                  [ "Lightbulb" ]
Dimmer  MudLights_Dimmer     "Garage Lights"    <light>  (eMudLights)               [ "Switch" ]
Number  MudLights_Scene      "Scene"                     (eMudLights)

switches.rb

rule "turn off all lights in the room when switch double-tapped down" do
  changed gRoomOff.members, to: 2.3
  run do |event|
    event
      .item
      .location
      .equipments(Semantics::Lightbulb)
      .members
      .points(Semantics::Switch)
      .ensure.off
  end
end

Finding a related item that doesn’t fit in the semantic model

We can use custom tags to identify certain items that don’t quite fit in the semantic model. The extensions to the Enumerable mentioned above can help in this scenario.

In the following example, the TV Equipment has three Points. However, we are using custom tags Application and Channel to identify the corresponding points, since the semantic model doesn’t have a specific property for them.

Here, we use Enumerable#tagged to find the point with the custom tag that we want.

Group   gTVPower
Group   lLivingRoom                                 [ "LivingRoom" ]

Group   eTV             "TV"       (lLivingRoom)    [ "Television" ]
Switch  TV_Power        "Power"    (eTV, gTVPower)  [ "Switch", "Power" ]
String  TV_Application  "App"      (eTV)            [ "Control", "Application" ]
String  TV_Channel      "Channel"  (eTV)            [ "Control", "Channel" ]

rule 'Switch TV to Netflix on startup' do
  changed gTVPower.members, to: ON
  run do |event|
    application = event.item.points.tagged('Application').first
    application << 'netflix'
  end
end

Find all semantic entities regardless of hierarchy

# All locations
items.locations

# All rooms
items.locations(Semantics::Room)

# All equipments
items.equipments

# All lightbulbs
items.equipments(Semantics::Lightbulb)

# All blinds
items.equipments(Semantics::Blinds)

# Turn off all "Power control"
items.points(Semantics::Control, Semantics::Power).off

# All items tagged "SmartLightControl"
items.tagged("SmartLightControl")