Having a Sitemap but How to Add Items?


I just started recently with OpenHAB and yes, I am a newbie regarding this. But the docs did not bring any light here…

I create with the site builder UI a sitemap which I copied to ./sitemaps/LOCATION.sitemap. According to the log the sitemap is read and I can see it in my Basic UI.

On the paper UI I have several things already discovered and configured (mostly Enocean devices) and I can switch the (experimental) light on and off through PaperUI. Perfect so far.

But how do I tell the Basic UI (which shows the sitemap) which item is in which room? Soory, I do not get it here…

I thought I have to use the device ID or stuff like this. But where to add it? And what to add?

It is a little bit confusing, sorry for this.

Any hints here?

Thanks a lot!


If you used the Site Builder, that is where you do that. Most of us edit the sitemap file(s) directly.

Well, I thought I use the HomeBuilder to create my site. And then edit the sitemap file to add the correct things/ items to the file.

But again: I have things in my PaperUI which I want to add to a room in my sitemap.

How to do this? (command line preferred) If not command line- HomeBuilder is not really useable as it appears to me it always creates a sitemap from scratch so I would have to re-build it every time when my smart home grows… I think this is not the way it is supposed to work…

Use site builder to create a sitemap once and then edit it on command line. Adding things and stuff… but again: how and where?



Have you looked in the official documentation?

Well, I really did. But it does not explain how and where to add the things from PaperUI.

Ok, I will show you guys. In PaperUI I have a sensor for my window (called “Fensterschalter”):

In Basic UI I have my sitemap (which I configured through HomeBuilder):

where I can see the different Rooms and so on:

So in the wardrobe (Erdgeschoss- Garderobe) I have a door (“Tür”):

And I want to tell OpenHAB the above “Fensterschalter” from the PaperUI is the one which covers the door in the wardrobe.

So, how to do this?

I hope my explanation was good enough now.

THanks again!


please show us your sitemaps file.
The official docs have a section about the sitemap concept and examples how to define items there.

Ok, the full one, here you are:

sitemap GROSS label="GROSS" {
    Frame label="Keller" icon="cellar" {
        Group item=C_Boiler
        Group item=C_LaundryRoom
        Group item=C_Stairwell
        Group item=C_StorageRoom
        Group item=C_Werkstatt

    Frame label="Draußen" icon="garden" {
        Group item=OU_Backyard
        Group item=OU_FrontYard
        Group item=OU_Garage
        Group item=OU_Shed
        Group item=OU_Terrace
        Group item=OU_Entryway
        Group item=OU_Huhnerstall
        Group item=OU_Schafstall

    Frame label="Erdgeschoss" icon="groundfloor" {
        Group item=GF_Bathroom
        Group item=GF_Wardrobe
        Group item=GF_Hallway
        Group item=GF_Kitchen
        Group item=GF_LivingRoom
        Group item=GF_StorageRoom
        Group item=GF_FamilyRoom

    Frame label="Erster Stock" icon="firstfloor" {
        Group item=FF_MasterBedroom
        Group item=FF_Bathroom
        Group item=FF_GuestRoom
        Group item=FF_Office
        Group item=FF_KidsRoom
        Group item=FF_Hallway
        Group item=FF_Loft
        Group item=FF_Studio

    Frame {
        Text label="Licht" icon="light" {
            Default item=C_Boiler_Light label="Heizungsraum"
            Default item=C_LaundryRoom_Light label="Waschküche"
            Default item=C_Stairwell_Light label="Treppenhaus"
            Default item=C_StorageRoom_Light label="Lagerraum"
            Default item=C_Werkstatt_Light label="Werkstatt"
            Default item=OU_Garage_Light label="Garage"
            Default item=OU_Shed_Light label="Schuppen"
            Default item=OU_Entryway_Light label="Zufahrt"
            Default item=OU_Huhnerstall_Light label="Hühnerstall"
            Default item=OU_Schafstall_Light label="Schafstall"
            Default item=GF_Bathroom_Light label="Badezimmer"
            Default item=GF_Wardrobe_Light label="Garderobe"
            Default item=GF_Hallway_Light label="Flur"
            Default item=GF_Kitchen_Light label="Küche"
            Default item=GF_LivingRoom_Light label="Wohnzimmer"
            Default item=GF_StorageRoom_Light label="Lagerraum"
            Default item=GF_FamilyRoom_Light label="Familienzimmer"
            Default item=FF_MasterBedroom_Light label="Hauptschlafzimmer"
            Default item=FF_Bathroom_Light label="Badezimmer"
            Default item=FF_GuestRoom_Light label="Gästezimmer"
            Default item=FF_Office_Light label="Büro"
            Default item=FF_KidsRoom_Light label="Kinderzimmer"
            Default item=FF_Hallway_Light label="Flur"
            Default item=FF_Loft_Light label="Loft"
            Default item=FF_Studio_Light label="Studio"

        Text label="Steckdose" icon="poweroutlet" {
            Default item=C_Boiler_Power label="Heizungsraum"
            Default item=OU_Schafstall_Power label="Schafstall"

        Text label="Temperatur" icon="temperature" {
            Default item=C_Boiler_Temperature label="Heizungsraum"
            Default item=GF_Hallway_Temperature label="Flur"

        Text label="Luftfeuchtigkeit" icon="humidity" {
            Default item=C_Boiler_Humidity label="Heizungsraum"

        Text label="Heizung" icon="heating" {
            Default item=GF_Bathroom_Heating label="Badezimmer"
            Default item=FF_Bathroom_Heating label="Badezimmer"

        Text label="Tür" icon="door" {
            Default item=GF_Wardrobe_Door label="Garderobe"

        Text label="Bewegungsmelder" icon="motion" {
            Default item=GF_StorageRoom_Motion label="Lagerraum"
            Default item=GF_FamilyRoom_Motion label="Familienzimmer"
            Default item=FF_Hallway_Motion label="Flur"

        Text label="Fenster" icon="window" {
            Default item=FF_MasterBedroom_Window label="Hauptschlafzimmer"
            Default item=FF_Bathroom_Window label="Badezimmer"
            Default item=FF_GuestRoom_Window label="Gästezimmer"
            Default item=FF_KidsRoom_Window label="Kinderzimmer"
            Default item=FF_Loft_Window label="Loft"

That is because you can’t do that.

You have just listed group items. Do you have any items assigned to those groups?
Please read the sitemap section carefully.


I can’t do that? Why not?

I have a sensor (enocean) which is on my door. I would like to see my house in terms of rooms, not items. Therefore I have a sitemap. And now you say I can not add any devices there? So the sitemap is useless as it is just a map without content?

What am I missing here?

This might be the point. And no, this is not mentioned in the docs (or I do not understand it there). They mention groups as a special Item type that can be used to define a category. Which I do not want (nor need currently).
I shortened the sitemap now an hopefully you can tell me where and how to add the item from PaperUI to the sitemap:

sitemap Demo label="Demo" {
    Frame label="EG" icon="groundfloor" {
        Group item=GF_Wardrobe

So I have a single location defined. Within this location I have a frame called “EG” and one group called GF_Wardrobe.

So you say I have to define the group items here?
In the docs I read about configuring group items which is not really helpful as it simply groups groups together (livingroom, temperature) but still not having a clue how to tell about the door contact…

Number Livingroom_Temperature "Temperature [%.1f °C]" {channel="..."}

Appears I have to add something like the channel paramer to the line (as an item? as a switch?).

But where do I get the channel from?


That is essentially it, yes.
A sitemap only describes which Items to show and how to show them.
It has no influence at all over what Items actually exist in openHAB, what kind of Items they are, how they are linked to any Things representing real devices, or how the Items might be arranged in Groups.

All that happens elsewhere.
You will references to managing Items, links, and Things with both PaperUI or with a text file based method of xxx.items and xxx.things files.
What you do when using Sitebuilder I do not know, but therelationships will be the same.
Real devices -> Things -> channels -> idealized Items -> sitemap for display of Items.

Still don’t get it, sorry.
I see screenshots from sitemaps where i.e. current degrees are shown. In my sitemap above I see a slider for the light.
Am I right these values change depending on what the devices (temperature measuring or a Enocean switch for the light). But for this the sitemap needs to know WHICH device it should show.

And this is what I am missing here…
How the heck do I tell my sitemap to use the value from device foo?
I mean, if it would not have this linking there would be absolutely no sense in a sitemap as I do not see any current states…

Well, this looks more or less what I am looking for. I guess I alread have the first two links somehow through PaperUI (real device [door contact] to a thing [in PaperUI] which is connected to a channel.

Now I am looking for a way for the next steps. What means “idealized items”? Where do I define them? And how do I tell my sitemap to display the values of these items?



You don’t.
You tell the sitemap to interact with an Item.
An Item is an idealized model device, like a dimmer, which are at the heart of openHAB.
A logical, imaginary, perfect device. All dimmer Items look and behave alike, whether they eventually link to a zwave dimmer or a modbus motor speed controller or an ethernet relay board or a remote webpage.
So it becomes easier to manage Items in rules and displays.

Things are the representation of real devices in openHAB, like a zwave dimmer device.
Things have channels, like a brightness % channel or an on/off channel.
Things take care of all the differences between real world devices, whether they dim 0-100%, or 0-254 steps, or 0-10. Whether they have different commands for on/off and setting brightness, or just the one setting. Whether they give feedback about changes, or none.

To do anything useful, you’d link an Item, using a channel, to a Thing.

When that chain has happened … your sitemap will be able to show and command a zwave dimmer.

Hi @knebb

I suspect that you didn’t see the New User Tutorial for “Creating a sitemap”. There’s a crucial statement in it, which I’ve bolded below.

Controlling your things via Paper UI is nice, but currently you can sort them only by editing the “Location” in the thing configuration. If you want to create your own view you can use a so-called “sitemap” which can be displayed in the Basic UI (you remember, it was automatically installed at the beginning).

But before that, you have to create an items file.

I think what you’re trying to do is go straight from PaperUI to a sitemap. Per @rossko57’s comments, there’s an in-between step of creating text-based items files. The tutorial above will take you through the entire process: take the things from PaperUI, link them to items you define in text files, and then show those items in a sitemap.

Hope that helps!


I read the Beginenr’s Guide. But it did not really explain it (well, somehow it does once you know…).
Ok, I think I understood how it should work…
But I am still struggling with it.

So this is the current state:
Having a thing in PaperUI which is a door contact:
From the edit icon in PaperUI I copied the channel (?) of “Contact”:

Then, I created an item in a file called manual.items (at the right location) which simply contains only this thing (item):

Contact Door_Contact "Eingangstür" <switch> { channel = "enocean:mechanicalHandle:FTB3SXG:FEF70304:contact" }

As it is a “contact” and not a switch (I can not send any commands to it) I did not use the “Switch” type as per docs.

Now I have an item called "Door_Contact which I then tried to add to my Demo.sitemap:

sitemap Demo label="Demo" 
    Frame label="Erdgeschoss" icon="groundfloor" {
        Contact item=Door_Contact label="Eingangstür"

But I am getting strange errors in openhab.log:

2020-04-25 08:50:31.857 [INFO ] [el.core.internal.ModelRepositoryImpl] - Refreshing model 'manual.items'
2020-04-25 08:50:45.108 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model 'Demo.sitemap' has errors, therefore ignoring it: [4,2]: required (...)+ loop did not match anything at input 'Contact'
[6,1]: extraneous input '}' expecting EOF

2020-04-25 08:50:46.149 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model 'Demo.sitemap' has errors, therefore ignoring it: [4,2]: required (...)+ loop did not match anything at input 'Contact'
[6,1]: extraneous input '}' expecting EOF

2020-04-25 08:50:49.805 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model 'Demo.sitemap' has errors, therefore ignoring it: [3,2]: required (...)+ loop did not match anything at input 'Contact'
[5,1]: extraneous input '}' expecting EOF

2020-04-25 08:50:50.844 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model 'Demo.sitemap' has errors, therefore ignoring it: [3,2]: required (...)+ loop did not match anything at input 'Contact'
[5,1]: extraneous input '}' expecting EOF

So I am really stuck here. Where is my mistake?

Thanks a lot!



seems to be an issue with the “Contact” type of the thing/ item.

I now used a network device to add i to my manual.items:

        Switch Net_BackupPC "BackupPC" <network> { channel="network:pingdevice:192_168_9_1:online" }

And added it to Demo.sitemap:

sitemap Demo label="Demo"
        Switch item=Net_BackupPC label="BackupPC"

Now I am not getting any errors in openhab.log and I can indeed see my network device in my Demo site:

Appears to be working so far now. But why can I not create a Contact item? I want to see if my door is open or not. Using a Switch is not correct as I can not send a command to my door: “Close”…

For contact item, best use a string item in your sitemap.

Nothing wrong with your Contact type Item, of itself.

As we covered before, the sitemap is just a bunch of instructions about how to display Items. It’s structured list of widgets, each with additional details about how to configure that widget.

So here’s your sitemap.
Frame is a widget with no associated Item, it just makes a box graphic.
Contact is a … error. There is no Contact type widget in sitemaps.

While some have similar names, there is no relationship between sitemap widgets and the Item types you can associate with them. It’s common for example to use a Switch sitemap widget with a Number type Item, presenting buttons 1 to 4 and suchlike.

So, if there is no Contact type widget, how do you display a Contact type Item?
Use a Text widget, which shows Item details without any user buttons. You can use a Text widget with any Item type.

It’s hard work getting started in openHAB, because there is lot of different concepts and things to get right from end to end to get just that first device working.
Stick with it, it comes together.


I meant a text item widget on the sitemap…