I am currently developing a binding integrating home automation system with openHAB, and I came across a problem, or maybe just my misunderstanding of the idea behind channel commands and states, and their labels.
The binding implements a thing with two string type channels (well, actually four - but let’s forget about the second pair for now). First channel (let’s call it Tx) is for sending commands as requests to the system, and second channel (Rx) serves as a state holder of the last acknowledge from the system. From the system side these commands are called tasks, and these states are called results.
Both channels are configured (at the moment of their thing initialization) with a system API, which composes of dynamically created lists of - respectively - tasks and results, because each system has its own unique user configuration, so the lists must be provided by the user at the the level of a thing configuration (not statically at the level of its source code). This required implementing DynamicCommandDescriptionProvider and DynamicStateDescriptionProvider that are now loaded with List<CommandOption> and List<StateOption>, and that further provide commands for the Tx channel and states for the Rx channel. Configuration is provided as a JSON string in a form of a dictionary, and looks more or less like this:
{
"API" : {
"tasks" : {
"T31" : "Do something",
"T75" : "Do something else",
"T90" : "Do another thing"
},
"results" : {
"R12" : "This happened",
"R27" : "That happened",
"R33" : "Nothing happened"
}
}
The system itself uses only tasks and results ID’s in a form that they are presented as keys in each pair above (“T31”, “R12” etc.). Values are just descriptions for a user. DynamicCommandDescriptionProvider for Tx channel is loaded with a list of tasks - key is taken as CommandOption.command, and value is taken as CommandOption.label. DynamicStateDescriptionProvider for Rx channel is loaded with a list of results - key is taken as StateOption.value, and value is taken as StateOption.label.
And it seems to work fine. When you open Control section in Paper UI, it displays a list of labels related to each channel (“Do something”, “This happened” etc.). When one of these Tx labels is clicked (e.g. “Do something”), handleCommand() of a thing handler receives actual command (“T31”), and sends it to the system. When system responds with something (e.g. “R12”), this direct value is passed to updateState() of Rx, and a corresponding label is displayed (“This happened”).
However, when I try to use it in Rules or Habpanel (e.g. for constructing a rule or a widget that sends some request to Tx channel), I do not have these labels loaded when I select the channel. What’s more, in a configuration field, I have to actually type not these labels, but direct commands/values in order to make it work (so not “Do something”, but “T31”). Which makes this solution hardly useful for me, because the idea behind this API configuration was that the user does not have to deal with these obscure commands/values strings, and can focus just on comprehensible labels.
And here - after this very long preface - is my problem/question. OpenHAB itself has an access to this command/value-label pairing, because at least Control section in Paper UI can load it and use it properly, or at least in a manner that seems proper to me: user sees only labels, code deals only with commands/values - perfect encapsulation. But other tools do not seem to handle it properly, or even at all. So what is the actual purpose of the labels? How should I actually treat them? Is there something in the concept that I missed or misunderstood, is there something more that I should implement in the binding code or implement in some other way?