Device Profile

A device profile specifies the components and capabilities used by a device. It allows developers to communicate to SmartThings devices by simply referring to their device profile.

We will see below how named components help refer to particular capabilities and how capabilities define the features of the device.

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 simple capability called switch.

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. We leave it to you to explore the capabilities available on the SmartThings platform.