Custom Capabilities

caution

Devices with custom Capabilities are not supported by the Works with SmartThings (WWST) 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.

Capability Namespaces

A namespace is an identifier used to group a developer’s Capabilities or Preferences together. When you create a custom Capability or a Device Preference, it is created under your namespace. A unique namespace is created for you when you create your first custom Capability or Preference for your developer account; only one namespace per account is generated. A namespace may look something like perfectlife6617.

Custom Capabilities, similar to 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 perfectlife6617.customGarageDoor.

note

Standard capabilities are contained under the smartthings namespace. However, when accessing a standard Capability, no namespace is required to be given.

Create a Custom Capability

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:

{
  "name": "Custom Garage Door",
  "attributes": {
    "door": {
      "schema": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "enum": [
              "open",
              "opening",
              "closed",
              "closing",
              "partial"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "value"
        ]
      },
      "setter": "setDoor",
      "enumCommands": []
    }
  },
  "commands": {
    "setDoor": {
      "name": "setDoor",
      "arguments": [
        {
          "name": "door",
          "optional": false,
          "schema": {
            "type": "string",
            "enum": [
              "open",
              "closed"
            ]
          }
        }
      ]
    }
  }
}

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 open and closed arguments for the 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 open and 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, where capability.json is the above file:

smartthings capabilities:create -i capability.json

You can also create a capability interactively by leaving off the input file:

smartthings capabilities:create

Add a Capability Presentation

In order for your Custom Capability to properly function, you will need to create a Capability Presentation and associate it with your Custom Capability.

Visit the Capability Presentation documentation to learn more about creating a Capability Presentation and associating it with your Custom Capability.

After creating your Capability Presentation, you can upload your Capability Presentation and associate it with your Custom Capability using the following command in the CLI:

smartthings capabilities:presentation:create <yourNameSpace.myCustomCapability> 1 -i <myPresentation>.json

Use your Custom Capability

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.

info

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:

{
  "name": "Custom Garage Door",
  "components": [
    {
      "id": "main",
      "capabilities": [
        {
          "id": "perfectlife6617.customGarageDoor",
          "version": 1
        },
        {
          "id": "refresh",
          "version": 1
        },
        {
          "id": "healthCheck",
          "version": 1
        }
      ],
      "categories": []
    }
  ],
  "metadata": {
    "ocfDeviceType": "oic.d.garagedoor"
  }
}

tip

A Device's custom Capabilities can be used in Rules, depending on the commands or attributes configured for them. A custom Capability must have at least one attribute or one command.

Next, we'll look at how Capability Presentations allow you to control how your Capability is shown in the SmartThings mobile app.