What do the channel-type/state/options/option actually do?

I have a channel-type defined like so

<channel-type id="source-format">
		<state readOnly="true">
				<option value="02">480p</option>
				<option value="03">576p</option>
				<option value="04">720p50</option>
				<option value="05">720p60</option>
				<option value="06">1080i50</option>
				<option value="07">1080i60</option>
				<option value="08">1080p24</option>
				<option value="09">1080p50</option>
				<option value="0A">1080p60</option>
				<option value="0B">No Signal</option>
				<option value="0C">720p 3D</option>
				<option value="0D">1080i 3D</option>
				<option value="0E">1080p 3D</option>
				<option value="0F">Out of Range</option>
				<option value="10">4K(4096)60</option>
				<option value="11">4K(4096)50</option>
				<option value="12">4K(4096)30</option>
				<option value="13">4K(4096)25</option>
				<option value="14">4K(4096)24</option>
				<option value="15">4K(3840)60</option>
				<option value="16">4K(3840)50</option>
				<option value="17">4K(3840)30</option>
				<option value="18">4K(3840)25</option>
				<option value="19">4K(3840)24</option>
				<option value="1C">1080p25</option>
				<option value="1D">1080p30</option>
				<option value="1E">2048x1080 p24</option>
				<option value="1F">2048x1080 p25</option>
				<option value="20">2048x1080 p30</option>
				<option value="21">2048x1080 p50</option>
				<option value="22">2048x1080 p60</option>
				<option value="23">3840x2160 p120</option>
				<option value="24">4096x2160 p120</option>
				<option value="25">VGA(640x480)</option>
				<option value="26">SVGA(800x600)</option>
				<option value="27">XGA(1024x768)</option>
				<option value="28">SXGA(1280x1024)</option>
				<option value="29">WXGA(1280x768)</option>
				<option value="2A">WXGA+(1440x900)</option>
				<option value="2B">WSXGA+(1680x1050)</option>
				<option value="2C">WUXGA(1920x1200)</option>
				<option value="2D">WXGA(1280x800)</option>
				<option value="2E">FWXGA(1366x768)</option>
				<option value="2F">WXGA++(1600x900)</option>
				<option value="30">UXGA(1600x1200)</option>
				<option value="31">QXGA</option>
				<option value="32">WQXGA</option>

Are the channel-type/state/options simply there for documentation, or can they be applied? Values seem to pass-through updateState() unchanged. I need to get a better understand of what to expect.

It is some kind of value limiting and mapping. In Your case, a value of 02 will be shown in PaperUI as 480p.

value limiting and mapping

This is what I am expecting, but this is not what I’m seeing. Where is it applied? I’ve traced the code all the way up to the OSGiEventPublisher.post() call, and I don’t see where any of it tries to do a transformation, aside from profiles in the CommunicationsManager.

be shown in PaperUI

I’m developing in v3 environment. PaperUI is gone now?


Problem accessing /paperui/index.html. Reason:

Not Found

[Powered by Jetty:// 9.4.20.v20190813](http://eclipse.org/jetty)

There are other UIs


Did not know that. It should still limit possible values.

I have seen ways to do this in items and with profiles. However, I am developing a binding, and I’m must develop a contract for my interface. As the developer of a binding, my job is to hide the physical implementation details behind my interface and provide users with a predictable contract. It would be inappropriate to supply a binding that can’t work out-of-the-box without hundreds of UI hacks. All of the mapping needs to happen inside the binding, and the users needs to be interacting with a sane API (channels), and not have to get their hands on a device manual in order to figure out what to do with raw values.

openHAB wisely divided concerns and supplies physical, logical(virtual), presentation, etc. abstractions. Bindings from what I can see expose an interface between the physical (channel) and logical(item) abstractions. Users are free to create virtual and UI aggregation and higher level abstractions, but I’m looking to understand developing a sane binding interface that honors separation of concerns and provides the correct level of abstraction for the virtual consumer.

The options are used with sitemaps. If you show an item on a sitemap it will display the option content and if you configure it as a Selection the ui will render it as a selection box.
Its also possible to fill these options dynamically in the binding. For example for a list tv channels.

Options are also used in the new MainUi by openHAB 3.0.
As you can see in the screenshop, only mode (Betriebsart) options defined in thing-type channels are seen and selectable.

So, is it safe to say that raw values, as supplied by the binding, are carried throughout, at least with string type, and <options> provides a dictionary with which various elements in the system can get a translation?

So rather than values being translated once as they enter or exit the binding, they’re translated by each element of the system each time they’re needed?

Are there cases where a user might need to interact with an untranslated value, like during scripting, configuring, rule creation, etc., or will the raw value always be hidden from user view? I may translate the raw device values to at least “parser friendly” mnemonics in that case.

That sounds about right. After all, the Item does not “belong” to the binding, the user may do with it what they wish - including linking to other bindings etc. stateDescription may be used to offer ‘suggestions’ like a menu, but should not otherwise constrain the Item.
I haven’t figured out what happens when an Item is linked to channels with competing stateDescriptions!

Your binding can of course apply any constraint it likes to channel data in/out, and can helpfully offer descriptions of the data.

Considering actual Item state, you can’t please everyone e.g. due to language. Whether it’s best to use raw device supplied codes or substitute your own, you’re best placed to decide.

Interaction with the binding will always be done trough the raw values. From your example in the first post, 02 will be the raw values, needed e.g. in rules, whereas 480p is what the UI presents to the user. You can also define this as parameters, used for translation into different languages.

Furthermore, as said before, you can limit the possible values like many bindings do if it comes to special operation modes like thermostat, hvac, air conditioners, …

Well, I don’t really want to translate more than necessary. So, I’m okay with

Device   Binding   UI
0F ->    0F ->     "Out Of Range"

But, while 0F is efficient for parsing, it means nothing to a user who might need to interact with it. So, in that case I’d prefer

Device    Binding         UI
0F   ->   "outOfRange" -> "Out Of Range"

to be parse friendly you want to keep mnemonics to [A-Za-z0-9]. When you start introducing () * +, and such, often found in the full description, you end up with processing problems.

It’s my understanding that users can supply localized strings if they want to translate to different languages.

Not only users, binding developers can provide this for thing, channel and option description as well.