Developers: New Item type(s) wanted

Wanted: An Item type ‘Selection’ or ‘Switch’, preferrably using an optional mapping definition

To the developers:

This is to ask for the implementation of another item type as described above. Please see the post at Missing item type: Selection list / Switch with mapping definition
for an example which shows (a) one menu with a number of categories, and (b) another menu which opens when I select the ‘Heizkreis1’ category which displays the configurable parameters of category ‘Heizkreis 1’. If I understand the concept of OpenHAB correctly, then each of the ‘Heizkreis 1’ parameters is represented by one ‘Item’ which can be queried and possibly set.

The one-of-n selections are a common mechanism of real-world things to modify their behavior, for instance during configuration or to select another operation mode. For instance, not restricted to my application which communicates with a heater controller:
o Select one of the seven weekdays
o Select one of many radio stations
o Select an operation mode (example in German): Frostschutz | Reduziert | Komfort | Automatik
o Select a lighting mood (Business | Reading | Romantic | …)

Users will be able to come up with many own examples.

The sitemap Elements syntax does indeed implement the Switch and Selection types but, as I understand, has a quite different purpose from the Items menu. The Sitemap elements define a top-level menu which can be likened to a table of contents (see the explanation quoted in the sitemap description). As such, the sitemap ‘Selection’ and ‘Switch’ elements will certainly serve a number of users well but not if they want to use Selections or Switch options in a lower level menu for an Item.

I believe that the addition of at least the Switch with an arbitrary number of options, preferrably with a transform function using a mapping definition, would be a great benefit for the users. Maybe some code or the concepts from the sitemap elements syntax can be reused.

Did you see the selection widget? You can use this as follows:

String	Yamaha_Input	"Input"	(Receiver)		{ yamahareceiver="uid=woziamp, zone=main, bindingType=input" }
Number	Chart_Period	"Zeitraum [MAP(]"


Selection item=Yamaha_Input		mappings=[HDMI1="BlueRay",HDMI2="Satellite",HDMI3="HDMI3",HDMI4="HDMI4",HDMI5="HDMI5",AV1="AV1",AV2="AV2",AV3="AV3",AV4="Roku",AV5="AV5",AV6="AV6","V-AUX"="V-AUX",USB="USB",SERVER="Server",TUNER="Tuner",AUDIO="Audio"]
Setpoint item=Chart_Period step=1 minValue=1 maxValue=12

1=1 Stunde
2=4 Stunden
3=8 Stunden
4=12 Stunden
5=24 Stunden
6=3 Tage
7=7 Tage
8=2 Wochen
9=1 Monat
10=2 Monate
11=4 Monate
12=1 Jahr

This will result in two widgets, the former will open a list from which you can select one entry, the latter will display a setpoint item with text, you can select one entry by browse with up/down buttons

You could use the Selection item also with a number item.

You can use this definition in every level of sitemap.


@brhar I’m not sure if this is a misunderstanding on either side…

This wouldn’t be an Item type. It would be a Sitemap element or at least a new way to construct the Sitemap. The Items involved would still be Number or String Items.

To meet the use case you have outlined the Mappings tag with Switch or Selection as @Udo_Hartmann describes are the current ways to achieve what you are after.

If you want to use subframes for something like this you must use separate Items for each entry in the subframe.

Well, but this new Item type is exactly for what I am looking because such Items with multiple selections shall be interspersed with other Items in the .items file and be displayed among those other items.

Thank you, Udo, for your examples. I have tried them and they display entries in the Sitemap menu, not in one of the submenus which constitute lists of Items and where I want them.

TomDietrich: Yes, I am aware of the Selection type or Switch type, each with multiple states, in the Sitemap syntax. As I have pointed out, Sitemap entries are not for what I am looking.

So, to sum up the current status: It looks as if Items cannot assume multiple values, at least not with the present OpenHAB core.

Hallo Harald,

I’ve read your whole posting again and I’m still uncertain of what you are looking for.

“Select one of the seven weekdays” and all the other examples you gave can be implemented just as @Udo_Hartmann showed in his example and this solution is used among many users. The different options are linked to certain states of items (be it number or string) and these states can then be used in rules or sitemaps. If you want to change the content of your sitemap based on said state, the visibility property can be used.

Could you give a small code or sketch example to illustrate your idea?

I agree with Thom, I’m confused.

A subframe is like another little sitemap you can navigate to. It is not intended to behave like a menu for selection.

And I also strongly maintain that what is being asked for is a UI feature and therefore would not be appropriate to implement as an Item.

Let me start with an OpenHAB quote from

Emphasis is mine. I am glad that the OpenHAB developers quoted this definition from, because it describes – also in their understanding - what a sitemap should be: an instrument to navigate through a maze of controls, a table of contents to quickly locate the subject one needs to find, in short: A mile-high view on a project. What it is not IMHO: a description of single controls and their behavior.

With this in mind, just looking at the current OpenHAB core implementation baffles me. There are sitemap elements like Selection and Switch which can have a number of options to select from. The important observation to me is that just by themselves they are not even bound to an Item but require some contrived incantations to accomplish that. But even then these sitemap elements are displayed in the same menu as all the other high-level view sitemap elements, while other menus defined in the .item file define the lower level view on one or more groups of items. In OpenHAB, the Items are which reflect the actions in the real world. Therefore it is in the .item files where Items with more than two options should be declared. It may be that the Selection and Switch elements in the sitemap files exist for some purpose and indeed are of use for some people. But their purpose and logic (!) eludes me.

It is illogical that an Item can already now be defined as a switch with two states ON and OFF but not as a switch with more than two states; after all, logically the two-position switch is only a special case of the multi-position switch, and the Selection is nothing else but a slightly different view on a multi-position switch. Both, the multi-option Switch and Selection exist side by side for a purpose.

It does not make sense for me that the Selection and Switch – both with multiple options - live as elements in the sitemap. The sitemap declares the top level view on whatever the implementation wants to control; the sitemap defines the entry level menu, not the Items.

On the other hand, if an Item is the thing closest to the real-world level of things, and since real-world things may have more than two options to select from or states which they can report, it is only sensible to allow Item definitions with more than two states or selections.

A sitemap may for instance define the rooms in a house; the Items to control within one room (for instance lights, roller shutters, receivers etc.) would be declared as separate groups of items for each room in an .items file. In my example I want to have a high level ordering scheme which declares segments of a heating installation (the radiators, the floor heating, the hot water boiler, the furnace, the heat pump, the solar system, etc.) in a .sitemap file. An .item file then aggregates the parameters of each segment as separate groups of Items. And it is there where I need to also declare Items which can assume one of multiple Selections. A click on an element in the sitemap display opens the display of parameters (Items) for this sitemap element, say, the hot water boiler, or “Heizkreis 1”.

Below are two screen shots how I picture an OpenHAB heating system controller. The sheer number of controls makes it practically impossible to stuff all controls into one menu. Therefore an ordering scheme or sitemap which lets the user select one segment or category at a time from the heating system controls serves as a navigation menu (first screen shot). A click on one of the entries brings up a display of controls for this category. The second screen shot shows such a group of control parameters (=Items) from the “Heizkreis 1” category which can be queried or set.

I have hinted before: Maybe I can’t see the forest for the trees. In that case I hope that your feedback helps me to see it :wink:

First screenshot: Sitemap view, high level

Second screenshot: Items view of category “Heizkreis 1”

following this thread, and have to say something. either

  1. if you arent happy with current, see if you can change it yourself


  1. if it doesnt work for you, maybe openHAB isnt for you

oh has come a long way in a short time, its not perfect, but there really is no perfect option, but in my opinion, its the most versatile option available. You can achieve what you are wanting with existing ways as Udo said, but this may not work for YOU, exactly as you want…

I will not go to this level of the discussion: take it or leave it. I prefer a logical level of exchange.

Maybe someone point out that my arguments are ill-conceived or simply wrong, and why. That might also help me to understand the OpenHAB philosophy.

If the following facts stand

  1. Items in the real world can have a number of choices how they work, as is exemplified by the ubiquitous pull-down menus in UI implementations
  2. There is no syntax for OpenHAB Items to include such Items in an Item file

then I see not much merit in your dismissive post.

Thank you to those who contributed their insight and have been willing to help.

It is perfectly alright with me if the developers answer “This feature would be nice to have but we do not have the resources right now to implement it.” THIS would be an understandable and an acceptable answer in this discussion. Branden_Smale, are you a developer?

Hi Harald,
I’m confused too, but i hope to know where your misunderstanding is.
As you described above this could all be done with the examples Udo, Rich and Thom tried to explain.
I think you focus on groups alot, right? So maybe you should post your sitemap-file of the example you posted. If you only add groups of items to the sitemaps you are unable to create “multi-position-switches” because they are defined in the sitemap based on an item with multiple possible values.
So you want something like this?

Maybe you can just make a picture of what you think it should look like.


Just to complete my example…
I don’t see all my Items in just one page, they are organized through frames and sub pages.
I’m using OH since many years, so I built my own sitemap from scratch long time ago. You will have to do this in OH2, too, the automatically built _default.sitemap is a virtual sitemap, only for testing purpose!

For example, when using my amp, I see this:

When selecting a Source, I see this (just a section, cropped a few rows…)

When displaying a chart, I decided to use setpoint to select the period:

[quote=“DRAGandDROP, post:12, topic:20673”]
I think you focus on groups alot, right? So maybe you should post your sitemap-file of the example you posted.[/quote]
You are right; I found the Group feature fits my purpose very well. Do you have a different suggestion?

See, this is apparently what I was missing.

Here is my sitemap; the relation to the first picture above is obvious g:

sitemap siemensbsbus label="BS-Bus Heizung"
    Frame label="Date" {
        Text item=Date
    Frame label="Kategorie" {
    Group item=gUhrzeitDatum            label="Datum und Zeit setzen"         icon="calendar"
    Group item=gZeitprogramm_HK1        label="Zeitprogramm Heizkreis 1"     icon="clock-on"
    Group item=gZeitprogramm_HK2        label="Zeitprogramm Heizkreis 2"     icon="clock-on"
    Group item=gZeitprogramm4_TWW        label="Zeitprogramm Trinkwasser"     icon="clock-on"
    Group item=gZeitprogramm5            label="Zeitprogramm 5"                 icon="clock-on"
    Group item=gFerienHK1                label="Ferien Heizkreis 1"             icon="calendar"
    Group item=gFerienHK2                label="Ferien Heizkreis 2"             icon="calendar"
    Group item=gHeizkreis1                 label="Einstellungen Heizkreis 1" icon="heating"
    Group item=gHeizkreis2                 label="Einstellungen Heizkreis 2" icon="heating"
    Group item=gTrinkwasser             label="Einstellungen Trinkwasser" 
    Group item=gTrinkwasserspeicher     label="Einstellungen Trinkwasserspeicher"    icon="cistern-80"
    Group item=gWartungSonderbetrieb    label="Wartung/Sonderbetrieb"
    Group item=gStatus                     label="Status"
    Group item=gDiagnoseErzeuger        label="Diagnose Erzeuger"
} // end of Frame label="Kategorie"
//Switch item=language mappings=[0="German" 1="English"]
} // sitemap siemensbsbus

And here is an excerpt from the .items file; the Selection in the second-to-last line is commented out because there is no such thing in the Item syntax. But RIGHT THERE BETWEEN other Items I would like to display a selection list.

 * There are several authorization levels of commands; they are in descending
 * order: OEM, Expert, Install, User.  Commands can be sorted into one of 
 * these groups.
 * Some more group definitions help to bring order into the commands.
// Hierarchy levels
Group    gAll
Group    gOEM                // OEM; top level, requres mfgr password
Group    gF        (gOEM)    // Fachmann, included in 'OEM'
Group    gI        (gF)        // Installation, included in 'Fachmann'
Group    gE        (gI)        // Endbenutzer, included in 'Installation'
// The different levels of authorization are only mentioned here; a scheme
// how users can elevate their authorization level is not implemented.

// ****************************************************
// Categories as defined in the manufacturer manuals
// ****************************************************
Group    gUhrzeitDatum
Group    gBedieneinheit
Group    gFunk
Group    gZeitprogramm_HK1
Group    gZeitprogramm_HK2
Group    gZeitprogramm_HK3
Group    gZeitprogramm4_TWW
Group    gZeitprogramm5
Group    gFerien_HK1
//Group    gKuehlkreis1   // if a heat pump is installed
Group    gFerien_HK2
Group    gFerien_HK3
Group    gHeizkreis1
Group    gHeizkreis2
Group    gHeizkreis3
Group    gTrinkwasser
(more ...)

// Heizkreis 1                     710 - 900
Number    Komfortsollwert_HK1           "Komfortsollwert HK1 [%.1f °C]"             <temperature>    (gHeizkreis1,gE)     {siemensbsbus="710"}
Number    Reduziertsollwert_HK1         "Reduziertsollwert HK1 [%.1f °C]"           <temperature>    (gHeizkreis1,gE)    {siemensbsbus="712"}
Number    Frostschutzsollwert_HK1       "Frostschutzsollwert HK1 [%.1f °C]"         <temperature>    (gHeizkreis1,gE)     {siemensbsbus="714"}
Number    KennlinieSteilheit_HK1        "Kennlinie Steilheit HK1 [%.2f]"            <line2>           (gHeizkreis1,gE)     {siemensbsbus="720"}
Number    KennlinieVerschiebung_HK1     "Kennlinie Verschieb HK1 [%.1f °C]"          <line3>             (gHeizkreis1,gF)     {siemensbsbus="721"}
Switch    KennlinieAdaption_HK1        "Kennlinie Adaption HK1"                                        (gHeizkreis1,gE)    {siemensbsbus="726"}
Number    SommerWinterHeizgrenze_HK1    "Sommer/Winterheizgrenze HK1 [%.1f °C]"    <temperature>    (gHeizkreis1,gE)     {siemensbsbus="730"}
Number    TagesHeizgrenze_HK1            "Tagesheizgrenze HK1 [%.1f °C]"                <temperature>    (gHeizkreis1,gF)     {siemensbsbus="732"}
Number    VorlaufsollMinimum_HK1        "Vorlaufsollwert Minimum HK1 [%.1f °C]"    <temperature>    (gHeizkreis1,gF)     {siemensbsbus="740"}
Number    VorlaufsollMaximum_HK1        "Vorlaufsollwert Maximum HK1 [%.1f °C]"    <temperature>    (gHeizkreis1,gF)     {siemensbsbus="741"}
Number    Raumeinfluss_HK1                "Raumeinfluss HK1 [%.1f %%]"                    <temperature>    (gHeizkreis1,gI)     {siemensbsbus="750"}
Number    RaumtempBegrenzung_HK1        "Raumtemperaturbegrenzung HK1 [%.1f °C]"    <temperature>    (gHeizkreis1,gF)     {siemensbsbus="760"}
Number    Schnellaufheizung_HK1        "Schnellaufheizung HK1 [%.1f °C]"            <temperature>    (gHeizkreis1,gF)     {siemensbsbus="770"}
//Selection Schnellabsenkung_HK1        "Schnellabsenkung HK1"    (gHeizkreis1,gF)     {siemensbsbus="780"}
// // !!!! here I would like to insert a Selection "Aus|Bis Reduziertsollwert|Bis Frostschutzsollwert"
Number    EinschaltoptngMax_HK1        "Einschaltoptimierung Max HK1 [%.1f min]" 

I can live with the OpenHAB Selection UI if I can mesh Selections it with other Items in the UI (like in the second to last commented line in the .items file which can of course not work) .

Sorry, Mario, no picture because so far I was unable to get the intended result on my screen :frowning: I hope the two pictures above in a previous post, the two files and my last remark answer Mario’s question.

Thanks again for your patience.

See, Udo, I started with Groups in the sitemap and matching Groups in the .items file; that gave me the expected separation of items which are now displayed in separate menus, one menu for each category. I suspect that was not the best way (but it looked exactly like I pictured (pun intended) the result).

ok. nice.
The problem with goups is that you cannot modify them in the sitemap.
So my sitemap only uses groups for values that have to be displayed without modification.
Most of the time in my sitemap every item defined in the .item file will have to be put in the sitemap manually and might be treated/formatted as i want it.

so your problem could be solved with the examples provided above.
you need one item that points to the right state.
That might be a Number that is returned by you SPS that represents the various states:
0 = Aus
1 = Bis Reduziertsollwert
2 = Bis Frostschutzwert
Or It’s a String that tells you the exact state like “Aus”, “Bis Reduziertsollwert” and so on. But I expect it’s a number that represents a state. So let’s assume this for the moment.

you need an item:

Number SelectionSollwert "Status der Heizung [%d]" {siemensbsbus="???"} 

in your sitemap you then need to enter this

Switch item=SelectionSollwert mappings=[0="Aus", 1="Bis Reduziertsollwert", 2="Bis Frostschutzwert"]

You can now setup a rule where you check for SelectionSollwert receives update or changes and then send commands to your heater to change temperature to specific values.

I hope this helps…


Selection item=MyItem 

Is a contrived incarnation? It follows the same pattern as literally every other sitemap element.

For cases where more than 2 states are possible a Number or String Item is used. If you want a Switch with more than two states you simply use one of these two for the Item Type and the Switch or Selection element on the sitemap.

Now you will have problems if you try to use Groups to define your sitemap because you cannot customize how am item is represented in the subframe. Instead you need to define the subframe yourself using

Text item=My group {
    Switch item=Item mappings ...

In short, what you want already exists .

After reading a lot further down I think you might be a little confused by that fact that one can define a very limited set of UI characteristics in the .item’s file. It is an unfortunate case of inconsistency. Really, for consistency sake, all UI attributes should by done on the sitemap.

1 Like

Rich, where is the “Like” button?

The examples above which other contributors provided had already given me helpful and valuable guidance; your explanation was the concise summary which I was missing when I started out to design my UI. Your diagnosis where I was mislead is right on the spot.

Since I had anyhow copied the OpenHAB online docs into LibreOffice files to have them at my fingertips during my attempts to get a grasp on this subject, I’ll include your post in my offline docs for future reference.

Thank you to all!

Hello @brhar,
I’m back looking at this thread and very happy to see that 1. this was indeed solvable and 2. you were able to come to an understanding. I was really confused in the beginning as we were apparently talking at cross-purposes (“an einander vorbei”). Building your own sitemap is a challenging task. I’ve revised my sitemap a lot and reached a few decisions for best practice.

If you are interested, check out my sitemap here. Open the image to see the full result.

You can find the following concepts:

  • Clean main page: Only the most important and summarized elements are shown, e.g. Speedtest, Kodi, Heating
  • Summarized Elements consist of a subframe with all the (relevant) details and controls
  • Conditional presentation: Elements are only shown if relevant, e.g. Sunset/Sunrise, Kodi Controls, Heating battery warnings
  • Groups are not used in the main part. The reasons are probably clear by now. Pay attention to this exeception: Text item=gLights, here the number of active lights based on the group is shown.
  • Administrative elements at the bottom. Here I’ll find ALL my items automatically sorted by groups, it’s a huge part of my sitemap but only a few lines in the sitemap file. This part should be available in every installation for debugging, tests and experiments. I’ve seen users with a dedicated sitemap for this.

On another note: You’ve linked the openhab 1.x wiki sitemap article in a previous comment. I hope you are aware of the successor for openHAB 2?

I would like to ask you to check the documentation again and tell us where and how this misunderstanding could have been avoided for you and can be for all future interested users.


Hi Thomas, shall do. Just give me a little time to digest it all before I respond here again.