From MQTT 1-x to 2.4 -> how to get things into BasicUI?

Hi guys,

I’ve installed OH2 a few months ago on my RPi 3 and updated it to the latest release last week, and now I wanted to get all my things to the new MQTT binding.
After reading some tutorials I understood how to create things in PaperUI, but I didn’t understand how I can get them to BasicUI, which is the UI I use for control.
Do I still have to create an .items configuration file? If yes, then I don’t understand if I have to create them in PaperUI also. If no, then I’d like to know if I refer to the PaperUI created things in my .sitemap file.

Thank you for helping!

The answer is “either or”, you can use PaperUI to create and link items to your things (even automatically) or you can create the items with a file. While creating the items with a file you can link them to a Thing (or batter a channel) directly or do the linking in PaperUI.

Examples for an items file are posted in the docs.

1 Like

Hallo Jürgen,

that means if I want to use BasicUI i MUST create .items files, right?


Yep, you have to create items and link them to the channels of the things. That way, you can see your data in the Basic UI (and all other clients).

Incidentally, if you have no linked item at all for a thing, that thing will not be displayed in the Paper UI as well.

…and when I use MQTT 2 binding I have to create the .items file with the new syntax, right?

In short terms:

  • PaperUI: create things first, then items from the channel ON WEBSITE
  • BasicUI: create NEW MODE .items file ON CONSOLE


As said it is either or. You can use items created by or with PaperUI in a Sitemap.
For openhab there is no difference

Ummmm… I would say that this is not correct, sorry. You can create your items either using Paper UI or through manually defined .items files. Once items are defined (it doesn’t matter how you have defined them), you can create your personalized user interface for Basic UI defining .sitemap files.

But the two worlds are totally separated: items and sitemaps. The second ones are created based on the first ones, but it is irrelevant how you have defined the first ones.

Are thing more clear now? :+1:

Best regards,


Ok, it’s clear now.

Anyway I have problems integrating new things by using the PaperUI.
An example: I have a Blitzwolf switch, MQTT topic is “Blitzwolf_SHP2_02”.
With PaperUI I have configured a thing first and a channel then.
Problem is: I don’t know how to integrate it into my sitemap, what do I have to insert after “Switch item=”? Whats the items name?
Or did I fail to insert the thing itself? Are thing’s NAME and ID relevant for the sitemap?!

Thank oyu again for your precious help!!!

You decide:

Switch item=MyFancyNameItem { channel="mqtt:xxx:xxx:channel" }

You can copy and paste the channel name from the thing overview:

From null

1 Like


I have exactly the same problem/request than “Lemon”.
I tried what you say and add the following line to my mqtt.sitemap file:
Switch item=MyFancyName { channel=“mqtt:topic:SW01:INT_01” }

So that my full file is this one:

sitemap mqtt label=“MQTT”
Frame label=“MQTT Demo”
Switch item=MyFancyName { channel=“mqtt:topic:SW01:INT_01” }
} // end of Frame
} // end of sitemap

I then have a parsing error. Here is a copy of the log file:

2019-01-17 16:54:45.692 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model ‘mqtt.sitemap’ is either empty or cannot be parsed correctly!

2019-01-17 16:54:46.877 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model ‘mqtt.sitemap’ has errors, therefore ignoring it: [5,27]: mismatched input ‘{’ expecting ‘}’

To be clear, I did exactly as Lemon explain

  • add mqtt broker thing in paper UI
  • add a channel for that thing in paper UI
  • Now, I want to link that to a sitemap

I did NOT have .things or .items files !!

Thank you for support!

The item definition which you copied from @vzorglub has to be pasted into the items file!

1 Like

I already tried that but there is another problem:

If I do that I have a second item that is created.
The both items are linked to the same channel !
I can see both items in Paper UI / Control

  • The 1st is the one created via paper UI
  • The second is the one created by the .items file

How to link a sitemap to an item but without creating a new item ???
Thank you

Ok, I put

    Group item=Stock1_Schlafzimmer {
      Switch item=MyFancyNameItem { channel="mqtt:topic:Blitzwolf_SHP2_02:Power" }

but the log tells me

Configuration model ‘home.sitemap’ has errors, therefore ignoring it: [107,32]: mismatched input ‘{’ expecting ‘}’

and sitemap is not available anymore in BasicUI.

Don’t know if this matters (other posts tell of just optical bug, not funtional in OH 2.4):

Did your consider to take a look at the Sitemap documentation
Furthermore you have most probably selected " automated item linking" . That way items are automatically created.

It seems you have created the Broker by file and die a Change to that file. You Need to Restart openhab!

Hallo Jürgen,

in fact I did take a look at the sitemap documentation. But there was nothing written about putting items directly into sitemap:

I have active MQTT 1.x and MQTT 2.4, all my other items are in a .items file, this Blithwolf switch should be the first MQTT 2.4 thing.

By the way, “Simple Mode” was always off, so no automatic item linking did succeed.

Ok, seems to be clear now.
I’ve discovered that after creating the channel I have to link it and the link name will be the name I have to use in my sitemap file, in this example it will be EinsZweiDrei_Power:

In sitemap file I write then:

Switch item=EinsZweiDrei_Power

and that’s it.

Did I miss something?

Sorry, but I mixed that up, it wasn’t you stating to have no items file.

Regarding what to put into the sitemap file:
Items are needed in the sitemap file, but only the name is used. The definition of the item ( " {channel…}" ) belongs into the .items file.
The connection between the item and thing-channel is done by linking. The link has no name, you are only referring to the item.
When creating the link via PaperUI you did create an item ( with the selected name ).

Your posting shows the contents of an items file!
A sitemap looks like that (copied from the link above):

sitemap demo label="My home automation" {
    Frame label="Date" {
        Text item=Date
    Frame label="Demo" {
        Switch item=Lights icon="light"
        Text item=LR_Temperature label="Livingroom [%.1f °C]"
        Group item=Heating
        Text item=LR_Multimedia_Summary label="Multimedia [%s]" icon="video" {
            Selection item=LR_TV_Channel mappings=[0="off", 1="DasErste", 2="BBC One", 3="Cartoon Network"]
            Slider item=LR_TV_Volume

I’ do see several “items=…”.

Well, that is an important information. So I have to either create still an item file or do this linking. Good to know :slight_smile:

Thank you again!!!