openHAB Basics Tutorial - (Part 4/n) - Sitemaps & UIs

Sitemaps & UIs

Now, we’ll move on to the fun part of setting your openHAB system up - the user interface! This is the most rewarding part of your configuration, because you’ll actually get to see real-time results of all your work until now, and interact with your home automation things directly via the user interface.

So, in the previous post, I showed you a sample of my favorite user interface - the Habpanel. Habpanel is the most touch-friendly and easily configurable user interface in openHAB, and it doesn’t require anything more than what you’ve done so far (that is, creating the Items for your Thing Channels). That is because Habpanel interfaces directly to the Items, using “Widgets”. There are many types of Widgets and they use Items to show things like the state of your HVAC system temperature, or to control the color of your lamp. If you had nothing but computers and touchpads controlling your home automation system, you could easily get away with only using Habpanel.

However, Habpanel definitely likes large displays and may not be the best user interface for something like your phone screen.

For the phone screen, there are much better options, like the Basic UI or Classic UI. What you’re seeing here is the Basic UI, and I won’t focus on Classic UI in this video, because both are extremely similar in design and configuration, and only slightly differ in look and feel.

Both the Basic UI and the Classic UI do NOT interface directly to your items, like Habpanel does. Instead, these user interfaces depend on a configuration file called a “Sitemap”. Sitemaps define the layout and handling of items for the user interface, and tell the Basic or Classic UI how to interact with your Items.

Take a look at the layout of my Basic user interface. This is my “Home” or top-level layout of the Basic UI. My items are grouped into different sections based on things like location (first floor, second floor, garage, etc…), based on function (i.e. my Thermostat) and general status information. If you notice, this layout is pretty similar to the Demo user interface you installed if you followed my steps in the original openhabian configuration video.

As I’ve said before, the way that Basic user interface looks is defined by your sitemap file. The sitemap file lets you organize your items into meaningful sections, and use specific user controls for each item. For example, the sitemap file will you let you define how to show a Number item, whether you want to use a switch to select an audio input source to your whole-house amplifier


or a selection menu for one of the many possible effects on your holiday light LED strip


You can also hide different items under their own sections. Take a look at the island lights section in my kitchen.

In the Items & Links video, I showed you how I grouped the three different lights into a single Group:Dimmer item. Normally, I will want to use this single Group:Dimmer item to control all three lights. For the few occasions where I want to control each single light individually, I can click on the individual lights widget, and my Basic UI will switch to a new screen which shows me only the three lights that make up my kitchen island group. My sitemap allows me to do this - I would much rather hide these three individual light items on their own sub section of my user interface, rather than clutter my screen with all of the items shown at once.

So, now let’s look at my actual sitemap definition file. Just like the rest of the openHAB configuration files, the .sitemap files live underneath the openhab-config file directory. And just like with items files, you can have multiple sitemap files. However; when you configure your user interface on your phone or the PaperUI, you will have to select only one of those files to show up. The way you do this, is by opening up PaperUI

and clicking on the Configuration Section, Services page, and the UI tab. Click on the Configure link on the BasicUI item, and in the dialog window that pops up, fill in this Default Sitemap settting with the name of your sitemap file (without the .sitemap extension) and hit “Save”. You’ll notice that I have nothing configured for this in my system. That is because, if you do not change the name of your default sitemap (i.e. if the file is named “default.sitemap”), OpenHAB will use it as the UI sitemap automatically.

Every sitemap file has to start with this opening definition of a sitemap - the second argument on this line is the actual sitemap name that openHAB will use to identify it. The label is how you can name your sitemap however you want - I labeled mine simply with “home”

The rest of the sitemap file has to be written within these opening and closing brackets.

If you’ve been following this series from the start, I recommended you install openHAB with the demo configuration. If you did this, you already have a complete sitemap defined, and you can use it to modify it into your own design, or just play with it and see how your changes affect the look of the user interface.

If you’re starting out from scratch, you’ll want to find out about all the different possible components you can use in your sitemap definition.

The best source of this is the openHAB documentation, which I’ll link to in the video description.


Now, I will go over the basic components you can use in your sitemap, and show you examples of how they work to build up a fully functional user interface!

“Switch” is the most basic and easiest element to show you first. It’s exactly what you expect, and it ties to the “Switch” item directly.


Switch item=Light_Outdoor_FrontDoor

Notice that all I had to do to bring in the switch item into my Sitemap was call the Switch element and link it to the proper Item, I didn’t even define the text to show in the user interface. That’s because the User interface will pull that information directly from the item definition, including any formatting I configure in the items file.

“Slider” is most often used for Dimmer items, or things like lamp brightness or audio volume.


“Text” is a very versatile sitemap element, that can display the string value from any item. For example, I have Text elements in my sitemaps showing things like room temperature and humidity values or the date and time. Of course, you can format the string using all available string formatters.


Text item=Sunrise_Time icon="sunrise"

WIth this sitemap definition for the Sunrise time, notice that I also have defined a specific icon, showing the sun. You can define your own icons for the sitemap file, separate from the items definition. The sitemap icon definition will override your item definition. The list of available system icons is the same as I showed you in the Items video, but you can also add your own.

“Setpoint” elements are useful for Number items that require a precise selection within a small range. The best example of that is a thermostat heating setpoint.


Setpoint item=HVAC_CoolSetPoint minValue=60.0 maxValue=90.0 step=1.0 valuecolor=[>0="blue"] labelcolor=[>0="blue"]

Setpoint elements show up as numerical values with UP/Down buttons to allow you to modify the value. With these, you can also define the range you want to allow for your setpoint, as well as the step value. In my case, for the heating setpoint, I have a minValue of of 45 degrees Fahrenheit, a maxValue of 80, and a step of 1 degree. With these settings, The user interface will allow me to set the heating setpoint within the range of 45 to 80, and the value will change by 1 degree every time I press the UP or DOWN pushbutton.

“Colorpicker” elements are used with Color items, and allow you to select the hue, saturation and intensity of your color light bulbs or LED strips. The down and up arrows are simlar to the Setpoint element, and allow you to change the lamp brightness without opening up the full color picker control.


“Selection” elements are great for Number items with more than about 5 options. For example, my LED strips have over 30 different possible effects so far (and I’m always looking to add more). There’s no way I could fit all those items on a single line switch, like my audio source selection switch. The Selection element keeps all of the effects in one menu that pops up when I click on it.


At this point, I want to show you one very useful feature of sitemap files. That is the “mappings” element parameter. I mentioned that the Selection element modifies a Number item, but what you see in the menu that pops up is human-readable text corresponding to each available effect. I would rather see an informative text telling me that I’m about to select the “Hue Breathe” effect, as opposed to seeing a number like 32, which means nothing to me. In order to allow this, I need to define a mapping between the selection menu items, and the values that each selection will send to the Number item. In the sitemap element definition, you can define the mapping by opening up a square bracket, typing in the value that you want to send and the label you want to show to the user, and repeat this for all the values that are possible to select, separated by commas. Close the square bracket to complete the mapping. Now, when you select the informative and readable “Juggle” menu option, openHAB will use this sitemap mapping to send a value of “9” to the LEDstrip effect Number item.

Selection item=LEDStrip_Kitchen_Cabinet_FX icon="mediacontrol" mappings=[1="BPM",2="Noise",3="Fire",4="Rainbow",5="Twinkle",6="Glitter",7="Solid",8="Sinelon",9="Juggle",10="Confetti",11="Dots",12="Lightning",13="Candy Cane",14="Cyclon Rainbow",15="Ripple",16="Christmas Alternate",17="Police All",18="Police One",19="Random Stars",20="Sine Hue",21="Christmas",22="St Patty",23="Valentine",24="Turkey Day",25="Thanksgiving",26="USA",27="Independence",28="Halloween",29="Go Lions",30="Hail",31="Touchdown",32="Punkin",33="Lovey Day",34="Holly Jolly",35="Full Hue",36="Breathe",37="Hue Breathe"]

You can use mappings with other sitemap elements, as you may have already seen before on the audio source Switch element, where I mapped the possible, currently connected audio input sources to their correct values in the Switch element mapping. Now, instead of having to choose the number “5” and knowing it’s my Chromecast input, I can use a more informative label on the Switch element, which will send the value of 5 to my Monoprice amp audio source Number item.


Switch item=MonoPrice_Z11_Source mappings=[2=BT,3=DJ,5=CAST,6=CD] visibility=[MonoPrice_Z11_Power==ON] icon="receiver"

“Group” elements are great for dropping a full set of items into your sitemap file with a single line. For example, I just add the Group sitemap element with the second floor group, and all of the items (including subgroups) that belong to my second floor group are going to be added to the user interface, using the default sitemap elements for each item type.

Group item=gSF

One thing to consider when using the Group sitemap element is that you won’t be able to modify any of the parameters (including icons or mappings) of the group members within your sitemap. So, if I wanted to make some modifications to a volume slider icon or map my audio input sources within the Kitchen group items, I can’t just add the Kitchen group to my sitemap. Instead, I have to add all items within that group to my sitemap individually.

“Frame” - Up until now, every sitemap element I showed you required an item to be defined for it. However, “Frame” is a specific type of sitemap element, which does not require an item. “Frame” elements are used to layout and organize other sitemap elements into sections within your user interface. For example, you can see how my sitemap file is made up of three major Frame elements. The first “Frame” contains my house area group items, like the Attic, first and second lfoors and outdoors. All of the items I define within the Frame element (that is, between the opening and closing brackets) will be grouped into their own section, as you can see on my user interface. For the second “Frame” which contains my Thermostat elements, you can see I also added a “label” field. I can use the label field as a title for my specific sitemap section. As you see, the “Thermostat” label shows as a big title for the Thermostat section in my user interface when I use the label field on the Frame element.

As you may have already seen, user interfaces aren’t limited to a single page. You can easily create nested, multi-level interfaces. Let me show you an example.

As we saw earlier, I had the group dimmer for my kitchen island lights on the main Kitchen page, but also another element which opens up a new page with the individual island light sliders. I did this by adding a Text element to my Kitchen sitemap page, opening up the curly brackets, and putting the additional Slider elements within the brackets. You can nest these Text (or Group) elements as you wish, to create multi-level user interfaces, like I showed you here.

					Text label="Island Light Individual" icon="slider"
						Slider item=Light_FF_Kitchen_Island_L
						Slider item=Light_FF_Kitchen_Island_C
						Slider item=Light_FF_Kitchen_Island_R

So now that I’ve shown you the different sitemap elements and how to use them, let me also quickly show you some nifty ways to pretty up your user interface, with these additional element options.

The first two are labelcolor and valuecolor. Both allow you to change the color of the label or the value, based on conditions like the value of the item, or even other item states. For example,


valuecolor=[>0="red"] labelcolor=[>0="red"]

I have these thermostat heat and cool setpoint labels set up to turn red or blue, depending on their function, and based on the value of the setpoint (in this case, it’s set to always turn red or blue when the value is greater than 0).

This Outside temperature value color is modified using the state of the Weather_LastUpdate item. This item stores the length of time since the outside temperature item was updated, and the valuecolor option changes the color of the sitemap value depending on that length of time. Basically, you can use this to show if a value you’re looking at it stale or if it’s been recently refreshed. Check out all of these ranges and possible colors - you can use all logical operators here, for example the greater than/less than signs, or use the double equal signs for conditional true or false statements.


Text item=localCurrentTemperature valuecolor=[Weather_LastUpdate=="Uninitialized"="lightgray",Weather_LastUpdate>90="lightgray",>25="orange",>15="green",>5="orange",<=5="blue"]

I think one of the coolest modifiers to use is the visibility option. Sometimes, you just don’t want to see all of the sitemap elements, unless a specific switch is on or another condition is true. For example, my Monoprice amp allows me to set the source, set or mute the volume and other options, per zone. But, if that zone is turned off, I may not want to see or use any of the additional settings.

So, in my user interface, if I have the Office Audio zone turned OFF, I only see that switch, and the rest of my office items on the sitemap. As soon as I turn the zone ON, all of the remaining sitemap elements and audio zone settings show up - pretty cool, right?

					Switch item=MonoPrice_Z12_Power
					Switch item=MonoPrice_Z12_Source mappings=[2=BT,3=DJ,5=CAST,6=CD] visibility=[MonoPrice_Z12_Power==ON] icon="receiver"
					Slider item=MonoPrice_Z12_Volume visibility=[MonoPrice_Z12_Power==ON] icon="soundvolume"
					Switch item=MonoPrice_Z12_Mute visibility=[MonoPrice_Z12_Power==ON]				

The way to do this in the sitemap file is very easy - just add the visibility option to each sitemap element you want to hide, and use a conditional statement to check the item you want to use to show or hide those elements. In my case, I’m checking whether the Monoprice zone 12 power item is set to ON (notice, this is the same item I’m switching with the power switch element above). and only showing these three items if that power switch item is set to “ON”.

I hope this gives you some ideas on how to use these options in your own sitemap. For example, you could use the visibility option to show an alarm condition on your sitemap, but only if the value of the alarm status item is set to a particular state.

So, we’ve reached the end of another section of this tutorial series. By now, you should have a really good idea of how to configure your openHAB system for controlling your home’s smart devices. In the next topic of this series, we’ll start looking at Rules, which allow you to do actual automation tasks (like turning on some of your interior lights when the sun sets).

Previous Topic

Next Topic

Full VIdeo