Capability Reference Completeness


#1

Is the API documentation for capabilities complete? I see some example programs that use commands not present in any capability in the API doc. For example, set code/pin on locks doesn’t seem to be anywhere.


Know when a power socket has tripped, thoughts?
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #2

Not a direct answer, but extensive discussion on Capabilities can be found here and in its forum category. The platform needs new Capabilities.


(Andy Rawson) #3

It isn’t complete but you may be seeing a custom command added near the top of the device type code, look for “command” then the name of the command and then look for code to handle that command farther down.

By the way the current list of capabilities is below but what the commands are for some of them is anybody’s guess. :stuck_out_tongue_winking_eye:

name|displayName|smartAppStyleName
Illuminance Measurement|Illuminance Sensor|illuminanceMeasurement
Temperature Measurement|Temperature Sensor|temperatureMeasurement
Relative Humidity Measurement|Humidity Sensor|relativeHumidityMeasurement
Switch|Switch|switch
Battery|Battery|battery
Contact Sensor|Contact Sensor|contactSensor
Motion Sensor|Motion Sensor|motionSensor
Presence Sensor|Presence Sensor|presenceSensor
Alarm|Alarm Device|alarm
Water Sensor|Water Sensor|waterSensor
Polling|Polling Device|polling
Configuration|Configuration Device|configuration
Tone|Tone|tone
Three Axis|Orientation Sensor|threeAxis
Switch Level|Dimmer Switch|switchLevel
Lock|Lock|lock
Acceleration Sensor|Acceleration Sensor|accelerationSensor
Refresh|Refresh|refresh
Thermostat|Thermostat|thermostat
Momentary|Momentary|momentary
Image Capture|Camera|imageCapture
Energy Meter|Energy Meter|energyMeter
Power Meter|Power Meter|powerMeter
Indicator|Indicator|indicator
Valve|Valve|valve
Location Mode|Location Mode|locationMode
Signal Strength|Signal Strength Detector|signalStrength
Smoke Detector|Smoke Detector|smokeDetector
Carbon Monoxide Detector|Carbon Monoxide Detector|carbonMonoxideDetector
Button|Button|button
Music Player|Music Player|musicPlayer
Lock Codes|Lock Codes|lockCodes
Color Control|Color Control|colorControl
Sensor|Sensor|sensor
Actuator|Actuator|actuator
Relay Switch|Relay Switch|relaySwitch
Beacon|Beacon|beacon
Sleep Sensor|Sleep Sensor|sleepSensor
Step Sensor|Step Sensor|stepSensor
Test Capability|Test Capability|testCapability
Door Control|Door Control|doorControl
Media Controller|Media Controller|mediaController
Speech Synthesis|Speech Synthesis|speechSynthesis
Speech Recognition|Speech Recognition|speechRecognition
Thermostat Cooling Setpoint|Thermostat Cooling Setpoint|thermostatCoolingSetpoint
Touch Sensor|Touch Sensor|touchSensor
Thermostat Mode|Thermostat Mode|thermostatMode
Thermostat Fan Mode|Thermostat Fan Mode|thermostatFanMode
Thermostat Operating State|Thermostat Operating State|thermostatOperatingState
Thermostat Heating Setpoint|Thermostat Heating Setpoint|thermostatHeatingSetpoint
Thermostat Setpoint|Thermostat Setpoint|thermostatSetpoint
TV|TV|tV
Color Temperature|Color Temperature|colorTemperature
Garage Door Control|Garage Door Control|garageDoorControl
Estimated Time Of Arrival|Estimated Time Of Arrival|estimatedTimeOfArrival
Notification|Notification Device|notification
Thermostat Schedule|Thermostat Schedule|thermostatSchedule
Health Check|Health Check|healthCheck
Ultraviolet Index|Ultraviolet Index|ultravioletIndex
Video Camera|Video Camera|videoCamera
Video Capture|Video Capture|videoCapture
Zw Multichannel|Z-Wave Multichannel|zwMultichannel


#4

From where did you get that list?
Yes, I know that device handlers can define their own capabilities. I was interested in the standard ones. If there is no single list, how does ST expect us to know what’s out there?


(Andy Rawson) #5

Yeah, the documentation has a little note near the top that says the capabilities aren’t fully documented yet. Not sure where on the list that item is to be worked on but bugging @Jim about it may get more info on the subject.

The list is from https://graph.api.smartthings.com/api/capabilities/ you have to be logged into the ide to see it.


#6

This is very strange. What use is it to document just the capability names and not their commands/attributes?
Can anyone from SmartThings comment?


(Tim Slagle) #7

I’m not totally sure. I want to make sure you get the right answer so I am going to pull in our documentation guy @Jim.


(Jim Anderson) #8

We’ll need to look into why https://graph.api.smartthings.com/api/capabilities/ isn’t redirecting to http://docs.smartthings.com/en/latest/capabilities-reference.html, as it should.

A little background - it used to be that capabilities were documented in a simple HTML table, that just showed the capability name, attributes, and commands. We moved that to the link above, where we also have a similar “At a Glance” section that shows basic information, but also a place where we can put more descriptive information around each capability (general description, command and attribute descriptions, and example code using the capability). In the initial roll-out, we have added more information around many capabilities, but many still need more information needed. We’ve been trying to add more information to about 1-2 capabilities per week, though in all honesty we haven’t been very good at that recently as we focus on some other items.

We will make every effort to get back into regular updates in this area, and investigate why the link on the graph server isn’t redirecting as it should.

Sorry for the confusion!


#9

Thanks for the info. How does the SmartThings team find out what are the capabilities that exist? Is there some link I could access to just know the capability names, commands and attributes? Or is there some internal link you could share with me. I could also help with documentation if there is some technique you guys use.

I am working on a project that does not need example code (that might be the thing that slows down the documentation process).


(Alex) #10

Hi @Jim,

There is “Indicator” capability. It’s not mentioned in the documentation. Could you please shed some light on that?

Thanks


(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #11

Guessing it means that the Device has an indicator LED that can be turned on or off or set to automatic… Or a color.

Really sad that the API can exist without any documentation, but that’s not atypical of a lot of software companies.


(Andy Rawson) #12

Ok, so if you go into “My Device Types” on the far left of the table is an icon next to each device type, click that. This will take you to the Device Properties page and it will have Capabilities listed and next to each one is a ?, click that and you will see the attributes and commands for that capability.

Indicator 
Attributes: indicatorStatus
Commands: indicatorWhenOn, indicatorWhenOff, indicatorNever

(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #13

Helpful… But not a substitute for a natural language description of the purpose of the Capability, of course…


(Alex) #14

Still doesn’t change the fact that it’s not documented.


(John Rucker) #15

Updated list. Had to format it so I could find an undocumented capability so I thought I would just share results.


Sending commands to custom device type from SmartApp
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #16

Ummm, thanks … what’s the source of this? And what are the Attributes and Commands (and icons too) for each?


(John Rucker) #17

The source is from one of the links above. Good question on documentation on the attributes and commands. I sort of thought this list was going to phase out but when I looked at it I noticed they have added new capabilities like SamSungTV so it must still be the master list. Humm that link no longer works. Going to be the last time we get to see it I guess.


(Andy Rawson) #18

The link still works but you have to be logged in to retrieve it.


(John Rucker) #19

Humm I’m logged in the same as I was yesterday. Can’t see it. Its okay I found what I needed for now.


(Endoplasmic) #20

Here it is formatted in text (JSON parsed from the link above)

[
   {
      "name":"Illuminance Measurement",
      "displayName":"Illuminance Sensor",
      "smartAppStyleName":"illuminanceMeasurement"
   },
   {
      "name":"Temperature Measurement",
      "displayName":"Temperature Sensor",
      "smartAppStyleName":"temperatureMeasurement"
   },
   {
      "name":"Relative Humidity Measurement",
      "displayName":"Humidity Sensor",
      "smartAppStyleName":"relativeHumidityMeasurement"
   },
   {
      "name":"Switch",
      "displayName":"Switch",
      "smartAppStyleName":"switch"
   },
   {
      "name":"Battery",
      "displayName":"Battery",
      "smartAppStyleName":"battery"
   },
   {
      "name":"Contact Sensor",
      "displayName":"Contact Sensor",
      "smartAppStyleName":"contactSensor"
   },
   {
      "name":"Motion Sensor",
      "displayName":"Motion Sensor",
      "smartAppStyleName":"motionSensor"
   },
   {
      "name":"Presence Sensor",
      "displayName":"Presence Sensor",
      "smartAppStyleName":"presenceSensor"
   },
   {
      "name":"Alarm",
      "displayName":"Alarm Device",
      "smartAppStyleName":"alarm"
   },
   {
      "name":"Water Sensor",
      "displayName":"Water Sensor",
      "smartAppStyleName":"waterSensor"
   },
   {
      "name":"Polling",
      "displayName":"Polling Device",
      "smartAppStyleName":"polling"
   },
   {
      "name":"Configuration",
      "displayName":"Configuration Device",
      "smartAppStyleName":"configuration"
   },
   {
      "name":"Tone",
      "displayName":"Tone",
      "smartAppStyleName":"tone"
   },
   {
      "name":"Three Axis",
      "displayName":"Orientation Sensor",
      "smartAppStyleName":"threeAxis"
   },
   {
      "name":"Switch Level",
      "displayName":"Dimmer Switch",
      "smartAppStyleName":"switchLevel"
   },
   {
      "name":"Lock",
      "displayName":"Lock",
      "smartAppStyleName":"lock"
   },
   {
      "name":"Acceleration Sensor",
      "displayName":"Acceleration Sensor",
      "smartAppStyleName":"accelerationSensor"
   },
   {
      "name":"Refresh",
      "displayName":"Refresh",
      "smartAppStyleName":"refresh"
   },
   {
      "name":"Thermostat",
      "displayName":"Thermostat",
      "smartAppStyleName":"thermostat"
   },
   {
      "name":"Momentary",
      "displayName":"Momentary",
      "smartAppStyleName":"momentary"
   },
   {
      "name":"Image Capture",
      "displayName":"Camera",
      "smartAppStyleName":"imageCapture"
   },
   {
      "name":"Energy Meter",
      "displayName":"Energy Meter",
      "smartAppStyleName":"energyMeter"
   },
   {
      "name":"Power Meter",
      "displayName":"Power Meter",
      "smartAppStyleName":"powerMeter"
   },
   {
      "name":"Indicator",
      "displayName":"Indicator",
      "smartAppStyleName":"indicator"
   },
   {
      "name":"Valve",
      "displayName":"Valve",
      "smartAppStyleName":"valve"
   },
   {
      "name":"Location Mode",
      "displayName":"Location Mode",
      "smartAppStyleName":"locationMode"
   },
   {
      "name":"Signal Strength",
      "displayName":"Signal Strength Detector",
      "smartAppStyleName":"signalStrength"
   },
   {
      "name":"Smoke Detector",
      "displayName":"Smoke Detector",
      "smartAppStyleName":"smokeDetector"
   },
   {
      "name":"Carbon Monoxide Detector",
      "displayName":"Carbon Monoxide Detector",
      "smartAppStyleName":"carbonMonoxideDetector"
   },
   {
      "name":"Button",
      "displayName":"Button",
      "smartAppStyleName":"button"
   },
   {
      "name":"Music Player",
      "displayName":"Music Player",
      "smartAppStyleName":"musicPlayer"
   },
   {
      "name":"Lock Codes",
      "displayName":"Lock Codes",
      "smartAppStyleName":"lockCodes"
   },
   {
      "name":"Color Control",
      "displayName":"Color Control",
      "smartAppStyleName":"colorControl"
   },
   {
      "name":"Sensor",
      "displayName":"Sensor",
      "smartAppStyleName":"sensor"
   },
   {
      "name":"Actuator",
      "displayName":"Actuator",
      "smartAppStyleName":"actuator"
   },
   {
      "name":"Relay Switch",
      "displayName":"Relay Switch",
      "smartAppStyleName":"relaySwitch"
   },
   {
      "name":"Beacon",
      "displayName":"Beacon",
      "smartAppStyleName":"beacon"
   },
   {
      "name":"Sleep Sensor",
      "displayName":"Sleep Sensor",
      "smartAppStyleName":"sleepSensor"
   },
   {
      "name":"Step Sensor",
      "displayName":"Step Sensor",
      "smartAppStyleName":"stepSensor"
   },
   {
      "name":"Test Capability",
      "displayName":"Test Capability",
      "smartAppStyleName":"testCapability"
   },
   {
      "name":"Door Control",
      "displayName":"Door Control",
      "smartAppStyleName":"doorControl"
   },
   {
      "name":"Media Controller",
      "displayName":"Media Controller",
      "smartAppStyleName":"mediaController"
   },
   {
      "name":"Speech Synthesis",
      "displayName":"Speech Synthesis",
      "smartAppStyleName":"speechSynthesis"
   },
   {
      "name":"Speech Recognition",
      "displayName":"Speech Recognition",
      "smartAppStyleName":"speechRecognition"
   },
   {
      "name":"Thermostat Cooling Setpoint",
      "displayName":"Thermostat Cooling Setpoint",
      "smartAppStyleName":"thermostatCoolingSetpoint"
   },
   {
      "name":"Touch Sensor",
      "displayName":"Touch Sensor",
      "smartAppStyleName":"touchSensor"
   },
   {
      "name":"Thermostat Mode",
      "displayName":"Thermostat Mode",
      "smartAppStyleName":"thermostatMode"
   },
   {
      "name":"Thermostat Fan Mode",
      "displayName":"Thermostat Fan Mode",
      "smartAppStyleName":"thermostatFanMode"
   },
   {
      "name":"Thermostat Operating State",
      "displayName":"Thermostat Operating State",
      "smartAppStyleName":"thermostatOperatingState"
   },
   {
      "name":"Thermostat Heating Setpoint",
      "displayName":"Thermostat Heating Setpoint",
      "smartAppStyleName":"thermostatHeatingSetpoint"
   },
   {
      "name":"Thermostat Setpoint",
      "displayName":"Thermostat Setpoint",
      "smartAppStyleName":"thermostatSetpoint"
   },
   {
      "name":"TV",
      "displayName":"TV",
      "smartAppStyleName":"tV"
   },
   {
      "name":"Color Temperature",
      "displayName":"Color Temperature",
      "smartAppStyleName":"colorTemperature"
   },
   {
      "name":"Garage Door Control",
      "displayName":"Garage Door Control",
      "smartAppStyleName":"garageDoorControl"
   },
   {
      "name":"Estimated Time Of Arrival",
      "displayName":"Estimated Time Of Arrival",
      "smartAppStyleName":"estimatedTimeOfArrival"
   },
   {
      "name":"Notification",
      "displayName":"Notification Device",
      "smartAppStyleName":"notification"
   },
   {
      "name":"Thermostat Schedule",
      "displayName":"Thermostat Schedule",
      "smartAppStyleName":"thermostatSchedule"
   },
   {
      "name":"Health Check",
      "displayName":"Health Check",
      "smartAppStyleName":"healthCheck"
   },
   {
      "name":"Ultraviolet Index",
      "displayName":"Ultraviolet Index",
      "smartAppStyleName":"ultravioletIndex"
   },
   {
      "name":"Video Camera",
      "displayName":"Video Camera",
      "smartAppStyleName":"videoCamera"
   },
   {
      "name":"Video Capture",
      "displayName":"Video Capture",
      "smartAppStyleName":"videoCapture"
   },
   {
      "name":"Zw Multichannel",
      "displayName":"Z-Wave Multichannel",
      "smartAppStyleName":"zwMultichannel"
   },
   {
      "name":"Sound Sensor",
      "displayName":"Sound Sensor",
      "smartAppStyleName":"soundSensor"
   },
   {
      "name":"Consumable",
      "displayName":"Consumable",
      "smartAppStyleName":"consumable"
   },
   {
      "name":"Timed Session",
      "displayName":"Timed Session",
      "smartAppStyleName":"timedSession"
   },
   {
      "name":"Carbon Dioxide Measurement",
      "displayName":"Carbon Dioxide Measurement",
      "smartAppStyleName":"carbonDioxideMeasurement"
   },
   {
      "name":"Sound Pressure Level",
      "displayName":"Sound Pressure Level",
      "smartAppStyleName":"soundPressureLevel"
   },
   {
      "name":"pH Measurement",
      "displayName":"pH Measurement",
      "smartAppStyleName":"pHMeasurement"
   },
   {
      "name":"Tamper Alert",
      "displayName":"Tamper Alert",
      "smartAppStyleName":"tamperAlert"
   },
   {
      "name":"Voltage Measurement",
      "displayName":"Voltage Measurement",
      "smartAppStyleName":"voltageMeasurement"
   },
   {
      "name":"Window Shade",
      "displayName":"Window Shade",
      "smartAppStyleName":"windowShade"
   },
   {
      "name":"Shock Sensor",
      "displayName":"Shock Sensor",
      "smartAppStyleName":"shockSensor"
   },
   {
      "name":"Samsung TV",
      "displayName":"Samsung TV",
      "smartAppStyleName":"samsungTV"
   }
]