Devices with custom Capabilities are not supported by the Works with SmartThings certification program at this time.
Not finding a standard Capability that captures your Device functionality? Custom Capabilities allow you to define your own Capabilities. A custom Capability consists of a namespace and a Capability name to uniquely identify it.
Custom Capabilities, similar to the standard Capabilities, contain Attributes and Commands. The Capability is accessed by referencing
namespace.capabilityName. This combination is referred to as the
capabilityId. An example capability ID may look like
For additional information about Namespaces, see Namespaces
Standard capabilities are contained under the
smartthings namespace. However, when accessing a standard Capability, no namespace is required to be given.
When creating a custom Capability, consider what statuses the Capability can have (Attributes) and what it can do (Commands). The example below is a custom garage door capability that provides status and control of the door:
This capability follows a typical pattern of defining an attribute (
door in this case) and a
"setter" command that modifies that attribute. Note that the command argument has different constraints than the attribute.
That's because the device only accepts commands to open and close the door, but the door can be in a number of other
states as it is opening and closing. With this definition the API will accept only
closed arguments for
setDoor command, but will allow any of the other attribute values in the device state as the door operates.
We could have chosen to define separate
close commands instead of, or in addition to the setter, but this
approach works well with attributes that have many possible values.
Create your custom capability using the SmartThings CLI,
capability.json is the above file:
You can also create a capability interactively by leaving off the input file:
Custom Capabilities are used the same way standard Capabilities are used, and are assigned to Devices via Device Profiles. There are no special permissions needed to use a custom Capability on a Device Profile. Anyone who knows the
capabilityId and version has access to view details about the Capability. However, only the namespace owner is able to create or modify Capabilities under that namespace.
When using the Developer Workspace to define a Custom Capability, you will only be able to see Capabilities created under your own namespace or under the standard SmartThings namespace.
For example, here's a Device Profile that uses our custom garage door capability together with a couple of standard capabilities:
Next, we'll look at how Capability Presentations allow you to control how your Capability is shown in the SmartThings mobile app.