Device Preferences

tip

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:

1. Explicitly, similar to Custom Capabilities, as a standalone entity
2. 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.

note

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

tip

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, or enumeration

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

String Preference