How to make virtual item changeable in UI

Setup, Configuration and Use Beginners
1

For a functional workaround see below, but as a OH newbie, I might miss a better solution.

I have already have an (nonvirtual) item linked to a channel:

Thing mqtt:topic:evcc "evcc" (mqtt:broker:mqtt_default_broker) {
    Type string: warp2_charge_mode "warp2_charge_mode" [stateTopic="evcc-prod/loadpoints/1/mode", commandTopic="evcc-prod/loadpoints/1/mode/set", allowedStates="pv,now,off"]
}

The corresponding item:

String wallbox_charge_mode (g_wallbox) ["Sensor"] { channel="mqtt:topic:evcc:warp2_charge_mode"}

can be set in the UI and presents the allowed states for selection. So far so good.

Now I want a virtual item with a similar behavior. It should be configurable via the UI and present the same 3 options as above:

String wallbox_mode_after_charge "Modus nach Ende" (g_wallbox_timer) ["Point"]

The value is used in OH only, as a future state for the charge mode, when a charge timer runs out.

In the UI, it is read only, and I don’t know neither how to enable input nor how to configure a list of accepted values for a popup selection.

For now, I use a workaround by linking it to another (otherwise useless) MQTT channel, similar to the first item/thing link. Works fine, but smells funny. Is there a more elegant way?

2

From the UI’s perspective there is no such thing as a “real” Item and a “virtual” Item. There are just Items. The UI doesn’t know nor care if the Item is linked to a Channel or not. However, some bindings push information to the Item. In this case the MQTT binding pushes a State Description options when you use the allowedStates property. And the State Description very much influences how an Item appears.

First, there is probably a more appropriate semantic tag than “Piont” for this. Generally, it’s the Item type + the semantic tag that controls what widget gets shown by default.

But in your case, you need more than choosing between a slider and a stepper widget. You also need to supply some options.

  1. Navigate to the Item and click “add metadata” and choose “State Description”
  2. Set the “Options” to value=label pairs. The value is the command that will be sent to the Item when it’s selected and the label is what will appear in the list to the end user. Look to see if the Item appears and works as you need it to. If so you are done. If not continue.
  3. Save, click :“add metadata” and choose “default list item widget”
  4. Choose a “Label List Item:” for the type, fill out the properties and choose “Command Options” as the “Action”. This is the widget that will appear in the cards on the Locations, Equipment, and Properties tabs.
  5. If this Item appears by itself on some other Page, repeat 3 and 4 on “default standalone widget”.
3

My first approach is textual, as I am used to use infrastructure-as-code. But if has limitations, I grab a mouse. With State Description and a list of options, it works.

I also just found the concept page about the types. I misunderstod ‘Point’ as a measurement (i.e. point of a curve) instead of a coordinate.

Two documents that helped further helped my understanding:

Found with grep in the core repo, good enough for me. Maybe this information is noted elsewhere in an more approachable form.

4

There are some things that cannot be done through text files, mostly stuff related to custom MainUI widgets, some MainUI configs, and there are some limitations in some bindings.

Though it’s worth mentioning that even the stuff you configure through the UI is saved as text files. It’s just JSON and stored in another location ($OH_USERDATA/jsondb). I do all my launching and configuration using Ansible but I also have a 99% managed config in OH with not problem.

Item metadata can be defined in .items files between the { }. It takes the format <namespace>="<value>"[<config1>=<value1>, <config2>=<value2>]. stateDescription is one of the well known namespaces. Not all of the well known metadata is fully documented. Often the easiest way to learn how to use it is to create one in the UI and look at the code tab. The format there will be:

value: <value>
config:
  <config1>: <value1>
  <config2>: <value2>

For example:

value: ""
config:
  options: foo=bar,bim=baz
  readOnly: true
  pattern: "%d"
  min: "0"
  max: "100"
  step: "1"

would be in a .items file

stateDescription=""[options="foo=bar,bim=baz", readOnly=true, pattern="%d", min=0, max=100, step=1]

Point isn’t a coordiant in this context either. It’s a type of semantic tag. See Semantic Model | openHAB. The semantic model provides additional information to Items that allow add-ons like HABot to reason about your home automation and respond to natural language queries and it’s what lets MainUI automatically create the Overview Locations, Equipment, and Properties tags. But that’s all it’s used for.

The tags are hierarichal. In this case Point is the root of the hierarchy so it would only be used in cases where there is no other viable option and you decide not to create your own custom tag but you really want this Item to be in the semantic model (my rule of thumb is only about 60% of Items belong in the model).

For something like a “wallbox_charge_mode” I would expect the Point tag to be something like “Status” and the Property tag to be something like “Power”. The Point tag indicates what the Item represents or does (a control, a setpoint, a measurement, etc.) and the Property tag indicates what it does it to (e.g. temperature, humidity, power, etc.). A thermometer reading would be “Measurement, Temperature” but a thermostat heating setpoint would be “Setpoint, Temperature” and a heat alarm could be “Alarm, Temperature”.

The Point tag tells MainUI what UI widget to use when showing the Item (e.g. a Setpoint tells it to use a stepper widget) and the Property tag controls where the Item will appear on the Properties tab (e.g. all Temperature related Items appear in the Temperature card).

I don’t think the second document has anything to do with the semantic model.