Add events to PushButton

[benfrancis]

Currently the PushButton capability exposes a single PushedProperty property.

It turns out that many buttons only expose events for a press, double press and long press which would require hacks to expose as a single pushed property because there are no release events.

What do people think of adding:

• PressedEvent
• DoublePressedEvent
• LongPressedEvent

in addition to or instead of PushedProperty?

[mrstegeman]

I am fully in favor of this.

[dhylands]

I used the following: pressed, doublePressed, and held. This is consistent with the terminology used by the SmartThings UI. I didn't have anything else to go by, which is why I chose those.

I think that there should also be a released event for devices which support it.

For the SmartThing button, I was going to have it generate these events: pressed, doublePressed, held

For the dimmer switch, I was going to have it generate these events: pressed, held, released.

I'd be agreeable to use longPressed instead of held. I'm not sure that the event name needs the word 'Event' added onto it since it is by definition an event, but Im happy to go along with it either way.

[dhylands]

For devices with more than one button, (i.e. the dimmer switch has 2 buttons), I've been prepending the button number followed by a dash to the event name.

So the dimmer device actually generates these events: 1-pressed, 2-pressed, 1-held, 2-held, 1-released, 2-released

[dhylands]

I'd like to get the event names resolved fairly soon, so that I can land the SmartThing button support in the zigbee adapter.

[benfrancis]

Oh, the actual event names (as in the key of the JSON object) can be whatever you want. The thing we need to standardise on is the @type, for which we've been using a convention of appending "-Property", "-Action" or "-Event" to the name.

Based on the feedback I suggest we stick with:

• PressedEvent
• DoublePressedEvent
• LongPressedEvent

which is nice and consistent.

We can add a ReleasedEvent too if you want, though I don't know if that's a bit confusing?

It occurs to me that the Thing Description has no way of expressing the fact that "1-pressed", "1-held" and "1-released" relate to one button and "2-pressed", "2-held" and "2-released" related to another. The relationship is only expressed by a naming convention, which is a bit clunky. Sub-properties can be grouped together as objects (although we don't currently support that in the UI), I'm not sure that approach really works for events.

The above at least allows us to generate a Thing Description for the SmartThings Button. To be honest for the dimmer switch I think your original instinct to treat it like a MultiLevelSwitch might have been a better idea.

[dhylands]

The dimmer switch actually does both - it has an on property and level property, and also generates events. The user can choose to use whichever one is most appropriate for what they're doing.

The rules engine currently only supports events per "thing" as far as I can tell, so multi-button devices need to generate differently named events until such time as we support nested stuff in the rules engine and/or UI,

[dhylands]

So just to clarify here, you're suggesting that PressedEvent, DoublePressedEvent, and LongPressedEvent are different @types and the SmartThings button would advertise something like:

'@type': ['PressedEvent', 'DoublePressedEvent', 'LongPressedEvent'],

and the dimmer switch would look like:

'@type': ['OnOffSwitch', 'MultiLevelSwitch', 'PressedEvent', 'LongPressedEvent'],

I guess I don't quite see why you'd list multiple event types in the @type field?

[mrstegeman]

@dhylands No. The button would advertise itself as '@type': ['PushButton']. Then, each of the events would have the corresponding @type, i.e. '@type': 'PressedEvent'.

[mrstegeman]

So, the dimmer would be:

'@type': ['OnOffSwitch', 'MultiLevelSwitch', 'PushButton'],

[benfrancis]

No, the PressedEvent, DoublePressedEvent and LongPressedEvent @types apply to three separate Event objects.

{
  "name": "My Button",
  "description": "A push button",
  "@type": ["PushButton"],
  "events": {
    "pressed": {
      "@type": "PressedEvent",
      "description": "The button was pressed briefly.",
      "href": "/things/lamp/events/pressed"
    },
    "doublePressed": {
      "@type": "DoublePressedEvent",
      "description": "The button was pressed twice in a row.",
      "href": "/things/lamp/events/double-pressed"
    },
    "longPressed": {
      "@type": "LongPressedEvent",
      "description": "The button was pressed for a long period of time.",
      "href": "/things/lamp/events/long-pressed"
    }
  }
}

You can have an array of values for @type (at least for the top level device type), but it isn't necessary in this example.

P.S. Sorry @type for all the mentions, whoever you are!

[benfrancis]

(What Mike said :P)

[dhylands]

OK - in that case, the dimmer switch will also be generating an event with the name 'released'. Should it have an @type of ReleasedEvent?

And does the href of an event just return the thing description corresponding to just that event?

[mrstegeman]

No, that href returns a list of generated events with that name.

[mrstegeman]

Question: Do people like PressedEvent or SinglePressedEvent better? The latter seems to fit the theme of the others better.