Custom Capabilities

caution

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.

Capability Namespaces#

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 perfectlife6617.customGarageDoor.

tip

For additional information about Namespaces, see Namespaces

note

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

Creating Your 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

Using 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.

In order to use custom Capabilities in SmartThings app Routines, the Capability must include a valid configuration in its presentation's Automation View (conditions and/or actions).

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