New Capabilities Docs

(Jim Anderson) #1

Hey all,

Forgive the tardy announcement, but we added some new capabilities to the docs recently:

Carbon Dioxide Measurement
Sound Pressure Level
Shock Sensor
pH Measurement
Tamper Alert
Voltage Measurement
Window Shade

Many of these were created by @yaimavaldivia in response to community requests - so hat tip to Yaima! :tophat:

Rule Machine Feature Requests
Fibaro Z-Wave Motion Sensor
( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #2

I hate to be “that guy”… But wait, I am he…

What happened to my suggestion that new Capabilities go through a “Community Review process” prior to implemention?

There’s just so much valuable input that I believe we (or, frankly, I), could have made.

e.g., Window Shade

Missing at least two critical Attributes and associated Commands:

  • percentOpen (0 to 100)
  • bladeAngle (0 to 359 degrees, or 0 to 180 degrees, or - 100 to +100 gradient … subject to discussion).

Instead, just a single string enum Attribute “windowShade” ["unknown" "open" "closing" "closed" "opening" "partially open"]… Seriously? :cry:

Perhaps it’s not too late @yaimavaldivia? And please also strongly consider encouraging Community review/feedback involvement prior to finalization of future Capabilities…? :confused:

Capability Reference Completeness
(Sean Kendall Schneyer) #3

A window “shade” would not have blades. Those would be window “blinds”, so really you need two different capabilities as they are two different things.

On the topic of a window shade though, some shade motors (like many of the Somfy motors) have a concept of a “favorite” location. So then you end up with “open”, “closed” and “favorite” or maybe “saved position” or something.

Also, why is one in past tense (“closed”) and the other isn’t (“open”)?

EDIT: Not trying to be a Negative Nancy and am glad to see updates being made to capabilities!

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #4

Thanks for your comments, Sean…

Because it takes so long to get new Capabilities (and, apparently, even longer to get them right…), and for several other very good reasons, I think it is reasonable to “overload” a Capability with some broadness.

If you want to read (and, please, please contribute to) my academic discussion on what should the scope and granularity of a Capability be, please reference this link:

TL;DR; … Since there is no Capability “Window Blinds”, and we’re not likely to get new capabilities for a very long time, I think it is reasonable to figure out how to have Attributes in a Capability that may not apply to all Device Types implementing it. i.e., Windows Blinds are a special type of Window Shade.

(Sean Kendall Schneyer) #5

Will absolutely give it a look and hopefully contribute (hopefully in a positive manner).

As an “engineer” I like to be precise. Agree that overloading here is a good thing, but then the Capability Type should likely have been called “Window Covering” or some such. Having just built a new house recently and having installed motorized window coverings, those professionals take their terminology seriously within their own domain.

Just like we wouldn’t call a Thermostat a “Temperature Setter” :o)

Speaking of Thermostats, I’ve been working on a Device Handler for a thermostat and see gaps in those capabilities. There really is a need for a Programmable Thermostat since most of these smart thermostats have some kind of “program” capability, it makes sense to take advantage of those features. But without a proper capability it won’t be implemented in the same way across device types, thus it won’t show up as a default feature in apps like Rule Machine.

But anyway, I’ve now digressed…

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #6

Actually, I think you’re bang on Topic…

I wrote the treatise I referenced exactly 1 year ago (February 2015). It received ZERO response from SmartThings and pretty much no comment from the Community either.

The stuff you mention in your response above (precision of terminology … i.e., the importance of meaningful capability names, attribute names, command names … Events), and the implications of this, are all points I touched upon in my write-up.

If you think I’ve made even a tiny bit of sense in that post, then perhaps you can help revive the important points again. DRAFT: Guidelines for Capabilities (under construction...)

(Alex) #7

In case someone wants to browse and play, here is a complete listing of currently implemented capabilities and their attributes and commands.

(Adam V) #8

Great to see Carbon Dioxide and pH in there.

Would love to get VOC & particulate matter… I think you’d then cover all air quality measures

(Jody) #9

We are meeting tomorrow 2/19/2016 to discuss the process for new capabilities. The next batch will not take 12 months, but we do need to spend some time getting the process right. Everything from suggesting new capabilities to the features they have will be reviewed. We should start a new topic for this and also revisit the existing threads for capability suggestions.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #10

Yup… it’s a challenge.

I don’t have to point you to the volumes I’ve written on the subject – part of the problem are the limitations of the implementation of the Capability ("interface) paradigm in SmartThings, such as only being able to specify a single Capability as an input() filter (i.e., no boolean logic).

Random example reference … discuss as you wish, private or public … super appreciated!

(Jared Fisher) #11

I noticed the documentation for device attributes state,

For any supported attribute, it is expected that the Device Handler creates and sends events with the name of the attribute in the parse() method."

Is it possible to leave an attribute undefined? Forcing attributes to be defined would be a pain if we start adding a ton of “possibly used” attributes. But on the other hand, using capabilities/attributes as an interface/contract would make handling all kinds of device types a lot easier. Also, am I missing something or is there no way to get a list of capabilities to iterate over in a SmartApp? I’d love to see a sequential attribute with a map of direction and step amount, but for now that has to be logic within a SmartApp. But for a capability.switchLevel supported device, that kind of logic belongs in the device handler.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #12

It should be possible for a subset of Attributes (and/or Commands) to be explicitly defined in the Capability as optional; though the implications would have to be seriously considered.

Indeed, the Device Object has three methods (and probably associated properties that can be iterated over?): hasAttribute(), hasCommand(), hasCapability(); a SmartApp Developer should be able to assume that if a Device “hasCapability”, then it will have all of the mandatory Attributes and Commands, but the developer needs to check for the optional ones.

If the scope / granularity of each new Capability is “wisely chosen”, then I’d much prefer that the platform define officially optional Attributes & Commands, rather than letting each DTH Developer run amok with ad hoc / custom Attributes & Commands (i.e., those listed with the attribute and command keywords.

The latter case (ad hoc amokness…) is extremely common at the moment due to the staleness of the Capability Taxonomy. Unfortunately, every Device Type with ad hoc attributes and/or commands has lost the potential for it’s device instances to be compatible across more than a few specialized SmartApps.

@bravenel cleverly came up with a way to solve this modularly in the “Expert Features” section of Rule Machine, by allowing the user to enumerate the custom Commands of a “Test Device” (ummm… I haven’t checked if he handle custom Attributes too?).

But… I can tell by your post that you definitely “get” the concepts around Capability = interface = contract. Let’s go ahead and consider when optional attributes and commands make sense … and, well, when when “ad hoc / custom” ones are also appropriate or inappropriate!

(Mark S Groves-Zen Studios) #13

I agree, a lot of have specific expertise in one or more areas and could reduce the implementation pain of new capabilities.

(Stuart Buchanan) #14

I can confirm he does not. I requested this a while back but he decided against it. For now I have to create my own smartapps when I want to do something based on a custom attribute.