Skip to main content

Device Presentations and Configurations

Device Presentations#

A Device Presentation determines how the Capability Presentations of a Device are grouped and displayed in the SmartThings app. A Device Presentation is generated based on the Device Configuration (described below). If no Device Configuration is specified, the Capability Presentation will be used to determine how the Device is presented.

Device Presentations define how a Device is displayed in the three main views of the SmartThings app and follow the conventions outlined in the Capability Presentations section:

Device Configurations#

A Device Configuration contains developer-configured options for the presentation of a Device. A Device Configuration allows you to override the default view behavior specified in the Capability Presentation.

The following terms are used in Device Configurations as defined below. All terms are optional. If a term is not used in a Device Configuration, the behavior specified in the Capability Presentation is used instead:

  • States - Overrides the formatted state strings as defined in the Capability Presentation. This allows Devices to have state strings relevant to their unique integration.
  • Actions - Overrides the action values that are specified in the Capability Presentation.
  • Conditions - Overrides the conditions that are specified in the Capability Presentation.

The example below shows the Device Configuration dashboard view for a custom dimmer switch:

"dashboard": {
"states": [
{
"component": "main",
"capability": "switch",
"values": [
{
"key": "switch",
"enabledValues": [
"on"
]
}
]
},
{
"component": "main",
"capability": "switchLevel",
"values": [
{
"key": "level",
"range": [
10,
80
],
"step": 1
}
]
},
{
"component": "comp1",
"capability": "switch"
}
],
"actions": [
{
"component": "main",
"capability": "switchLevel",
"values": [
{
"key": "level",
"range": [
10,
80
],
"step": 1
}
]
},
{
"component": "main",
"capability": "switch",
"values": [
{
"key": "switch",
"enabledValues": [
"on"
]
}
]
},
{
"component": "comp1",
"capability": "switch"
}
]
}

For the same custom dimmer switch, we specify the Detail view behavior below. Notice that we use the same override values as before to ensure Capabilities are displayed in a consistent manner across all three views:

"detailView": [
{
"component": "main",
"capability": "switch",
"values": [
{
"key": "switch",
"enabledValues": [
"on"
]
}
]
},
{
"component": "main",
"capability": "switchLevel",
"values": [
{
"key": "level",
"range": [
10,
80
],
"step": 1
}
]
},
{
"component": "comp1",
"capability": "switch"
}
]

The Automation view for the same Device in the example below is similar to the Dashboard and Detail views. conditions is a new field introduced in this view, but is structured identically to the states and actions structure detailed above.

visibleCondition is used to ensure the switch only appears if the value is off. In other words, when setting up an Automation condition, we can specify whether this Capability appears in the Conditions or Actions section of the Autoomation based on the state as described in visibleCondition.

In the example below, we include both the on and off values in enabledValues. Because these are the only two valid values specified in the Capability, they are not required to be included, but are included here to illustrate usage of the field:

"automation": {
"conditions": [
{
"component": "main",
"capability": "switch",
"values": [
{
"key": "switch",
"enabledValues": [
"on",
"off"
]
}
]
},
{
"component": "main",
"capability": "switchLevel",
"values": [
{
"key": "level",
"range": [
10,
80
],
"step": 1
}
]
}
],
"actions": [
{
"component": "main",
"capability": "switchLevel",
"values": [
{
"key": "level",
"range": [
10,
80
],
"step": 1
}
]
},
{
"component": "main",
"capability": "switch",
"values": [
{
"key": "switch",
"enabledValues": [
"on",
"off"
]
}
],
"visibleCondition": {
"capability": "switch",
"component": "main",
"attribute": "switch",
"operator": "EQUALS",
"operand": "off"
}
}
]
}