Skip to content

SmartThings Integration

We provide the following capabilities to interact with SmartThings:

  • On/Off
  • Percentage (light)
  • Color Temperature (light)
  • Fan Speed (fan)

Prerequisites

Upload Corresponding Information Model

Before using your connector, please upload a corresponding information model with Integration Schema filled in to the Admin Site.

  • No device will be shown in the SmartThings app if there is no information model on the Admin Site.
  • Make sure the content in your information model is correct. If your information model is incorrect, you cannot discover your device. For more details about the content of information models, you can refer to Using Information Models.
  • We strongly suggest that you change the nickname for your device, not using a general name or device type as the device name.
  • For more details about uploading information models to the Admin site, you can refer to Managing Information Models.

Create SmartThings Account and Enroll Your Company

Please create an account and login at Developer Center.

Once you've logged in, please enroll your organization for project distribution.

Ask Exosite to Provide the Needed Info

You will need Exosite to provide the ExoHome's client ID and client secret to setup your project.

Step 1: Register New Schema App

First, you need to create a schema cloud connector for your devices.

  1. Go to Schema Cloud Connector

  2. Click "Register New Schema App"

    Please choose the correct organization (on the top right corner) to create your schema cloud connector.

  3. Choose "WebHook Endpoint" and click "Next"

  4. Schema App Display Name: Fill in your desired connector name that is friendly to the end user

  5. Target URL: https://YOUR-DOMAIN-NAME.apps.exosite.io/api:1/smartthings
  6. Client ID: Fill in the client id provided by Exosite
  7. Client Secret: Fill in client secret provided by Exosite
  8. OAuth URL: https://YOUR-DOMAIN-NAME.apps.exosite.io/oauth2/authorize/smartthings
  9. OAuth Scope: Fill in "profile"
  10. Token Refresh URL: https://YOUR-DOMAIN-NAME.apps.exosite.io/oauth2/token/smartthings
  11. Alert Notification Email: Fill in your desired email contact
  12. Click "Register Schema App" and copy the Client ID and Client Secret shown afterwards. Please provide the copied information to Exosite.

Step 2: Create Device Profile

After a schema app is registered, you need to define your device and its features by adding device profile. Go to Device Profile Builder, or simply expand the indicator "4 Create Device Profile" on the right of the Schema app builder page. ExoHome supports various combinations of fan and light capabilities. If your device includes multiple fan or light components, or uses custom capabilities instead of the default SmartThings ones, refer to the customization examples below.

Information model for the duplicate capabilities

  1. If the device profile includes multiple fans, lights, switches, or any combination of these capabilities, you need to add the corresponding component keys in the information model.
  2. If the device profile contains only a single fan, a single light, or a fan with a light, the component key is NOT required in the information model.

Single Feature Device (e.g. Fan)

  1. Click "Add new Device Profile".
  2. Name this profile and click "Edit capabilities".
  3. Search switch and fan speed in Capability Library and add them to the main component.
  4. Hit "Save and Close" and go back to profile details.
  5. On Dashboard View, choose fan for "Profile icon" and Main --> Switch to both "State" and "Action" then click "Create Profile".
  6. Copy the Device Profile ID which needs to be placed in the information model's deviceProfileId field.

3-speed Fan

For fan capability, SmartThings supports 4-speed fan as default. If your device is a 3-speed fan, please follow the steps below to customize the settings.

  1. Follow the steps 1 to 5 in Fan section above.
  2. Click the ellipses(…) of the device profile you just created and choose "Download file".

  3. Edit device profile json file. In "detailView", "automation", and "action" section's fanSpeed capability, add fanspeed.value and range as below:

    {
  "key": "fanSpeed.value",
  "range": [
    1.0,
    3.0
  ]
}

    For example: 

    {
  ......

  "deviceConfiguration": {
    "mnmn": "xxxxx",
    "vid": "xxxxx",
    "version": "0.0.1",
    "type": "profile",
    "dashboard": {
      "states": [
        {
          "component": "main",
          "capability": "switch",
          "version": 1,
          "idx": 0,
          "group": "main",
          "values": [],
          "composite": false
        }
      ],
      "actions": [
        {
          "component": "main",
          "capability": "switch",
          "version": 1,
          "idx": 0,
          "group": "main"
        }
      ],
      "basicPlus": []
    },
    "detailView": [
      {
        "component": "main",
        "capability": "healthCheck",
        "version": 1,
        "values": [],
        "patch": []
      },
      {
        "component": "main",
        "capability": "refresh",
        "version": 1,
        "values": [],
        "patch": []
      },
      {
        "component": "main",
        "capability": "switch",
        "version": 1,
        "values": [],
        "patch": []
      },
      {
        "component": "main",
        "capability": "fanSpeed",
        "version": 1,
        "values": [
          {
            "key": "fanSpeed.value",
            "range":[
              1.0,
              3.0
            ]
          }
        ],
        "patch": []
      }
    ],
    "automation": {
      "conditions": [
        {
          "component": "main",
          "capability": "healthCheck",
          "version": 1,
          "values": [],
          "patch": [],
          "exclusion": []
        },
        {
          "component": "main",
          "capability": "switch",
          "version": 1,
          "values": [],
          "patch": [],
          "exclusion": []
        },
        {
          "component": "main",
          "capability": "fanSpeed",
          "version": 1,
          "values": [
            {
              "key": "fanSpeed.value",
              "range":[
                1.0,
                3.0
              ]
            }
          ],
          "patch": [],
          "exclusion": []
        }
      ],
      "actions": [
        {
          "component": "main",
          "capability": "healthCheck",
          "version": 1,
          "values": [],
          "patch": [],
          "exclusion": []
        },
        {
          "component": "main",
          "capability": "refresh",
          "version": 1,
          "values": [],
          "patch": [],
          "exclusion": []
        },
        {
          "component": "main",
          "capability": "switch",
          "version": 1,
          "values": [],
          "patch": [],
          "exclusion": []
        },
        {
          "component": "main",
          "capability": "fanSpeed",
          "version": 1,
          "values": [
            {
              "key": "fanSpeed.value",
              "range":[
                1.0,
                3.0
              ]
            }
          ],
          "patch": [],
          "exclusion": []
        }
      ]
    },
    "presentationId": "xxxxx",
    "manufacturerName": "xxxxx"
  }
}

  4. Click ellipses(…) of the device profile again and choose "Upload new file". Upload the modified json file and click "Override Device Profile".

  5. Copy the Device Profile ID which needs to be placed in the information model's deviceProfileId field.

Ceiling fan with light

  1. Click "Add new Device Profile".
  2. Name this profile and click "Edit capabilities".
  3. Click "Add Component+" button and enter "fan" or a name that is easy to identify.
  4. Search switch and fan speed in Capability Library and add them to the fan component you just added.
  5. Click "Add Component+" button and enter "light" or a name that is easy to identify.
  6. Search switch, switch level and color temperature(optional) in Capability Library and add them to the light component you just added.
  7. Hit "Save and Close" to go back to the profile details page.
  8. Scroll down to the "Dashboard View", choose light for Profile icon and light --> Switch to both "State" and "Action" then click "Create Profile". Or if you prefer, choose fan for the dashboard view.
  9. Copy the device profile ID and add it to information model's deviceProfileId field.

Ceiling fan with 2 lights and 1 switch control

  1. Click "Add new Device Profile".
  2. Name this profile and click "Edit capabilities".
  3. Click "Add Component+" button and enter "fan" or a name that is easy to identify.
  4. Search switch and fan speed in Capability Library and add them to the fan component you just added.
  5. Click "Add Component+" button and enter "light1" or a name that is easy to identify.
  6. Search switch, switch level and color temperature(optional) in Capability Library and add them to the component you just added.
  7. Click "Add Component+" button and enter "light2" or a name that is easy to identify.
  8. Search switch, switch level and color temperature(optional) in Capability Library and add them to the component you just added.
  9. Click "Add Component+" button and enter "switch" or a name that is easy to identify.
  10. Search switch in Capability Library and add it to the component you just added.
  11. Hit "Save and Close".
  12. Scroll down to the "Dashboard View", choose fan for Profile icon and fan --> Switch to both "State" and "Action" then click "Create Profile". Or if you prefer, choose either light1, light2, or switch for the dashboard view.
  13. Click the ellipses(…) of the device profile you just created and choose "Download file".

  14. Edit device configuration json file. In "detailView" and "automation" section's colorTemperature capability, add "key" (colorTemperature.value) and "range" under "values". In "action" section's colorTemperature capability, add "key" (setColorTemperature) and "range" values. For example, if the light's color temperature can be adjusted between 3000K to 6500K, please put 3000 and 6500 in the range field.

    {
  "key": "colorTemperature.value",
  "range": [
    3000,
    6500
  ]
}

    You may download an device profile example for reference.

    For devices with a color temperature setting, the key in the action (setColorTemperature) section differs from that in the detailView and automation (colorTemperature.value).

  15. Click ellipses(…) of the device profile again and choose "Upload new file". Upload the modified json file and click "Override Device Profile".

  16. Add the component key to each SmartThings capability in the information model. Here's an example: 
    {
    "appliedDomain": [
        "smartthings"
    ],
    "id": "STFAN1",
    "type": "fan",
    "append_name": " fan1",
    "component": "fan",
    "attributes": {
        "fan_speed": {
            "before": [
                {
                    "key": "H0B",
                    "value": 1
                }
            ],
            "key": "H0C",
            "max": 100,
            "min": 1,
            "on_off": {
            "key": "H0B",
            "values": {
                "off": 0,
                "on": 1
            }
        }
    },
    "description": "Dual Light FAN"
},
{
    "appliedDomain": [
        "smartthings"
    ],
    "id": "STLIGHT1",
    "type": "light",
    "component": "light1",
    "append_name": "Light1",
    "attributes": {
        "percentage": {
            "max": 100,
            "key": "H0C",
            "min": 1,
            "before": [
                {
                    "key": "H0B",
                    "value": 1
                }
            ]
        },
        "on_off": {
            "key": "H0B",
            "values": {
                "on": 1,
                "off": 0
            }
        },
        "color_temperature": {
            "key": "H0C",
            "max": 6500,
            "min": 3000,
            "before": [
                {
                    "key": "H0B",
                    "value": 1
                }
            ]
        }
    },
    "description": "Dual LIGHT Fan 1"
},
{
    "appliedDomain": [
        "smartthings"
    ],
    "id": "STLIGHT2",
    "type": "light",
    "component": "light2",
    "append_name": " Light2",
    "attributes": {
        "percentage": {
            "before": [
                {
                    "key": "H0B",
                    "value": 1
                }
            ],
            "key": "H0C",
            "max": 100,
            "min": 1
        },
        "on_off": {
            "key": "H0B",
            "values": {
                "on": 1,
                "off": 0
            }
        },
        "color_temperature": {
            "key": "H0C",
            "max": 6500,
            "min": 3000,
            "before": [
                {
                    "key": "H0B",
                    "value": 1
                }
            ]
        }
    },
    "description": "Dual LIGHT Fan 2"
},
{
    "appliedDomain": [
        "smartthings"
    ],
    "append_name": " switch1",
    "id": "STSWITCH1",
    "component": "switch",
    "type": "switch",
    "attributes": {
        "on_off": {
            "key": "H0D",
            "values": {
                "on": 1,
                "off": 0
            }
        }
    },
    "description": "A Switch"
}

Note

Ensure the information model includes the correct device profile ID and matching component names before proceeding.

Step 3: Create a Product and Brand Info

  1. Go to Certification Console.
  2. Click "Products" on the side navigator to add a new product.
  3. Fill in the required info as instructed. For the "Integration Details", please choose "Cloud Device". Select the schema app from the drop down list and enter the device profile ID you created in step 1 and 2.
  4. Click "Create Product"
  5. Click "Brands" on the side navigator to add your brand info.

Step 4: Connect Your Device On Mobile to Test

You may follow this document for more detail.

  1. Sign in ExoHome App with your admin account and add a device .
  2. Install app "SmartThings" and login to your SmartThings developer account.
  3. You can follow Test your device App to:
    • Enable developer mode
    • Link your device
  4. Choose your testing connector:
    • Tap Add device on the Dashboard, or in the Devices tab. Tap Partner Devices.
    • Click "My testing device"
    • Choose the product's schema app name you set in the SmartThings Developer.
  5. Login ExoHome for authentication
  6. Authentication succeeds
  7. All linked devices will be listed
  8. You could refresh current status of devices and operate them
  9. Go to Test Suite and you'll see the device you added.
  10. Try to run the automated self-test.

Publish

After completing your self-testing in developer mode, you can submit the certification request.

Have more questions? Submit a request