Parameters for on() and off() methods?

So, I found this in the official laundry SmartApp:

which raises questions for me:

  1. this suggests that there are parameters for the on() and off() methods of the switch capability. There is no reference to this in the docs. Just another enhancement that hasn’t made it into the docs yet? @Jim? Is this functionality that exists but ST does not intend to expose to devs explicitly?

  2. Is there any significance to the fact that the ‘delay’ parameter is presented in JSON format rather than just the value? Maybe a way to pass a parameter to a method without explicitly defining a format for method parameters (ie method(param1, param2)) .

How is this delay implemented? Job scheduler (cron/Quest)? Does using the delay parameter result in tying up a thread?

1 Like

The command method (“on”) in this case, is documented to support parameters (the delay parameter being the only supported parameter at this time).

You can find it here: https://graph.api.smartthings.com/ide/doc/device

Since command methods vary by capability/device type, it’s documented as <command name>(arguments, [delay: N])

2 Likes

Thanks @Jim! I did not look there (search terms I used would not have put me there). This makes more sense now.

Also, it looks like there is a distinction drawn between an ‘argument’ and an ‘option’ explaining the different formats.

I looked in the dimmer Device-Type for code that implements the delay but didn’t find it. Would it be correct to say that ‘arguments’ are handled in the Device-Type and ‘options’ are handled by the platform?

This may just be newbishness on my part. . . .thanks for your patience with me!

My first instinct is to say that “options” are just optionalarguments” – i.e., it does not imply conclusively that certain arguments are handled by Device Type code and others may be intercepted by the platform.

1 Like

Thanks @tgauchat. I think I can get my head around the idea that optional arguments have to be in JSON because they may or may not be there and may or may not be in any particular order.

I have to say that the idea that some things are just picked off and handled by the platform on the way from the application layer to the device-type layer just adds to the confusion . . . at least for me ;-).

Indeed … there’s a few things in play here:

  1. The use of a Map (List with named items, Named Arguments, …) in Groovy for default and/or optional arguments is a typical Groovyism. (Ref: Default arguments in Groovy — Groovy Programming). Handling the same semantics in Java requires more work to ensure method signature matching.

  2. It is important to keep in mind that in SmartThings, “Device” and “SmartDevice Type” are two different Classes (the Reference Material sub-section titles are a bit confusing in this regard, because the links imply class names “device” and “deviceType”, which seems more consistent than “SmartDevice Type” (@Jim?), but … whatever (https://graph.api.smartthings.com/ide/documentation)

  • This means that when a SmartApp is calling method command “<device>.on()”, note that device is an instance of “Device”, not “SmartDevice Type”. Every Thing you’ve added to SmartThings is accessible to SmartApps and the REST-API as instances of “Device”.

  • And yet, the Handler for similar Devices is a part of an object of class “SmartDevice Type” – notDevice”.

  • So compare the Reference Material for these two classes and notice the difference:

  • Device:

  • SmartDevice Type:

i.e.,: Accurately documented that instances of Device accept the “[delay: N]” argument, but instances of SmartDevice Type do not.

So… SmartThings isn’t doing any magical “picking off”. We just have to be aware that SmartApps call a particular set of methods in the Device Class, some of which, in turn, do some stuff and THEN call similar (but not the same) methods in SmartDevice Class, passing along only the applicable argument values.

The whole thing might be less confusing if they gave the methods different names? (e.g., <device>.sendCommandOn<deviceType>.commandOn?

Or would that be worse?

For now… the Documentation currently says:

(but am not sure that “merging” them is the best plan…):

…CP / Terry.

3 Likes

Ha! Well, it was much easier to think of the platform arbitrarily picking off things along the way ;-).

I’m no less confused but way more informed. Much appreciated, @tgauchat. As always, great seeds for additional investigation.

Looking at the docs . … is this a typo:

should the ‘description’ for details be details(List<String>)?

2 Likes

Yes (NB: @Jim – or would you prefer pull requests in GitHub for typos like this :smiley:?).
Good catch. (Heck “difference” should read “different”, in the previous pasted documentation snips too…).

Example code:

main(["status","contact", "acceleration"])
details(["status","contact", "acceleration", "temperature", "3axis", "battery", "lqi"] 
2 Likes

Not that this will unconfuse you…, but I’ve wanted to share this somewhere, possibly for my own benefit…

I think that what’s going on is that SmartThings is using the Object-Oriented (OO) “Factory Pattern”. This is very common pattern, yet, my formal Java education is limited to one semester + a bunch of reading, so I’ve never studied, umm…, factories. Inaccurately, I’m assuming that when we add a Thing, the factory is used to create a Device Instance, and the factory performs important magic that links it to the correct SmartDevice Type.

Maybe @duncan or ? or @ben can someday give us a peek under the covers at the architecture? (And/or I’m getting in over-my-head at the moment, and need to study and better understand the possible OO patterns that could be in play here.). – Or this part of ST’s implementation may be proprietary.

Intent
creates objects without exposing the instantiation logic to the client.
refers to the newly created object through a common interface
Implementation
The implementation is really simple
The client needs a product, but instead of creating it directly using the new operator, it asks the factory object for a new product, providing the information about the type of object it needs.
The factory instantiates a new concrete product and then returns to the client the newly created product(casted to abstract product class).
The client uses the products as abstract products without being aware about their concrete implementation.


*really simple” eh? Well… perhaps after translating all the important terminology used in that snip!

…CP / Terry.

1 Like

We actually don’t keep our reference documentation in GitHub (but I love the collaborative spirit!). I’ll need to update it; it might be a week or more until it shows up.

Good catch!

1 Like

Thanks, Jim! I think that “obvious” typos are definitely lower priority than the tremendous stuff you’ve done in expanding and reorganizing the overviews and examples; since the former we can guess the fix, but the latter is valuable new information.

Us newbs have to assume the docs are correct and errors like this create confusion as we try to reconcile what’s there. Not to mention, obvious errors make the authors look silly. I know there are lots of demands on everyone’s time but I say fix these as they come up . . . . .FWIW

n00bs

:wink:

1 Like

I agree. The fix for the docs will be released with our next general release sometime this week.

2 Likes