I don’t think we are using actuators appropriately. In the real world, an actuator has a very narrow definition. I would not consider a button or light switch an actuator. Your finger that presses the button is technically the actuator. The motor that rolls up your blinds is an actuator. The switch that engages the actuator is just a switch.
In network design for at least 25 years an “actuator” is a switch. Zigbee has defined nodes as being controllers, actuators, or sensors since the beginning, there’s nothing new in this. In zigbee terminology, a dimmer switch is an actuator.
However, in zwave terminology, it’s the other way around: a valve actuator self identifies as a switch.
A Sensor is any device that can DETECT a change in the environment. Examples are Contact, Motion, Temperature, Acceleration, Tilt, Water, Sleep. I think even a Switch could be a Sensor, since it detects and reports when it is turned on or off physically; but I don’t know if the spec would have included it.
An Actuator is any device that can MAKE a change in the environment. Examples are Switch, Thermostat, Garage Door Opener, Valve, Music Player, Siren.
(NB: Notice that all my “examples” are actually the names of “real” Capabilities. Sensor and/or Actuator should really be a Property (“Characteristic” is the word I seemed to use in my Guidelines Document) of each Capability definition, rather than a property of each Device Type. This incorrectness is easy to explain though – simplicity of implementation for use in the input method).
Why have these categories or “base capabilities”?
It’s for the “planned” “Rules Engine” and/or for writing flexible SmartApps with fewer Input statements to bother the user with…
Consider this: Many SmartApps are in the form of:
IF
triggerTHENaction.
Well… Let’s alter the names of the placeholders a little bit:
IF
sensoreventTHENactivateactuator
In practical use? Instead of having half a dozen input statements for the various sensor types (i.e., “When these doors or windows open?” + “or When motion is detected by?” + “or When any of these switches are turned on?” … THEN … “Turn on these lights?” + “and/or Turn on these Sirens” + etc., etc., etc…
In other words: Grouping Capabilities into a Category gives input the “OR” ability (Contact OR Motion or Temperature OR Switch OR Tilt OR …); just not very flexibly, since it is an all or nothing situation.
How the heck would a SmartApp deal with a Device List variable that contained Devices of heterogeneous Types? 
They would have to use some or all of the these Device Class Properties to determine what specific Attributes and Commands are available: https://graph.api.smartthings.com/ide/doc/device
capabilities (List<Capability>)
supportedAttributes (List<Attribute>)
supportedCommands (List<Command>)
1 Like
This is good.
One minor point: I would argue that a switch would only be considered a sensor if it actually detected its physical position, otherwise it’s not “detecting” the off, it’s just notifying the hub as to the last command.
1 Like
Then we need to just settle on one of those words. If all switches are actuators or all actuators are switches we are just building a convoluted capability list.
Agreed. Again, I suspect this has to do with trying to build a universal protocol overlayer on top of existing third party certifications. Zigbee uses sensor and actuator. Zwave uses sensor and switch. Somehow instead of picking one, ST ended up with both.
In network design, many people argue that the end device is not an actuator. So the light switch is an actuator, the light bulb is not. (But a smart bulb is usually considered an actuator.)
A siren is generally considered neither a sensor nor an actuator. But if it’s networked, there’s likely an actuator there somewhere.
Many home automation systems put doorlocks into their own category, neither sensor nor actuator. (This is opposed to thermostats, which are both a sensor and an actuator but usually get put into their own category as well.)
System gateways and controllers are neither sensor nor actuator.
A repeater is generally considered neither a sensor nor an actuator.
I’m sure there are some more, but those are the main categories. Controllers is the biggest one, I think just about every HA network has a separate controller category. Sirens are debateable, but if they have no internal detector, they just go off when you tell them to, they do look like end devices. But like a smart bulb, they may be treated as an actuator with on/off.
p.s. Cameras are a whole separate issue. Some older HA systems just treat them as a light switch–on or off. Newer ones tend to put them in their own category.
1 Like
@tgauchat is correct here (and I may even ask to borrow some of the wording 
). And at the implementation-level this means that any device that has commands should support the “Actuator” capability, and any device that has attributes should support the “Sensor” capability.
2 Likes
@tgauchat 's stuff is good, but the sentence above still makes no sense.
I’d be OK with
any non controller device that issues commands for another device to follow should support the Actuator capability and any noncontroller device that reports attributes should support the Sensor capability
Because we know the actuators will often set the attribute values in the commands and we know the sensors will often receive commands.
It’s the word “has” that isn’t working for me.
But I still prefer the existing documentation’s concept that
Attributes are the possible values for a particular command
Would an example help clarify?
If you look at the capabilities reference, you’ll notice that the Contact Sensor capability only defines attributes - it has no commands. The open/closed sensor device-type handler supports the “Contact Sensor” and “Sensor” capabilities. It supports the “Sensor” capability because it has attributes (“Contact” attribute). It does not have any commands through its supported capabilities, so it does not support the “Actuator” capability.
The list of capabilities is not consistent with the proposed sentence
any device that has commands is an Actuator and any device that has attributes is a Sensor.
Alarm has both attributes and commands. That might make sense if it were both a sensor and an actuator, but the attributes are strobe, siren, off, or both, which doesn’t fit the sensor model.
ColorControl has both attributes and commands. My guess it’s intended as a controller, which makes sense, but doesn’t fit the sentence.
Lock has both attributes and commands. My guess is it’s (surprise!) a lock. Neither an actuator nor a sensor.
Relay switch has got to be an actuator or nothing makes any sense, but it has both commands and attributes.
Same with switch. If that’s not an actuator, actuator has no meaning. But it, too, has both commands and attributes.
And again valve has both, when it has to be an actuator in any sense of the word.
MusicPlayer is obviously not a sensor, yet has attributes. (It’s likely that third category, controller, which is missing from the taxonomy of the sentence under discussion.)
One of the weirdest is that we are presented with distinct capabilities for “button,” “contact sensor,” and “momentary” leading us to wonder just what the heck is button if it’s neither a contact sensor (sensor) or a momentary switch (which is an actuator)? Unless perhaps it’s intended for a button controller, which is indeed different from an Actuator–but isn’t a Sensor either.
So the fact that contact sensor can be made to fit the sentence
any device that has commands is an Actuator and any device that has attributes is a Sensor.
Doesn’t change the fact that the examples I’ve given above can’t.
Submitted respectfully…
You’re right, JD. I think it is an incorrect generalization to use the pretense of Attributes and/or Commands to determine if a device is a Sensor and/or Actuator.
Refer instead to my earlier post:
1 Like
I’m ok with this. This should more pronounced in the documentation.
Edit:
I think it would be a good convention. I’m not crazy about the terminology but it helps to have such a marker.
1 Like
This vesternet doc has a really good discussion of controllers, actuators and sensors in a zwave environment. I think recognizing that some devices, like the aeon Minimote, are controllers is important. Three device categories, not just two.
@Jim
After digesting this for a while, I have new questions using “proper” terminology:
How come capability.momentary is not a sensor if it’s state changes?
Why is there no capability.device in case I want a device and don’t care what kind it is?
I still think there need to be at least three groupings, not two, to allow for the Minimote and other controllers. And I still like the vesternet definitions linked to above.
That said, capability.device would be tautological, as anything that has capabilities is a device of some type.
Momentary switches are a problem in any definition scheme, because they are contact sensors that work as switches. They do report open vs closed, but their purpose traditionally was to actually close a load circuit that powered another device, like a doorbell button causes the chime to sound. (That’s no longer required, though.). Mostly they get defined as switches just because that’s the security grouping they fall under, but as you point out you can argue it either way.
Alright, how do I define a SmartApp input that takes any device?
Is there a network address/node ID attribute in smartthings device types? That would do it.
I’m looking for something like this:
input "someDevice", "capability.device", title: "Select devices", multiple: true
1 Like
Seems unlikely. You want to list all the devices known to the network? That’s not a capability paradigm.