Thing actions


(David Graeff) #1

Hello developer community,

this is one of a few Ideas I like the AC to consider.

We have no good pattern for pairing devices. And pairing actually differs a lot (OAuth, Pin, Button-press, scanning a barcode). And also no good ways to present other Thing management actions like “Reset remote device”, “Reboot remote” or “Create new user token” etc.

I propose to add Thing actions. Those are listed via the REST endpoint and also available via the OSGI console. UIs would present them in the Thing screen:

Bildschirmfoto%20vom%202019-02-12%2017-46-08

An action can either just trigger something (that is reported via the Thing status) or be a web-link to a binding hosted html endpoint. The latter one is necessary for showing oauth dialogs. One binding that requires this functionality is the Amazon Echo/Alexa binding, which atm hosts such a mechanism non-standardized and would benefit.

Cheers, David


(Rich Koshak) #2

I created the AC topic.

What would be the impact here if the custom per/binding HTML widget idea doesn’t happen? Is there a way to support this without? Are some of the use cases still valid?

This sounds like it would primarily be used on Bridge Things and Things that represent a connection to some other service, right? Maybe the Unpair makes sense for regular Things.

This proposal looks like it is purely additive meaning it doesn’t really have that much of an impact on the rest of the API, right? I definitely see this as a way to bring more Habmin zwave/zigbee management capability into the main UI.

This is starting to feel like a new feature though rather than a simplification so I’d definitely say it’d be targeted to OH 3.


(David Graeff) #3

Yes this is a new feature, but it only adds and does not break. It is comparable to the “recently” added Thing action “Enable”/“Disable”. I’m targeting add adding a generic Thing action part, not just for enabling/disabling a Thing.


(Łukasz Dywicki) #4

I’m not certain if “pairing” in terms of OAuth is a valid case for thing actions - this is usually something which comes from lower level of binding code related to retrieval of data.

In many cases, if not most of them, you can’t do anything with a thing unless you set up your account. That’s first step to give OH access to your resources at 3rd party server. Only then you can create and populate things from results returned by remote service call. In case if you want to repeat process and pairing fails you will end up with uncertain state and things which will keep choking (or in offline mode).

Maybe having something like “security vault” or “credential store”, like introduced with esh oauth2 client apis, would be better for that?

Kind regards,
Łukasz


(David Graeff) #5

Think about Bridge Things: Take the Hue binding as example (but I’d be happy about examples from your side as well):

  • You can find the device via discovery.
  • The bridge thing can be added but will appear OFFLINE with CONFIGURATION_ERROR and the message “Pairing required”. In my world, the bridge would not do anything anymore, no polling, nothing. It waits for the user to act.
  • You issue the “pairing” action. The bridge now tries for a limited amount of time (Amazon and various Bluetooth devices settled on 1 minute) to pair.
  • You put your remote device into pairing mode (push the Hue bridge button).
  • Your bridge Thing gets a token and leaves pairing mode again.

Very straight forward process. And this works (in contrast to current workaround solutions) also with other pairing methods (bluetooth pairing, zigbee pairing etc, everything that requires a dedicated “pair” action).


(Łukasz Dywicki) #6

It’s great that hue bridge is locally discoverable, however there are other situations where you might not have any network element to query nor discover. Its fine that it forces you to press buttons as part of oauth flow, but I wouldn’t follow on that as “reference”. I would say its quite far from examples how normal (a standard) oauth flow looks a like in 90% of cases out there.

Any device/integration which doesn’t have or have limited local communication capabilities - ie. netatmo or nest will fit into “no bridge” category. In such case bridge is completely virtual and uses tokens retrieved during oauth process, more over things which you create are similarly like bridge - completely virtual and come from resources retrieved by external service. I guess that over time even more devices or rather services will fall into this category.
Even now if you think about usage of google apis to ie. calculate travel time, send alarm mails or access calendar items - quite often you will need to start from pairing accounts.

My point, which I gave above is fairly simple - in many cases you need to start from oauth to even call service. You might run into situation that tokens expire but then there are more things which gets affected - all which use same, odd token.

Cheers,
Lukasz


(David Graeff) #7

But do you see the proposed actions contradicting this? Those actions would also include “reset”, “reboot”, “unpair” and any other actions on the remote device or service that cannot be modeled via channels.

Pairing was an example, please don’t harden on that. I was also taking about “web link actions” in the proposal to cover oath btw.


(Łukasz Dywicki) #8

Thing actions is a great idea no doubts on that. All I’m trying to say is to be consistent in what is shown and where. If you give more than two paths to users for certain functionality they will soon get lost.
Because each and every binding is different keeping some bare minimum regularity (even at oauth level) will improve overall user experience.

Cheers,
Łukasz


(Rich Koshak) #9

This sounds like a good idea but it isn’t something the AC needs to consider since it has no wider impacts. Open a GitHub issue and discuss with the other maintainers.