This Wiki topic’s goal is to serve as a working document, in order to provide an up-to-date tutorial for OH3 aimed at new users and novices. Everyone is welcome and encouraged to edit it, when we’re satisfied it will make its way to the official docs. You may reply for the specific purpose of improving the article are allowed, but please, this is NOT a support thread: if you’re stuck while reading this and are simply seeking support please open another thread. Thanks!
There are many ways to organize your items, we suggest making use of the semantic (descriptions for where the item is located or what type of equipment it is) feature right from the start and sticking to it as this will make your life easier in the long run. Taking the time to understand and choose a logical structure for your home will save you from needing to re-do the work a second time in the future. This section gives a good example of one way to model your home with locations and equipment descriptions. This feature when setup correctly will allow Openhab to turn all lights off in a kitchen when asked as the framework can understand the kitchen location and what items are lights in that location.
Introduce the ontology and relationships:
A Location is always a Group item, it can contain Sub-Locations, Equipments or Points.
An Equipment is normally always a Group item, it can contain sub-Equipments or Points
A Point is always a non-Group item and is usually linked to a Channel.
Example of an advanced model:
Depending on your situation, you can omit some layers of locations. For instance if you live in a flat (apartment) your root Locations might just be the rooms. If you only have one building, you can omit the indoor/outdoor layer and the building layer - only have a hierarchy of floors and rooms, etc.
Equipments are often mapped to Things but not always - you can represent a single Equipment with several Things - for instance a computer might have points to switch it on (send a wake-on-lan packet), off (shell command), determining if it’s online (network polling), how much power it consumes (Z-Wave wall plug). A front door can have points to determine if it’s open or closed (with a sensor) or locked (with a smart lock), and a camera/motion detector.
From the Settings screen, click on Model.
Let’s start with a hierarchy of Locations. Click on Add Location.
Add your first item, a group representing the ground floor: Give it a name (choose carefully, you cannot change it afterwards, a popular convention is to prefix groups with “g” but it’s not mandatory). Choose a label, category (it mostly defines the default icon), and specialize the item by choosing a more accurate semantic class than “Location”, here “GroundFloor”.
Once it’s created, make sure it’s still selected on the left, and click on “Add Location” again - this will add another location within the first floor. Typically rooms are directly under floor locations.
Add an item representing the living room, call it
gGF_Living, set the
sofa category and the
LivingRoom semantic class.
Now let’s add the kitchen: Make sure to select Ground Floor again and choose Add Location to add the third item (name:
gGF_Kitchen, category: kitchen, semantic class: Kitchen).
To add the first floor to the root level, we need to clear the selection first, click on the white space in the tree, or Clear in the bottom toolbar. Add the ground floor, and its rooms (master bedroom, bathroom, etc…) to your model.
You should end up with something resembling this:
(side note: there might be Home Builder-like functionality in a wizard in the future to prepare the locations).
Now let’s add some Equipments and Points.
You could proceed like for the Locations and create them by hand, but there’s an easier way.
If the Equipment you’re adding is one of the Things that you already added, you have two options.
1. from the Model page
Select where in the model you want to add the Equipment, for instance, the kitchen, and click on Create Equipment from Thing.
Select the Thing you want to create the Equipment from, and alter the details of the Equipment item that will be created. If you don’t find an appropriate Equipment class, choose Equipment.
Below are all the Channels defined by the Thing, sometimes Things will have hundreds of channels so here you have the opportunity of choosing which ones will be linked to new Points items. Check the channels you’re interested in and only those.
For the plant sensor Thing added earlier, we have an opportunity to change the default basic Number types and make them quantifiable. Quantity types (Number with a dimension) provide conversion facitilities between Units of Measurement, and the default persistence is more granular. For percentages like humidity or battery levels, use Number:Dimensionless, which a quantity type without a dimension.
Also set the semantic class to Measurement and choose an appropriate related property.
When you’re finished, click Add in the title bar: the Equipment and Points should be added to the model where you wanted:
The “Plant Sensor” Equipment has been created under the Kitchen location and all the selected Points represent the selected Channels of the Thing.
2. from a Thing’s page
From the Settings, click on Things and click on the Thing you wish to add to the model. Switch to the Channels tab.
Click on Add Equipment to Model below the list: you’ll encounter a similar screen to the one above. The difference is, rather than selecting the Thing, you have to select where in the model you want to add the Equipment.
Select Pick From Model in the Parent Group section, the treeview of the Locations and Equipments will appear; select the parent group, for instance Living Room, then choose Pick in the top-right corner of the dialog box.
Then do the same as above, configure the Equipment item and the Points, then click Add.
Go back to the Model by choosing Model in the sidebar and verify that the Equipment added to the model from the thing page is effectively there as well as its Points.
Note how the Channel Links section lists the link to the Thing/Channel, and you also have a control widget to control the item - since it’s linked to the Color channel of the Hue bulb, the light will reflect the state of the item.
Finish adding Equipments and Points from your Things.