Working with Devices

On the SmartThings platform a device is represented in terms of device abstractions such as capabilities and components. This section explains these device abstractions.

Capabilities

A device is a set of capabilities. Capabilities are composed of commands that can be issued to the device, and attributes that can be read from the device. For example, a lock device supports two commands:

  • lock and
  • unlock

and one attribute:

  • lock

Component

Devices can have components. For example, a refrigerator that is built with two components: the main cooling section and the freezer. Each component can be controlled independently.

NOTE

Support will be restricted to one “main” component” until further notice.


Device profile

Each device is associated with a device profile. A device profile is a description that contains the details of the device including the device’s components and its capabilities. The SmartThings platform knows how to interact with the device from the device profile.

Devices can have more than one variation, for example, due to firmware difference. Each such variation will have its own separate device profile.

Here is an example of a JSON body sent with a POST request to create a device profile for LIFX color bulb:

{
  "name": "lifx-color-bulb",
  "components": [
    {
      "id": "main",
      "capabilities": [
        { "id": "colorControl"},
        { "id": "colorTemperature"},
        { "id": "switch" },
        { "id": "switchLevel"},
        { "id": "refresh"}
      ]
    }
  ],
  "metadata": {
    "dthName": "LIFX Color Bulb",
    "dthNamespace": "smartthings"
  }
}

Accessing device information

Information on the devices that are integrated into SmartThings Cloud can be accessed with the Devices API.

List devices

Below is an example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices path.

{
  "items": [
    {
      "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
      "name": "Kitchen fridge",
      "deviceManufacturerCode": "010F-0B01-2002",
      "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
      "components": [
        {
          "id": "main"
        }
      ],
      "app": {
        "installedAppId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
        "externalId": "Th13390",
        "profile": {
          "id": "user@example.com/thermostat.model1"
        }
      },
      "dth": {
      },
      "type": "ENDPOINT_APP"
    }
  ],
  "_links": {
    "next": {
      "href": "https://..."
    },
    "previous": {
      "href": "https://..."
    }
  }
}

Get a device’s description

Here is an example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId} path.

{
  "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
  "name": "color.light.100x",
  "label": "color.light.100x",
  "deviceManufacturerCode": "010F-0B01-2002",
  "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
  "components": [
    {
      "id": "main",
      "capabilities": [
        {
          "id": "switch"
        }
      ]
    }
  ],
  "app": {
    "installedAppId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
    "externalId": "Th13390",
    "profile": {
      "id": "user@example.com/thermostat.model1"
    }
  },
  "dth": {

  },
  "type": "ENDPOINT_APP"
}

Get the full state of a device

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/states path.

{
  "main": {
    "switch": {
      "value": "on"
    },
    "temperature": {
      "value": 10,
      "unit": "°C"
    }
  }
}

List the components of a device

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components path.

{
  "items": [
    {
      "id": "main",
      "capabilities": [
        {
          "id": "switch"
        }
      ]
    }
  ],
  "_links": {
    "next": {
      "href": "https://..."
    },
    "previous": {
      "href": "https://..."
    }
  }
}

Get a component’s details

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components/{componentId} path.

{
  "id": "main",
  "capabilities": [
    {
      "id": "switch"
    }
  ]
}

Get a component’s state

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components/{componentId}/states path.

{
  "switch": {
    "value": "on"
  }
}

Get the state of a capability

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/states path.

{
  "switch": {
    "value": "on"
  }
}

Example with Postman

You can use Postman app for accessing and updating your devices using SmartThings API.

In the example below we will use Postman to get a list of all the devices for a user account, and actuate and update a device. Make sure that you have at least one device in your SmartThings user account and follow the steps below:

Install Postman

Install the Postman app and create a Postman account for yourself (a free account is sufficient for this example).

Obtain SmartThings personal access token

  • If you don’t have it already, open your Samsung account.

  • Next, get a personal access token for calling the SmartThings API. You will use this as a bearer token in the Postman app.

Go to the personal access tokens page and click on the Generate new token on top-right.

Create a token

Give a name for your token. Select Devices to authorize the scope of the token for the devices. Click on Generate Token in the bottom right.

Select devices

This will generate a token, as shown below (token display hidden in the pictures below). Copy the token and save it somewhere safe and private.

Display token

Get a list of devices

  • In the Postman window, select GET and type in the SmartThings API https://api.smartthings.com/v1/devices.

  • In the Authorization section, for the TYPE field, select Bearer Token from the drop-down menu list. This will display the Token form field on the right. Copy and paste here the personal access token that you obtained from above.

Get devices list

  • Click Send in the top right.

The response from SmartThings Cloud will be seen in the bottom half of the Postman window. SmartThings Cloud will respond with a JSON body containing a list of devices, as shown in the picture below.

ST response devices list

Get the description of a specific device

For any device in the above list of devices, using the deviceId of that device, we can get a full description of that device.

  • For any device of your choice from the above list in the JSON response body, copy the value of the deviceId.

  • In the Postman window, select GET and type in the SmartThings API https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID} as shown below.

Get device description

  • Click Send in the top right. You will get a detailed description of the device in the same response window of the Postman app.

Execute commands on the device

To actuate a device you need to send a POST request to the https://api.smartthings.com/v1/devices/{deviceId}/commands API with the device command in the body of the request.

  • In the Postman window, select POST and type in the SmartThings API https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID}/commands.

  • In the Body section of the Postman request window, select raw option, and JSON (application/json) from the pull down menu, as shown below.

Execute ON device command

  • Type in the JSON command body. In this example, the below device command to turn ON a Sylvania Smart bulb is issued:
{
"commands": [
    {
        "component": "main",
        "capability": "switch",
        "command": "on"
    }
]
}
  • Click Send in the top right. This will turn ON the Sylvania bulb.

Update a device

You can change the properties of a device with the PUT request to the SmartThings API https://api.smartthings.com/v1/devices/{deviceId}.

  • In the Postman window, select PUT and type in the SmartThings API https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID}.

  • In the Body section of the Postman request window, select raw option, and JSON (application/json) from the pull down menu, as shown below.

Update device

  • Type in the JSON command body. In this example, the label property of the Sylvania bulb is changed to New Bulb.
{
    "label": "NEW Bulb"
}
  • Click Send in the top right. This will change the label of the Sylvania bulb. This is confirmed by pull-down refreshing the My Home screen of the SmartThings app.