Smart Home – openHAB 2 Configuration with Smart Home Desginer

Some of the readers of my blog do have problems with the openHAB 2 configuration and the Smart Home Designer. I fully can understand that. It will take some time to understand the logic and coding syntax. This post will guide you how to use the Smart Home Designer. Furthermore will you will learn about Sitemaps, Items, Groups etc. to get the most out of your openHAB 2 Smart Home.

First of all you need an up and running openHAB 2 server. If you do not have one, read the post Smart Home – openHAB 2 Installation und Configuration. Here you will learn what hardware you need and how to get the openHAB 2 server running.

If you would like a structured openHAB 2 video training, please enroll in my openHAB 2 training.

openHAB 2 Configuration – Eclipse SmartHome Designer

openHAB 2 Configuration – Eclipse SmartHome Designer – Installation

First of all download the  Eclipse SmartHome Designer. You will find the latest release version and also snapshot version. I suggest you download both versions, because sometimes there are features and syntax checks, that are not in the stable version. My recommendation is to work with the release version and switch to the snapshot version if you encounter any problems. If you still have an error in your syntax, it will be wrong in most of the cases. =)

Unpack the downloaded files and you will find SmartHome-Designer.exe. Because you will work on your Smart Home from time to time, you should put a link to this file in your start menu. Double Click to start the Smart Home Designer.

openHAB 2 Configuration – Eclipse SmartHome Designer – Folder

At the beginning you have to pick the folder were openHAB 2 stores the configuration files. In Windows this will be in your openHAB 2 installation folder. There is a folder conf. So if you installed openHAB 2  C:\openhab\ the path will C:\openhab\conf. Pick the small folder icon (1) and choose the configuration folder (2). Click OK (3)

openHAB 2 Configuration – Eclipse SmartHome Designer – File Creation

It is not self explaining how to create your files in which you will put your source code for the Items, Rules etc. This files are missing and you have to create them.

Follow these steps:

1. Open the folder in the section Configurations in which you want to create the file.
2. Do a double click on readme.txt. Here you will find a hint “All items files have to have the “.items” file extension and must follow a special syntax.” on the file extension. I will do so. Right Click on the readme.txt
3. Choose Copy

Now do a right click on the readme.txt again and paste. Now put in a Name and the file extension. I will choose meine.items.

After clicking OK double click on your new file (1) and delete the existing text (2)

Now you are ready to go to create your first items.

openHAB 2 Configuration – Items

The syntax of an item looks like this.

itemtype itemname "description" <iconname> (group1, ..., groupn) ["speech_tag"]{binding}

Confusing? Yeah, but I will guide you through the item configuration step by step.

openHAB 2 Configuration – Items – Itemtypen

The item type will be needed to differ between the different functions (dimming, switches, heating etc.)  Here is an overview of the different item types.

floorlevel_room_function_place

Switch gf_ba_li_ceiling

Switch gf_ba_li_ceiling "Bath Ceiling"

Switch gf_ba_li_ceiling "Bath Ceiling" <rain>

Group gBath
Group gLight

Switch gf_ba_li_ceiling "Bath Ceiling" <rain> (gBath, gLight)

If you are a proud owner of a Amazon Echo or Echo Dot, you may tag your item to get Speech Recognition functionality for your item. You will do that with square brackets []. A detailed guide how it works can be read in the post Smart-Home-Speech-Recognition. An by the way. You do not need KNX. You could also control your Z-Wave, Zigbee or whatever devices.

The following tags are possible.

["Lighting"]
["Switchable"]
["TargetTemperature"]

Our item will grow a bit more.

Switch gf_ba_li_ceiling "Bath Ceiling" <rain> (gBath, gLight)["Lighting"]

openHAB 2 Configuration – Items – Binding Configuration

Still not enough of brackets. No we get the last one. The curly brackets {} are for the binding configuration. The configuration is very specific for each binding. You should check the offical documentation of openHAB 2 to get the correct syntax. I will show you an example of KNX. KNX will be connected to the group address that has been configured in your ETS.

My item looks like this.

Switch gf_ba_li_ceiling "Bath Ceiling" <rain> (gBath, gLight)["Lighting"] { knx="<5/1/41" }

If you use the Philips Hue, it might look like this.

Color gf_ba_li_mirror "Bath Mirror" <rain> (gBath, gLight)["Lighting"] { channel="hue:0210:001234567890:2:color" }

openHAB 2 Configuration – Items – Examples

Now we put all our items into the item file.

/************************************************** Groups ********************************************/
//--> Rooms
Group gBath

//--> Functions
Group gHLight



/************************************************** Items ********************************************/
//---> Ground Flooor
//-->  Bath
Switch gf_ba_li_ceiling "Bath Ceiling" <rain> (gBath, gLight)["Lighting"] { knx="<5/1/41" }
Color gf_ba_li_mirror "Bath Mirror" <rain> (gBath, gLight)["Lighting"] { channel="hue:0210:001234567890:2:color" }

openHAB 2 Configuration – Sitemap

The next element is your sitemap. Create an file as described above. Use the file extension .sitemap. I will name it myHome.sitemap Building your sitemap also has some logic (Syntax). The syntax looks like this.

sitemap [NAME] [label="Description"] {
  Frame [label="Description"] {
      [Eure Items]
  }
}

Always remember the following. The sitemap is always the first element.  In curly brackets {} will be your frames. They will structure your sitemap and show items and groups. Groups will be opened in another screen.

openHAB 2 Configuration – Sitemap definition and first call

Try it first by creating your sitemap. I pick “Daheim” as description.

sitemap Standard [label="Daheim"] {
}

Now you may already call your sitemap with the following link. The

http://<openHAB_IP>:8080/basicui/app?sitemap=myHome

If you would like to use the Classic UI? You have to call

http://<openHAB_IP>:8080/classicui/app?sitemap=myHome

openHAB 2 Configuration – Frames

Now its time to get your items into the sitemap. We will use two frames. One will be used for the groups. The other one will be used to show items on the main screen. Typically this is useful for items you use a lot. This could be a central function like switching off all light before you leave your house or go to bed.

sitemap meinHaus label="Daheim" {
Frame label="Gruppen" {
   Group item=gBath     label="Bath GF" 	icon="rain"
   Group item=gLight    label="Light"  	        icon="group"
      }

 Frame label="Items" {
   Switch item=gf_ba_li_ceiling 
   Colorpicker item=gf_ba_li_mirror
 }
}

To keep it simple I will only show the Basic UI. You will see the groups and the items. 

I hope it is a bit easier for you now. If you would like a audiovisual training that helps you getting startet, enroll in my openHAB 2 Course.

openHAB 2 Configuration – Resources

• openHAB Documentation Items
• openHAB Documentation Sitemaps