Capabilities
Visit the Production Capabilities page to find a full list of production Capabilities maintained by SmartThings.
Capabilities are core to the SmartThings architecture. They abstract specific devices into their underlying functions, allowing us to retrieve the state of a Device component or control a function of the Device. Capabilities are then incorporated into Device Profiles, which encapsulate the entire functionality of a Device (read more about Device Profiles here).
A Capability definition consists of Attributes and Commands. Attributes represent the state of information or properties of the Device, while Commands allow for the control of device functions. Generally, a Command is used to control an Attribute. This will result in a state change of the controlled Attribute. Note that not all Attributes have an associated Command; Capabilities used only for monitoring do not contain Commands. For example, a thermometer may only have an Attribute responsible for monitoring the temperature of the Device with no associated Command.
Data Types
The following table contains a list of the data types associated with Command arguments and Attributes.
| Data type | Example | Description |
|---|---|---|
| string | "this is a string" | A string. A regex pattern property can be defined that restricts possible values for the string. |
| integer | 5 | A whole number. Limits can be defined to constrain the range of possible values. |
| number | 5.5 | A number that can have fractional values. Limits can be defined to constrain the range of possible values. |
| boolean | true | Either true or false |
| object | {x: 12, y: 24} | A map of name value pairs, where the values can be of different types. |
| array | ["heat", "cool"] | A list of values of a single type. |
Key Definitions
Several key definitions can be found in the definitions of Capabilities. These are defined below.
| Key | Description | Example |
|---|---|---|
| name | Name of the Capability | Acceleration Sensor |
| id | The ID of the Capability. | accelerationSensor |
| version | Integer version number (future use). Only version 1 is supported at this time. | 1 |
| status | Whether the Capability is ready or still in beta | live, proposed, or deprecated |
| attributes | A map of Attribute names and their definitions | acceleration: {...} |
| commands | A map Command names and their definitions | setAirConditionerMode: {...} |
Attributes
Attributes are used to describe the state of a Capability and store its status.
Attributes have a type, and may have a unit and one or more constraints.
In the following example, a light can be a range of
color temperatures ranging from warm to cool. The schema that defines the color temperature
attribute is JSON schema version 4.
"attributes": {
"colorTemperature": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "integer",
"minimum": 2600,
"maximum": 9000
},
"unit": {
"type": "string",
"enum": [
"K"
],
"default": "K"
}
},
"additionalProperties": false
},
"required": [
"value"
]
}
}
Commands
Commands describe the functionality of a Capability and what a Device can do. Commands can have zero or more arguments. Command arguments have types and can have constraints just as attributes do. Arguments are required by default but can be designated as being optional. In the example below, the light can be set to a value representing how warm or cool it is.
In this case, using the setColorTemperature Command to set a color temperature will
result in an updated value in the colorTemperature attribute in the Capability.
"commands": {
"setColorTemperature": {
"arguments": [
{
"name": "temperature",
"optional": false,
"schema": {
"type": "integer",
"minimum": 2600,
"maximum": 9000
}
}
]
}
}
Attribute and Command Constraints
Attributes and Command arguments can have constraints on their possible values. The SmartThings platform and APIs will reject the generation of events or execution of commands with values outside these constraints. The types of constraints available are dependent on the type of the property. The elements of array and object types can also have constraints.
String Constraints
Strings can be constrained with maxLength, pattern, and enum constraints.
maxLength
You can constrain a string to be no longer than a specified length. In this case a title attribute is limited to being no longer than 255 characters.
"title": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"maxLength": 255
}
pattern
You can constrain a string to match a regular expression. This can be particularly helpful for URLs and ISO 8601 time/date strings. In this case we have a startTime attribute that must be an ISO 8601 string:
"startTime": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "^(?:[1-9]\\d{3}-?(?:(?:0[1-9]|1[0-2])-?(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-?(?:29|30)|(?:0[13578]|1[02])-?31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-?02-?29)T(?:[01]\\d|2[0-3]):?[0-5]\\d:?[0-5]\\d(?:\\.\\d{3})?(?:Z|[+-][01]\\d(?::?[0-5]\\d)?)$"
}
enum
Enumerated values can be defined by typing the property as a string and providing a list of acceptable valid values.
In this case we have a lock attribute with the values "locked", "unlocked", and "jammed":
"lock": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": {
"locked",
"unlocked",
"jammed"
}
Integer and Number Constraints
Integer and number values can be constrained with a minimum value, maximum value, or both. In this case
we have a batteryVoltage attribute limited to between 0 and 15 volts:
"batteryVoltage": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 15
}
Non-Primitive Types
In addition to the primitive string, integer, number, and boolean types, attribute values can be defined as data structures composed of other types. Both object and array types are supported.
Object Type
Attributes can be defined as anonymous or typed object. The simplest object type is anonymous and can be set to any value.
"audioStream": {
"schema": {
"type": "object",
"properties": {
"value": {
"title": "Stream Descriptor",
"type": "object"
}
},
You can also specify what properties are valid for the object. Each property of the object can have its own type and constraints.
"energyEvent": {
"schema": {
"type": "object",
"properties": {
"value": {
"title": "Energy Event",
"type": "object",
"properties": {
"type": {
"title": "Event Type",
"type": "string",
"enum": [
"moderate",
"aggressive"
]
},
"level": {
"title": "Event Level",
"type": "integer",
"minimum": -1,
"maximum": 3
},
"start": {
"title": "Event Start Time",
"type": "string",
"pattern": "^(?:[1-9]\\d{3}-?(?:(?:0[1-9]|1[0-2])-?(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-?(?:29|30)|(?:0[13578]|1[02])-?31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-?02-?29)T(?:[01]\\d|2[0-3]):?[0-5]\\d:?[0-5]\\d(?:\\.\\d{3})?(?:Z|[+-][01]\\d(?::?[0-5]\\d)?)$"
},
"duration": {
"title": "Event Duration",
"type": "integer",
"minimum": 0
},
Array Type
Array attributes are ordered lists of a single type. Here's an example of an array attribute where the values are enumerated strings:
"supportedThermostatFanModes": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"title": "ThermostatFanMode",
"type": "string",
"enum": [
"auto",
"circulate",
"followschedule",
"on"
]
}
}
}
Production Capabilities
You can find a list of the standard production Capabilities maintained by the SmartThings development team here. You can interact with (for example, in an Automation) or include these Capabilities when developing your Device.
Next, we'll look at how Custom Capabilities allow you to create device functionality not found in the standard capabilities.