Trigger channels

[davidgraeff]

This issue is either about poor documentation or extending the trigger channel.

The way that the documentation is layout out, with the trigger channels described first in the channels section among other channel types like switch, made me understand the concept differently than it was meant to be.

There are generally two types of channel types, those that are read-only and show information to the user and those that are meant to be used for interacting:

Data type	Event from binding (Show to user)	Action on binding (User interact)
Boolean	Contact	Switch
Number	Text (, Gauge, Progressbar)	Dimmer
String	Text	State Option
Stateless	-	Trigger

As shown in the table, I understood the trigger channel to be the stateless way for interacting (the GUI would show a push button).

In reality the trigger channel is an event source and and is meant to be on the middle column of that table above.

I suggest to allow the trigger channel to be used in both ways by using the already existing "read-only" flag. If read-only is set, it is the event-source like now. If read-only is not set, it is meant to be used with a push button. The table from above would look like this:

Data type	Event from binding (Show to user)	Action on binding (User interact)
Boolean	Contact	Switch
Number	Text (, Gauge, Progressbar)	Dimmer
String	Text	State Option
Stateless	Trigger (read-only)	Trigger

What do you think?

Use-case

In the OpenHAB Milight binding I have a use-case for stateless channels. There are certain features that are like modes, they can be activated but can't be switched on/off. Because I misunderstood the concept, I modeled those as trigger channels and now I have users complaining that those can't be used (https://community.openhab.org/t/the-new-milight-ibox-and-milight-binding/17621/259?u=david_graeff).

[sjsf]

Well, the key point is that trigger channels only fire events, but they neither maintain a state (i.e. don't send state updates) nor accept any commands. Therefore they cannot be linked to items. Their only purpose (currently) is to trigger rules by listening to these events.

They only way I see which would allow linking trigger channels to items is by having something "in between" which translates the events into a state. This will be able with so called "profiles" (see #2226) which I already started working on with #4108 but they are not yet configurable. I already added RawButtonToggleProfile.java as an example for such a profile. With this, users would be able to link trigger profiles to items again - and they would feel like ordinary read-only channels.

Your are right that the documentation is lacking those details (mainly because it can't be used yet). Does this clarify your confusion nevertheless?

[davidgraeff]

My personal confusion is cleared, I'm just worried about fellow binding developers and see a need to clarify the documentation.

The profiles concept is great. But do I really need to have a State? The whole point of a trigger is to be stateless. To speak in code, I would expect handleCommand(channel, state) to have a null or EmptyState second argument for a trigger channel. And in a rule/script I would expect a method like channel.trigger() or trigger(channel) instead of the postCommand(channel, state).

[maggu2810]

@SJKA There has been already another issue some time ago where we discussed "write only" channels (perhaps not "discussed", but there should at least be two or three comments about it).
Haven't we agreed that we could use normal channels without state updates, so leaving the state UnDefType.UNDEF or UnDefType.NULL all the time?

[sjsf]

Yes, that was here. And you remember correctly.

In fact I got confused a little myself - now I understand that it's not the device who trigger something... So the same as was discussed for Sonos should work for the use-case here equally well.

Just one thought on the modeling of the channels, but keep in mind that I'm really not into the details of this binding... If you have several channels which are exclusive (e.g. "Mode A", "Mode B"), then sometimes it rather makes sense to only have one channel (e.g. "Mode") which accepts a StringType command with "A" and "B" in order to switch modes.

[davidgraeff]

But then again I have a state ("mode"). But take the milight "nightmode" for example. It's not really that I put the light bulb into that mode, it's more like a command that is just executed. If I send a colour later on, I'm immediately out of that "nightmode" or let's call it "very dimmed state" to avoid the word mode here.

I need a channel that is stateless and guis to provide pushbuttons to actually implement this correctly I think. The trigger channel can be reused for this but also open to just introduce another mechanism.

[maggu2810]

Isn't at what I have written above.
Use a channel mode, don't ever that a state to that channel (no state update), and only handle commands.

[davidgraeff]

But there's no way for a GUI to autolink this to a bush button like widget, because it's not obvious to a GUI.

[davidgraeff]

How to proceed with https://github.com/openhab/openhab2-addons/pull/3093? Is there documentation on how to use a stateless pushbutton like channel with the mentioned profiles architecture?

[kaikreuzer]

Trigger channels are documented at the end of this section. A couple of bindings already use them.
If you feel that something is missing, @SJKA might be able to help.