Device profile

A device profile contains the components, capabilities, and metadata (ID, name, ownership, etc.) that define a SmartThings device. Capabilities define the features of the device, and capabilities are grouped into components.

The following device integrations require a device profile:

You can create a device profile in Developer Workspace and associate it with an integration. You can then communicate to the device by referring to its device profile.

Components

A device profile must have at least one component. A component called main is automatically created for each new device profile. You will thus see the main component referenced throughout this documentation.

Capabilities

Each component must have at least one capability. Capabilities specify the features of the device, as defined in the capabilities reference. These may consist of attributes (state information or properties of the device) and commands (ways to control or actuate the device).

Let's take a look at the switch capability.

Attributes

The switch capability has a value attribute, indicating that it can store the "switch" status of the device (e.g. "on" or "off").

Here is an abridged snippet of the Switch capability specification. It contains a switch attribute containing a property called value.

name: Switch
attributes:
  switch:
    schema:
      type: object
      properties:
        value: ...
      required: ["value"]
    type: ENUM
    values:
      - 'off'
      - 'on'

Commands

We also see the commands available on the device. Here the Switch capability specifies two commands, on and off. These indicate that the device can respond to commands to turn on or turn off.

name: Switch
...
commands:
  'off':
    arguments: []
  'on':
    arguments: []

Not all capabilities have commands. For example, Temperature Measurement has an attribute called temperature with two resource properties (value, unit). This indicates it is capable of storing a temperature value as well as the temperature unit (e.g. 75, °F). In this capability, commands is an empty object.

name: Temperature Measurement
status: live
attributes:
  temperature:
    schema:
      type: object
      additionalProperties: false
      properties:
        value:
          $ref: TemperatureValue
        unit:
          $ref: TemperatureUnit
      required: ["value", "unit"]
...
commands: {}

Each capability specification may provide additional information, such as definitions for acceptable values, constraints such as number ranges, and more.

Creating a device profile

You can add a new device profile on Developer Workspace. If relevant to the integration type, you will see the option in the project's Develop menu.

Set your device profile information

  • Device Profile Name is used in the SmartThings app and should be easily identifiable by the end user.
  • Device Type determines the device's icon and default UI layout in the SmartThings app.
  • Vendor ID is an alphanumeric identifier for your device.

Define components and capabilities

  • Click + ADD CAPABILITY to display a list of available SmartThings capabilities. The attributes and commands associated with each capability are also shown.

    • Select a capability from the list to add it to the main component.
    • Repeat this process for each capability used by your device. Click NEXT when finished.
  • Assign a capability to the Dashboard State and Dashboard Action. These selections generate a default UI for the device in the SmartThings app.

Click CREATE DEVICE PROFILE to add this device profile to Developer Workspace.

You can now associate your device profile with a device integration.

See also