Is there a proper documentation on dynamic state options?


I´m currently struggling to get my DynamicStateDescriptionProvider running. In the Eclipse SmartHome the documentation for the is just (paraphrased) “If you want dynamic state descriptions, implement this interface”, which isn´t helpful at all. I used the kodi binding as a reference, but it´s still mostly guess work. My problem is that the getStateDescription method is called, but the only channel that is missing is the channel from my binding and I have no idea why. Is there somewhere a proper tutorial or documentation about this or do I have to try around until it somehow works?


It really is not well documented. Search the add-ons repository via GitHub for the class name.

Remember that it doesn’t provide a channel but only replaces the XML defined static state during runtime.

I think I have used it in the mqtt.generic binding as well, need to look that up to come up with an example later.

Cheers David

Another example can be found in the Kodi binding.

I didn’t find a good documentation either, but implemented dynamic state descriptions for digital channels in the OneWire binding.

@David_Graeff, @5iver, @J-N-K, anyone up to write some quick documentation for it? Even just a skeleton that could be fleshed out by someone like me who hasn’t been through the code or written a binding could flesh out.

I’ve only looked into the code to see how it was being done, and again when playing with JSR223 to add some Things/Channels that I could link Items to for custom lists of streaming radio stations. I’m definitely not much use for creating support documentation for binding development. But I would if I could!

Even experienced developers will have a major hurdle getting into OH development without proper documentation. Now is a good time to get this built up too, since there is a large chunk of openhab-core documentation that should be migrated over from the ESH documentation. I’m fully immersed in trying to figure out how to use ConfigOptionProviders (without documentation :slightly_frowning_face:). I have been thinking of starting up a topic about the need for development documentation when I come up for air, but that may be a while. Although, if someone would want to get that ball rolling, I’d surely chime in!

1 Like

I created and linked items to the corresponding channels and as I already stated, I´m using the kodi binding as a reference, but after one week of trial and error still zero progress. I still have now idea what to do that getStateDescription will be called on my channels. Every channel of every thing is being logged when i use in my description provider but the ones that I need.

Hi Robert,

Do you already have some code to link to? If so I can have a look into it. What do you exactly want to do? Which part of the StateDescription do you plan to change during runtime?

The DynamicStateDescriptionProvider of your binding will be an OSGI service which needs a consumer to get activated. Linking items to channels will not be sufficient. You have to add those items e.g. to a sitemap or inspect them in Paper UI. On the one hand the DynamicStateDescriptionProvider provides the information via the getStateDescription method to the consumer, on the other hand the bridge / thing handler - in other words you - are responsible for collecting the information and pass it towards the provider. Therefore the Kodi binding uses a polling job which frequently retrieves information about e.g. the users favorites or PVR / IPTV channels from the Kodi interface and stores them temporarily in a HashMap.

Just last night in bed I was wondering how I could phrase asking this exact same question, so I’ll be following this one with interest!

I’m currently writing a new Binding, which will need to dynamically modify aspects of some Channels (source names etc) - but I’ll also want to change the available options for a channel based on the value of a Property of the Thing - is that the same thing, or something different?


Here´s my current state

Seems the same or at least similar to me

Sounds similar. You can change every property of the StateDescription, which are

 * the minimum value of the state
 * the maximum value of the state
 * the step size
 * the pattern to render the state
 * the readOnly property - if the state can be changed by the system
 * the options - a predefined list of `StateOption`s

If you like to change the label, the description, or similar, you have to implement it in a different way by re-creating the channel.

@Zodiarc Thanks for the link, I will have a look later.

@cweitkamp thanks for the list of things I could do - I think that the final one is what I want.

Here’s my current code:

I’ve got a Property of the Zone thing type (selectableInputs), which is currently a comma-separated string. It’s this list that I’d like to then have as a drop-down in the Source channel. It would also then be nice to get the proper names of these from the units.

@Zodiarc, thanks for pointing in the direction of your WIP code - I’ve managed to utilise it as a basis and have my Source selection drop-downs in the Control section of PaperUI working absolutely perfectly. Each Zone Thing has a completely customised list, using a subset of the full list (the full list is maintained at the Bridge level).

Next I’ll look into replacing my comma-separated list with a drop-down list when configuring the Properties of my Zone Thing.

My latest code is up on my github repository if anyone else is interested.

How did you get it to work? I’ve made no progress since almost 2 weeks because I can’t get it to call getStateDescription on my channel.

It might be that when you’re calling updateOptions your Channel isn’t yet Linked as it’s too soon in the initialization process.

I’m calling setStateOptions from both initializeThingHandler (which actually only takes affect for me if the Thing is modified after it’s already fully Online) and most importantly from the channelLinked event - it’s this latter one which seemed to be the trick.

I still have defined a default set of Options in the config, but I’m then overwriting it once I’ve got the information I need. Not sure if this is required, or whether it’s OK to leave the config without any default Options…

Setting of the state options is not a problem. I used to output the options in the provider and it was populated correctly. The framework simply somehow refuses to call getStateDescription on my (linked) channel. I’ve put another into getStateDescription which outputs the channel UID when it’s called and I see every channel with a string type in my setup except the one I actually want.

@cweitkamp were you able to look at it?

Hi Robert,

I walked through your code and the implementation looks good. I could not find a reason why it is not working. Two minor things to mention:

  1. The originalStateDescription paremeter of the getStateDescription could be null which should be handled in your code before accessing it’s methods.

  2. The <state readOnly="false"></state> tag on your ac-mode channel type definition id superfluous because readOnly="false" is default.

We maybe have to look at a different place for your issue. Just to make sure everything is correct might I ask you to post your configuration (item, etc.) for it?

Currently I have an idea how to improve the implementation for dynamic state descriptions. As nearly 90% of the existing implementations are similar we could think about an abstract BaseDynamicStateDescriptionProvider class in for the framework which bindings are able to inherit. One problem I am aware of could be solved by this approach: translating the dynamic state options. For me it is not working right now.

@Confused I will look it your stuff too.

I’m configuring my things and items using Paper UI, so I don’t think that the error lies there.

The only difference I can really see between yours and mine is that I’ve got some default <options> set against my channel in thing-types.xml, and I’m then overwriting them with the dynamic stuff.