Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extending states with attributes #1298

Closed
cdjackson opened this issue Dec 26, 2019 · 44 comments
Closed

Extending states with attributes #1298

cdjackson opened this issue Dec 26, 2019 · 44 comments

Comments

@cdjackson
Copy link
Contributor

cdjackson commented Dec 26, 2019

For OH3, I think we should take a serious look at how states / commands are defined. We've had the legacy system for 10 years now, and I personally think it's creaking at the seems and limiting the way we can run the system.

Currently, we have a single dimension in the state - e.g. ON/OFF, a single value, etc. This is fine for basic information that goes to a user or UI, however, in many cases further information is required (or at least, is provided from the device sending the state) to fully describe an event. While this information may not be of primary concern, and may not be used in a UI, it is useful for triggering rules/scenes and I feel it would be useful to think if this could be attached to the state event.

A few use cases -:

  • A ZigBee light can provide a transition time - ie the amount of time required to move from ON to OFF. We want to be able to define this attribute, along with the state.
  • Z-Wave scene controller can can send a scene 'command' - this usually has a number of attributes - the scene number, but also the keypress type (KEY-DOWN, KEY-UP, etc), and sometimes a time is also provided. This is currently handled by defining a number - (scene number).(type) - e.g. 6.3 might be used for scene 6, keydown - we ignore the time so the device can not be fully utilised.
  • An alarm can have a type, and a state. Instead of implementing 25 channels for 25 different alarms, each with an on/off condition, it might be more convenient to provide a single Alarm channel with on/off state and alarm type attribute. The UI can show there's an alarm (i.e. showing the channel and it's state - as we now have) but a rule would be able to look at the attribute and decide exactly what alarm type this is and act with the appropriate response.
  • A smoke alarm can go into alarm - we want to show this on the UI, however the notification rule that rings the fire brigade probably doesn't want to do this if it's a test - we could add the "Test=true" attribute so that the system can work around this.
  • A door lock can have the state ON or OFF (LOCKED or UNLOCKED) but this can have attributes such as the reason it changed state (eg the user who opened the door).

Of course there are always ways around this with the current system - we can concatenate data together(e.g. alarm type number x 100 + alarm value), or we can use two channels, but then the rule has to resynchronise these two streams. Or we can use json strings to hold multiple bits of data which has been the recommendation so far.

I'd like to propose an extension to State updates to hold attributes - ie secondary data that provides context to the primary state.

Currently, we have -:

updateState(channelUID, state)

I believe (following an extremely quick look at the code!) that this could be extended with another parameter containing an object / attribute map. eg

updateState(channelUID, state, object)

eg in pseudo code.

updateState("channel.uid", OnOffState.ON, {"keypress":"down", "time":25})

Likewise in rules, we could have -:

Light.sendCommand(ON, {"duration", "10S"}),

A similar extension to rules would be required to read the attributes. The idea is not to impact the framework - all the generic information required to be system agnostic is still there, but it allows the framework to support the more advanced features that may be provided by systems like Z-Wave (and many more I'm sure).

I've also seen people talking about having things with 1500 channels - I've not looked at why this is, but I do wonder if the above suggest might in some cases allow better channel definition, and possibly reduction in channels (??).

This was originally proposed in ESH but not discussed - it seems to me that OH3.0 should take a good look at improving the command/state/items and I think something along these lines could significantly improve the system.

@kaikreuzer
Copy link
Member

I actually think that this has been discussed many times already - and it seems that there are misconceptions in here.
You mix commands and states in your examples. For commands, there is the clear distinction that item commands must be without parameters as they otherwise do not make sense to link to generic UI elements. To have the same channel used with different parameters, this should be done by using channel parameters, which can be set differently for different channels of the same type. For anything where dynamic parameters are required, this only makes sense to be used in rules and for that the Thing actions have been specifically introduced last year.
For states the situation is similar: They exist on items and items are the abstraction layer that is meant to be as independent from concrete devices as possible. Adding arbitrary key-value-maps to them seems to virtually break a fundamental part of the architecture. If we feel that states require more metadata, this should be imho be defined by the framework and be the same for all bindings as its content should really be independent from a certain technology (like "the user who opened the door" - this is on a very functional level and requires a strong semantical link to other core concepts like "persons". It makes no sense to introduce this for 1 of 250 bindings only).
For anything that that is technology-specific, we already have the possibility of defining custom events in place - they are issued from a Thing and not linked to an item, so they live at the right place of the architecture.

I understand that architectural constraints sometimes feel to hinder new features. But at the same time, they keep creeping featurism under control and adding undefined key-value-maps anywhere in an API is honestly the worst choice one can do within a framework.

But back to your concrete use cases:

  • Light with transition can and should be done as a thing action
  • The scene controller device must have a trigger channel. It is free to define its own event type that includes all details on the button, type and time.
  • 25 Alarms: There can be one alarm channel, signallling to the user that there is "some" alarm. Individual alarms can be defined as events of a trigger channel, which can be used from within rules.
  • Test flag: There were similar discussions on how rules can be tested without triggering real actions anywhere. Can be a nice feature, but it should definitely be independent of any binding, but rather be implemented in general on a framework level.
  • Reason for a change: As mentioned above, this is very functional information and thus should be defined on the abstract level. There were already similar ideas like providing information on "caused by rule xyz" or "caused by manual user interaction" - this definitely makes sense as a feature, but as it is not only about bindings, but also rules or any other source for events, it must be defined in the framework.

@cdjackson
Copy link
Contributor Author

I actually think that this has been discussed many times already - and it seems that there are misconceptions in here.

Sorry, maybe I missed it, but this message was something i raised on the Eclipse forum a few years back (https://www.eclipse.org/forums/index.php/m/1759688/#msg_1759688) and it received no response from anyone.

You mix commands and states in your examples. For commands, there is the clear distinction that item commands must be without parameters as they otherwise do not make sense to link to generic UI elements.

Sorry if I did not describe this clearly - I don't mix them up, but wanted to present the same concept for both, so the examples do cover both states and commands. As I tried to say in the above suggestion, the main state is the same as it currently is, and therefore still links to the UI element - and the attributes are available for further processing (eg rules etc). The suggestion was for both commands and states to try and consolidate the concept rather then the (IMHO) messy situation we have now.

they keep creeping featurism under control

We are talking about evolving a framework that is now 10 years old - don't you think some "feature creep" is now warranted as we move toward OH3??? I don't really call it feature creep - I'm more trying to start some discussion about how OH3 can improve on the success of previous versions rather than remaining static.

Test flag: There were similar discussions on how rules can be tested without triggering real actions anywhere.

You misunderstood - the test flag comes from the device (if someone presses the test button) - the smoke sensor sends a SMOKE alarm, but tags it as a TEST button. Again, this is just really an example of device specific tags that people might want to make use of. It's very much device dependant though, but from the numerous discussions I've had about trying to support the 1000 ZWave devices we support, people do want this sort of thing to allow them to make bet use of the devices they have spent their money on.

Adding arbitrary key-value-maps to them seems to virtually break a fundamental part of the architecture.

What fundamental part of the architecture does it "seem to virtually break"?

If we feel that states require more metadata, this should be imho be defined by the framework and be the same for all bindings

I think this would be near impossible - trying to agree on the additional metadata to suite all users and all bindings would be nigh on impossible to agree. Maybe we can agree some common ones (such as transition time or obvious things like that) to try and keep things standard where possible, but it's not going to be easy to accommodate features of all fancy modern devices that companies are coming out with now. We would end up still having to use json strings, as you've previously recommended, to accommodate these states, and IMHO this is pretty messy.

content should really be independent from a certain technology

I might agree in an ideal world, but I would argue that we have this already at the highest level. Eg a door sensor in OH is the same for all bindings - but there needs to be a way to provide supporting information that does allow device/technology specific functions. Otherwise we will always be limiting the framework to work with the lowest form of technology.

I really feel that all the different states/actions/trigger channels are a lot worse and much more confusing. It's extremely difficult to shoehorn modern devices into the antiquated OH system and it would really be good to consolidate things moving forward - again - OH3 should be a step change, not just the same old thing (IMHO of course). I want to see OH3 succeed, and am happy to try and help where I can, but I think we need to think a bit more progressively.

There are other issues with the current system - there is no ability to define groups that are sent to bindings (I have a separate issue open on this for a while - #1035). IMHO, we really should have a rethink about these concepts to allow OH3 to run for another 10 years rather than floundering with OH1 concepts.

I guess that this won't go anywhere and you have made up your mind that we will stick with the old system, but I thought I'd try to suggest some improvements as we move toward OH3. If you want to close this then, please feel free if you think there's nothing useful in here.

@cdjackson
Copy link
Contributor Author

An example of where I think we can improve -:

adding undefined key-value-maps anywhere in an API is honestly the worst choice one can do within a framework

Isn’t this what has been done with Thing Actions? This seems to have exactly this, and this is a good example of where we have multiple ways of doing the same (theoretically simple!) thing - just turning on a light. We have a nice standard OnOff channel - the user can interact with this channel via the Item, but they can’t set the transition time between On and Off. To do this, you recommended using a Thing Action so we can use the key/value parameters - so now the user has two ways to control their device - one through the Item, and the other that is the Thing Action (which can have an associated key/value map to allow us to set attributes).

Don’t you think this is strange? And confusing for users (let alone developers)? Don’t you think that there’s room for consolidation here - to simplify and enhance the system to the benefit of users and developers alike? OH3 seems like the perfect opportunity to do this.

@splatch
Copy link
Contributor

splatch commented Jan 8, 2020

I do believe there is a space and need for this improvement. Either by additional attributes or other more advanced way, whenever works.

For example BACnet supports prioritization of commands from 1 up to 16. First two are related to life safety, and last 7 are available slots for application specific needs. Operator might send command with priority 8 (manual operator) to override priority 9 (automated setting). This means that depending on a context, end device might be commanded with different level. As per specification rule can (and should) use default priority or priority above 8 and privileged user should be able to override it using priority 8. It is relevant as controller retains last received command priority.

I wouldn't mind to have a BACnet specific PrioririzedCommand as a wrapper for existing commands, however as pointed in https://community.openhab.org/t/flexibility-of-framework-supplied-types/ non-core command/state blows up core entirely. I doubt if any of existing mechanisms can mimic necessary logic and information which needs to be passed back to UI to binding and vice versa.

@J-N-K
Copy link
Member

J-N-K commented Jan 9, 2020

@splatch Command-Priority is indeed an interesting option for automation.

sACN (a DMX over Ethernet Protocol) also supports priority but with an extended range (1-200), where the highest is most important. I think that probably other protocols have something similar and we would need to have a way to map that. Maybe something openhab specific (with 5 to 10 different values) that bindings can then translate to the external needed values.

@bobadair
Copy link
Member

bobadair commented Jan 9, 2020

I’m not really sure what the best solution is, but I have a similar problem with the Lutron binding. Nearly all of the Lutron integration protocol commands allow the specification of fade and delay times. The fade times, as you would expect, generally apply to lighting dimmers and specify the time for the device to fade from the current level to the new level. The delay times apply to many device types and specify a delay before the device starts to fade, switch, or move to the new level.

The current binding doesn’t do a good job of exposing this functionality. The dimmer thing allows the user to define fadeInTime and fadeOutTime parameters, which it passes along in certain cases. The drawback, obviously, is that this doesn’t allow the user to select different fade times on a per-command basis, which is what you would typically want. None of the supported things currently allow the user to specify delay times for commands, as these are only really useful on a per-command basis.

In the past I’ve tried modifying the binding to provide fade and delay channels for each device type that supports fade and delay command parameters, but that isn’t really a satisfactory solution either. For one thing, if multiple threads were to try to send commands with different fade and delay parameters to the same device at the same time, the outcome would be unpredictable.

Lately, I’ve been considering using ThingActions in order to pass commands with fade and delay parameters. However, it seems to me that if many bindings were to do this without some abstraction or standard way of implementing it, it would lead to the unfortunate situation where sending equivalent commands to similar devices handled by different bindings would have to be done in different ways.

@cdjackson
Copy link
Contributor Author

@bobadair thanks for your comments. What you have presented is exactly the use case I have (well, one of them anyway) with both ZigBee and ZWave bindings. Currently it is quite messy to introduce these concepts - openHAB is simply not able to deal with modern technologies that support these sort of features (and while I say "modern" - these concepts are far from new).

Maybe there is some sort of middle ground to alleviate the dislike of key/value pairs by @kaikreuzer (even if the framework has many already) where we can define standard sets of attributes within the framework for features such as these where many bindings have such a need (much as we have system channels, but allow the binding to derive other custom channels). I am however concerned that trying to standardise this would be painful - you only need to look at other parts of the framework to see how difficult that has been and there must be an allowance for custom attributes.

Maybe in order to provide some error checking, and some level of up front definition, we could extend the channel definition to allow a binding to define what attributes a channel provides up front. This could allow the framework to check that attributes passed by the user are valid, and prevent the system being abused too much by requiring some level of up-front definition.

@kaikreuzer how do we proceed with this? It seems that from the discussion here there is reasonably widespread need - not just 1 in 250 bindings as you suggest. IMHO the framework needs to have a way to support additional information that can be used by users, in rules etc, but also working along side the standard types so that they are presented in a standard way in UIs. Can we add this into the feature list for OH3 (I'm not sure where this lives at the moment?) or define something similar to support this need.

@Hilbrand
Copy link
Member

I see similar request for the TP-Link bulb and dimmers. They have the option to set among others the transition time.

I do see 2 different features here. The first is for adding properties to commands. Which is what is mostly discussed here. The current option it to implement it as a ThingAction. My analysis of ThingActions:
+ Can handle multiple channel state changes in one call
+ Can directly be used in rules
- Requires implementing it differently by the binding developer than just handling commands.
- As a ThingAction becomes part of the list of all actions, adding lots of ThingActions would create a large list of actions making it difficult to find a specific action if all you want to do is set an additional parameter for 1 channel.

So I would say there is room for adding new functionality. I think the challenge is to how this should be defined. Having only key-value pairs to be given as additional parameters makes it very hard to create a rule in the UI using this feature or possible have a UI element that can use this feature. I would say to make this possible this can be done by adding it to the thing XML. Currently we have the option to specific channel specific configuration. We could either use this and make it possible to override those values dynamically or introduce new properties or additional arguments to specify they can be dynamically overridden. Then these parameters can be automatically generated for setting in the UI and validated.

Additional to give the user access on a state element (not in rule configuration, but in the control UI, if we want this at all) to these properties so the user can dynamically set values, we could enhance the item configuration that if such a parameter is specified on the item the UI then can show a UI element with the property and the user can than set such a parameter to be send when the user changes the state in the UI. This requires some additional thought and there would be the question about if setting something would be persisted.

Regarding the second feature, the handling of state. I can think of multiple possible ideas, but have no clear idea about it. There are several other discussions about this. What I see here is the issue of having multiple channels being updated and because each channel update is a atomic action it's difficult to handle in rules, if the rule would depend on multiple channels. Maybe this is something to discuss in a new issue?

Also I would not put to much emphasis on what openHAB version it should be in. There is already a lot on the plate of OH3 and I think putting much effort in getting as much as possible OH1 bindings added already can take a lot of effort. Of course if we come up with something and it can be implemented it's fine.

@cdjackson
Copy link
Contributor Author

cdjackson commented Jan 11, 2020

@Hilbrand thanks for your thoughts.

Having only key-value pairs to be given as additional parameters makes it very hard to create a rule in the UI using this feature

I'm not sure why? My first post provided just one simple suggestion -:

Light.sendCommand(ON, {"duration", "10S"}),

Surely this can be improved and was just my initial thinking, but I don't think this is too hard?

If you are talking about rule generation in a graphical UI, then again I'm sure some UI wizkids can think of a way of attaching arguments to a command.

Currently we have the option to specific channel specific configuration.

Personally, I would prefer not to mix this up with configuration as configuration descriptions have been around a long time and are well used. I think trying to do this via configuration may break things.

I suggested earlier though that we could define "attributes" in the channel description, so I think fundamentally this is what you are saying - I am just suggesting a new construct to keep things clean. Using a new system also allows these sort of "attributes" to be defined as "core" attributes for as many common things as we can think of that may be used across multiple bindings to afford some level of standardisation to users.

I see here is the issue of having multiple channels being updated and because each channel update is a atomic action it's difficult to handle in rules, if the rule would depend on multiple channels.

I would personally suggest to avoid multiple channels - to me this is a bit of a mess. We've tried this in the past - we end up with a proliferation of channels and I'm not sure how we could synchronise them. To me it makes a lot more sense to have all data as a single entity rather than providing multiple channels with some way to synchronise them.

Maybe this is something to discuss in a new issue?

I'm happy to discuss it separately if we really think it's a different feature? My original thought was to try and keep a similar concept for both commands and states to make it easier for everyone (users and devs). If we were to take your idea of multiple channels for commanding with some way to synchronise them as a single event, we would have lots of channels for (eg transition duration) that are only used for state updates, but we then provide a transition duration in a command in a totally different construct. To me, this seems strange, and we would be better off trying to have a common mechanism for this.

Also I would not put to much emphasis on what openHAB version it should be in.

To me, we have an opportunity here to change things, which in my mind we should avoid as much as possible within major versions.

There is already a lot on the plate of OH3

Where is the list held? I've not really seen anything "functional" other than the UI changes. All other changes are "under the hood" - eg Java updates, refactoring namespaces etc. I don't disagree that there's a lot of work here, and it's not something that I personally am likely to get involved with as it's not my area of expertise. However, putting more things like this "on the plate" may allow them to be picked up by others (including myself).

putting much effort in getting as much as possible OH1 bindings added already can take a lot of effort.

Again, I think that this is likely to be a different set of people - I know it takes time from core maintainers, but if we are focussing our efforts for OH3 on migrating OH1 bindings and not on improving the architecture, then unfortunately I think we will be lost and there needs to be some core improvements for OH3 to keep the framework moving with the times, and not stuck in 2010 with OH1.

@cdjackson
Copy link
Contributor Author

cdjackson commented Jan 12, 2020

@Hilbrand I was just re-reading this and wanted to clarify your comment -:

Having only key-value pairs to be given as additional parameters makes it very hard to create a rule

Are you thinking about a graphical rule editor here, and is your concern that with key/value type information there is insufficient description to allow this to be presented in the UI?

If that's the concern, then I think my earlier idea should alleviate this.

Maybe in order to provide some error checking, and some level of up front definition, we could extend the channel definition to allow a binding to define what attributes a channel provides up front.

For example -:

    <channel-type id="door_state">
        <item-type>Switch</item-type>
        <label>Door Lock State</label>
        <description>Locks and unlocks the door and maintains the lock state</description>
        <category>Door</category>
        <state>
            <options>
                <option value="0">Open</option>
                <option value="1">Closed</option>
            <options>
            <attributes>
                <attribute id="unlockmethod" type="Number">
                    <name>Unlock Method</name>
                    <description>The way in which the lock was opened</description>
                    <option value="0">Manual</option>
                    <option value="1">RFID</option>
                    <option value="2">UserCode</option>
                </attribute>
                <attribute id="userid" type="String">
                    <name>User Id</name>
                    <description>The user who opened the lock. Not provided for manual unlocking.</description>
                </attribute>
            <attributes>
        </state>
    </channel-type>

or...

    <channel-type id="dimmer">
        <item-type>Dimmer</item-type>
        <label>Dimmer</label>
        <description>Sets the light level</description>
        <category>Light</category>
        <command>
            <attributes>
                <attribute id="transition" type="Number">
                    <name>Transition Duration</name>
                    <description>Sets the transition duration in milliseconds</description>
                    <maximum>5000</number>
                </attribute>
            <attributes>
        </command>
    </channel-type>

The id could be defined to allow system definitions that are defined for the whole framework (similar to system channels) = eg id="system.transition" to provide some standard definitions where there is a clear need across multiple bindings/systems.

If this is indeed your concern, then I think we can easily come up with a definition to alleviate that through appropriate definition of the allowable attributes in the channel definition. As I suggested earlier, this could also be used to enforce what bindings can provide in the state updates so it's not abused , and could also be used to automatically generate documentation to show the user what is expected (the ZWave binding does this now - generating docs from the channel definition).

@Hilbrand
Copy link
Member

Are you thinking about a graphical rule editor here, and is your concern that with key/value type information there is insufficient description to allow this to be presented in the UI?

If that's the concern, then I think my earlier idea should alleviate this.

Yes that was what I was trying to express (English is not my native language, so that might be the problem too 😄). If I interpret how openHAB is intended than to make this possible or acceptable there should be support for a graphical I think. So I think we're on the same page here!

I was actually thinking about something similar what you described. Some thoughts I had related to the xml constructions:

  • Instead of putting it on the channel-type I was thinking about adding it to the channel. That way the (current) channel types can be reused, including the system channels. This could be an addition to also be able to do it on channel types. Hhere as an example using your command structure:
<channel id="dimmer" typeId="system.brightness">
   <command>
            <attributes>
                <attribute id="transition" type="Number">
                    <name>Transition Duration</name>
                    <description>Sets the transition duration in milliseconds</description>
                    <maximum>5000</number>
                </attribute>
            <attributes>
        </command>
    </channel>
  • Regarding the type of an attribute. Here I was thinking about using the same options as configuration parameters. (Maybe even use parameter) That way it would be possible to reuse existing functionality.

Regarding the state variant. What I meant with the synchronization problem is that these state attributes are now only possible as channels, but because each channel is updated individually it's not possible to deduct a relation between them and thus using channels makes it difficult, if not impossible, to use them effectively (If I interpret it correctly this was also what you meant as being the problem). So I understand your solution. But I also see some different issues to solve here. Like do these additional attributes need to be persisted? (With the command we could choose that those are not persisted and the value only is send with the command). When should something be an attribute and when a channel? Or are these kind of sub channels? Do these attributes need to be accessible to the user in the UI? Because I can easily see a case where it's an attribute and then the user want to see it in the user interface. So because of all these questions I think it requires some additional thoughts about what would be the best solution and hence my suggestion to make that a different issue. wdyt?

@cdjackson
Copy link
Contributor Author

English is not my native language, so that might be the problem too

No - I don't think so. Your English is fine - the only "problem" is that every engineer will think and describe things a bit differently and I interpreted this a bit differently when I read it the second time :)

If I interpret how openHAB is intended than to make this possible or acceptable there should be support for a graphical I think. So I think we're on the same page here!

👍 100%

Instead of putting it on the channel-type I was thinking about adding it to the channel.

Yes, this is probably better. We could do "both" - many of the channel-type definitions can be over-ridden in the channel definition. However, you are right that most flexible is the channel definition.

Regarding the type of an attribute. Here I was thinking about using the same options as configuration parameters

This sounds fine to me I think. I'd need to look over the parameter definition, but from memory I think this should cover everything that is needed, and clearly re-using functionality is nice.

What I meant with the synchronization problem is that these state attributes are now only possible as channels, but because each channel is updated individually it's not possible to deduct a relation between them and thus using channels makes it difficult

I may need to retract my statement above about your English as I'm not sure I understand this statement :). Can you explain this?

I am wondering if you are thinking that the information is provided in separate entities in the binding? If so, that may happen in some bindings I guess, but for both ZigBee and ZWave, the "attribute" information is provided in the same entity (eg ZWave packet) as the state. So we might have for example a Door Lock state update - in one frame it provides all the information "The lock changed state to UNLOCKED, but RF CONTROL with ID User 123". I want to use a Switch to show the state of the lock, but then add the attributes to show the user who opened the lock, and how they unlocked it. There is no correlation etc required to take information from different packets/sources - it is just a "repackaging" exercise. (I'm not sure if that covers your point though, so please feel free to rephrase).

Like do these additional attributes need to be persisted?

Good question. I would say "Yes". These are potentially important bits of information - if we take the lock example above, I think it's useful/necessary to be able to recall who opened the door after the event. Basically, I would expect the full state to be persisted and the historical interfaces to restore the same state later.

When should something be an attribute and when a channel?

It's probably up to the binding in some respects, but for me there's probably normally a kind of "main state" that probably links largely to existing item types (Switch, Number etc...). I'm not sure there's a hard and fast rule, but by requiring bindings to define the channels and attributes in the XML there's a clear opportunity for review and critique (ie it stops/reduces channel abuse).

Or are these kind of sub channels?

We could no doubt call them different things. For me it's a way of consolidating information that relates to an atomic event together.

Do these attributes need to be accessible to the user in the UI?

My initial thinking is that they are primarily for rules, however there is probably nothing to stop them being exposed in the UI and this is probably a good idea. They are defined in the channel description, so it should not be too hard to display them in the UI if desired - the UI could treat them as separate channels linked together, or a tree type interface for selecting the item or attribute.

I think it requires some additional thoughts about what would be the best solution and hence my suggestion to make that a different issue. wdyt?

Maybe - I think for now we should keep them together while we discuss the solutions. In my mind at least, we should try to make the solutions for commands and states as similar as possible - at least at top level. Once we agree on the general approach, then maybe we close this and open 1, 2, or even 3 different issues (eg one for states, one for commands, and maybe there's some common code - I don't know). I think at this point there's potential to keep them similar, so I would suggest continuing the discussion in this, but if others think it helps move it forward then I don't mind too much.

@kaikreuzer
Copy link
Member

For commands, I can only re-iterate that we have actions for exactly the purpose to pass arguments to a call. Everything about UIs in openHAB is designed in a way that arguments do not make sense there.

As a ThingAction becomes part of the list of all actions, adding lots of ThingActions would create a large list of actions making it difficult to find a specific action if all you want to do is set an additional parameter for 1 channel.

That's a valid concern, but the problem would be the same if you allow arbitrary key-value pairs or JSONs to be passed next to commands. But if we want to consolidate those actions (i.e. introduce some kind of common abstraction to it), we could simply define interfaces with methods that the actions are then implementing. So we could have LightTransitionAction interface that is implemented by different bindings and we could be sure that all are using the same signature.

@cdjackson
Copy link
Contributor Author

For commands, I can only re-iterate that we have actions for exactly the purpose to pass arguments to a call.

I go back to my earlier point though - why do we have two ways to do the same thing (or nearly the same thing). Doesn't this feel wrong - confusing for both developers and users alike?

if you allow arbitrary key-value pairs

It is not "arbitrary" - we are trying to make this clearer by defining them up front so it is clear to the UI, the user and developer.

we could simply define interfaces with methods that the actions are then implementing.

Then we either end up with hundreds of interfaces, or only one or two interfaces that are somehow allowed to be added, which would not meet the need we are discussing here.

@rkoshak
Copy link

rkoshak commented Jan 21, 2020

Doesn't this feel wrong - confusing for both developers and users alike?

Not a developer here but I do have some comments I think I can make concerning usability of both how it works now and with what is proposed.

First I want to reiterate some of what I understand here. First, the proposed changes would only impact rules as there is no way to provide attributes from the UI. I don't get the impression that the proposal is to somehow add attributes to commands from the UIs.

If that is correct, I don't really see a significant difference in usability between thing actions and command attributes except for the fact that it will be easier to configure the VSCode Extension to recognize and check calls to thing actions...maybe. It's a method call after all so it should be able to at least tell you if you have the right number of arguments and such. But it's a run time populated list so VSCode may not be able to figure out what's in the list through the LSP.

I don't see whether/how that could work using command attributes.

In both cases the user has to go to the binding readme to look up what is available and the proper syntax to use.

Looking to the future with UI developed Rules, again I think it's a wash from a usability level, but only assuming there is some sort of search function in the UI because Hilbrand's comment regarding the proliferation of these thing actions or command attributes will lead to quite a long list. The only difference I see is with thing actions, you would have a separate Action to choose but with command attributes you would have a list of attributes you can choose from when defining a "send a command to an Item" Action.

With thing actions though, you don't need to create an Item to use it. In fact, they completely bypass Items. Thus it feels like it starts to violate that conceptual separation between what an Item is supposed to represent and what a Thing is supposed to represent.

For example, look at the Mail Binding. The only Thing there represents the account (a Bridge Thing). There are no Items representing email destination accounts or anything like that. Instead we have the sendMail thing action. It works great actually and I've not seen anyone having any major confusion about that. But now let's look at one of Chris's use cases where you can pass how long it should take to turn on a bulb. Presumably you would have an item to represent this light, but in order to pass this parameter you have to ignore and bypass the item and go straight to the Thing.

This then raises the rhetorical question, what are items for then? Conceptually items represent a sensor or actuator on a device unless controlling it is too complicated, in which case you need to bypass the Item entirely and talk straight to the Thing. That is actually a little confusing, especially for those Things that actually represent a real device as opposed to Mail or Telegram or MQTT where pretty much every detail about the command is unknown until the Rule runs.

On-the-other-hand, if we have command attributes the user will naturally ask why they can't set the turn on time duration from a UI? I'm not sure we can get to supporting this from the UIs without a complete rethinking of how it all works.

Ultimately, I personally feel that the limited set of items and commands and states is one of the key features that allows users to effectively use openHAB. They completely abstract the user from details of the devices, which is as it should be. I share Kai's concern that injecting too much binding specific stuff into commands could become a problem both from an architectural perspective or from a usability perspective. But I also agree, thing actions also bring their own problems and confusions.

Ultimately, I think users will find both approaches confusing to a minor degree. One minor advantage of thing actions is they already exist. Another advantage is they are very similar to OH 1 Actions so most existing users will already know the basics of when, where, and why to use them. Beyond that, I don't see a great advantage to either one from a usability perspective.

@cdjackson
Copy link
Contributor Author

the proposed changes would only impact rules as there is no way to provide attributes from the UI.

Not necessarily - as we discussed above it should not be difficult for the UI to display attributes if desired. The thing/channel definition would define the attributes for each channel, so they can be thought of in some ways as sub-channels, but all linked together to a single event which is currently not possible.

sendMail thing action

Don't get me wrong - I'm not necessarily saying we should remove thing actions - maybe there is a case for these (eg things like the ZWave reinitialise, or exclude action where the binding currently uses a config parameter (for historical reasons). These are really actions on the thing - they have no context as an item or a channel.

This then raises the rhetorical question, what are items for then?

I'm not really sure I follow this section. Items don't change in my proposal - we "just" add more context to them about what happened in that event.

I personally feel that the limited set of items and commands and states is one of the key features that allows users to effectively use openHAB.

I agree - again, the item concept is not changed in my proposal.

I share Kai's concern that injecting too much binding specific stuff into commands could become a problem both from an architectural perspective or from a usability perspective.

But as we see here - it's not a single binding. We clearly need to provide a system to support features like dimmer transition times. We can't really just say that these are binding specific. Currently, binding developers must work around these limitations by using String item types and encoding information in json (as was recommended in the past for the ZWave binding). To me, this is really a horrible solution and we should try to provide something more structured than using json strings.

I think users will find both approaches confusing to a minor degree.

Why? Currently, users of the ZWave binding are (as mentioned above) required to use json strings. This is arbitrary and unstructured. No-one really complains that it's confusing, although it's clearly not very nice.

One minor advantage of thing actions is they already exist.

True, but it's unstructured, and we simply don't solve the issue with states - only commands. We also end up duplicating every item with an action - do you really think that's a good idea? To me that's a lot more confusing, but maybe I'm in the minority here?

Another advantage is they are very similar to OH 1 Actions

I don't remember such a concept in OH1, but that was in any case a long time ago and most users probably don't remember this (most have probably never used OH1).

@rkoshak
Copy link

rkoshak commented Jan 21, 2020

My main point of my post was a compare and contrast between command attributes and thing actions.

Not necessarily - as we discussed above it should not be difficult for the UI to display attributes if desired. The thing/channel definition would define the attributes for each channel, so they can be thought of in some ways as sub-channels, but all linked together to a single event which is currently not possible.

I don't see how this could work without a significant rethink on how the UIs work. For example, you define your own command attributes for how long it takes a light to dim up. Hilbrand adds his own command attributes to define the same thing and does so a little differently.

How does the UI present these? Another row on the sitemap? Another button on HABPanel? I have to right click to see and set it? Will it look different for Zwave Item than for a TP-Link Item? Doesn't this break the normalization that the Items layer is supposed to provide? To this point, it has never mattered what Thing my Item is linked to, it works the same no matter what. This consistency is important to the end users.

I'm not really sure I follow this section. Items don't change in my proposal - we "just" add more context to them about what happened in that event.

That whole paragraph was to address the use of thing actions only to address these use cases. So really that whole paragraph is in support of your proposal. Using thing actions to supply the parameters instead of command attributes poses it's own problems from a usability and confusion perspective, namely it bypasses the Items to send a command to the device.

I agree - again, the item concept is not changed in my proposal.

But the way an end user will interact with the Item will change quite significantly, some of the time.

Why? Currently, users of the ZWave binding are (as mentioned above) required to use json strings. This is arbitrary and unstructured. No-one really complains that it's confusing, although it's clearly not very nice.

I don't think anyone is arguing for the status quo here, though I could be wrong. My understanding is we have two proposals for passing this information:

  • add stuff to the command containing extra parameters (your proposal)
  • use a thing action instead of a command when extra stuff needs to be included with a command (Kai's suggestion)

I'm comparing and contrasting the two options from a user's perspective.

Command attributes are more consistent with the concept of Items but it requires a significant rethink on how UIs are built and are used, or it's only suitable to be used from rules.

Thing actions can be used now but only from rules and they completely bypass the Items.

But ultimately, ignoring the UI issues:

    MyItem.sendCommand(ON, "{ 'ontime'=5 }")

isn't really different from a usability perspective than

    actions.getAction("zwave", "zwave:sadfs:node12").onWithTime("dimmer", 5)

The former requires some research in the readme docs to figure out how to properly format it, what parameters are available, etc. If I change technology and MyItem later becomes linked to some other binding, that attribute will need to be re-researched and changed, or it might not even be available.

On-the-other-hand, thing actions are a little more verbose, also require doing some research into the binding readme, will only ever work with rules, and completely cut the Item out of the picture.

From the user's perspective, I don't think either approach is all that great. But neither is so awful as I would have a preference between the two. They both mostly get the job done and both introduce some of their own new problems.

True, but it's unstructured, and we simply don't solve the issue with states - only commands.

Perhaps I missed it, but I though the issue was with the commands. Does this proposal also introduce what will amount to complex Item types? And what the complex part looks like is specific to what ever binding/thing/channel it's linked to? That seems like it would break the normalization that Items provide. Which brings us back to a standard needs to be decided upon and implemented in the framework or we break the normalization that Items provide.

And it's a method call, not exactly unstructured, at least from the user's side of it.

We also end up duplicating every item with an action - do you really think that's a good idea?

From the user's perspective it isn't all that complicated or hard to reason about. All you need is the binding name and the Thing ID and the name of the action and it's arguments (the latter two of which come from the binding readme docs). The concepts scale in the brain pretty well. Once you know how to do it for one, you can do it for ten or a million without any additional mental load.

Where the problem lies, in my mind, is the fact that it's a completely different paradigm for interacting with devices, a paradigm that doesn't use Items at all. I don't like that aspect of it at all. It muddies the concepts

I don't remember such a concept in OH1, but that was in any case a long time ago and most users probably don't remember this (most have probably never used OH1).

They are still around and still used pretty heavily. Everything listed under the Actions tab in add-ons is a 1.x style Action. Until OH 2.4, they were the only actions. And even now, there are a good number of Actions there that 1) still require a corresponding 1.x binding installed and configured correctly (e.g. Astro) and have no thing action replacement.

But really, anyone who has use executeCommandLine or sendHttpGetRequest or createTimer has used this style of Action. The only difference between these and thing actions is you must first acquire the action before just blindly calling it.

@cdjackson
Copy link
Contributor Author

I don't see how this could work without a significant rethink on how the UIs work. For example, you define your own command attributes for how long it takes a light to dim up. Hilbrand adds his own command attributes to define the same thing and does so a little differently.

I'm not sure you understand. The BINDING defines the attributes - not users. They are defined by the channel definition. Firstly, this means it's not down to different people defining whatever attributes they like - it's down to the binding defining what it provides. This is (IMHO) a lot better than the current thing actions where there no definition. However, it also means that a UI can easily know what these attributes are, and it can provide them much the same as it could provide a list of things/channels etc. Yes, it's an extra thing to add to the UI, but it could be added quite easily if desired.

How does the UI present these?

That's up to the UI how it presents stuff. It could simply provide a list of the items and attributes. Everything is named and known.

Another row on the sitemap?

It could be defined just the same as a channel. As I think I said earlier, the attributes could be thought of as separate channels, all synchronised to the same event. Conceptually, this doesn't seem too hard.

But the way an end user will interact with the Item will change quite significantly, some of the time.

SOME of the time. But MOST of the time the item works exactly the same. The attributes are additional information. I've provided plenty of examples, but think of a light - we have a standard Switch type - you interact with it exactly the same as you always would, but we also have the ability to set the attributes.

add stuff to the command containing extra parameters (your proposal)
use a thing action instead of a command when extra stuff needs to be included with a command (Kai's suggestion)

But these two systems are quite similar - just that my suggestion consolidates the system to avoid confusion. We don't end up with multiple ways to do things - a Switch item to send the command, but if I want to send it with the other stuff (eg transition duration) you have to use a thing action. Fundamentally I'm suggesting to consolidate the two. All your concerns above that this can't work with the UI - why is it ok with the thing action. It's a similar concept, but is a) better defined as we define it in the channel definition, and b) consolidated with items.

Perhaps I missed it, but I though the issue was with the commands.

Yes, you missed it. The topic is STATES, and the first line at the top of this states -:

I think we should take a serious look at how states / commands are defined.

isn't really different from a usability perspective than

Agreed - you're catching on -the concepts are similar, so we should consolidate them so we don't have multiple systems.

The former requires some research in the readme docs to figure out how to properly format it,

No - again, you missed the point that the attributes are defined in the XML so they could be provided by a UI.

On-the-other-hand, thing actions are a little more verbose,

Based on Kais comment above that key.value pairs with no definition is bad, isn't that therefore a bad feature of this?

Where the problem lies, in my mind, is the fact that it's a completely different paradigm for interacting with devices

Not really, again, it combines the current concept of items and channels. We all know about this right? Also, we have OH3 - that's 2 more OH's than OH1, so I think we need to move on ;)

@J-N-K
Copy link
Member

J-N-K commented Jan 21, 2020

I fully agree with @cdjackson. There is a use-case for thing-actions but in most cases adding attributes/additional information to commands/states would be the better option. I also agree that an UI could render these as additional channels (if needed). I like the concept of items as abstraction and as @rkoshak pointed out: thing actions are contradicting that.

„mail“ (or „telegram“) are examples where I find thing actions to be useful, this is something that is only useful from rules and there is no need for an item. But writing rules to provide something like dim/fade-times (or using config-options for that like in „dmx“) is not very intuitive.

@ghys
Copy link
Member

ghys commented Jan 21, 2020

Chiming in here, since my ears have been ringing for some reason. If this ends up being adopted please make sure the StateDescription resp. CommandDescription (https://www.openhab.org/docs/developer/bindings/thing-xml.html#state-description) include the list of supported "extended" state/command attributes, so that an UI could conveniently retrieve them along with the item state (and the attributes) with a single API call. The docs linked above seem to indicate there are a number of static and dynamic provider interfaces, i.e. provided statically by a channel type or dynamically by a channel - that doesn't make much difference as long as they're well-defined in the description.

@rkoshak
Copy link

rkoshak commented Jan 21, 2020

The BINDING defines the attributes

That's what I mean by "you" in this context. Potentially each binding defines their own attributes. And binding developers being human, they will define multiple names and other differences for essentially the same thing. An now I've lost my normalization. How my UI looks and behaves depends on which binding my Items are linked to. The switch calls it "onTime" and the TP_link binding calls it "dimuptime". Zwave uses seconds, KNX uses milliseconds. No longer will uses have a nice normalized interface with their system. They now have a different interface depending on which binding they are using.

It could be defined just the same as a channel.

You don't put Channels on the sitemap or HABPanel. You put Items. And it's one Item = one element on sitemaps. HABPanel has more flexibility. But an Item is no longer just an Item. It has all this other stuff (attributes) that come with it so it's no longer just one Item = one element. It's one Item = multiple elements to provide a way for the user to interact with all the attributes.

But these two systems are quite similar - just that my suggestion consolidates the system to avoid confusion.

I agree that they are quite similar. I disagree that your suggestion avoids confusion. Or at least that it avoids more confusion than it introduces.

Agreed - you're catching on -the concepts are similar, so we should consolidate them so we don't have multiple systems.

But you said before that you see a need to thing actions. So we will still have at least two systems.

Not really, again, it combines the current concept of items and channels.

I was referring to thing actions. This is one of the negatives for thing actions.

Ultimately, I'm not arguing against your proposal in favor of thing actions. I'm arguing, from a user's perspective, IMHO, both ideas are bad. That doesn't mean I have an alternative so it's not worth much. But I see adding the attributes to Items all but killing the normalization that Items bring. And thing actions are weird to use for some of these use cases and don't fully solve the problem.

I could get behind the Item attributes if and only if these were somehow normalized so my UI and my Rules don't have to know or care what binding an Item is linked to. If that breaks than I ask, what good are Items? Lets just use the Things and Channels directly.

Were I king, I'd say everyone go back to the drawing board. But I'm not king and have nothing better than "bring me another rock." So my comments aren't worth much. But based on my experience helping users, I think neither approach is a good one.

@cdjackson
Copy link
Contributor Author

An now I've lost my normalization.

Yes, but as I also said earlier, we can define system attributes. Otherwise what you describe is the same situation as for channels. IT is up to the binding to define channels, but where we thing there are common features, we define system channels. We can do the same here to provide a level of standardisation.

Just because different bindings can do different things does not (IMHO) mean we should not have the facility - it means we should try to define some standards.

You don't put Channels on the sitemap or HABPanel. You put Items.

True - my point otherwise stands. It's easy to provide them just like second ITEMS.

But you said before that you see a need to thing actions. So we will still have at least two systems.

Let's face it - we have lots of different mechanisms - mostly they are for different things - configuration, thing actions (which should be for things - right - not channels or items?) and items. There should be a logical separation - not having two systems that do the same thing.

IMHO, both ideas are bad.

Fine - then please propose a solution. Clearly this is required - and the current solution of telling people to encode String items as Json is IMHO much worse than bad. I'm happy to discuss other solutions. Maybe you have a simple system with no need for this - it doesn't mean that others don't of course ;)

Were I king, I'd say everyone go back to the drawing board.

I agree that there should be a good hard look at a lot of things for OH3 - I agree here that we should possibly take a step back and look at the whole items/commands/states/channels, but, that's a really big topic and as we see here, just a simple suggestion like this is nearly impossible to get any agreement on.

Please offer some suggestions though - please don't just say everything is rubbish. I'm happy to discuss options, but we need options here - not just criticism that all options are bad.

But based on my experience helping users, I think neither approach is a good one.

Again - I made a proposal, and very much welcome feedback - please provide a suggestion. In my opinion, no solution is the worst idea.

@rkoshak
Copy link

rkoshak commented Jan 22, 2020

Just because different bindings can do different things does not (IMHO) mean we should not have the facility - it means we should try to define some standards.

I'm looking at this strictly from the user facing perspective. If each binding can "do their own thing" on the UI facing or rules facing parts of OH, from a usability perspective it's close to a disaster. It breaks the normalization with is really really important to OH's overall usability.

If we are going to do that, we may as well do away with Items entirely.

But maybe it's worth making OH harder for the users to use to get this capability. I can't comment on that. But I can say with conviction that this would harm the overall usability of OH for users.

There should be a logical separation - not having two systems that do the same thing.

But we've already agreed that thing actions have a purpose and need to exist no matter what. So we will always have two systems if we implement these attributes. Unless you are proposing doing away with the already existing thing actions and replace them with item attributes.

Fine - then please propose a solution. Clearly this is required - and the current solution of telling people to encode String items as Json is IMHO much worse than bad. I'm happy to discuss other solutions. Maybe you have a simple system with no need for this - it doesn't mean that others don't of course ;)

I don't know the code so how can I propose a better solution? But I spend hours and hours helping users, particularly new users, on the forum learn OH. Based on that experience I think I'm qualified to say whether a proposal would be helpful or damaging for those users. I could propose all sorts of ideas for how a user should interact with the system that may or may not have any bearing on what's feasible or even useful for the binding developers.

Feel free to ignore it. Honestly, OH has kind of a reputation for ignoring it's users anyway. Forget I commented. Carry on.

@cdjackson
Copy link
Contributor Author

I'm looking at this strictly from the user facing perspective. If each binding can "do their own thing" on the UI facing or rules facing parts of OH, from a usability perspective it's close to a disaster.

Sorry Rich, I don't really get this. This is exactly what we have with channels. Each binding can decide what channels it has. If the system designers think that there is a common need, then we have a system channel that should be used by all. It's the same here.

If we are going to do that, we may as well do away with Items entirely.

Now I'm lost. I'm thinking that you don't understand the concept here. The main item remains exactly as it is now. We just have secondary data - as I've said - these could be considered as linked channels.

But we've already agreed that thing actions have a purpose and need to exist no matter what. So we will always have two systems if we implement these attributes.

Again, I don't think you got what I meant. We already have a number of different systems - they are for different purposes. ThingActions, should be attributed to a THING (IMHO) - here we are talking about CHANNELS (or Items since the two are linked). So yes, we will still have multiple concepts to perform different functions on different logical entities.

I don't know the code so how can I propose a better solution?

As a user you have an opinion. You don't like what is suggested here (as a non programmer) so isn't there room for you to suggest something as a user?

OH has kind of a reputation for ignoring it's users anyway.

Quite possibly, but I'm raising this so that people can comment. As I've said earlier, you have an opinion that what I'm suggesting is useless - you make that opinion as a user - can't a user also make a suggestion of how you would like to see it implemented.

Forget I commented. Carry on.

I'm really not ignoring you Rich and I'm really sorry that you've taken this view - I'm trying to solicit feedback and engage with the community, developers and maintainers so that we can implement something that is right for everyone. I appreciate that you've taken the time to engage in this - as you point out - it's difficult to get that engagement so I'm sorry if you think I'm ignoring you - I'm simply trying to debate the issue!

@J-N-K
Copy link
Member

J-N-K commented Jan 22, 2020

@rkoshak I don't get you here. Especially not your last sentence. What @cdjackson proposes is improving the situation for the user. Editing key-value-pairs (where the key is already given) is clearly more intuitive than writing JSON. And it allows to implement functionality that has been requested and is not possible with the current design.

And it also helps separating items and things:

  • What now is an item can stay an item, it get's some additional functionality (with attributes, which may depend on the channels bound to that item).
  • Things are binding specific anyway and thing actions can be used for functionality which is not useful with items (like sending notifications). I think we agree that setting one channel to the email recipient, another channel to the email subject and a third one to the email content is not something that would be a good idea. So having an action for that seems legit.

@rkoshak
Copy link

rkoshak commented Jan 22, 2020

Sorry Rich, I don't really get this. This is exactly what we have with channels. Each binding can decide what channels it has. If the system designers think that there is a common need, then we have a system channel that should be used by all. It's the same here.

And the Channels are all normalized by linking them to Items. If I have a Switch I have a Switch that works like a Switch in all respects no matter what binding it's linked to.

Based on what has been said I see the following not only possible, but likely.

Let's say that attributes are implemented as described. Each binding can define their own in what ever way they want. You argued above that it will be all but impossible to create a fixed set as you will never get all the binding authors to agree, and I see no reason to argue with that limitation.

So, each binding author gets to define their own attributes. Let's assume we figure out how to put these attributes on the user facing UI (e.g. sitemaps based, HABPanel, whatever). As mentioned above, the binding author provides information to tell the UI what to present, however it presents it. I don't care so much as to the how, let's say attributes can be added just like Items can.

Binding author A decided to have an attribute that defines how fast a light dims up when turned on. A decided to use seconds as the units and call the attribute "onTime". Binding author B decided to have an attribute that does the exact same thing. But B decided to use milliseconds and call it "rampUpTime". Binding author C decided to have the same attribute but decided to use "HH:MM:SS.mmm" as the format for the attribute and call it "dimUpTime".

How do we present these three different attributes presented in three different ways so that the user doesn't have to do all sorts of special stuff in their UI or in their Rules that is binding specific to make it look and be used the same? Is it even possible to normalize the seconds and "HH:MM:SS.mmm" attributes at all? I'm a little less concerned about Rules than the UI, but it's important there as well.

I envision a situation where someone has three different lights in the same room with three different UI interfaces to control the dim up time. I just don't see how that's acceptable.

And don't get me wrong, the JSON String solution is just as bad.

Now if we just say that these attributes are simply not exposed on the user facing UI than we are only talking about Rules. In which case I have far fewer concerns. But I also don't see a whole lot of difference, from a user interaction perspective, between using a thing action or using an item attribute except the item attribute is a little more concise.

For example, I could see calling a thing action to "configure" the Channel with the desired value and the sending the command. Or just do it all on one line by passing the attribute as part of the sendCommand, as proposed above. Logically I think both are easy enough for users to grasp what is going on. I don't like the idea of issuing the ON command to the device in the thing action, as I've previously stated.

As a user you have an opinion. You don't like what is suggested here (as a non programmer) so isn't there room for you to suggest something as a user?

I think my biggest objections are a combination of "binding authors can do what they want" and "the binding will tell the UI how to render the attributes."

As I've said earlier, you have an opinion that what I'm suggesting is useless

Not useless. Not useless at all. But I see it making OH harder to learn and harder to use when binding specific stuff bubbles up to the user facing UI and to a lesser extent into the Rules. I totally see why this is desired and I see how it is useful. And I see how passing JSON strings as command is completely unacceptable.

I'm really not ignoring you Rich and I'm really sorry that you've taken this view
@rkoshak I don't get you here. Especially not your last sentence.

I'm just having a bad day and am being overly dramatic. I know you are not ignoring me. I'm just a little frustrated (it's OH community related and not even from this thread). I shouldn't have taken it out on you and I apologize.

What now is an item can stay an item, it get's some additional functionality (with attributes, which may depend on the channels bound to that item).

This is where the alarm bells start to go off. See my discussion above for why. If these attributes are to be exposed to the end user's UI (sitemap et. al.) than it will lead to all sorts of inconsistencies not only in the parts of the system that the openHAB admin sees and interacts with but what his/her family and guests need to use and interact with.

If we are given the assertion that creating a standard set of these attributes is impossible I'm left with no way to retain the normalization we currently have.

Things are binding specific anyway and thing actions can be used for functionality which is not useful with items (like sending notifications). I think we agree that setting one channel to the email recipient, another channel to the email subject and a third one to the email content is not something that would be a good idea. So having an action for that seems legit.

I totally agree with this. And like I mentioned above, I don't think it takes too large of a leap if we use thing actions to change parameters on a Channel. That too feels totally legit, at least from a user interaction perspective. The only part that doesn't feel legit is issuing a command to turn on a light and the light through a thing action. That's a step too far I think. That feels too like having two ways to control a light that I agree with Chris, is not something we want.

Do these attributes have to be set at runtime? Could a configurable parameter on the Channel (ignoring for the time being how possible that is) or a Profile or something like that be sufficient? I'm sure those are less than ideal as there are certain to be use cases where one want to adjust them based on state and events. But thought I'd ask, thinking outside the box and what not.

@splatch
Copy link
Contributor

splatch commented Jan 22, 2020

I don't know the code so how can I propose a better solution? But I spend hours and hours helping users, particularly new users, on the forum learn OH. Based on that experience I think I'm qualified to say whether a proposal would be helpful or damaging for those users. I could propose all sorts of ideas for how a user should interact with the system that may or may not have any bearing on what's feasible or even useful for the binding developers.

@rkoshak I think that it is a fair point, your inputs, help and community support are appreciated and much welcome. Yet if you find yourself unqualified to discuss code then maybe it is better primarily focus on UI and user experience? This will be better allocation of our limited resources.

There is definitely a need for dialog between all edges of community - developers, support, users, architectural council - all together. Denying of problem existence reported by one party from any other party does not help. We found a problem in framework core which is currently not addressed nor possible to solve within existing API/SPI. We would like to move forward to improve overall design and bring further clarity for more complex situations.

Its that simple.

@cdjackson
Copy link
Contributor Author

Each binding can define their own in what ever way they want. You argued above that it will be all but impossible to create a fixed set as you will never get all the binding authors to agree, and I see no reason to argue with that limitation.

I don't think that's completely true - I would fully expect that we get the most used features standardised - here we see a lot of bindings have the need to transition duration.

I think you somehow think that this is going to be a free for all and items are completely lost as people do anything they want. I don't think that is a likely scenario.

f these attributes are to be exposed to the end user's UI (sitemap et. al.) than it will lead to all sorts of inconsistencies not only in the parts of the system that the openHAB admin sees and interacts with but what his/her family and guests need to use and interact with.

The current alternative is to have lots of channels that are unsynchronised. I know I keep repeating this, but I don't really see the difference here with multiple items, and a single item with attributes - you end up with the same data, and the same amount of binding defined functionality. In both cases the binding author defines the channels/channel types etc or the attributes/attribute types etc. I dont see a lot of difference from a user perspective other than the ability to group channels together into a single atomic entity.

The only part that doesn't feel legit is issuing a command to turn on a light and the light through a thing action.

But that is what is currently recommended as the way this should be implemented in ZigBee. Apparently it's the "perfect match" ;)

If we are given the assertion that creating a standard set of these attributes is impossible

As stated, it's not impossible. I said it WAS possible to standardise common attributes - the same as we standardise common attributes. I only said that we couldn't completely standardise it to limit the outliers such as door locks. Really, I see this flexibility in the same way as bindings defining channels and channel types (as already stated many times).

Do these attributes have to be set at runtime?

Yes - clearly the user needs to be able to set the transition time. This can only be done at runtime by the user.

@J-N-K
Copy link
Member

J-N-K commented Jan 22, 2020

I think that the „transition time“ (or whatever we call it) is quite common. This should be a standard attribute (if any of the linked channels supports it). Others are probably binding specific and will only be available in one binding. Others may be shared between a small number of bindings and it‘s up to us maintainers to have a look that this is not splitted too much.

Looking at thing configuration, we have „name“, „login“, „user“, „username“ as parameters which are essentially all the same (maybe the most prominent case, but „host“ and „hostname“ are also both used). The same is true for channel-names. Why should it be easier to use thing actions (with different names for the same „action“) than attributes to states/commands? If a user decides to ignore them, it‘s all the same as before.

Edit: in opensprinkler there was a request for changing the valve-open-timespan when a open-valve-command is issued. This is clearly binding specific, but is an attribute „interval“ attached to the „on“-command really worse than a thing-action openValve(time)? Or is it better from the user-perspective to adjust the time in the ui and press „on“ than writing a rule for that? If he wants to calculate the time automatically he still can do that and use the „sendCommand“ he would use if there was no attribute.

@splatch
Copy link
Contributor

splatch commented Jan 22, 2020

I can think of one more situation with alarm systems. Some of them supports "delayed arming", meaning that there should be an delay before arm command is submitted during which arming can be cancelled. Another one is "forced arming" which ignores all warnings (such opened contacts) and arms system anyway. @druciak can elaborate more how it is currently implemented and if above proposal with attributes makes sense for one more place. :-)

@rkoshak
Copy link

rkoshak commented Jan 23, 2020

Denying of problem existence reported by one party from any other party does not help

I've never meant to imply that there isn't a problem at all. Clearly there is a problem. I just have grave concerns with both of the proposed solutions to the problem. I will probably continue to have such grave concerns until some sort of solution that doesn't expose binding specific stuff to my wife on the end user UI, for example, is found. Maybe it's tilting at windmills and such an approach is not feasible and the whole concept of a normalization layer gets significantly damaged. Short of defining another limited set of types for attributes like we have with Items I'm not sure we can necessarily get there from here.

Ultimately I agree there is a problem to solve. I have grave concerns about any solution that exposes too much binding specif stuff to the end users. I have minor concerns about any solution that exposes too much binding specific stuff to openHAB administrators/home automation developers. If you are sure that Item attributes would not result in that situation than I'm mollified.

@cdjackson
Copy link
Contributor Author

I will probably continue to have such grave concerns until some sort of solution that doesn't expose binding specific stuff to my wife on the end user UI

I struggle to understand this statement - sorry. This wasn't the original issue as you were initially thinking that this was only available through rules, so at least we've resolved that :)

The reason I struggle with this "grave concern" (which really feels somewhat over dramatic ;) ) is that we expose "binding specific stuff" all the time - in channels. As I've said, at the moment, we encode it as strings, or we create multiple channels to provide these features. This has the downside that there are loads of channels, and the data is not "atomic" (ie there's no way to ensure that all data for different channels is from a single "event").

Someone else gave the example above - setting the "transition duration" of a light via a separate channel works (I think bindings are doing this now) but the problem is if you want your lounge lights to change at one rate and at a similar time someone wants the kitchen lights to change at a different rate, then this doesn't work. You could say this isn't likely - but in my house the lounge and kitchen lights are at the same position, and when moving around the house I quite often do this.

In this example, the "transition duration" probably wouldn't be exposed to the user - but it's a binding specific channel (which you argue is bad?), and therefore could be presented on the UI if the UI designer (ie presumably you in your house) wanted to present it. You don't need to expose this channel/feature/cability to your wife in the UI - the UI is designed by you (I assume) so that you hide some of the detail from the user. Nothing really changes here - your wife shouldn't now get 200 detailed options relating to ZigBee/KNZ/ZWave/... protocols - I don't think that's a realistic concern (and if it was, then I would agree with you, but that's not what we're suggesting here).

The same concept should apply here - I keep saying this (sorry), but attributes here can be considered in a similar way to channels, which expose binding specific functions (as do channels - channels being defied by the binding).

Rich - I really hope I've helped to explain the concept and reduce your "grave concern", but I fear that I won't be able to do that fully to your satisfaction. Hopefully it's helped a bit though?

@ghys
Copy link
Member

ghys commented Jan 23, 2020

Would there be any situation where 1) attributes would be required for a command to work at all, or 2) the state's "main value" only (i.e. without the attributes shown) wouldn't be a acceptable representation of the channel behind the item?

In other words, can we consider attributes to be always optional and used to, for instance, override temporarily a default transition time normally set on the channel/channel type config, or get detailed information that isn't strictly necessary to display if the UI you're using doesn't happen to support displaying it?

From a frontend perspective I think it's important to make sure backwards compatibility is guaranteed - meaning commands and state shouldn't rely on attributes being present and should continue to work without them - if, say, we can't find a good way to handle them in a sitemap-like control interface like the mobile apps.

@cdjackson
Copy link
Contributor Author

attributes would be required for a command to work at all,

No - the system/binding should (must!) be designed to just take the item without attributes. Eg with the above example, the binding should use a default transition time (as it presumably does now - certainly that's the case with ZigBee and ZWave).

the state's "main value" only (i.e. without the attributes shown) wouldn't be a acceptable representation of the channel behind the item?

Again, I would say "no". The state should stand on its own - the attributes are supplementary information.

In other words, can we consider attributes to be always optional and used to, for instance, override temporarily a default transition time normally set on the channel/channel type config,

I would say yes and the UI should assume that. Since this can't be enforced, some implementations could of course always provide certain information.

From a frontend perspective I think it's important to make sure backwards compatibility is guaranteed

100% agree - that was always my starting point in the first post on this issue : The idea is not to impact the framework - all the generic information required to be system agnostic is still there,

@druciak
Copy link
Member

druciak commented Jan 23, 2020

Thank you @splatch for involving me into this interesting discussion.

Another one is "forced arming" which ignores all warnings (such opened contacts) and arms system anyway.

This is currently implemented in the way I am not really proud of, but I didn't have enough knowledge about OH2 to find a better one. It is a parameter in partition thing configuration, so you cannot use both ways (standard and forcing) in your system.

In OH1.x version of the binding it was defined as a parameter in the binding configuration for an item. I would vote for such solution in OH3.

Having command attributes would also help, but if the only way is to use them in rules, I don't think it will make them really useful. For such case, in my opinion, much better would be similar approach like in OH1.x - additional properties that you can specify for a channel link. This way I could have one switch item linked to "armed" channel for standard arming, and another one with additional property "force" set to "true" for forced arming. I could have them both in UI and also send standard ON command from rules to the appropriate item. There's one downside however: on the binding side the handler receives just command without any knowledge from which item and with what properiets the command was sent. One solution would be to pass link properties as command attributes. :)

@cdjackson
Copy link
Contributor Author

In OH1.x version of the binding it was defined as a parameter in the binding configuration for an item. I would vote for such solution in OH3.

This is already available in OH2 - you can have configuration parameters defined on the channel (which is basically the same as an item).

It sounds like you should have a channel configuration parameter to set the default, and then if you want, you can use a command attribute to allow the user to change this in rules.

@druciak
Copy link
Member

druciak commented Jan 23, 2020

This is already available in OH2 - you can have configuration parameters defined on the channel (which is basically the same as an item).

I can have more than one item for a channel. I may be wrong, but configuration on the channel does not help, as all the items linked to this channel will use the same configuration parameters. What I want to achieve is slightly different action (command) executed when using two items linked to the same channel.

@cdjackson
Copy link
Contributor Author

Ok, I'd not considered this sort of construct. My personal thought is that adding configuration to items, when it is already on channels, is quite messy, but I guess that's a different discussion ;)

If we add attributes here though, then it could be possible to set defaults in the items configuration maybe and that would provide what you want. It could then be changed through rules if desired.

@druciak
Copy link
Member

druciak commented Jan 23, 2020

I think link profiles could help here, instead of additional item/link configuration. But still the original command would need some additional information for the handler, an attribute or property.

@rkoshak
Copy link

rkoshak commented Jan 24, 2020

Grrr, somehow my replies never posted. I probably forgot to hit comment or something. Here's a second try.

I struggle to understand this statement - sorry. This wasn't the original issue as you were initially thinking that this was only available through rules, so at least we've resolved that :)

I realize that no matter what the approach, they all expose binding specific details to the Rules developers. I still have concerns about it and I would prefer to see there be a standardized way to achieve this but it's a lesser concern.

The reason I struggle with this "grave concern" (which really feels somewhat over dramatic ;) ) is that we expose "binding specific stuff" all the time - in channels. As I've said, at the moment, we encode it as strings, or we create multiple channels to provide these features. This has the downside that there are loads of channels, and the data is not "atomic" (ie there's no way to ensure that all data for different channels is from a single "event").

But not on the sitemap. Now, the fact that it's encoded as Strings is actually an advantage because the sitemap creator can present these attributes in a standardized manner using mappings or selections or proxy items or whatever. Based on the above, the proposal is to have bindings define their own attributes. These attributes are presented on the sitemaps and how they are presented on the sitemap is decided by the binding developer. Thus we have a situation where the end user (i.e. the person who's only interaction with openHAB is through a sitemap or HABPanel) being exposed to different ways to do the same thing.

I'd have to explain to my wife that if she wants to control how quickly one light linked to one binding dims up she needs to supply seconds but to control the other she has to supply milliseconds because the two different binding developers made different choices in how to control these. I'd have to explain that even though she used to use seconds for that one light, she now has to use milliseconds because I've changed the technology used by that light.

These are the situations I have grave concerns about. And I don't think that word is overly dramatic. This new feature, as described up to this point, leaves open the possibility that OH administrators are unable to present a unified and consistent UI to their users.

Someone else gave the example above - setting the "transition duration" of a light via a separate channel works (I think bindings are doing this now) but the problem is if you want your lounge lights to change at one rate and at a similar time someone wants the kitchen lights to change at a different rate, then this doesn't work. You could say this isn't likely - but in my house the lounge and kitchen lights are at the same position, and when moving around the house I quite often do this.

I think this is very likely. I've no concern that users may want to do that. My concern is if those two sets of lights are using different bindings, the way the end user sets those times on the UI could be inconsistent with each other. The example I'm using is they may require different units.

Let me try to be clear. I completely agree with the technical need for this. The use cases all make sense to me and I'm not arguing that there shouldn't be a way to achieve these use cases. My main concern is the lack of a way for OH administrators to present all these attributes to their end users in a consistent manner. It's all decided by the binding developers and without a standard, which was asserted would be neigh impossible, which I fully accept as true, I as a sitemap builder no longer have the power to create a consistent UI for my users.

In this example, the "transition duration" probably wouldn't be exposed to the user

Than I don't have as much of a concern. I've accepted the fact that no matter what how these attributes are used within Rules is going to be binding specific anyway. And dealing with inconsistencies between bindings is one of the jobs of Rules anyway.

therefore could be presented on the UI if the UI designer (ie presumably you in your house) wanted to present it. You don't need to expose this channel/feature/cability to your wife in the UI - the UI is designed by you (I assume) so that you hide some of the detail from the user.

But you are only offering me the choice between not showing it at all or being forced to show it in an inconsistent manner. Unless you are saying that these attributes would be linked to Items and that's how they are shown on the sitemap in which case I've no problem, but I also don't understand what this change brings. You can already link Channels to Items to change settings. My understanding was that you want to pass these attributes as part of the command which isn't really possible if we are dealing with Channels linked to Items. So if we put it on the sitemap, it has to be done in some other way than using Items. And there was talk of the binding passing information to the UI for how to display the attribute.

If there is a standard for how attributes are displayed (units, format, names) or if there is a way for the OH administrator to create a UI (sitemap et al) that presents the attributes on the UI in a consistent manner, than I don't have a problem. My understanding from what was proposed is that the OH administrator wouldn't have that power.

@cdjackson
Copy link
Contributor Author

the fact that it's encoded as Strings is actually an advantage because the sitemap creator can present these attributes in a standardized manner using mappings or selections or proxy items or whatever.

Bu that requires rules etc to split out the data and turn them into the virtual items. So you expect the binding to encode the data in its own format (going against your point that you wanted a standard mechanism) and then for the user to write rules to split out these json strings as separate virtual channels/items so that it can be displayed on the sitemap???

Maybe it's personal preference, but to me having a "proper" system that directly provides this data to users without all this messing around is a lot more user friendly - and I'm thinking here about the users ;)

These attributes are presented on the sitemaps and how they are presented on the sitemap is decided by the binding developer.

As are channels now. It's the same (but you might have heard me say that once or twice already ;) ). If you don't want to use a channel, or an attribute, then you as the user don't have to (the developers won't get upset - I promise ;) ).

one light linked to one binding dims up she needs to supply seconds but to control the other she has to supply milliseconds

Again, I know I'm repeating myself here, but since you keep making the same point I'll repeat myself again. We can standardise these sort of things - the same as channels. There are system channels - they are not used as much as they should but the concept is there. Also, the problem you talk about here is already a problem with OH - because we don't have these standards, bindings are ALREADY doing this - it's just that you've not yet come across this I guess.

This new feature, as described up to this point, leaves open the possibility that OH administrators are unable to present a unified and consistent UI to their users.

Again - in exactly the same way as we have now - with channels. There is really very little difference, and in general we should improve this standardisation. This requires engagement from the system designers, and IMHO that is lacking.

present all these attributes to their end users in a consistent manner.

"ALL" is a big word and as I've said above, it's probably not possible. However we should try to ensure consistency for the MAIN attributes - those that are used across multiple bindings (as I have said many times). However, I don't want to exclude bindings from implementing something that is unique - otherwise we don't solve the problem, and we continue to present things to users in a totally inconsistent way - as is the current situation, and that's why I propose this - to improve things for users.

But you are only offering me the choice between not showing it at all or being forced to show it in an inconsistent manner.

Have I really - or did you assume this? I've said that they could be provided to users in a similar way to channels. Users can override the formatting.

My understanding was that you want to pass these attributes as part of the command which isn't really possible if we are dealing with Channels linked to Items.

Why isn't it possible? We are talking about making exactly this possible.

If there is a standard for how attributes are displayed (units, format, names) or if there is a way for the OH administrator to create a UI (sitemap et al) that presents the attributes on the UI in a consistent manner, than I don't have a problem.

Clearly we need to make it user friendly. Nothing here I think has said that we wouldn't. We are trying to improve the situation we have now where all the valid concerns you raise are already existing and make it easer for users to use, and developers to implement. I'm sure there are further discussions to be had on how this looks in the UI, but we already see really good engagement here from @ghys and I'm sure he has ideas about how to provide a good user experience.

@splatch
Copy link
Contributor

splatch commented Jan 24, 2020

Dear all, I believe that we reached a place where all major arguments and concerns were expressed by all currently interested parties. Can we finally move on or decide if we bring more people to the table and see their opinions ie. from other binding maintainers or AC (DC 🔌)? From later we need a clear vision if the idea is welcome or not and not fruitless discussions which discourage people from getting involved. 🤝

@cdjackson
Copy link
Contributor Author

cdjackson commented Jan 29, 2020

Looking at the concrete implementation of this - I'd welcome feedback from @kaikreuzer and @Hilbrand but thought I'd throw a few ideas into the mix from a quick look at the code.

Firstly @Hilbrand your suggestion of using pre-existing functionality such as parameter descriptions seems good, but these reside in a different bundle from the core library where states and commands live, which would add a dependency which seems less nice. Also, if we want to define "System Attributes" to ensure commonality across bindings, this is not possible with configuration parameters. For this reason, I would propose to define this as a new construct. What do you think?

To define attribute-type -:

<attribute-type id=“system:transition-duration">
	<type>Number</type>
        <label>Transition Duration</label>
        <description>The time to transition between levels</description>
	<minimum></minimum>
	<maximum></maximum>
        <options>
            <option value=""></option>
            <option value=""></option>
        </options>
</attribute-type>

I suggest the following options for type -:

  • text
  • integer
  • decimal
  • boolean
  • object

This provides maximum commonality with existing terminology (eg parameter descriptions) and should allow the UI to present this appropriately to the user. The additional type I've added is object to allow for more complex data to be passed - this should not be made available in a UI but is available to be processed by other consumers on the event bus.

And then to use this within a channel -:

<channel-type id="button1"">
        <item-type>Dimmer</item-type>
        <label>Dimmer</label>
        <description>Sets the level of the light</description>
        <category>Light</category>

	<state>
		<attributes>
			<attribute id=“transition-duration” typeId="system:transition-duration"></attribute>
		</attributes>
	</state>
	<command>
		<attributes>
			<attribute id=“transition-duration” typeId="system:transition-duration"></attribute>
		</attributes>
	</command>
</channel>

In a similar way to we currently have with channel which can override some of the channel-type definition, we should also allow this here so that the channel could override for example name or minimum/maximum on a per instance basis.

We would then need a separate AttributeProvider so that we can consolidate the system and binding sources (as per other such systems (eg channels).

I've not looked at how this would be implemented in the State / Command classes yet.

Rosi2143 pushed a commit to Rosi2143/openhab-core that referenced this issue Dec 26, 2020
* improved wording, added OH3 teaser

Signed-off-by: Markus Storm <[email protected]>

* major changes to match OH3

Signed-off-by: Markus Storm <[email protected]>

* major changes to match OH3 

Signed-off-by: Markus Storm <[email protected]>

* Add link to meetup recording

Signed-off-by: Markus Storm <[email protected]>

* Update index.md

Signed-off-by: Markus Storm <[email protected]>

* Update index.md

Signed-off-by: Markus Storm <[email protected]>

* Update index.md

Signed-off-by: Markus Storm <[email protected]>

* Update index.md

Signed-off-by: Markus Storm <[email protected]>

* Small edit to test preview build tooling

Signed-off-by: Jerome Luckenbach <[email protected]>

* Update configuration/index.md

Co-authored-by: Jerome Luckenbach <[email protected]>

* Update index.md

Signed-off-by: Markus Storm <[email protected]>

Co-authored-by: Jerome Luckenbach <[email protected]>
@openhab-bot
Copy link
Collaborator

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-4-0-wishlist/142388/449

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

10 participants