Capabilities Reference

Capabilities are core to the SmartThings architecture.
They allow us to abstract specific devices into their underlying capabilities.

An application interacts with devices based on their capabilities, so once we understand the capabilities that are needed by a SmartApp, and the capabilities that are provided by a device, we can understand which devices (based on the Device’s declared capabilities) are eligible for use within a specific SmartApp.

Capabilities themselves are decomposed into both Commands and Attributes.
Commands represent ways in which you can control or actuate the device, whereas Attributes represent state information or properties of the device.

Capabilities are created and maintained by the SmartThings development team.

This page serves as a reference for the supported capabilities.

Data types

Before we present the Capabilities, it’s worth covering the various data types associated with Attributes and Commands.
Note that these data types are guidelines as to how actual values can be represented.
In most cases, the SmartThings platform contains the implementation logic and defines the actual objects for these data types.
Below is a table outlining the possible data types and what they mean.

Data type

Example

Description

STRING

“this is a string”

Represents character strings

NUMBER

5, 10.6

The Number data type is a guideline indicating that a number should be expected, and not a specific type. Device Handlers contain the implementation of what kind of number object is actually returned.

VECTOR3

(x, y, z)

This data type is a representation of x,y,z coordinates in space. Device Handlers contain the implementation of the actual data structure, but it is usually as a Map: [x: 0, y: 0, z: 0].

ENUM

“one”, “two”, “three”

The Enum data type is a static set of predefined String values that an Attribute can have, or that a Command can accept as an argument.

DYNAMIC_ENUM

“any”, “value”

Much like the Enum data type, Dynamic Enum is a set of String values. However, the set is not static or predefined.

COLOR_MAP

[hue: 50, saturation: 60]

The Color Map is a Map specifically for the use of color control. As such, the Map should contain a Hue and a Saturation value.

JSON_OBJECT

A standard JSON object. Device Handlers contain the implementation and thus should be consulted when looking for the JSON object structure.

DATE

A Date, usually represented as a java.util.Date object.

Key Definitions

Key

Description

Example

name

Name of the Capability

Acceleration Sensor

status

Whether the Capability is ready or still in beta

live or proposed

attributes

A list of Attributes and their key-value pairs supported for the Capability

acceleration

commands

A list of Commands and their key-value pairs supported for the Capability

setAirConditionerMode

id

The ID of the Capability.

airConditionerMode

Capabilities

Acceleration Sensor

The Acceleration Sensor capability allows for acceleration detection. Some use cases for SmartApps using this capability would be detecting if a washing machine is vibrating, or if a case has moved (particularly useful for knowing if a weapon case has been moved).