To be blunt, right now this is what we want from you guys; a process to add new capabilities suggested by community. This forum can be a good enough the tool, but needs to be moderated. Just create a topic and make sure you start monitoring on it.
The problem is ST staff isn’t always going through all of the topics. Historically, there has been suggestions for new capabilities in the community but it gets completely ignored by ST staffs. e.g [API Request] Alarm Panel device capability.
If this topic on capabilities wasn’t mentioned in the recent developer meeting(thank God for that), none of the ST staff would have noticed that developers in the community are struggling to understand not only the documentation, but the overall purpose of it.
I have an antenna on my roof. I cut the cords about two years ago. We have a media server with 4 digital TV tuners for recording over the air broadcasts. There is a fair amount of content available over the air for free. We also have several streaming video subscriptions and it’s all tied together with a harmony remote.
I’ll go even farther on this… I’ll suggest a full system for adding capabilities…
ST (with or without the community help) determines guidelines for adding new capabilities.
Understanding that everyone is going to flood ST with requests, and that most would be rejected and/or duplicates, ST should draft 2-3 community members (preferably people with dev experience) to filter the requests. Those members should meet (virtually) at least once a week to go through any existing requests and forward “approved” ones to ST. (This should significantly reduce the number of requests getting to ST and weed out 90% of the ones that don’t meet the guidelines set forth by ST.) Give the draftees a t-shirt or a lightbulb or something. (I suspect most people would be willing to help for free given the chance to help shape ST and make it better.)
Those draftees could come up with different ways for suggesting capabilities. A single thread might become too confusing (as I’m sure there would be discussion/debate for some of the proposals), so perhaps a subsection of the community forum would be nice. A single thread for each proposal. By having it “open” like that, various other people can give feedback/comments on proposals.
I certainly want to have an ability to create user-defined capabilities. Restricting available capabilities to a pre-defined set would be very limiting as devices with new capabilities appear every day and going through some kind of voting or approval process would hinder development.
Capability is nothing more than a named bundle of commands and attributes. This what Zigbee spec calls clusters. All the device would need to do is publish its capability in the global repository. It can use namespace the same way device type and apps use it today to avoid ambiguity. Then any app can request all devices that provide this capability the same way they do it now, i.e.
Sure, I’m finding more people than I thought do have ears on the roof.
The point of my rant on this specific device relates to the shortsightedness of it. The currently published capabilities are tied to a specific use case (samsung) over a specific control medium (TCP/IP), however every single consumer audio/video device I’ve seen/owned over the last 30 years is at the very least controlled by IR.
So the question regarding the TV device being: are there two separate TV devices? ipTV and irTV? required, or are we forced to create a composite device which implements the existing TV with a switch…, which violates what we are currently being told about device capabilities… I see evidence of the confusion even within the existing capability matrix. Some being holistic, some not…
[quote=“geko, post:44, topic:9917”]
Then any app can request all devices that provide this capability the same way they do it now, i.e.
[/quote]If any person can add a capability, then I suspect we’ll end up with a huge mess. You’ll define “capability.norad.lasergun”, and I’ll define “capability.garyd9.laserweapon”, and someone else will define “capability.someoneelse.LethalFocusedLightDevice”. All three will be extremely similar…
Three weeks later, someone decides that they want to write a smartapp to destroy anyone who trips a motion sensor. Which capability do they ‘input’ as the weapon? All three?
I really think that anything going into the global name space (such as capabilities), there must be controls.
That’s the whole point of the open system, isn’t it? Right now we have twenty implementations of thermostat with pretty much the same functionality. Choose which one you like. Why capabilities should be treated differently?
Three weeks later, someone decides that they want to write a smartapp to destroy anyone who trips a motion sensor. Which capability do they ‘input’ as the weapon? All three?
The answer is any. Overlapping capabilities are inevitable. This is already reality today. The apps that control lights must deal with both capability.switch and capability.switchLevel and the apps that provide voice notifications – with capability.speechSynthesis and capability.musicPlayer.
[quote=“geko, post:47, topic:9917”]
Choose which one you like. Why capabilities should be treated differently?
[/quote]Because capabilities are the glue that holds the system together. They are the language used to communicate. If my device type speaks Spanish and your device type speaks French… and a SmartApp speaks English, then we’ve done a ton of work to accomplish absolutely nothing.
There might be 3 different thermostat device types, but they all (in theory) should speak with the same capabilities (assuming that they expose the same abilities and attributes.)
Edit:
Let me put it another way… What if, instead of using the existing “switch” capability, there was a different capability defined for GE Switches, Linear Switches, Leviton Switches, Evolve Switches, and so on. How would you write a smartapp that turns on any light switch?
input “switches”, “capability.???”, title “Which Switches?”
Wow, I missed this part of your reply. I’m sorry about that.
Actually, devices that control lights don’t have to deal with “capability.switchLevel” if they are content with only turning a light on and off. There’s no overlap. “switch” defines on/off and “switchLevel” defines a level.
Same thing with speechSynthesis and musicPlayer. One defines ONLY speaking and the other defines functionality for playing music. No overlap. This, IMO, is how it should be. Some devices that are music players might not be capable of speech synthesis (and some speech devices might not have music playing abilities.)
Remember that capabilities define capabilities, not device types. A device type is an implementation of one or more capabilities.
To my way of thinking, the “overlap” problem is with capabilities such as “lock” and “lockCodes.” Why does “lockCodes” have the same attributes and commands as “lock”? Not only is this confusing and overlapping, but it leads to some interesting questions. For example, what if a device type has both capabilities (as many existing ones do. Take a look at ST’s device type for “z-wave lock”.) Which “unlock” command is that device type implementing? lock.unlock() or lockCodes.unlock()?
In this case, “lockCodes” should be fixed to remove the overlap (see a post above from me that talks about marking some things as “legacy” and then later removing them.) capability.lockCodes should have the attributes and commands related only to LOCK CODES. capability.lock should have the attributes and commands related only to LOCKS. If a device type supports locking/unlocking and supports lock codes, it should declare both capabilities (in much the same way that a dimmer switch declares both switch and switchLevel)
[quote=“copyninja, post:49, topic:9917”]
It’s a mess today, but we are hoping that it will not get any messier than this
[/quote]Agreed. I’d also like to clean up the existing mess. With rules/guidelines for capabilities, it would be easier to identify (and hopefully resolve) the ones that need to be fixed.
Yes, it’s a big task. That’s why I’m suggesting that community members are drafted to help with the process. Sure, the actual implementation will get dropped in the lap of ST employees, but at least the community can help deal with the spam, garbage, and filter things to a reasonable LOE for ST.
1 Like
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
51
Hi Matt … Welcome to the conversation: We really value SmartThings’s internal input here, and you’re an especially good candidate .
Disclaimer:Please note that I have not had the pleasure of meeting you in person nor one-one chat/conversation, so there is some risk in a Forum discussion that I may sound a little judgemental or even aggressive. That’s certainly not my intent, and I try to frame my questions and arguments appropriately – but in the interest of being efficient, I sometimes cut “right-to-the-point” … the “point” being my own personal opinion on the way I feel something is not quite right or a recommendation for something, but with nothing personal intended whatsoever. I don’t know all the internal history or cross-linked architecture stuff behind the scenes, so I can only comment from a black-box perspective, but do so with the utmost respect and recognition that things are always more complicated than they seem. The platform is based on excellent principals and must have gone through a lot of thought and debate and require compromise and flexibility. – TL;DR: If I say “WTF” or “that’s crazy” or some other sarcasm; it is just my folksy point-of-view language, not a judgement on the design or efforts of SmartThings’s team whatsoever!
Wow…, incredible growth and a testament to the power and potential of the SmartThings platform: 12,000 SmartDevice Types!? …
… and yet … The Capabilities Taxonomy has barely changed in 3 years. How is this possible?
Seriously … how is this possible?
The rather short Capabilities list was and is so brilliantly conceived that it really does cover such an incredible number of devices.
and/or
You’ve added new Capabilities that have not been published and shared with us.
and/or
A significant number of those 12,000 SmartDevice Types are using one-off attributes, commands, and/or ad hoc event Types in order to represent the unique interfaces of the physical world things.
Item #1 is beyond belief. #2 is partially fixed by documenting and sharing the new Caps, though these Caps must vary in maturity and rigor.
I fear, however, that the most common situation must be #3, and I can understand why:
As far as I know, Attributes are not only required by SmartApps and Services, but are required for the GUI (mobile app). If a certain brand of thermostat has a feature “highest temperature of the last 24 hours” and the coder needed to represent this in a tile, then they would have been unlikely to request a new Cap for this one new attribute, since, heck, SmartThings allows you to add Attributes on the fly, there’s no friction to doing the QUOTE “wrong thing” UNQUOTE.
and/or
The new device type was being added at the same time as one or more somewhat “tightly-coupled” SmartApps were being coded (i.e., SmartApps which are rather unlikely to be used with alternative devices of even similar capabilities, possibly because there aren’t any similar devices in existence yet, or there is tight coupling to the brand, or patent, etc.). In this case, these SmartApp(s) needed to use some unique Attributes and/or Commands and/or Events from this unique device, that did not fit in any existing Caps and, as this was a “one-off” Device Type, did not “justify” creating a new Cap.
Solution(s)?
Well… that’s where the discussion of granularity (ref: @thegibertchan) comes in; and I eventually get to in if you manage to stay awake through a few more paragraphs…
If a new SmartDevice Type requires special attributes or commands (NB: or Event Types – I have make this implied until further notice: I don’t understand if/how/why Event Types are being used as part of the device interface that isn’t defined with attributes and commands), then I think we have two options:
If there is a need for urgency, and/or if the new attributes and commands are difficult to comprehend outside the context of this particular device type, then it should be flagged with “capability.extended” or some similar {metadata} that distinguishes and identifies the variances from the applied standard official Caps.
This seems safe for “added” attributes or commands, but is still unsafe with respect to the standard attributes and command. e.g., if the device has capability.switch, then all SmartApps and Services that use the device will expect on/off/on()/off(), and there’s NO currently existing way around this without the real risk of making entire bunches of SmartApps fail – i.e., ALL attributes and commands must be implemented, because some SmartApp may, and is legally allowed to, get/set any of those Cap associated attributes and/or call any of those Cap associated commands.
In other words; this quote from your post makes no sense to me:
What do you mean? How can a SmartDevice Type with a particular Capabilitynot implement all of the commands [or attributes] of that Capability? That is a non-sequitur, and can be resolved. Either completely remove the claimed but unfulfilled Capability from the SmartDevice Type (and replace it with a new claimed Capability), or, at the very least, populate the missing commands and attributes with “safe” stubs and defaults.
So to give an example based on your posting: You mention the context of non-published/non-shared devices, and give the example:
OK… Well… first of all, I would say this device is NOT a Switch. It does not have capability.switch. BUT: I totally understand that there are countless unpredictable scenarios in which it is useful to call this a Switch so that (among other reasons?) SmartApps that offer a list of devices with capability.switch can will include instances of this SmartDevice Type. Yet … non-sequitur – most of those SmartApps are likely to fail, since they will most likely try to call the expected “command: off()”.
Sub-Conclusion: At the very least, if a SmartDevice Type claims a Cap, then it must have safe dummy-stub commands and safe default attributes. The non-off-able “Switch” here, can have a blank off(){} command, and should, apparently, permanently set Attribute switch = off.
Implementation Alternative: Some Attributes and Commands of any Capability could be explicitly declared “optional”. Again, I am suggesting this possibility for the Capability definition, not the Device Type definition. For the latter case, if you demand maximum flexibility, all ad hoc Attributes and/or Commands defined in a SmartDevice Type are implicitly and unavoidably “optional”. The behavior of this could be handled in one of two ways:
(a) Optional attributes and commands will automagically return default values and safe-null actions, saving coders the responsibility from writing stubs. The syntax: optional attribute weirdVar String default "off" could be used to set that “meaningful default”
OR
(b) All SmartApps and Services that wish to use any Attribute or Command that is documented (and declared in the Capability or Device Type) as “optional”, should do an “if exists( Device.attribute)” and “if exists( Device.command)” prior to using those optional characteristics, and/or use try/catch or some other exception handling mechanism – i.e., SmartApps and Services can use optional attributes if they know about them AND if they confirm that the individual Device Instances they are using actually have them implemented.
(NB: I am not particularly enamored to this particular Implementation Alternative; heck, I don’t like partially implemented or ad hoc exceptions to Capabilities in any form, but, it’s fun to theorize.)
While I’m still “unsure” as to why such a weird “Switch” would be created, the use of stubs and defaults probably help.
Proposed Rigorous Solution and New Suggestion: “Optional Characteristics”:
I think it is obvious that if Capability are extremely granular, then quite a few problems go away: There is much less risk of having a SmartDevice Type that cannot implement a particular Attribute or Command, because an extremely granular Capability will have: as few attributes and commands as possible (i.e., the minimal set, not the optimal set).
Proposal #1 works well in the existing platform (phasing out non-granular Caps) … almost. The problem: “SmartApp.preferences{input(capability.x)}” only accepts a single “capability.x”. A complex SmartApp really may require a particular set of Capabilities from each Device. Thus, a change is required so that the Capability filter of SmartApp.preferences can use operator “AND” (i.e., An extreme and unlikely example of granularity: capability.on AND capability.off).
NB: It would be nice to also support an OR operator, but code that uses a Device List would no longer be able to reliably iterate a single command over that single combined Device List – unless SmartThings also implements the miracle of Polymorphism (e.g., capability.switch has on()/off(), but capability.lock has unlock()/lock() – both are binary actions, therefore, a Device List made up of capability.switch OR capability.lock could be iterated over with commands activate()/deactivate() inherited from capability.binary. This is worth a spin-off Topic, no?
If Capabilities are granular, even if “reasonably granular” (i.e., .switch is good, but .on and .off is probably overkill…), then the platform would really benefit from the ability to pre-define compound capabilities (e.g., capability.dimmableLight = capability.switch + capability.switchLevel), so that each of hundreds of very similar non-trivial Device Types do not need to manually include the possibly very long list of individual granular Capabilities.
NB: I still see this as a possible step to true Inheritance (and Polymorphism), as discussed at length elsewhere (i.e., capability.switchextendscapability.binary); but that is, admittedly, not a “baby step”.
Conclusion: I think my post covers some important material about the nature of Capabilities that is important to settle before we add any more Capabilities:
The discussion as to “What process, forum, committee should be used to officially add (and, sometimes delete or modify) standard Capabilities” is certainly important – but, IMHO, that can’t proceed with any sanity if the issues I’ve raised here (and, certainly some small and big stuff I’ve missed) are not settled first.
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
52
Wonderful discussion, friends! (@copyninja, @jody.albritton, @Mike_Maxwell, @geko, and … who am I forgetting to tag? Well… we should all be set to “Notifications” on this post if we are vested).
Please see my immediate prior response to @matthewnohr, particularly near the end where I make specific recommendations regarding granular capabilities (pros and cons), and I again bring up the hope for eventual support of Inheritance / Polymorphism…
But hey, nobody said you have to agree with me and neither do I.
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
54
capability.thermostat is an excellent example of a “Compound Capability” which I define here:
In other words, @geko: You ARE right… there is significant overlap in the existing Capabilities, and myself, and others in this conversation are also right to mention this is not an ideal situation. But I’ve provided a solution (“Compound Capabilities” … and, someday, perhaps Inheritance / Polymorphism). Hashtag #rehash.
( [quote=“garyd9, post:55, topic:9917”]
The point is that I agree that it’s a mess. I just think the solution is to clean the mess (and not contribute to making it worse.)
[/quote] )
[quote=“geko, post:53, topic:9917”]
Both capabilities provide Text-to-Speech commands:
[/quote]I didn’t see “playText()”. So, you are right that they overlap… As for relaySwitch, I pointed that one out above (post 40)
[quote=“garyd9, post:40, topic:9917”]
Capabilities should define capabilities, not devices. “switch” and “relaySwitch” define the exact same attributes and commands. They should NOT be two unique capabilities
[/quote]It IS a mess. It should be cleaned. Also from that same post 40:
The point is that I agree that it’s a mess. I just think the solution is to clean the mess (and not contribute to making it worse.)
Man, it makes me wonder how a relatively simple problem can grow into a freaking monster.
The problem you’re trying to solve has been solved multiple times before. All existing standards already have notion of device capabilities in one form or another - Zigbee, Z-Wave, UPnP, just to name a few. Just open a spec and spend a couple of hours reading and understanding it. Then there would be no need to re-invent the wheel
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
57
Yes … but we disagree on how this problem was solved (or disagree on what the “problem” is…):
My assertion is that it has been solved in the Object Oriented Paradigm (Java, etc.) with the concretely defined concept of Interface. Now Interface in Java only mandates this list of “methods”, but I think it is reasonable to extend it to “attributes” since ST doesn’t mandate “getter/setter” methods.
The advantage to my choice of “solution”: Other OO concepts like Inheritance / Extension and Polymorphism can enter the conversation and have a context that might magically “make sense”, because these are also well defined in the OO paradigm.
There are situations when even simple problems require complex solutions, but the complexity needs to be justified. I don’t see it being the case here.
In other words, I’d perfectly fine if SmartThings would just adopt one of the existing standards (Zigbee HA Profile is a good candidate since they already support it) and closed the case.
I agree with @tgauchat in that we need a major re-think on the way we handle capabilities. There is even more duplication than has been discussed at this point. Technically, a lock is just a switch. It is either locked or unlocked; on or off. The current taxonomy blends devices with what those devices are able to do.
We do not need a capability.thermostat
All I care about is what the thermostat can do. Other devices such as window air conditioner units should not have to be described as thermostats to have the capability “coolSetPoint”. Any smart app that adjusts a cooling set point should be able to apply to all devices with the capability of having a cooling set point. Refrigerators also have a cooling set point.
We also need device classes.
In my smart app I could say “requires a device class of refrigerator and a capability coolSetPoint”
This would open up more avenues of smart app discovery as the future smart app store could display all of the smart apps they your devices can take advantage of.
1 Like
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
60
But SmartThings isn’t ZigBee or Z-Wave!
It is all of the above and any other protocol existing and future. It thr Internet of ALL Things.
Therefore a paradigm designed to represent arbitrary Objects in an extendable but contractual manner is the most future proof.
@jody.albritton has it bang-on. His “Device Class” = my “Combo Capability”.
.
