Device Preferences
Click here to jump to the list of standard Device Preferences.
A Device Preference is a configuration that enables users to customize the behavior of their device. A Device Preference is typically set to provide users with a way to tweak their device, and may optionally include a default value. Users can change a Device Preference to customize their device by tapping their device in the SmartThings app, tapping the overflow (3-dot) menu icon, and tapping settings.
Device Preferences may be defined one of two ways:
- Explicitly, similar to Custom Capabilities, as a standalone entity
- Embedded directly into the Device Profile of the device
Explicit Device Preferences
Explicit Device Preferences allow users to author a single Preference for use by many devices.
Device Preferences defined explicitly will always be namespaced under the author's personal Namespace. Device Preferences that are defined this way are not versioned, and Device Profiles that integrate these Preferences do not get updated if the Preference is updated - the Profile will always have the same version of the Device Preference it had when it was added.
In order to include Explicit Device Preferences for use with a device you will need to tag the profiles that need the Preference as using it. This is done within each profile YAML file in the driver package. Here is a simple profile example using one of these Preferences:
name: preference-profile
components:
- id: main
capabilities:
- id: temperatureMeasurement
version: 1
preferences:
- preferenceId: tempOffset
explicit: true
For common use cases, SmartThings has developed a number of standard Device Preferences that may be integrated into devices. The current set of Standard Device Preferences may be found here.
Standard Device Preferences are contained under the smartthings
namespace. However, when accessing a standard Preference, no namespace is required to be given. Device Preferences authored by users will use the namespace owned by the user.
Embedded Device Preferences
To simplify the process of creating unique Preferences relevant only for a specific model of a device, a Device Preference may be defined directly within a Device Profile.
Embedded Device Preferences are unique to an individual Device Profile. They are defined directly in the Device Profile of the device that will be using the Preference. These Preferences and are not versioned, shareable, or update-able; the Preference exists only within the Device Profile. The Preference also includes additional information about the type and limits of the Preference.
Below is an example profile YAML file using an Embedded Preference:
name: preference-profile
components:
- id: main
capabilities:
- id: switch
version: 1
- id: battery
version: 1
categories:
- name: RemoteController
preferences:
- title: "IP Address"
name: ipAddress
description: "IP address of the Pi-Hole"
required: true
preferenceType: string
definition:
minLength: 7
maxLength: 15
stringType: text
default: localhost
The preferenceId
(and thus what you will use to reference the Preference from the driver) will be the name you define in the Preference definition.
Device Preference Value Types
Visit the Device Preferences Reference section for a list of Preferences and their types.
A Device Preference's value can be one of five types:
- Boolean
- Number
- Integer
- String
- Enumeration
All Device Preferences must have at minimum three required fields:
-
title
: The Device Preference Title must conform to Custom Capability naming conventions. -
preferenceType
: This field is a constant based on the type of Device Preference. Must be one of:boolean
,number
,integer
,string
, orenumeration
-
definition
: This block is required, but may be empty if no further customization is required.
Optional fields that apply to all Preference types include:
-
description
: Describes the Device Preference. -
required
: A Boolean value that represents whether this Preference must be set. Default:false
-
definition.default
: The default value for this Preference if the user does not set the Preference.
Boolean Preference
{
"title": "string",
"description": "string",
"required": "boolean",
"preferenceType": "boolean",
"definition": {
"default": "true" or "false"
}
}
Boolean Preferences must have a preferenceType
of boolean
.
Boolean Preferences must have a definition
block, but may be empty if default
does not need to be set.
Number Preference
{
"title": "string",
"description": "string",
"required": "boolean",
"preferenceType": "number",
"definition": {
"minimum": "a number",
"maximum": "a number",
"default": "a number"
}
}
Number Preferences must have a preferenceType
of number
.
Number Preferences may optionally have a minimum
and maximum
number value, that define the lower and upper bound
constraint this number may be set to.
Integer Preference
{
"title": "string",
"description": "string",
"required": "boolean",
"preferenceType": "integer",
"definition": {
"minimum": "an integer",
"maximum": "an integer",
"default": "an integer"
}
}
Integer Preferences must have a preferenceType
of integer
.
Replace "integer"
with your desired integer value. Integer Preferences may optionally define a minimum
and maximum
number value, that define the lower and upper bound
constraint this integer may be set to.