Device Basics

Devices are physical products that connect to and operate with the SmartThings Platform.

A Device Profile defines the features and functionality of a Device. These features are broken down into individual components called Capabilities. Capability Presentations then describe how a Capability is displayed in a SmartThings client, such as in the SmartThings app.

SmartThings provides a list of standard Capabilities to quickly get you started with your Device integration. Custom Capabilities allow you to create your own Capability and define the unique features of your Device.

A Device Preference is a configuration that enables users to customize the behavior of their Device. You may wish to implement Device Preferences when integrating your Device with SmartThings to provide users with a way to customize their Device's behavior.

Device Types#

The SmartThings Platform supports the following Device integration types:

Direct Connected Devices - Connect your Device directly to the SmartThings Platform via WiFi.
Cloud Connected Devices - Connect Devices on your existing cloud to the SmartThings Platform.
Hub Connected Devices - Connect Matter, Zigbee, Z-Wave, and LAN Devices to SmartThings-compatible Hubs.
Mobile Connected Devices - Bluetooth Devices connected to a Samsung Galaxy device can be controlled in the SmartThings app. SmartThings Find enables compatible Devices to quickly and easily be located using the SmartThings app.

Namespaces#

A namespace is an identifier used to group a developer’s Capabilities or Preferences together. When you create a custom Capability or a Device Preference, it is created under your namespace. A unique namespace is created for you when you create your first custom Capability or Preference for your developer account; only one namespace per account is generated. A namespace may look something like perfectlife6617.

Development Workflow#

To integrate a Device with SmartThings Platform:

Pick the Device integration type that best suits your needs. Each Device-type documentation section gives you a more in-depth look at the integration to help you choose the correct integration.
Build your Device integration. The SmartThings SDKs on our GitHub page contain example Device integrations and tools to help you get started.
Test your Device.
Publish your Device to make it available on the SmartThings app.

Manage Devices With the Devices API#

Interact with the Devices API to access Devices integrated with the SmartThings Platform. The Devices API allows you to control Devices connected to the SmartThings Platform, access Device metadata, and access Device states.

note

You will need a Personal Access Token (PAT) with the appropriate scopes to interact with the Devices API.

Example Payload Using Postman#

This example uses the Postman app to send a GET request to https://api.smartthings.com/v1/devices/<deviceID> for a SmartThings motion sensor.

Begin by creating a new GET request in Postman.
Enter the request URL: https://api.smartthings.com/v1/devices/<deviceID> where <deviceID> is the Device ID of the Device you want to retrieve info for.
In the Authorization tab of your GET request in Postman, select Bearer Token as your authorization type. Enter your PAT in the Token field.
tip
Use variables in Postman to keep your PAT secure and to easily authorize future API requests made from Postman.
Click Send in Postman. Below is the payload from the GET request:

{
    "deviceId": "<deviceID>",
    "name": "SmartThings Motion Sensor",
    "label": "Motion Sensor",
    "manufacturerName": "SmartThings",
    "presentationId": "SmartThings-smartthings-SmartSense_Motion_Sensor",
    "deviceManufacturerCode": "SmartThings",
    "locationId": "<locationID>",
    "roomId": "<roomID>",
    "deviceTypeId": "<deviceTypeId>",
    "deviceTypeName": "SmartSense Motion Sensor",
    "deviceNetworkType": "ZIGBEE",
    "components": [
        {
            "id": "main",
            "label": "Motion Sensor",
            "capabilities": [
                {
                    "id": "temperatureMeasurement",
                    "version": 1
                },
                {
                    "id": "battery",
                    "version": 1
                },
                {
                    "id": "motionSensor",
                    "version": 1
                },
                {
                    "id": "configuration",
                    "version": 1
                },
                {
                    "id": "refresh",
                    "version": 1
                },
                {
                    "id": "sensor",
                    "version": 1
                },
                {
                    "id": "healthCheck",
                    "version": 1
                },
                {
                    "id": "firmwareUpdate",
                    "version": 1
                }
            ],
            "categories": [
                {
                    "name": "MotionSensor",
                    "categoryType": "manufacturer"
                }
            ]
        }
    ],
    "parentDeviceId": "<deviceID>",
    "dth": {
        "completedSetup": true,
        "deviceNetworkType": "ZIGBEE",
        "deviceTypeId": "<deviceTypeId>",
        "deviceTypeName": "SmartSense Motion Sensor",
        "executingLocally": true,
        "hubId": "<hubID>",
        "networkSecurityLevel": "UNKNOWN"
    },
    "type": "DTH",
    "restrictionTier": 0
}

Since this motion sensor operates on the Zigbee network, the parentDeviceId field tells us what Device this motion sensor is associated with (a GET request to this parent device ID tells us this parent Device is a SmartThings v3 Hub).

Notice the Components listed for this Device. These Components help make up the Device Profile associated with this motion sensor. In the next sections, we look at Device Profiles, Capabilities, and Device Configurations and Presentations.