Mastering the Semantic Model in openHAB: A Definitive Guide
Introduction to the Semantic Model
The semantic model is the backbone of openHAB’s organizational framework. It defines relationships between locations, equipment, and points, making your smart home intuitive, structured, and easy to manage. Proper tagging ensures:
- Clean UI integration in MainUI.
- Optimized voice assistant compatibility (e.g., Alexa, Google Home).
- Dynamic rule creation, leveraging relationships between items.
This guide explains how to use the semantic model, avoid common mistakes, and create a clean, scalable smart home setup.
Key Components of the Semantic Model
The semantic model consists of three core elements: Locations, Equipment, and Points. Here’s how they interact:
-
Locations
- Represent physical areas in your home (e.g.,
Living Room,Kitchen,Basement). - Define where equipment and points are located.
Example:
Group gLocLivingRoom "Living Room" <sofa> ["Location"] - Represent physical areas in your home (e.g.,
-
Equipment
- Represent physical devices or systems (e.g.,
Lights,Motion Detectors,TV). - Group points related to the device or system.
Example:
Group gEquipLivingRoomLights "Living Room Lights" <lightbulb> (gLocLivingRoom) ["Lightbulb"] - Represent physical devices or systems (e.g.,
-
Points
- Represent individual functionalities of equipment (e.g., a switch, dimmer, or sensor).
- Each point has one role (Point) and one characteristic (Property).
Example:
Switch LivingRoomLightSwitch "Living Room Light Switch" <light> (gEquipLivingRoomLights) ["Switch", "Power"] {channel="mqtt:homie300:Queen:light-12345:switch#power"}
Semantic Tags: Points and Properties
Each item must have:
- One Point Tag: Defines its functional role.
- Examples:
Switch,Control,Measurement,Status.
- Examples:
- One Property Tag: Defines the characteristic being controlled or measured.
- Examples:
Power,Brightness,Presence,Temperature.
- Examples:
Common Point Tags
| Point | Description |
|---|---|
Switch |
Binary control (e.g., on/off). |
Control |
General control role (e.g., dimmer, setpoint). |
Measurement |
Observes or measures a value (e.g., temperature, presence). |
Status |
Represents a state or alert (e.g., low battery). |
Common Property Tags
| Property | Description |
|---|---|
Power |
Controls or measures power state (on/off). |
Brightness |
Controls or measures brightness level (0-100%). |
Presence |
Detects motion or presence. |
Temperature |
Measures temperature. |
LowBattery |
Indicates low battery state. |
Examples of Correct Semantic Tagging
1. Switch Light (Non-Dimmable)
- Point:
Switch(binary control role). - Property:
Power(on/off state).
Switch LivingRoomLightSwitch "Living Room Light" <light> (gEquipLivingRoomLights) ["Switch", "Power"] {channel="mqtt:homie300:Queen:light-12345:switch#power"}
2. Dimmer Light
- Point:
Control(adjustable control role). - Property:
Brightness(light intensity).
Dimmer LivingRoomLightDimmer "Living Room Light Dimmer" <lightbulb> (gEquipLivingRoomLights) ["Control", "Brightness"] {channel="mqtt:homie300:Queen:light-12345:dimmer#level"}
3. Motion Sensor
- Point:
Measurement(measuring motion detection). - Property:
Presence(motion detected or not).
Switch FrontDoorMotion "Motion Detected" <motion> (gEquipFrontDoorMotion) ["Measurement", "Presence"] {channel="mqtt:homie300:Queen:motion-12345:motion#detect"}
4. Door Contact Sensor
- Point:
Measurement(measuring state). - Property:
OpenState(open/closed).
Switch FrontDoorContact "Door Open State" <door> (gEquipFrontDoor) ["Measurement", "OpenState"] {channel="mqtt:homie300:Queen:door-12345:contact#open"}
5. Battery Level
- Point:
Measurement(measuring state). - Property:
Battery(battery level as a percentage).
Number MotionSensorBattery "Battery Level" <battery> (gEquipMotionSensor) ["Measurement", "Battery"] {channel="mqtt:homie300:Queen:battery-12345:battery#level"}
6. Low Battery Warning
- Point:
Status(state representation). - Property:
LowBattery(battery low state).
Switch MotionSensorLowBattery "Low Battery Warning" <lowbattery> (gEquipMotionSensor) ["Status", "LowBattery"] {channel="mqtt:homie300:Queen:battery-12345:battery#low"}
Best Practices for the Semantic Model
-
Points Belong to Equipment:
- Points should be part of an equipment group for clear hierarchy and UI structure.
-
One Point, One Property:
- Each point can have only one Point tag and one Property tag.
-
Avoid Redundancy:
- Use equipment tags to describe the device. Avoid duplicating this information in point tags.
-
Reflect Real-World Usage:
- Model locations and equipment based on user expectations, not hardware placement.
-
Custom Tags Caution:
- Only define custom tags when absolutely necessary, as some behaviors (e.g., UI display) depend on default tags.
-
Not Everything Belongs in the Model:
- Technical or intermediate items (e.g., rule triggers) need not be included in the semantic model.
Advanced Use: UI Semantics
To enhance UI presentation, use uiSemantics metadata. This adds natural-language context for locations, equipment, and points.
Example:
Group gEquipLivingRoomLights "Living Room Lights" <lightbulb> (gLocLivingRoom) ["Lightbulb"] {uiSemantics="uiSemantics"[preposition=" in the", equipment="Lights", location="Living Room"]}
Benefits:
- Improved natural-language descriptions in the UI.
- Customizable equipment and location naming.
Learn more: Semantic UI: Using Enriched Semantic to Ease UI Creation.
Dynamic Rules Using Semantic Tags
Semantic tags can be used in rules to dynamically interact with related items.
Example: Equipment and Status Check
var equipment = actions.Semantics.getEquipment(items[alertItem]);
if (equipment !== null) {
var statusItem = equipment.members.find(i => i.tags.includes('Status') && i.tags.includes('LowBattery'));
if (statusItem && statusItem.state === 'ON') {
logInfo("Alert", "Low battery for: " + equipment.label);
}
}
