Skip to main content

Capability Presentations

tip

Looking for a detailed list of the display types used by Capability Presentations? Visit the display types reference.

A Capability Presentation defines how the SmartThings app presents the Attributes and Commands of a Capability in the user interface.

Capability Presentations are created by using an existing Capability ID and version. The Presentation describes how the Capability attributes and commands will appear in the SmartThings app, what actions and states are shown, and how conditions and actions are expressed in an Automation.

Capability Presentations control the user interface of the device in three views of the SmartThings app:

  • Dashboard view
  • Detail view
  • Automations view
What's the difference between a Device Presentation and a Capability Presentation?

A Device Presentation determines which Capabilities are displayed and how they are arranged when presented; a Capability Presentation determines how the Capability's attributes and commands are displayed within the Device Presentation.

Dashboard View​

The dashboard view is the main view in the SmartThings app. Here, users will see a list of their favorite devices and their statuses. Because the dashboard displays many devices at once, the space available to display a Capability is limited. Below, we examine the primary attributes found in the dashboard view.

State​

Use the state attribute to show the current status of a Device’s Capability. This can be a formatted string with an attribute value. For example, {{<attributeName>.value}}{{<attributeName>.unit}} may be used to display the current temperature of an attribute in a given unit of measurement.

State Alternatives​

Alternatives in the state model allow us to replace an attribute value with another string in the UI. In the example below, instead of showing the partial value, the UI will display Partially open.

Actions​

Dashboard actions allow the user to initiate a Command on a device straight from the dashboard view.

Dashboard actions have a display type; valid display types include:

  • pushButton
  • toggleSwitch
  • switch
  • standbyPowerSwitch
  • statelessPowerToggle
  • playPause
  • playStop

Dashboard Example​

The dashboard example below incorporates the concepts described above into the garage door capability we created in the Custom Capabilities section. The states section displays the status of the door and the actions section displays a toggle button for controlling the door. Note how it maps the "on" and "off" states of the toggle button to setDoor("open") and setDoor("closed") commands that are sent when the button is pushed in each state. The alternatives section specifies the strings that are displayed in place of the actual attribute values, for example "Partially open" rather that "partial".

"dashboard": {
  "states": [
    {
      "label": "{{door.value}}",
      "alternatives": [
        {
          "key": "closed",
          "value": "Closed",
          "type": "inactive"
        },
        {
          "key": "open",
          "value": "Open",
          "type": "active"
        },
        {
          "key": "opening",
          "value": "Opening",
          "type": "active"
        },
        {
          "key": "closing",
          "value": "Closing",
          "type": "active"
        },
        {
          "key": "partial",
          "value": "Partially open",
          "type": "active"
        }
      ]
    }
  ],
  "actions": [
    {
      "displayType": "toggleSwitch",
      "toggleSwitch": {
        "command": {
          "name": "setDoor",
          "on": "open",
          "off": "closed",
          "argumentType": "string"
        },
        "state": {
          "value": "door.value",
          "on": "open",
          "off": "closed",
          "valueType": "string"
        }
      }
    }
  ]
}

Detail View​

The detail view is displayed when a user taps a Device from the dashboard. The detail view requires a label and a displayType. Available display types include:

  • toggleSwitch
  • standbyPowerSwitch
  • switch
  • slider
  • pushButton
  • playPause
  • playStop
  • list
  • textField
  • numberField
  • stepper
  • state
info

The SmartThings platform follows certain ordering rules for displaying Capabilities in the detail view. Capabilities are rendered in the detail view as follows:

  • Top: switches, Device status, and tip cards are automatically placed at the top.
  • Middle: the card ordering follows the UI metadata. This order can be manipulated by the Device developer.
  • Bottom: battery status.

Detail View Example​

The example below shows the garage door capability as a labeled drop-down list control. Just like the capability itself, the command has a smaller set of alternatives than the attribute. If desired you can further limit the command alternatives in the presentation, which will control what the user can do in the detail view but not in API calls.

"detailView": [
  {
    "label": "Garage Door Status",
    "displayType": "list",
    "list": {
      "command": {
        "name": "setDoor",
        "alternatives": [
          {
            "key": "closed",
            "value": "Closed",
            "type": "inactive"
          },
          {
            "key": "open",
            "value": "Open",
            "type": "active"
          }
        ],
        "argumentType": "string"
      },
      "state": {
        "value": "door.value",
        "valueType": "string",
        "alternatives": [
          {
            "key": "closed",
            "value": "Closed",
            "type": "inactive"
          },
          {
            "key": "open",
            "value": "Open",
            "type": "active"
          },
          {
            "key": "opening",
            "value": "Opening...",
            "type": "active"
          },
          {
            "key": "closing",
            "value": "Closing...",
            "type": "active"
          },
          {
            "key": "partial",
            "value": "Partially open",
            "type": "active"
          }
        ]
      }
    }
  }
]

Automation View​

The automation section of a Capability Presentation describes how a Capability can be used in an Automation.

Conditions​

A Condition is an evaluation used as a trigger for an action, such as an if statement (read more about Conditions here). This section of the automation view determines how the user is able to choose a value for the Automation to be triggered.

The condition under which an Automation for this Capability is triggered can be rendered with the following display types:

  • slider
  • list
  • numberField
  • textField

Actions​

The action section of the Presentation defines how the user is able to configure the effect (or action) of the Automation once the condition is triggered.

The action that an Automation can take when triggered can be rendered with the following display types:

  • slider
  • list
  • numberField
  • textField

Automation Example​

The automation view example below allows Automations based on volume condition and play status. This will allow you to set up an Automation with a volume condition, while the actions in the automation view allow the device to play or pause music in an Automation.

"automation": {
    "conditions": [
        {
            "label": "Volume",
            "displayType": "slider",
            "slider": {
                "range": [
                    0,
                    11
                ],
                "step": 1,
                "value": "volume.value"
            }
        }
    ],
    "actions": [
        {
            "label": "Player actions",
            "displayType": "list",
            "list": {
                "command": "setPlaybackStatus",
                "alternatives": [
                    {
                        "key": "playing",
                        "value": "Playing"
                    },
                    {
                        "key": "paused",
                        "value": "Paused"
                    }
                ]
            }
        }
    ]
}

In this example, you cannot set the volume of the device in an automation. If you wanted to enable this functionality, add an entry for it under actions next to setPlaybackStatus.

Create and Upload your Capability Presentation​

Here's a complete capability presentation file for our custom garage door capability:

{
  "dashboard": {
    "states": [
      {
        "label": "{{door.value}}",
        "alternatives": [
          {
            "key": "closed",
            "value": "Closed",
            "type": "inactive"
          },
          {
            "key": "open",
            "value": "Open",
            "type": "active"
          },
          {
            "key": "opening",
            "value": "Opening",
            "type": "active"
          },
          {
            "key": "closing",
            "value": "Closing",
            "type": "active"
          },
          {
            "key": "partial",
            "value": "Partially open",
            "type": "active"
          },
          {
            "key": "jammed",
            "value": "Jammed or unresponsive",
            "type": "active"
          }
        ]
      }
    ],
    "actions": [
      {
        "displayType": "toggleSwitch",
        "toggleSwitch": {
          "command": {
            "name": "setDoor",
            "on": "open",
            "off": "closed",
            "argumentType": "string"
          },
          "state": {
            "value": "door.value",
            "on": "open",
            "off": "closed",
            "valueType": "string"
          }
        }
      }
    ],
    "basicPlus": []
  },
  "detailView": [
    {
      "label": "Garage Door Status",
      "displayType": "list",
      "list": {
        "command": {
          "name": "setDoor",
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            }
          ],
          "argumentType": "string"
        },
        "state": {
          "value": "door.value",
          "valueType": "string",
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            },
            {
              "key": "opening",
              "value": "Opening...",
              "type": "active"
            },
            {
              "key": "closing",
              "value": "Closing...",
              "type": "active"
            },
            {
              "key": "partial",
              "value": "Partially open",
              "type": "active"
            },
            {
              "key": "jammed",
              "value": "Jammed or unresponsive",
              "type": "active"
            }
          ]
        }
      },
      "state": null
    }
  ],
  "automation": {
    "conditions": [
      {
        "label": "Garage Door Status",
        "displayType": "list",
        "list": {
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            },
            {
              "key": "partial",
              "value": "Jammed or unresponsive",
              "type": "active"
            }
          ],
          "value": "door.value",
          "valueType": "string"
        }
      }
    ],
    "actions": [
      {
        "label": "Garage Door",
        "displayType": "list",
        "list": {
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            }
          ]
        }
      }
    ]
  },
  "id": "perfectlife6617.customGarageDoor",
  "version": 1
}

Upload it to the SmartThings platform with the SmartThings CLI command below, where presentation.json is the above example file:

smartthings capabilities:presentation:create perfectlife6617.customGarageDoor 1 -i presentation.json

Next, we'll look at how Capability Translations allow you to define labels and values in multiple languages and have them automatically displayed based on the phone's settings