Skip to main content

Capabilities

tip

Looking for the full list of standard Capabilities maintained by SmartThings? Visit the Capabilities Reference.

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 typeExampleDescription
string"this is a string"A string. A regex pattern property can be defined that restricts possible values for the string.
integer5A whole number. Limits can be defined to constrain the range of possible values.
number5.5A number that can have fractional values. Limits can be defined to constrain the range of possible values.
booleantrueEither 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.

KeyDescriptionExample
nameName of the CapabilityAcceleration Sensor
idThe ID of the Capability.accelerationSensor
versionInteger version number (future use). Only version 1 is supported at this time.1
statusWhether the Capability is ready or still in betalive, proposed, or deprecated
attributesA map of Attribute names and their definitionsacceleration: {...}
commandsA map Command names and their definitionssetAirConditionerMode: {...}

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"
]
}
}
}

Standard Capabilities#

You can find the standard 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.